Second Life Wiki - User contributions [en]

LlEmail

2009-03-18T21:18:56Z

James Linden:

{{LSL_Function
|func_id=119|func_sleep=20.0|func_energy=10.0
|sort=Email|func=llEmail
|p1_type=string|p1_name=address
|p2_type=string|p2_name=subject
|p3_type=string|p3_name=message
|func_footnote=The entire message (including the address, subject and other miscellaneous fields) can't be longer than 4096 bytes combined.
|func_desc=Sends an email to '''address''' with '''subject''' and '''message'''.
|return_text
|spec=The '''message''' is prefixed with information about the prim sending the email.
{{{!}}{{Prettytable}}
{{!}}-{{Hl2}}
!Template
!Example
{{!}}-
{{!}}<pre>
Object-Name: *prim*
Region: *simname* (*simpos.x*, *simpos.y*)
Local-Position: (*primpos.x*, *primpos.y*, *primpos.z*)

*message*
</pre>
{{!}}
<pre>
Object-Name: Object
Region: Gibson (254976, 256000)
Local-Position: (117, 129, 50)

The real message starts here.
</pre>
{{!}}}
|caveats=* There is a limit to the number of email messages an object can send in a given amount of time.
* There is a limit of 500 messages from a single agent's objects in a one hour period.
* The 4096 byte size limit includes the subject line and automatically added text. The practical maximum body size is approximately 3600 bytes.
* (Sept-2008) The Email Throttle was modified slightly, Per Prospero Linden's comments: "there has long been a throttle that makes a single script sleep for 20 seconds after sending an email. The new throttle is per user... some were using many, many different scripts to send spam. (the new throttle applies) when the destination is outside of Second Life. I know that messages within the same region were not throttled (beyond the 20-second delay), and I *believe* that messages between different sims were not throttled (between the 20-second delay)."
* Due to the bug {{Jira|SVC-23}} (present since 2005), objects may stop receiving emails completely until either the region is restarted or the object crosses a region boundary (resetting the script doesn't help). Emails sent may eventually be received after a restart/region-cross. Hence, don't rely on this function for reliable inter-region messaging.
|constants
|examples=
<lsl>
string email_address = "somebody@example.com"; // who will receive the messages

default
{
state_entry() {

//Send an email to a normal email account
llEmail( email_address, "Look it's an email subject line!", "Testing 1 2 3" );
}

touch_start( integer num_detected ) {
integer i = 0;

// Send another email, telling who touched the prim.
do
llEmail( email_address, "No touching!", "I was defiled by: " + llDetectedName(i) + "\nKey: " + (string) llDetectedKey(i) );
while(++i < num_detected);
}
}
</lsl>
|also_functions=
{{LSL DefineRow|[[llGetNextEmail]]}}
{{LSL DefineRow|[[llMessageLinked]]}}
|also_events=
{{LSL DefineRow|[[email]]}}
{{LSL DefineRow|[[link message]]}}
|also_tests
|also_articles
|notes=* Because of the long delay on this function, it is often called from a second script triggered by [[link_message]].
* If you are sending email to a prim within Second Life, its address is ''[key]''@lsl.secondlife.com
** Which means if the key returned by [[llGetKey]] is "a2e76fcd-9360-4f6d-a924-000000000003", then its email address is "a2e76fcd-9360-4f6d-a924-000000000003@lsl.secondlife.com".
** Agents do not have fixed email addresses, use [[llInstantMessage]] or [[llOwnerSay]].

===Prim2Prim Email===

In LSL you can both send email with llEmail and receive it with the [[email]] event.

The email event is triggered with 5 pieces of information.
{{{!}}
{{LSL DefineRow|string|time|When the message was sent, in the <code>(string)[[llGetUnixTime]]</code> format}}
{{LSL DefineRow|string|address|Who sent the message}}
{{LSL DefineRow|string|subject|Subject of the message}}
{{LSL DefineRow|string|message|Body of the message}}
{{LSL DefineRow|integer|num_left|The number of emails left in the email queue}}
{{!}}}

When receiving a message sent with [[llEmail]] it helps to separate the message from the prefixed header. The header and original message body are separated by "\n\n"

<lsl>integer divide = llSubStringIndex(message, "\n\n");
string header = llDeleteSubString(message, divide, -1);
message = llDeleteSubString(message, 0, divide + 1);</lsl>

To get just 1 of the header items, do this:
<lsl>list lines = llParseStringKeepNulls(header, ["\n"], []);
string objname_line = llList2String(lines, 0);
string region_line = llList2String(lines, 1);
string localpos_line = llList2String(lines, 2);</lsl>

To get a pure region name, do this:
<lsl>string region_name = llStringTrim(
(string)llDeleteSubList(
llParseStringKeepNulls(
llDeleteSubString(region_line, 0, 12),
[],
["("]
), -2, -1), STRING_TRIM);</lsl>

This application uses email to have objects check with a central server to see if the owner has the latest version. In the objects:
<lsl>string version = "1"; //
string type = "lolcube";
default
{
on_rez(integer start_param)
{
llEmail("5a634b27-f032-283f-2df2-55ead7724b23@lsl.secondlife.com",
version,
(string)llGetOwner() + "," + type);
}
}</lsl>
The server:
<lsl>default
{
state_entry()
{
llSetTimerEvent(15.0);
}

timer()
{
llGetNextEmail("", "");
}

email( string time, string address, string version, string message, integer num_left )
{
if ((integer)version < 2)
{
list info = llCSV2List( llDeleteSubString(message, 0, llSubStringIndex(message, "\n\n") + 1));
llGiveInventory(llList2Key(info,0), llList2String(info,1));
}

if(num_left)
llGetNextEmail("","");
}
}</lsl>
|helpers=
<lsl>
email( string time, string address, string subj, string message, integer num_left )
{
if(llGetSubString(address, -19, -1) == "@lsl.secondlife.com")//trim the header
message = llDeleteSubString(message, 0, llSubStringIndex(message, "\n\n") + 1);
}
</lsl>
|permission
|negative_index
|cat1=Communications
|cat2=Email
|cat3
|cat4
}}
<div id="box">
== Open Source Portal ==
<div style="padding: 0.5em;">
{{OSWikiFeatureNav}}
=== Feature Design Document ===
(none)

=== Functional Spec ===
(none)

=== Test scripts ===
[https://osiris.lindenlab.com/mediawiki/index.php/Email_Test internal test]

=== Discussion for future improvements ===
(none)

=== Relationship to other features ===
<b> List of features that need to be tested when this feature changes, and why. </b>

[[IM to email]] - verify IM -> email still works.

[[Postcards]] - Postcards use email out?

=== User Guides ===
[http://lslwiki.net/lslwiki/wakka.php?wakka=llemail llEmail on LSLwiki.net]
</div></div>

Category:LSL XML-RPC

2009-02-11T20:15:51Z

James Linden: Added curl / raw XML example

{{LSL Header|ml=*}}{{LSLC|}}{{LSLC|Communications}}
[http://en.wikipedia.org/wiki/XMLRPC XML-RPC] is a standard for sending Procedure Calls (e.g. function calls) to Remote systems. It sends [http://en.wikipedia.org/wiki/XML XML] data over HTTP that remote system then handles.

LSL receives XML-RPC requests and passes them to the prim specified. It may not establish this connection, but it may reply and keep two-way communication with that server. These responses seem to be able to transport the largest amount of data out of Second Life (vs. [[Email]] and {{LSLGC|HTTP}} Requests).

=== NOTE: ===

XML-RPC requests often time-out due to the front-end server being overloaded. LL has continued to upgrade the server hardware periodically, but it has remained unreliable. LL developers have advised that the XML-RPC design isn't scalable (due to the single server bottle-neck) and that the service is "deprecated". They suggest using HTTP polling as an alternative. If an XML-RPC request does time-out the script's remote_data event may or may not be triggered (and any script response is lost).

=== IMPORTANT IMPLEMENTATION NOTE: ===

The current implementation of XML-RPC only allows ONE request to be queued on the front-end server (xmlrpc.secondlife.com) at a time. Any additional requests to the same data channel overwrite any pending one. This has serious ramifications for the design of XML-RPC communications where the in-world object could receive requests faster than it can respond to them. In addition, the 3-second delay in [[llRemoteDataReply]] exacerbates this problem even more.

The observed issue is this: if you send multiple quick requests to an in-world object via XML-RPC, one which is scripted to perform some processing and then return a response (via llRemoteDataReply), there is a potential for earlier requests to get lost on the front end server (they still should generate [[remote_data]] events, though), and have the response meant for an earlier request end up being passed back to a later one, while the earlier requests will time out back at your external application.

As a result, if you intend to do any serious work with XML-RPC, you will have to design your external client application to manually serialize all requests to each individual RPC channel. That means you have to wait for a response from the previous request before you attempt to send the next one. If you don't care about receiving responses, then this problem is not an issue, as all requests seem to get passed on to the script, regardless of the queueing issue.

Also note that there is NO way to get around the 3-second delay for llRemoteDataReply; you cannot use the multiple-slave-comm-script trick, because XML-RPC channels are *script-specific*, NOT *object-specific*.

For more information, see these forum threads [http://forums.secondlife.com/showthread.php?t=158437 here] and [http://forums.secondlife.com/showthread.php?p=1379244 here].

==Other Resources==
* [http://www.xmlrpc.com/ XMLRPC.com]
* [http://scripts.incutio.com/xmlrpc/ Incutio's XML-RPC PHP library]
* [http://perisic.com/sl/ A simple form to launch an XMLRPC request into Second Life]

==Examples==

=php=

To initialize a xmlrpc from an external server you'll need some kind of web-application.
One language to create a webapplication in is PHP.
Here is an example of how to send a xmlrpc message to your SL-script from a webserver using PHP:
<php><?php
echo '<pre>';
$channel = ""; //Fill in the channel you are using (key)
$intvalue = ""; //Fill in the intvalue you are using (integer)
$strvalue = ""; //Fill in the strvalue you are using (string)
$xmldata = "<?xml version=\"1.0\"?><methodCall><methodName>llRemoteData</methodName>
<params><param><value><struct>
<member><name>Channel</name><value><string>".$channel."</string></value></member>
<member><name>IntValue</name><value><int>".$intvalue."</int></value></member>
<member><name>StringValue</name><value><string>".$strvalue."</string></value></member>
</struct></value></param></params></methodCall>";
echo sendToHost("xmlrpc.secondlife.com", "POST", "/cgi-bin/xmlrpc.cgi", $xmldata);
echo '</pre>';

function sendToHost($host,$method,$path,$data,$useragent=0)
{
$buf="";
// Supply a default method of GET if the one passed was empty
if (empty($method))
$method = 'GET';
$method = strtoupper($method);

$fp = fsockopen($host, 80, $errno, $errstr, 30);

if( !$fp )
{
$buf = "$errstr ($errno)<br />\n";
}else
{
if ($method == 'GET')
$path .= '?' . $data;
fputs($fp, "$method $path HTTP/1.1\r\n");
fputs($fp, "Host: $host\r\n");
fputs($fp, "Content-type: text/xml\r\n");
fputs($fp, "Content-length: " . strlen($data) . "\r\n");
if ($useragent)
fputs($fp, "User-Agent: MSIE\r\n");
fputs($fp, "Connection: close\r\n\r\n");
if ($method == 'POST')
fputs($fp, $data);
while (!feof($fp))
$buf .= fgets($fp,128);
fclose($fp);
}
return $buf;
}
?></php>

=perl=

The perl code and corresponding LSL code to contact an object in Second Life is given below. The perl code makes use of the RPC::XML module. You can run the perl code from the command line. It creates an rpc object and sends a message to an object that is rezzed on the grid. Note that you have to supply the UUID of the object within the perl code.

The perl code sends the message that contains the string "Message to pass" and the number "2007." The LSL code responds by sending the string "I got it" and the number "2008."

<perl>#!/usr/bin/perl
#

use RPC::XML;
use RPC::XML::Parser;
use RPC::XML::Client;

my $llURL = "http://xmlrpc.secondlife.com/cgi-bin/xmlrpc.cgi";
$P = RPC::XML::Parser->new();

my $cli = RPC::XML::Client->new($llURL);
my $req = RPC::XML::request->new(
"llRemoteData",
{'Channel' => RPC::XML::string->new("UUID for the open channel from the object GOES HERE!"),
'IntValue' => RPC::XML::int->new(2007),
'StringValue' => RPC::XML::string->new("message to pass")});

# Print out the message to send
print "ref(req): ",ref($req),"\n";
$xml = $req->as_string();
print "Length: ",$req->length,"\n\n",$xml,"\n\n";

$res = $P->parse($xml);
print ref($res),"\n";
if (ref($res)) {
%h = %{$res->args->[0]->value};
foreach $lupe (keys %h) {
print "$lupe: $h{$lupe}\n";
}
}

# Submit the request to send the information above.
my $resp = $cli->send_request($req);

# Print out the response
print "\n\n\nResponse\n";
print "ref(resp): ",ref($resp),"\n";
$xml = $resp->as_string();
print "Length: ",$resp->length,"\n\n",$xml,"\n\n";

$res = $P->parse($xml);
print ref($res),"\n";
if (ref($res)) {
%h = %{$res->value};
foreach $lupe (keys %h) {
$val = $h{$lupe};
print "$lupe: $val\n";
}
}</perl>

=Java=

This Java code uses the org.apache.xmlrpc library, a jar file for this can be found at http://www.perisic.com/xmlrpc/cis69mc.jar (the code has been tested with this). See http://perisic.com/xmlrpc for a simple introduction into Java & XMLRPC if necessary.
* Save the code in a file named SLClient.java and download the jar file cis69mc.jar from the location above.
* Add the channel id where it says '<add channel id here!!!>', so this line may eventually look similar to <code>theData.put("Channel", "24a2c834-c984-9209-78df-20608d4c8ade");</code>
* Compile the code with the command: javac -classpath "cis69mc.jar;." SLClient.jar (you may get a note about unchecked or unsafe operations, ignore that).
* Run the code with the command: java -classpath "cis69mc.jar;." SLClient

<java>import java.util.*;
import org.apache.xmlrpc.*;

public class SLClient {
public static void main (String [] args) {
try {
Hashtable theData = new Hashtable();
XmlRpcClient server = new XmlRpcClient("http://xmlrpc.secondlife.com/cgi-bin/xmlrpc.cgi"); //
theData.put("Channel", "<add channel id here!!!>");
theData.put("IntValue", 2483);
theData.put("StringValue", "The date is: "+ (new Date()).toString() );
Vector params = new Vector();
params.add(theData);

Object result = server.execute("llRemoteData", params );

} catch (Exception exception) {
System.err.println("SL_Client: " + exception);
exception.printStackTrace();
}
}
}</java>

=Visual Basic 6=

This piece of Visual Basic 6 code makes use of the Microsoft WinSock 6.0 control. Make a new project, and place a Winsock control on the form.

<vb>
Dim Channel As String
Dim IntValue As Integer
Dim StrValue As String
Dim XMLData As String

Private Sub Form_Load()
Channel = "<add channel id here!!!>"
IntValue = 2007
StrValue = "This is a test string."
XMLData = "<?xml version=""1.0""?><methodCall><methodName>llRemoteData</methodName><params><param><value><struct>"
XMLData = XMLData & "<member><name>Channel</name><value><string>" & Channel & "</string></value></member>"
XMLData = XMLData & "<member><name>IntValue</name><value><int>" & CStr(IntValue) & "</int></value></member>"
XMLData = XMLData & "<member><name>StringValue</name><value><string>" & StrValue & "</string></value></member>"
XMLData = XMLData & "</struct></value></param></params></methodCall>"

Winsock1.Connect "xmlrpc.secondlife.com", 80
End Sub

Private Sub Winsock1_Connect()
WinsockSend "POST /cgi-bin/xmlrpc.cgi HTTP/1.1" & vbCrLf
WinsockSend "Host: xmlrpc.secondlife.com" & vbCrLf
WinsockSend "Content-type: text/xml" & vbCrLf
WinsockSend "Content-length: " & CStr(Len(XMLData)) & vbCrLf
WinsockSend "Connection: close" & vbCrLf & vbCrLf
WinsockSend XMLData & vbCrLf
End Sub

Private Sub Winsock1_DataArrival(ByVal bytesTotal As Long)
Dim TempStr As String
Winsock1.GetData TempStr
MsgBox TempStr
End Sub

Sub WinsockSend(str As String)
Winsock1.SendData str
End Sub
</vb>

=Command line curl=
If you want to debug XML-RPC from the command line you can use "curl" to do so. Put this in a file called <code>rpc.xml</code>, replacing the UUID for Channel with your script's channel id:

<xml>
<?xml version="1.0"?>
<methodCall>
<methodName>llRemoteData</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>Channel</name>
<value><string>1ee246fc-e60d-2fd3-6242-f5fc5d19850f</string></value>
</member>
<member>
<name>IntValue</name>
<value><int>42</int></value>
</member>
<member>
<name>StringValue</name>
<value><string>Hello, world!</string></value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>
</xml>

Then call curl to make a POST to the XMLRPC server:

<code>
curl --verbose --data "@rpc.xml" http://xmlrpc.secondlife.com/cgi-bin/xmlrpc.cgi
</code>

=LSL Server Code=

Corresponding LSL code (copy and paste this code as a script in an object, save and rezz it, a message with the channel id (and other stuff) will be printed):

<lsl>key remoteChannel;
init() {
llOpenRemoteDataChannel(); // create an XML-RPC channel
llOwnerSay("My key is " + (string)llGetKey());
}

default {
state_entry() {
init();
}

state_exit() {
return;
}

on_rez(integer param) {
llResetScript();
}

remote_data(integer type, key channel, key message_id, string sender, integer ival, string sval) {
if (type == REMOTE_DATA_CHANNEL) { // channel created
llSay(DEBUG_CHANNEL,"Channel opened for REMOTE_DATA_CHANNEL" +
(string)channel + " " + (string)message_id + " " + (string)sender + " " +
(string)ival + " " + (string)sval);
remoteChannel = channel;
llOwnerSay("Ready to receive requests on channel \"" + (string)channel + "\"");
state receiving; // start handling requests
} else {
llSay(DEBUG_CHANNEL,"Unexpected event type");
}
}
}

state receiving {

state_entry() {
llOwnerSay("Ready to receive information from outside SL");
}

state_exit() {
llOwnerSay("No longer receiving information from outside SL.");
llCloseRemoteDataChannel(remoteChannel);
}

on_rez(integer param) {
llResetScript();
}

remote_data(integer type, key channel, key message_id, string sender, integer ival, string sval) {
if (type == REMOTE_DATA_REQUEST) { // handle requests sent to us
llSay(DEBUG_CHANNEL,"Request received for REMOTE_DATA_REQUEST " + (string)channel + " " +
(string)message_id + " " + (string)sender + " " + (string)ival + " " + (string)sval);
llRemoteDataReply(channel,NULL_KEY,"I got it",2008);
llOwnerSay("I just received data in "+ llGetRegionName() +
" at position " + (string)llGetPos() + "\n" +
"The string was " + sval + "\nThe number was " + (string)ival + ".");
}
}
}</lsl>

Linden Lab Official:Map API

2009-02-10T16:56:24Z

James Linden: /* Accessing map images directly */

{{Help/Box|Update notice|<b>We've made improvements and changes to the Map API, effective January 15, 2009.<br>Some information here may be out of date as we update this wiki with the changes. Thanks for your patience.</b>}}

{{:API Portal/navigation}}
__TOC__

== Getting Started ==

The Second Life Map API is a set of Javascript objects and functions that enable you to embed Second Life maps onto your web pages. It is a purely client-side Javascript API. If needed, you can also [[#Accessing_map_images_directly|directly access]] the map images.

'''NOTE:'''
This API is still in beta. URLs and API signatures may change.

=== Map UI features ===

The Map API enables you to create web pages that have Google Maps functionality, using maps of Second Life, rather than Earth. In general, the default map interface looks as shown here.

[[Image:Map ui cropped.png|right]]

The main map display area shows the current map area. By default, the map provides the following features:

* Click and drag the mouse pointer to pan the map view up, down, left, and right. If desired, you can [[Map_API_Advanced_Examples#Disabling_and_enabling_dragging|disable this behavior]].
* Double-click to zoom in by one level (power of two) and display the teleport window.
* Click anywhere on the map to open a "teleport" window; see '''Teleport window''' below.
* Use the mouse wheel to zoom in and out. See [[#Zoom_levels|Zoom levels]] for more information about zoom levels.
* Use the zoom and pan controls at upper left to zoom the view in and out and to pan the view up, down, left, and right. If desired, you can easily [[Map_API_Advanced_Examples#Customizing_zoom_and_pan_controls|create your own custom zoom and pan controls]].
* Use the overview control to move the view around by clicking and dragging, or double-clicking. Close the overview control by clicking on the diagonal arrow at the very bottom right of the map. You can specify whether the map provides an overview control when you [[Map_API_Reference#MarkerOptions|create the map object]].

<br clear="all" />

'''Teleport window'''
[[Image:Teleport window.png|left]]
Clicking anywhere on the map opens a window, such as the one shown at left, indicating the point on which you clicked. Clicking on the teleport button in the window then starts the Second Life Viewer, automatically teleporting you to the window's location. This feature is implemented with the [[Map_API_Reference#Global_functions|gotoSLURL()]] global function.

<br clear="all" />

=== Using slurl.com and DirectSLurl ===

The website http://slurl.com uses the Map API to provide a mechanism to teleport directly to locations in Second Life from web pages.

For more information, see [[Using Second Life URLs (SLURLs)]].

=== Prerequisites ===

To use the Second Life Map API in a web page, you must first:

* [http://www.google.com/apis/maps/signup.html Sign up for a Google Maps API key]. This enables you to use the Google Maps API, which is required to use SLMAPI. See the [http://code.google.com/apis/maps/documentation/ Google Maps API documentation] for more information.
* Add the [[#Common_HTML_header|common header code]] at the beginning of each HTML file. This code loads the Google Maps and Webmap Javascript libraries, the Webmap cascading stylesheet (CSS), and some other basic code.

NOTE: In general, it is best to reference the Map API Javascript library and CSS files that are on http://slurl.com. Although you can download these files locally and modify them for your own use, if Linden Lab updates or changes these files, your applications will not get the benefit and may even stop working properly.

=== Common HTML header ===

To use the Map API, put the following lines at the beginning of each HTML page. This includes:
* Statements to load the required Second Life Map API and Google Maps Javascript libraries.
* Link to the Webmap cascading style sheet.
* Style declaration for the map div element. This defines the size and other layout attributes of the map display.

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}"
type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</pre>

Replace {GOOGLE MAPS KEY} with you Google Maps Key.

All the examples also require additional script statements in the HTML header.

'''Stylesheet'''

To use your own stylesheet, just include it AFTER the Webmap CSS, for example:

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<link rel="stylesheet" type="text/css" href="myStyleSheet.css" />

'''Body element'''

Use the following body element in your HTML document:

<body load="loadmap()" onunload="GUnload();">
...

The '''GUnload()''' function is a Google Maps API function that reduces memory leaks, particularly with Internet Explorer. For more information, see the [http://code.google.com/apis/maps/documentation/#Memory_Leaks Google Maps API documentation].

=== Browser compatibility ===
The Map API has been tested to work with the following browsers:
* Internet Explorer 6.0
* Internet Explorer 7.0
* Firefox 2.0 or greater
* Safari 2.0

Other browsers may work but little issues may appear. Unless otherwise noted, all features work in all supported browsers.

=== Comments and feedback ===

If you encounter problems or bugs or have feature requests, please email '''webmap@secondlife.com'''.

Happy coding from the Second Life Web team!

== Basic concepts ==

The Map API's fundamental class is [[Webmap_API_Reference#SLMap|SLMap]]. It is a Javascript object representing the map with a large number of methods, enabling you to zoom, pan the view, and so on.

Additionally, the API includes the following key classes:
* [[Webmap_API_Reference#Marker|Marker]] - represents an image to display at a specify (x,y) point on the map. You provide a set of images to display at each zoom level. Contains several event handlers and other properties. See [[#Map_with_a_marker|Map with a marker]] for a basic example.
* [[Webmap_API_Reference#MapWindow|Window]] - represents a captioned balloon pointing to a specified map location. See [[Webmap_API#Map_with_an_initial_open_window|Map with an initial open window]] for a basic example.
* [[Webmap_API_Reference#Img|Img]] and [[Webmap_API_Reference#Icon|Icon]] - represent an image to use for markers, controls, or in windows.

===About coordinates===

Map coordinates are based on the Second Life grid system for positioning regions.

[[Image:Webmap coords.jpg]]

As illustrated in the diagram above, the Map API maps the Second Life world to the upper right quadrant of the Google world map. A large scaling value
called slGridEdgeSizeInRegions (equal to 2<sup>20</sup> or 1,048,576) defines the largest region coordinate at the top and far right edge of the displayed area. This value creates a map area with room for one trillion sims.

The little blue square illustrates where the populated sims are in Second Life.

=== Zoom levels ===
There are eight zoom levels: one through eight, one being the closest and eight being the farthest. Each level zooms by a power of two. In other words, at zoom level five, each region is twice the width as it was at zoom level six.

== Basic Examples ==

=== Required image files ===

Some of the following examples use image files for markers. To run the examples with the code as shown, download the image files and save them in the same directory as the example HTML files. Alternatively, create the Img objects using the URLs listed in the table below that refer to the images stored on this wiki.

The following table lists the images used in the examples:

{| {{Prettytable}}
|-{{Hl2}}
! Image
! File name
! URL

|-
| [[Image:Yellow marker.gif]]
| b_map_yellow.gif
| <br>http://slurl.com/examples/b_map_yellow.gif

|-
| [[Image:Fountain.gif]]
| fountain.gif
| http://slurl.com/examples/fountain.gif

|-
| [[Image:Forsale.png]]
| forsale.png
| http://slurl.com/examples/forsale.png

|-
|[[Image:Forsale-shadow.png]]
| forsale-shadow.png
|http://slurl.com/examples/forsale-shadow.png
|}

=== Simple map ===

The first example is a map with basic panning and zooming capabilities. When you are done, it will look as shown here.

[[Image:MapAPI ex1.png|thumb|right|Simple map]]

You can pan the map and zoom in and out.

To create this example, follow these steps:

# Add common HTML header code.
# Add HTML body element.
# Add '''loadmap()''' function.
# Save and test.

<br clear="all"/>

'''1. Add common HTML header'''

First, include the [[Webmap_API#Common_HTML_header|common header code]], required by all Webmap applications.

<pre><nowiki>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</head>
</nowiki></pre>

Be sure to replace {GOOGLE MAPS KEY} with your Google Map key.

'''2. Add HTML body element'''

Next, add the HTML body element to contain your map. The body contains a Javascript onload event handler that calls the '''loadmap()''' function you will define in the next step.

<pre>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

The div element is passed to the SLMap object constructor, using the <code>document.getElementById('map-container')</code> DOM method call.

NOTE: If you want the position attribute of the div element to be absolute, either set it programmatically using Javascript or using the style attribute tag. Setting the position attribute of this element in the CSS stylesheet will not work.

'''3. Add loadmap() function'''

The body element you just added has a Javascript event handler for the "onload" event, called when the browser initially loads the page. You deifined this to call a '''loadmap()''' function. Now, define that Javascript function in the head of your page (after the code that is already there), as follows:

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);
}
</script>

The first line defines a new Map object from the HTML div element. The second line centers the map at a specific point, and zooms it to zoom level three.

'''4. Save and test'''

When you are done, save the file, and then load it into your web browser. Try panning the map by clicking and dragging the mouse cursor; you can also pan by clicking on the arrow icons on the four sides. Also try zooming the view in and out by clicking the "+" and "-" icons.

'''Complete source code'''

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key=[GOOGLE MAPS KEY]" type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);
}
</script>

</head>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker ===

[[Image:Map with Marker.png|thumb|right|Map with a marker]]

A ''marker'' is simply an image displayed at a specific location on the map. The Map API enables you to define an image for each zoom level, so the marker can appear differently at each zoom level if you wish.

This example shows how to make a map with a marker. The code is the same as the first example, with with addition of some Javascript after the initialization of the map in the page's onload event handler function, '''loadmap()'''.

To use the code below verbatim, you must download the marker image as described in [[#Required_image_files|Required image files]]; you can also use the URL of the wiki image if you prefer.

The code first creates the icon for the marker, then places it on the map at (997, 1002) at the welcome area fountain. Because the same icon is specified for every zoom level, it appears the same size regardless of zoom level.

<br clear="all"/>
<pre>
// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
</pre>

In this example, clicking on the marker does nothing. Subsequent examples illustrate adding some onClick behavior.

'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// creates the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);

// creates the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// creates the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>There should be a yellow marker in the center of this map:
<div id="map-container"></div>
</body>
</pre>

=== Map with an initial open window ===

[[Image:Map_with_window.png|thumb|right|Map with a window]]

A Webmap ''window'' is a caption pointing to a specific point on the map, as shown in the screenshot at right. It looks something like a comic book dialog bubble.

Use the [[Webmap_API_Reference#MapWindow|MapWindow]] object to create a window.
For example, to create a window that opens initially when the page loads:
# Instantiate a [[Webmap_API_Reference#MapWindow|MapWindow]] object with the desired caption.
# Call the '''addMapWindow()''' method on the [[Webmap_API_Reference#SLMap|SLMap]] object to add the window to the map.
<br clear="all"/>
For example:

<pre>
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
</pre>

The code adds an open window to the map positioned again at (997, 1002), right above the welcome area fountain.

NOTE: after the user closes the window there is no way to bring it back. A subsequent example will show how to enable the user to reopen the window, by using markers with windows.
<br clear="all"/>

To make the map initially centered on the fountain, change the call to '''centerAndZoomAtSLCoord()''' as follows:

mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

'''Source code'''

This example shows how to create a map with a window. The code is the same as the first example, with the addition of some lines of Javascript after the initialization of the map, in the '''loadmap()''' function. In addition, the map is centered in a different location in order to make the window fully visible.

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

// Create window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<h1>Simple Map Example</h1>
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker that opens a window ===

[[Image:Map with marker and window.png|thumb|right|Map with marker that opens a window]]

This example shows how to create a map with a marker which opens a window when clicked. It is a combination of the previous two examples, because the code first creates a marker and a window.

The difference comes in adding the marker to the map: this time you provide the window object as well as the marker object in the call to '''addMarker()''':

mapInstance.addMarker(marker, mapWindow);

Doing this adds the marker and causes it to open the specified window when the user clicks it. If the user subsequently closes the window, s/he can open it again by clicking on the marker.

<br clear="all" />
'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// Create the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997.5, 1001.5), 2);

// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));

// Create a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='fountain.gif'>");

// Adds the marker to the map
mapInstance.addMarker(marker, mapWindow);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>This map shows a yellow marker on the welcome fountain. When you click the marker,
a window appears with a screenshot of the fountain.</p>
<div id="map-container"></div>
</body>
</pre>

== Accessing map images directly ==

The Second Life map images are stored on [http://aws.amazon.com/s3/ Amazon Simple Storage Service (Amazon S3)]. You can access the map images directly on the Amazon S3 servers using the following URL format (new as of February 10, 2009):

<nowiki>http://map.secondlife.com/map-Z-X-Y-objects.jpg</nowiki>

Where:
* Z - Zoom level desired:
** One (1) is the most zoomed-in view, showing individual region tiles.
** Eight (8) is the maximum zoom level, showing the entire world.
* X,Y - X and Y coordinates on the Second Life Grid of the region, for example, region Ahern is (997,1002).

Tiles with zoom greater than one are stored at the lower left corner coordinate of the tiles that are included in the image.
In other words, you can find the zoom tile containing region (X,Y) for zoom level Z with the filename map-Z-X'-Y'-objects.jpg where:

X' = X - (X % (2<sup>Z - 1</sup>) )

and

Y' = Y - (Y % (2<sup>Z - 1</sup>) )

Note that 2<sup>Z - 1</sup> is the number of regions encompassed by the width of a tile at resolution Z.

=== Examples ===

For example: if Z = 1, the four region tiles are:

* http://map.secondlife.com/map-1-1000-1000-objects.jpg
* http://map.secondlife.com/map-1-1001-1000-objects.jpg
* http://map.secondlife.com/map-1-1000-1001-objects.jpg
* http://map.secondlife.com/map-1-1001-1001-objects.jpg

These four region tiles are compressed into the single tile:

http://map.secondlife.com/map-2-1000-1000-objects.jpg

The following shows the map zoomed all the way out, showing the entire Second Life world view:
http://map.secondlife.com/map-8-1024-896-objects.jpg

The following displays a single tile contained in the view above, zoomed all the way in:
http://map.secondlife.com/map-1-1027-1019-objects.jpg

===Implementation notes===

The map generation process is more scalable than the previous release, and is able to image the entire Second Life grid of about 30,000 regions in less than two days.

There is a "decay period" for offline regions. If a region is disabled, the tile will stay up for several days (in case it comes back or something else has gone wrong) before the tile disappears. That several-day period will be longer than the time it takes to update existing regions or put new regions on the map.

=== Getting a map URL from LSL ===

The following LSL script illustrates how to display a map of the current region to an avatar:

<lsl>
ShowMap(key avatar) {
string url = "http://map.secondlife.com/";
vector sim_coord = llGetRegionCorner();
string x = (string)((integer)(sim_coord.x / 256.0));
string y = (string)((integer)(sim_coord.y / 256.0));
url += "map-1-" + x + "-" + y + "-objects.jpg";
llLoadURL(avatar, "View the sim map", url);
}
</lsl>

Contributed under GPL v3 license by [[User:Henri Beauchamp|Henri Beauchamp]] 09:00, 24 January 2009 (UTC), updated by [[User:James Linden|James Linden]] 20:51, 7 February 2009 (UTC)

== Release notes ==

This section describes new features and known issues with the current release of the Map API. See also [http://blog.secondlife.com/2009/01/22/improvements-to-mapping-and-upgrade-to-slurlcom/ Philip Linden's blog post announcement].

The current release of the Map API was released on Jan 15, 2009.

=== New features ===

This release of the Map API provides significant performance improvements over the previous release, including:
* Map loads faster and operates more smoothly.
* Map images are updated more accurately and rapidly. Changes to the Second Life Grid or content will now be visible within about two days.
* Map images look smoother and are more accurate when compared to the actual in-world content.

Changes in functionality:
* You can now single-click on any location on the map and teleport directly there.
* Zoom levels go up to eight, so you can now zoom out and see how big SL has really become!
* More intuitive map tile image file naming convention.

The Map API now gets map tile images directly from [http://aws.amazon.com/s3/ Amazon S3], and the file naming convention will make it easier to develop other third party maps based on the tiles we are generating.

=== Known issues ===

These need to be confirmed.
--[[User:Rand Linden|Rand Linden]] 23:29, 6 February 2009 (UTC)

* Can't set Map object click and doubleclick handlers. They always have the default behavior.
* Method '''SLMap.clickMarker(marker)''' doesn't work.
* Marker options apparently not working:
** '''centerOnClick: true''' - This works, but does NOT work if you open a window onclicking the marker.
** '''autopanOnClick: false''' - Always autopans
** '''autopanPadding: n''' - No effect
* Setting a different marker image/icon for each zoom level doesn't work - always uses first icon.
* Window width option doesn't work.

'''Questions:'''
* Now that there are 8 zoom levels instead of 6, when you instantiate a Marker, do you use an array of images of size 8 instead of 6?
* Old docs said that Map object clickhandler and doubleclickhander have (x,y) passed to them. Is that true (or rather, will it be true when they work?)

Linden Lab Official:Map API

2009-02-10T16:54:33Z

James Linden: Removed references to old tile URL format, updated example URLs to use new tile URL format

{{Help/Box|Update notice|<b>We've made improvements and changes to the Map API, effective January 15, 2009.<br>Some information here may be out of date as we update this wiki with the changes. Thanks for your patience.</b>}}

{{:API Portal/navigation}}
__TOC__

== Getting Started ==

The Second Life Map API is a set of Javascript objects and functions that enable you to embed Second Life maps onto your web pages. It is a purely client-side Javascript API. If needed, you can also [[#Accessing_map_images_directly|directly access]] the map images.

'''NOTE:'''
This API is still in beta. URLs and API signatures may change.

=== Map UI features ===

The Map API enables you to create web pages that have Google Maps functionality, using maps of Second Life, rather than Earth. In general, the default map interface looks as shown here.

[[Image:Map ui cropped.png|right]]

The main map display area shows the current map area. By default, the map provides the following features:

* Click and drag the mouse pointer to pan the map view up, down, left, and right. If desired, you can [[Map_API_Advanced_Examples#Disabling_and_enabling_dragging|disable this behavior]].
* Double-click to zoom in by one level (power of two) and display the teleport window.
* Click anywhere on the map to open a "teleport" window; see '''Teleport window''' below.
* Use the mouse wheel to zoom in and out. See [[#Zoom_levels|Zoom levels]] for more information about zoom levels.
* Use the zoom and pan controls at upper left to zoom the view in and out and to pan the view up, down, left, and right. If desired, you can easily [[Map_API_Advanced_Examples#Customizing_zoom_and_pan_controls|create your own custom zoom and pan controls]].
* Use the overview control to move the view around by clicking and dragging, or double-clicking. Close the overview control by clicking on the diagonal arrow at the very bottom right of the map. You can specify whether the map provides an overview control when you [[Map_API_Reference#MarkerOptions|create the map object]].

<br clear="all" />

'''Teleport window'''
[[Image:Teleport window.png|left]]
Clicking anywhere on the map opens a window, such as the one shown at left, indicating the point on which you clicked. Clicking on the teleport button in the window then starts the Second Life Viewer, automatically teleporting you to the window's location. This feature is implemented with the [[Map_API_Reference#Global_functions|gotoSLURL()]] global function.

<br clear="all" />

=== Using slurl.com and DirectSLurl ===

The website http://slurl.com uses the Map API to provide a mechanism to teleport directly to locations in Second Life from web pages.

For more information, see [[Using Second Life URLs (SLURLs)]].

=== Prerequisites ===

To use the Second Life Map API in a web page, you must first:

* [http://www.google.com/apis/maps/signup.html Sign up for a Google Maps API key]. This enables you to use the Google Maps API, which is required to use SLMAPI. See the [http://code.google.com/apis/maps/documentation/ Google Maps API documentation] for more information.
* Add the [[#Common_HTML_header|common header code]] at the beginning of each HTML file. This code loads the Google Maps and Webmap Javascript libraries, the Webmap cascading stylesheet (CSS), and some other basic code.

NOTE: In general, it is best to reference the Map API Javascript library and CSS files that are on http://slurl.com. Although you can download these files locally and modify them for your own use, if Linden Lab updates or changes these files, your applications will not get the benefit and may even stop working properly.

=== Common HTML header ===

To use the Map API, put the following lines at the beginning of each HTML page. This includes:
* Statements to load the required Second Life Map API and Google Maps Javascript libraries.
* Link to the Webmap cascading style sheet.
* Style declaration for the map div element. This defines the size and other layout attributes of the map display.

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}"
type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</pre>

Replace {GOOGLE MAPS KEY} with you Google Maps Key.

All the examples also require additional script statements in the HTML header.

'''Stylesheet'''

To use your own stylesheet, just include it AFTER the Webmap CSS, for example:

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<link rel="stylesheet" type="text/css" href="myStyleSheet.css" />

'''Body element'''

Use the following body element in your HTML document:

<body load="loadmap()" onunload="GUnload();">
...

The '''GUnload()''' function is a Google Maps API function that reduces memory leaks, particularly with Internet Explorer. For more information, see the [http://code.google.com/apis/maps/documentation/#Memory_Leaks Google Maps API documentation].

=== Browser compatibility ===
The Map API has been tested to work with the following browsers:
* Internet Explorer 6.0
* Internet Explorer 7.0
* Firefox 2.0 or greater
* Safari 2.0

Other browsers may work but little issues may appear. Unless otherwise noted, all features work in all supported browsers.

=== Comments and feedback ===

If you encounter problems or bugs or have feature requests, please email '''webmap@secondlife.com'''.

Happy coding from the Second Life Web team!

== Basic concepts ==

The Map API's fundamental class is [[Webmap_API_Reference#SLMap|SLMap]]. It is a Javascript object representing the map with a large number of methods, enabling you to zoom, pan the view, and so on.

Additionally, the API includes the following key classes:
* [[Webmap_API_Reference#Marker|Marker]] - represents an image to display at a specify (x,y) point on the map. You provide a set of images to display at each zoom level. Contains several event handlers and other properties. See [[#Map_with_a_marker|Map with a marker]] for a basic example.
* [[Webmap_API_Reference#MapWindow|Window]] - represents a captioned balloon pointing to a specified map location. See [[Webmap_API#Map_with_an_initial_open_window|Map with an initial open window]] for a basic example.
* [[Webmap_API_Reference#Img|Img]] and [[Webmap_API_Reference#Icon|Icon]] - represent an image to use for markers, controls, or in windows.

===About coordinates===

Map coordinates are based on the Second Life grid system for positioning regions.

[[Image:Webmap coords.jpg]]

As illustrated in the diagram above, the Map API maps the Second Life world to the upper right quadrant of the Google world map. A large scaling value
called slGridEdgeSizeInRegions (equal to 2<sup>20</sup> or 1,048,576) defines the largest region coordinate at the top and far right edge of the displayed area. This value creates a map area with room for one trillion sims.

The little blue square illustrates where the populated sims are in Second Life.

=== Zoom levels ===
There are eight zoom levels: one through eight, one being the closest and eight being the farthest. Each level zooms by a power of two. In other words, at zoom level five, each region is twice the width as it was at zoom level six.

== Basic Examples ==

=== Required image files ===

Some of the following examples use image files for markers. To run the examples with the code as shown, download the image files and save them in the same directory as the example HTML files. Alternatively, create the Img objects using the URLs listed in the table below that refer to the images stored on this wiki.

The following table lists the images used in the examples:

{| {{Prettytable}}
|-{{Hl2}}
! Image
! File name
! URL

|-
| [[Image:Yellow marker.gif]]
| b_map_yellow.gif
| <br>http://slurl.com/examples/b_map_yellow.gif

|-
| [[Image:Fountain.gif]]
| fountain.gif
| http://slurl.com/examples/fountain.gif

|-
| [[Image:Forsale.png]]
| forsale.png
| http://slurl.com/examples/forsale.png

|-
|[[Image:Forsale-shadow.png]]
| forsale-shadow.png
|http://slurl.com/examples/forsale-shadow.png
|}

=== Simple map ===

The first example is a map with basic panning and zooming capabilities. When you are done, it will look as shown here.

[[Image:MapAPI ex1.png|thumb|right|Simple map]]

You can pan the map and zoom in and out.

To create this example, follow these steps:

# Add common HTML header code.
# Add HTML body element.
# Add '''loadmap()''' function.
# Save and test.

<br clear="all"/>

'''1. Add common HTML header'''

First, include the [[Webmap_API#Common_HTML_header|common header code]], required by all Webmap applications.

<pre><nowiki>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</head>
</nowiki></pre>

Be sure to replace {GOOGLE MAPS KEY} with your Google Map key.

'''2. Add HTML body element'''

Next, add the HTML body element to contain your map. The body contains a Javascript onload event handler that calls the '''loadmap()''' function you will define in the next step.

<pre>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

The div element is passed to the SLMap object constructor, using the <code>document.getElementById('map-container')</code> DOM method call.

NOTE: If you want the position attribute of the div element to be absolute, either set it programmatically using Javascript or using the style attribute tag. Setting the position attribute of this element in the CSS stylesheet will not work.

'''3. Add loadmap() function'''

The body element you just added has a Javascript event handler for the "onload" event, called when the browser initially loads the page. You deifined this to call a '''loadmap()''' function. Now, define that Javascript function in the head of your page (after the code that is already there), as follows:

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);
}
</script>

The first line defines a new Map object from the HTML div element. The second line centers the map at a specific point, and zooms it to zoom level three.

'''4. Save and test'''

When you are done, save the file, and then load it into your web browser. Try panning the map by clicking and dragging the mouse cursor; you can also pan by clicking on the arrow icons on the four sides. Also try zooming the view in and out by clicking the "+" and "-" icons.

'''Complete source code'''

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key=[GOOGLE MAPS KEY]" type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);
}
</script>

</head>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker ===

[[Image:Map with Marker.png|thumb|right|Map with a marker]]

A ''marker'' is simply an image displayed at a specific location on the map. The Map API enables you to define an image for each zoom level, so the marker can appear differently at each zoom level if you wish.

This example shows how to make a map with a marker. The code is the same as the first example, with with addition of some Javascript after the initialization of the map in the page's onload event handler function, '''loadmap()'''.

To use the code below verbatim, you must download the marker image as described in [[#Required_image_files|Required image files]]; you can also use the URL of the wiki image if you prefer.

The code first creates the icon for the marker, then places it on the map at (997, 1002) at the welcome area fountain. Because the same icon is specified for every zoom level, it appears the same size regardless of zoom level.

<br clear="all"/>
<pre>
// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
</pre>

In this example, clicking on the marker does nothing. Subsequent examples illustrate adding some onClick behavior.

'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// creates the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);

// creates the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// creates the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>There should be a yellow marker in the center of this map:
<div id="map-container"></div>
</body>
</pre>

=== Map with an initial open window ===

[[Image:Map_with_window.png|thumb|right|Map with a window]]

A Webmap ''window'' is a caption pointing to a specific point on the map, as shown in the screenshot at right. It looks something like a comic book dialog bubble.

Use the [[Webmap_API_Reference#MapWindow|MapWindow]] object to create a window.
For example, to create a window that opens initially when the page loads:
# Instantiate a [[Webmap_API_Reference#MapWindow|MapWindow]] object with the desired caption.
# Call the '''addMapWindow()''' method on the [[Webmap_API_Reference#SLMap|SLMap]] object to add the window to the map.
<br clear="all"/>
For example:

<pre>
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
</pre>

The code adds an open window to the map positioned again at (997, 1002), right above the welcome area fountain.

NOTE: after the user closes the window there is no way to bring it back. A subsequent example will show how to enable the user to reopen the window, by using markers with windows.
<br clear="all"/>

To make the map initially centered on the fountain, change the call to '''centerAndZoomAtSLCoord()''' as follows:

mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

'''Source code'''

This example shows how to create a map with a window. The code is the same as the first example, with the addition of some lines of Javascript after the initialization of the map, in the '''loadmap()''' function. In addition, the map is centered in a different location in order to make the window fully visible.

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

// Create window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<h1>Simple Map Example</h1>
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker that opens a window ===

[[Image:Map with marker and window.png|thumb|right|Map with marker that opens a window]]

This example shows how to create a map with a marker which opens a window when clicked. It is a combination of the previous two examples, because the code first creates a marker and a window.

The difference comes in adding the marker to the map: this time you provide the window object as well as the marker object in the call to '''addMarker()''':

mapInstance.addMarker(marker, mapWindow);

Doing this adds the marker and causes it to open the specified window when the user clicks it. If the user subsequently closes the window, s/he can open it again by clicking on the marker.

<br clear="all" />
'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// Create the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997.5, 1001.5), 2);

// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));

// Create a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='fountain.gif'>");

// Adds the marker to the map
mapInstance.addMarker(marker, mapWindow);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>This map shows a yellow marker on the welcome fountain. When you click the marker,
a window appears with a screenshot of the fountain.</p>
<div id="map-container"></div>
</body>
</pre>

== Accessing map images directly ==

The Second Life map images are stored on [http://aws.amazon.com/s3/ Amazon Simple Storage Service (Amazon S3)]. You can access the map images directly on the Amazon S3 servers using the following URL format (new as of February 10, 2009):

<nowiki>http://map.secondlife.com/map-Z-X-Y-objects.jpg</nowiki>

Where:
* Z - Zoom level desired:
** One (1) is the most zoomed-in view, showing individual region tiles.
** Eight (8) is the maximum zoom level, showing the entire world.
* X,Y - X and Y coordinates on the Second Life Grid of the region, for example, region Ahern is (997,1002).

Tiles with zoom greater than one are stored at the lower left corner coordinate of the tiles that are included in the image.
In other words, you can find the zoom tile containing region (X,Y) for zoom level Z at the directory Z/X'/Y' where:

X' = X - (X % (2<sup>Z - 1</sup>) )

and

Y' = Y - (Y % (2<sup>Z - 1</sup>) )

Note that 2<sup>Z - 1</sup> is the number of regions encompassed by the width of a tile at resolution Z.

=== Examples ===

For example: if Z = 1, the four region tiles are:

* http://map.secondlife.com/map-1-1000-1000-objects.jpg
* http://map.secondlife.com/map-1-1001-1000-objects.jpg
* http://map.secondlife.com/map-1-1000-1001-objects.jpg
* http://map.secondlife.com/map-1-1001-1001-objects.jpg

These four region tiles are compressed into the single tile:

http://map.secondlife.com/map-2-1000-1000-objects.jpg

The following shows the map zoomed all the way out, showing the entire Second Life world view:
http://map.secondlife.com/map-8-1024-896-objects.jpg

The following displays a single tile contained in the view above, zoomed all the way in:
http://map.secondlife.com/map-1-1027-1019-objects.jpg

===Implementation notes===

The map generation process is more scalable than the previous release, and is able to image the entire Second Life grid of about 30,000 regions in less than two days.

There is a "decay period" for offline regions. If a region is disabled, the tile will stay up for several days (in case it comes back or something else has gone wrong) before the tile disappears. That several-day period will be longer than the time it takes to update existing regions or put new regions on the map.

=== Getting a map URL from LSL ===

The following LSL script illustrates how to display a map of the current region to an avatar:

<lsl>
ShowMap(key avatar) {
string url = "http://map.secondlife.com/";
vector sim_coord = llGetRegionCorner();
string x = (string)((integer)(sim_coord.x / 256.0));
string y = (string)((integer)(sim_coord.y / 256.0));
url += "map-1-" + x + "-" + y + "-objects.jpg";
llLoadURL(avatar, "View the sim map", url);
}
</lsl>

Contributed under GPL v3 license by [[User:Henri Beauchamp|Henri Beauchamp]] 09:00, 24 January 2009 (UTC), updated by [[User:James Linden|James Linden]] 20:51, 7 February 2009 (UTC)

== Release notes ==

This section describes new features and known issues with the current release of the Map API. See also [http://blog.secondlife.com/2009/01/22/improvements-to-mapping-and-upgrade-to-slurlcom/ Philip Linden's blog post announcement].

The current release of the Map API was released on Jan 15, 2009.

=== New features ===

This release of the Map API provides significant performance improvements over the previous release, including:
* Map loads faster and operates more smoothly.
* Map images are updated more accurately and rapidly. Changes to the Second Life Grid or content will now be visible within about two days.
* Map images look smoother and are more accurate when compared to the actual in-world content.

Changes in functionality:
* You can now single-click on any location on the map and teleport directly there.
* Zoom levels go up to eight, so you can now zoom out and see how big SL has really become!
* More intuitive map tile image file naming convention.

The Map API now gets map tile images directly from [http://aws.amazon.com/s3/ Amazon S3], and the file naming convention will make it easier to develop other third party maps based on the tiles we are generating.

=== Known issues ===

These need to be confirmed.
--[[User:Rand Linden|Rand Linden]] 23:29, 6 February 2009 (UTC)

* Can't set Map object click and doubleclick handlers. They always have the default behavior.
* Method '''SLMap.clickMarker(marker)''' doesn't work.
* Marker options apparently not working:
** '''centerOnClick: true''' - This works, but does NOT work if you open a window onclicking the marker.
** '''autopanOnClick: false''' - Always autopans
** '''autopanPadding: n''' - No effect
* Setting a different marker image/icon for each zoom level doesn't work - always uses first icon.
* Window width option doesn't work.

'''Questions:'''
* Now that there are 8 zoom levels instead of 6, when you instantiate a Marker, do you use an array of images of size 8 instead of 6?
* Old docs said that Map object clickhandler and doubleclickhander have (x,y) passed to them. Is that true (or rather, will it be true when they work?)

Linden Lab Official:Map API

2009-02-08T00:12:46Z

James Linden: /* Release notes */

{{Help/Box|Update notice|<b>We've made improvements and changes to the Map API, effective January 15, 2009.<br>Some information here may be out of date as we update this wiki with the changes. Thanks for your patience.</b>}}

{{:API Portal/navigation}}
__TOC__

== Getting Started ==

The Second Life Map API is a set of Javascript objects and functions that enable you to embed Second Life maps onto your web pages. It is a purely client-side Javascript API. If needed, you can also [[#Accessing_map_images_directly|directly access]] the map images.

'''NOTE:'''
This API is still in beta. URLs and API signatures may change.

=== Map UI features ===

The Map API enables you to create web pages that have Google Maps functionality, using maps of Second Life, rather than Earth. In general, the default map interface looks as shown here.

[[Image:Map ui cropped.png|right]]

The main map display area shows the current map area. By default, the map provides the following features:

* Click and drag the mouse pointer to pan the map view up, down, left, and right. If desired, you can [[Map_API_Advanced_Examples#Disabling_and_enabling_dragging|disable this behavior]].
* Double-click to zoom in by one level (power of two) and display the teleport window.
* Click anywhere on the map to open a "teleport" window; see '''Teleport window''' below.
* Use the mouse wheel to zoom in and out. See [[#Zoom_levels|Zoom levels]] for more information about zoom levels.
* Use the zoom and pan controls at upper left to zoom the view in and out and to pan the view up, down, left, and right. If desired, you can easily [[Map_API_Advanced_Examples#Customizing_zoom_and_pan_controls|create your own custom zoom and pan controls]].
* Use the overview control to move the view around by clicking and dragging, or double-clicking. Close the overview control by clicking on the diagonal arrow at the very bottom right of the map. You can specify whether the map provides an overview control when you [[Map_API_Reference#MarkerOptions|create the map object]].

<br clear="all" />

'''Teleport window'''
[[Image:Teleport window.png|left]]
Clicking anywhere on the map opens a window, such as the one shown at left, indicating the point on which you clicked. Clicking on the teleport button in the window then starts the Second Life Viewer, automatically teleporting you to the window's location. This feature is implemented with the [[Map_API_Reference#Global_functions|gotoSLURL()]] global function.

<br clear="all" />

=== Using slurl.com and DirectSLurl ===

The website http://slurl.com uses the Map API to provide a mechanism to teleport directly to locations in Second Life from web pages.

For more information, see [[Using Second Life URLs (SLURLs)]].

=== Prerequisites ===

To use the Second Life Map API in a web page, you must first:

* [http://www.google.com/apis/maps/signup.html Sign up for a Google Maps API key]. This enables you to use the Google Maps API, which is required to use SLMAPI. See the [http://code.google.com/apis/maps/documentation/ Google Maps API documentation] for more information.
* Add the [[#Common_HTML_header|common header code]] at the beginning of each HTML file. This code loads the Google Maps and Webmap Javascript libraries, the Webmap cascading stylesheet (CSS), and some other basic code.

NOTE: In general, it is best to reference the Map API Javascript library and CSS files that are on http://slurl.com. Although you can download these files locally and modify them for your own use, if Linden Lab updates or changes these files, your applications will not get the benefit and may even stop working properly.

=== Common HTML header ===

To use the Map API, put the following lines at the beginning of each HTML page. This includes:
* Statements to load the required Second Life Map API and Google Maps Javascript libraries.
* Link to the Webmap cascading style sheet.
* Style declaration for the map div element. This defines the size and other layout attributes of the map display.

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}"
type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</pre>

Replace {GOOGLE MAPS KEY} with you Google Maps Key.

All the examples also require additional script statements in the HTML header.

'''Stylesheet'''

To use your own stylesheet, just include it AFTER the Webmap CSS, for example:

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<link rel="stylesheet" type="text/css" href="myStyleSheet.css" />

'''Body element'''

Use the following body element in your HTML document:

<body load="loadmap()" onunload="GUnload();">
...

The '''GUnload()''' function is a Google Maps API function that reduces memory leaks, particularly with Internet Explorer. For more information, see the [http://code.google.com/apis/maps/documentation/#Memory_Leaks Google Maps API documentation].

=== Browser compatibility ===
The Map API has been tested to work with the following browsers:
* Internet Explorer 6.0
* Internet Explorer 7.0
* Firefox 2.0 or greater
* Safari 2.0

Other browsers may work but little issues may appear. Unless otherwise noted, all features work in all supported browsers.

=== Comments and feedback ===

If you encounter problems or bugs or have feature requests, please email '''webmap@secondlife.com'''.

Happy coding from the Second Life Web team!

== Basic concepts ==

The Map API's fundamental class is [[Webmap_API_Reference#SLMap|SLMap]]. It is a Javascript object representing the map with a large number of methods, enabling you to zoom, pan the view, and so on.

Additionally, the API includes the following key classes:
* [[Webmap_API_Reference#Marker|Marker]] - represents an image to display at a specify (x,y) point on the map. You provide a set of images to display at each zoom level. Contains several event handlers and other properties. See [[#Map_with_a_marker|Map with a marker]] for a basic example.
* [[Webmap_API_Reference#MapWindow|Window]] - represents a captioned balloon pointing to a specified map location. See [[Webmap_API#Map_with_an_initial_open_window|Map with an initial open window]] for a basic example.
* [[Webmap_API_Reference#Img|Img]] and [[Webmap_API_Reference#Icon|Icon]] - represent an image to use for markers, controls, or in windows.

===About coordinates===

Map coordinates are based on the Second Life grid system for positioning regions.

[[Image:Webmap coords.jpg]]

As illustrated in the diagram above, the Map API maps the Second Life world to the upper right quadrant of the Google world map. A large scaling value
called slGridEdgeSizeInRegions (equal to 2<sup>20</sup> or 1,048,576) defines the largest region coordinate at the top and far right edge of the displayed area. This value creates a map area with room for one trillion sims.

The little blue square illustrates where the populated sims are in Second Life.

=== Zoom levels ===
There are eight zoom levels: one through eight, one being the closest and eight being the farthest. Each level zooms by a power of two. In other words, at zoom level five, each region is twice the width as it was at zoom level six.

== Basic Examples ==

=== Required image files ===

Some of the following examples use image files for markers. To run the examples with the code as shown, download the image files and save them in the same directory as the example HTML files. Alternatively, create the Img objects using the URLs listed in the table below that refer to the images stored on this wiki.

The following table lists the images used in the examples:

{| {{Prettytable}}
|-{{Hl2}}
! Image
! File name
! URL

|-
| [[Image:Yellow marker.gif]]
| b_map_yellow.gif
| <br>http://slurl.com/examples/b_map_yellow.gif

|-
| [[Image:Fountain.gif]]
| fountain.gif
| http://slurl.com/examples/fountain.gif

|-
| [[Image:Forsale.png]]
| forsale.png
| http://slurl.com/examples/forsale.png

|-
|[[Image:Forsale-shadow.png]]
| forsale-shadow.png
|http://slurl.com/examples/forsale-shadow.png
|}

=== Simple map ===

The first example is a map with basic panning and zooming capabilities. When you are done, it will look as shown here.

[[Image:MapAPI ex1.png|thumb|right|Simple map]]

You can pan the map and zoom in and out.

To create this example, follow these steps:

# Add common HTML header code.
# Add HTML body element.
# Add '''loadmap()''' function.
# Save and test.

<br clear="all"/>

'''1. Add common HTML header'''

First, include the [[Webmap_API#Common_HTML_header|common header code]], required by all Webmap applications.

<pre><nowiki>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</head>
</nowiki></pre>

Be sure to replace {GOOGLE MAPS KEY} with your Google Map key.

'''2. Add HTML body element'''

Next, add the HTML body element to contain your map. The body contains a Javascript onload event handler that calls the '''loadmap()''' function you will define in the next step.

<pre>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

The div element is passed to the SLMap object constructor, using the <code>document.getElementById('map-container')</code> DOM method call.

NOTE: If you want the position attribute of the div element to be absolute, either set it programmatically using Javascript or using the style attribute tag. Setting the position attribute of this element in the CSS stylesheet will not work.

'''3. Add loadmap() function'''

The body element you just added has a Javascript event handler for the "onload" event, called when the browser initially loads the page. You deifined this to call a '''loadmap()''' function. Now, define that Javascript function in the head of your page (after the code that is already there), as follows:

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);
}
</script>

The first line defines a new Map object from the HTML div element. The second line centers the map at a specific point, and zooms it to zoom level three.

'''4. Save and test'''

When you are done, save the file, and then load it into your web browser. Try panning the map by clicking and dragging the mouse cursor; you can also pan by clicking on the arrow icons on the four sides. Also try zooming the view in and out by clicking the "+" and "-" icons.

'''Complete source code'''

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key=[GOOGLE MAPS KEY]" type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);
}
</script>

</head>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker ===

[[Image:Map with Marker.png|thumb|right|Map with a marker]]

A ''marker'' is simply an image displayed at a specific location on the map. The Map API enables you to define an image for each zoom level, so the marker can appear differently at each zoom level if you wish.

This example shows how to make a map with a marker. The code is the same as the first example, with with addition of some Javascript after the initialization of the map in the page's onload event handler function, '''loadmap()'''.

To use the code below verbatim, you must download the marker image as described in [[#Required_image_files|Required image files]]; you can also use the URL of the wiki image if you prefer.

The code first creates the icon for the marker, then places it on the map at (997, 1002) at the welcome area fountain. Because the same icon is specified for every zoom level, it appears the same size regardless of zoom level.

<br clear="all"/>
<pre>
// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
</pre>

In this example, clicking on the marker does nothing. Subsequent examples illustrate adding some onClick behavior.

'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// creates the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);

// creates the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// creates the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>There should be a yellow marker in the center of this map:
<div id="map-container"></div>
</body>
</pre>

=== Map with an initial open window ===

[[Image:Map_with_window.png|thumb|right|Map with a window]]

A Webmap ''window'' is a caption pointing to a specific point on the map, as shown in the screenshot at right. It looks something like a comic book dialog bubble.

Use the [[Webmap_API_Reference#MapWindow|MapWindow]] object to create a window.
For example, to create a window that opens initially when the page loads:
# Instantiate a [[Webmap_API_Reference#MapWindow|MapWindow]] object with the desired caption.
# Call the '''addMapWindow()''' method on the [[Webmap_API_Reference#SLMap|SLMap]] object to add the window to the map.
<br clear="all"/>
For example:

<pre>
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
</pre>

The code adds an open window to the map positioned again at (997, 1002), right above the welcome area fountain.

NOTE: after the user closes the window there is no way to bring it back. A subsequent example will show how to enable the user to reopen the window, by using markers with windows.
<br clear="all"/>

To make the map initially centered on the fountain, change the call to '''centerAndZoomAtSLCoord()''' as follows:

mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

'''Source code'''

This example shows how to create a map with a window. The code is the same as the first example, with the addition of some lines of Javascript after the initialization of the map, in the '''loadmap()''' function. In addition, the map is centered in a different location in order to make the window fully visible.

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

// Create window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<h1>Simple Map Example</h1>
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker that opens a window ===

[[Image:Map with marker and window.png|thumb|right|Map with marker that opens a window]]

This example shows how to create a map with a marker which opens a window when clicked. It is a combination of the previous two examples, because the code first creates a marker and a window.

The difference comes in adding the marker to the map: this time you provide the window object as well as the marker object in the call to '''addMarker()''':

mapInstance.addMarker(marker, mapWindow);

Doing this adds the marker and causes it to open the specified window when the user clicks it. If the user subsequently closes the window, s/he can open it again by clicking on the marker.

<br clear="all" />
'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// Create the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997.5, 1001.5), 2);

// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));

// Create a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='fountain.gif'>");

// Adds the marker to the map
mapInstance.addMarker(marker, mapWindow);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>This map shows a yellow marker on the welcome fountain. When you click the marker,
a window appears with a screenshot of the fountain.</p>
<div id="map-container"></div>
</body>
</pre>

== Accessing map images directly ==

The Second Life map images are stored on [http://aws.amazon.com/s3/ Amazon Simple Storage Service (Amazon S3)]. You can access the map images directly on the Amazon S3 servers using the following URL format:

<nowiki>http://map.secondlife.com/Z/XXXXX/YYYYY/map-Z-X-Y-objects.jpg</nowiki>

Note: Starting the week of February 9, 2009 tiles will be switching to newer, simpler URLs:

<nowiki>http://map.secondlife.com/map-Z-X-Y-objects.jpg</nowiki>

Where:
* Z - Zoom level desired:
** One (1) is the most zoomed-in view, showing individual region tiles.
** Eight (8) is the maximum zoom level, showing the entire world.
* X,Y - X and Y coordinates on the Second Life Grid of the region, for example, region Ahern is (997,1002).
** In the "directory path" (not the file name), pad the coordinate values to five characters with leading zeros; so for the previous coordinates, the path would be "00997/01002".
** The padding requirement will go away the week of February 9, 2009. [[User:James Linden|James Linden]]

Tiles with zoom greater than one are stored at the lower left corner coordinate of the tiles that are included in the image.
In other words, you can find the zoom tile containing region (X,Y) for zoom level Z at the directory Z/X'/Y' where:

X' = X - (X % (2<sup>Z - 1</sup>) )

and

Y' = Y - (Y % (2<sup>Z - 1</sup>) )

Note that 2<sup>Z - 1</sup> is the number of regions encompassed by the width of a tile at resolution Z.

=== Examples ===

For example: if Z = 1, the four region tiles are:

* http://map.secondlife.com/1/01000/01000/map-1-1000-1000-objects.jpg
* http://map.secondlife.com/1/01001/01000/map-1-1001-1000-objects.jpg
* http://map.secondlife.com/1/01000/01001/map-1-1000-1001-objects.jpg
* http://map.secondlife.com/1/01001/01001/map-1-1001-1001-objects.jpg

These four region tiles are compressed into the single tile:

http://map.secondlife.com/2/01000/01000/map-2-1000-1000-objects.jpg

The following shows the map zoomed all the way out, showing the entire Second Life world view:
http://map.secondlife.com/8/01024/00896/map-8-1024-896-objects.jpg

The following displays a single tile contained in the view above, zoomed all the way in:
http://map.secondlife.com/1/01027/01019/map-1-1027-1019-objects.jpg

===Implementation notes===

The map generation process is more scalable than the previous release, and is able to image the entire Second Life grid of about 30,000 regions in less than two days.

There is a "decay period" for offline regions. If a region is disabled, the tile will stay up for several days (in case it comes back or something else has gone wrong) before the tile disappears. That several-day period will be longer than the time it takes to update existing regions or put new regions on the map.

=== Getting a map URL from LSL ===

The following LSL script illustrates how to display a map of the current region to an avatar:

<lsl>
ShowMap(key avatar) {
string url = "http://map.secondlife.com.s3.amazonaws.com/1/";
vector sim_coord = llGetRegionCorner();
string x = (string)((integer)(sim_coord.x / 256.0));
string y = (string)((integer)(sim_coord.y / 256.0));
string x0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(x)), STRING_TRIM_HEAD) + x;
string y0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(y)), STRING_TRIM_HEAD) + y;
url += x0 + "/" + y0 + "/" + "map-1-" + x + "-" + y + "-objects.jpg";
llLoadURL(avatar, "View the sim map", url);
}
</lsl>

Contributed under GPL v3 license by [[User:Henri Beauchamp|Henri Beauchamp]] 09:00, 24 January 2009 (UTC)

Starting the week of February 9, 2009, I recommend switching to this:

<lsl>
ShowMap(key avatar) {
string url = "http://map.secondlife.com/";
vector sim_coord = llGetRegionCorner();
string x = (string)((integer)(sim_coord.x / 256.0));
string y = (string)((integer)(sim_coord.y / 256.0));
url += "map-1-" + x + "-" + y + "-objects.jpg";
llLoadURL(avatar, "View the sim map", url);
}
</lsl>

[[User:James Linden|James Linden]] 20:51, 7 February 2009 (UTC)

== Release notes ==

This section describes new features and known issues with the current release of the Map API. See also [http://blog.secondlife.com/2009/01/22/improvements-to-mapping-and-upgrade-to-slurlcom/ Philip Linden's blog post announcement].

The current release of the Map API was released on Jan 15, 2009.

=== New features ===

This release of the Map API provides significant performance improvements over the previous release, including:
* Map loads faster and operates more smoothly.
* Map images are updated more accurately and rapidly. Changes to the Second Life Grid or content will now be visible within about two days.
* Map images look smoother and are more accurate when compared to the actual in-world content.

Changes in functionality:
* You can now single-click on any location on the map and teleport directly there.
* Zoom levels go up to eight, so you can now zoom out and see how big SL has really become!
* More intuitive map tile image file naming convention.

The Map API now gets map tile images directly from [http://aws.amazon.com/s3/ Amazon S3], and the file naming convention will make it easier to develop other third party maps based on the tiles we are generating.

=== Known issues ===

These need to be confirmed.
--[[User:Rand Linden|Rand Linden]] 23:29, 6 February 2009 (UTC)

* Can't set Map object click and doubleclick handlers. They always have the default behavior.
* Method '''SLMap.clickMarker(marker)''' doesn't work.
* Marker options apparently not working:
** '''centerOnClick: true''' - This works, but does NOT work if you open a window onclicking the marker.
** '''autopanOnClick: false''' - Always autopans
** '''autopanPadding: n''' - No effect
* Setting a different marker image/icon for each zoom level doesn't work - always uses first icon.
* Window width option doesn't work.

'''Questions:'''
* Now that there are 8 zoom levels instead of 6, when you instantiate a Marker, do you use an array of images of size 8 instead of 6?
* Old docs said that Map object clickhandler and doubleclickhander have (x,y) passed to them. Is that true (or rather, will it be true when they work?)

Linden Lab Official:Map API

2009-02-07T20:51:21Z

James Linden: Updated docs for new URL format we're switching to next week.

{{Help/Box|Update notice|<b>We've made improvements and changes to the Map API, effective January 15, 2009.<br>Some information here may be out of date as we update this wiki with the changes. Thanks for your patience.</b>}}

{{:API Portal/navigation}}
__TOC__

== Getting Started ==

The Second Life Map API is a set of Javascript objects and functions that enable you to embed Second Life maps onto your web pages. It is a purely client-side Javascript API. If needed, you can also [[#Accessing_map_images_directly|directly access]] the map images.

'''NOTE:'''
This API is still in beta. URLs and API signatures may change.

=== Map UI features ===

The Map API enables you to create web pages that have Google Maps functionality, using maps of Second Life, rather than Earth. In general, the default map interface looks as shown here.

[[Image:Map ui cropped.png|right]]

The main map display area shows the current map area. By default, the map provides the following features:

* Click and drag the mouse pointer to pan the map view up, down, left, and right. If desired, you can [[Map_API_Advanced_Examples#Disabling_and_enabling_dragging|disable this behavior]].
* Double-click to zoom in by one level (power of two) and display the teleport window.
* Click anywhere on the map to open a "teleport" window; see '''Teleport window''' below.
* Use the mouse wheel to zoom in and out. See [[#Zoom_levels|Zoom levels]] for more information about zoom levels.
* Use the zoom and pan controls at upper left to zoom the view in and out and to pan the view up, down, left, and right. If desired, you can easily [[Map_API_Advanced_Examples#Customizing_zoom_and_pan_controls|create your own custom zoom and pan controls]].
* Use the overview control to move the view around by clicking and dragging, or double-clicking. Close the overview control by clicking on the diagonal arrow at the very bottom right of the map. You can specify whether the map provides an overview control when you [[Map_API_Reference#MarkerOptions|create the map object]].

<br clear="all" />

'''Teleport window'''
[[Image:Teleport window.png|left]]
Clicking anywhere on the map opens a window, such as the one shown at left, indicating the point on which you clicked. Clicking on the teleport button in the window then starts the Second Life Viewer, automatically teleporting you to the window's location. This feature is implemented with the [[Map_API_Reference#Global_functions|gotoSLURL()]] global function.

<br clear="all" />

=== Using slurl.com and DirectSLurl ===

The website http://slurl.com uses the Map API to provide a mechanism to teleport directly to locations in Second Life from web pages.

For more information, see [[Using Second Life URLs (SLURLs)]].

=== Prerequisites ===

To use the Second Life Map API in a web page, you must first:

* [http://www.google.com/apis/maps/signup.html Sign up for a Google Maps API key]. This enables you to use the Google Maps API, which is required to use SLMAPI. See the [http://code.google.com/apis/maps/documentation/ Google Maps API documentation] for more information.
* Add the [[#Common_HTML_header|common header code]] at the beginning of each HTML file. This code loads the Google Maps and Webmap Javascript libraries, the Webmap cascading stylesheet (CSS), and some other basic code.

NOTE: In general, it is best to reference the Map API Javascript library and CSS files that are on http://slurl.com. Although you can download these files locally and modify them for your own use, if Linden Lab updates or changes these files, your applications will not get the benefit and may even stop working properly.

=== Common HTML header ===

To use the Map API, put the following lines at the beginning of each HTML page. This includes:
* Statements to load the required Second Life Map API and Google Maps Javascript libraries.
* Link to the Webmap cascading style sheet.
* Style declaration for the map div element. This defines the size and other layout attributes of the map display.

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}"
type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</pre>

Replace {GOOGLE MAPS KEY} with you Google Maps Key.

All the examples also require additional script statements in the HTML header.

'''Stylesheet'''

To use your own stylesheet, just include it AFTER the Webmap CSS, for example:

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<link rel="stylesheet" type="text/css" href="myStyleSheet.css" />

'''Body element'''

Use the following body element in your HTML document:

<body load="loadmap()" onunload="GUnload();">
...

The '''GUnload()''' function is a Google Maps API function that reduces memory leaks, particularly with Internet Explorer. For more information, see the [http://code.google.com/apis/maps/documentation/#Memory_Leaks Google Maps API documentation].

=== Browser compatibility ===
The Map API has been tested to work with the following browsers:
* Internet Explorer 6.0
* Internet Explorer 7.0
* Firefox 2.0 or greater
* Safari 2.0

Other browsers may work but little issues may appear. Unless otherwise noted, all features work in all supported browsers.

=== Comments and feedback ===

If you encounter problems or bugs or have feature requests, please email '''webmap@secondlife.com'''.

Happy coding from the Second Life Web team!

== Basic concepts ==

The Map API's fundamental class is [[Webmap_API_Reference#SLMap|SLMap]]. It is a Javascript object representing the map with a large number of methods, enabling you to zoom, pan the view, and so on.

Additionally, the API includes the following key classes:
* [[Webmap_API_Reference#Marker|Marker]] - represents an image to display at a specify (x,y) point on the map. You provide a set of images to display at each zoom level. Contains several event handlers and other properties. See [[#Map_with_a_marker|Map with a marker]] for a basic example.
* [[Webmap_API_Reference#MapWindow|Window]] - represents a captioned balloon pointing to a specified map location. See [[Webmap_API#Map_with_an_initial_open_window|Map with an initial open window]] for a basic example.
* [[Webmap_API_Reference#Img|Img]] and [[Webmap_API_Reference#Icon|Icon]] - represent an image to use for markers, controls, or in windows.

===About coordinates===

Map coordinates are based on the Second Life grid system for positioning regions.

[[Image:Webmap coords.jpg]]

As illustrated in the diagram above, the Map API maps the Second Life world to the upper right quadrant of the Google world map. A large scaling value
called slGridEdgeSizeInRegions (equal to 2<sup>20</sup> or 1,048,576) defines the largest region coordinate at the top and far right edge of the displayed area. This value creates a map area with room for one trillion sims.

The little blue square illustrates where the populated sims are in Second Life.

=== Zoom levels ===
There are eight zoom levels: one through eight, one being the closest and eight being the farthest. Each level zooms by a power of two. In other words, at zoom level five, each region is twice the width as it was at zoom level six.

== Basic Examples ==

=== Required image files ===

Some of the following examples use image files for markers. To run the examples with the code as shown, download the image files and save them in the same directory as the example HTML files. Alternatively, create the Img objects using the URLs listed in the table below that refer to the images stored on this wiki.

The following table lists the images used in the examples:

{| {{Prettytable}}
|-{{Hl2}}
! Image
! File name
! URL

|-
| [[Image:Yellow marker.gif]]
| b_map_yellow.gif
| <br>http://slurl.com/examples/b_map_yellow.gif

|-
| [[Image:Fountain.gif]]
| fountain.gif
| http://slurl.com/examples/fountain.gif

|-
| [[Image:Forsale.png]]
| forsale.png
| http://slurl.com/examples/forsale.png

|-
|[[Image:Forsale-shadow.png]]
| forsale-shadow.png
|http://slurl.com/examples/forsale-shadow.png
|}

=== Simple map ===

The first example is a map with basic panning and zooming capabilities. When you are done, it will look as shown here.

[[Image:MapAPI ex1.png|thumb|right|Simple map]]

You can pan the map and zoom in and out.

To create this example, follow these steps:

# Add common HTML header code.
# Add HTML body element.
# Add '''loadmap()''' function.
# Save and test.

<br clear="all"/>

'''1. Add common HTML header'''

First, include the [[Webmap_API#Common_HTML_header|common header code]], required by all Webmap applications.

<pre><nowiki>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</head>
</nowiki></pre>

Be sure to replace {GOOGLE MAPS KEY} with your Google Map key.

'''2. Add HTML body element'''

Next, add the HTML body element to contain your map. The body contains a Javascript onload event handler that calls the '''loadmap()''' function you will define in the next step.

<pre>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

The div element is passed to the SLMap object constructor, using the <code>document.getElementById('map-container')</code> DOM method call.

NOTE: If you want the position attribute of the div element to be absolute, either set it programmatically using Javascript or using the style attribute tag. Setting the position attribute of this element in the CSS stylesheet will not work.

'''3. Add loadmap() function'''

The body element you just added has a Javascript event handler for the "onload" event, called when the browser initially loads the page. You deifined this to call a '''loadmap()''' function. Now, define that Javascript function in the head of your page (after the code that is already there), as follows:

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);
}
</script>

The first line defines a new Map object from the HTML div element. The second line centers the map at a specific point, and zooms it to zoom level three.

'''4. Save and test'''

When you are done, save the file, and then load it into your web browser. Try panning the map by clicking and dragging the mouse cursor; you can also pan by clicking on the arrow icons on the four sides. Also try zooming the view in and out by clicking the "+" and "-" icons.

'''Complete source code'''

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key=[GOOGLE MAPS KEY]" type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);
}
</script>

</head>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker ===

[[Image:Map with Marker.png|thumb|right|Map with a marker]]

A ''marker'' is simply an image displayed at a specific location on the map. The Map API enables you to define an image for each zoom level, so the marker can appear differently at each zoom level if you wish.

This example shows how to make a map with a marker. The code is the same as the first example, with with addition of some Javascript after the initialization of the map in the page's onload event handler function, '''loadmap()'''.

To use the code below verbatim, you must download the marker image as described in [[#Required_image_files|Required image files]]; you can also use the URL of the wiki image if you prefer.

The code first creates the icon for the marker, then places it on the map at (997, 1002) at the welcome area fountain. Because the same icon is specified for every zoom level, it appears the same size regardless of zoom level.

<br clear="all"/>
<pre>
// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
</pre>

In this example, clicking on the marker does nothing. Subsequent examples illustrate adding some onClick behavior.

'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// creates the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);

// creates the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// creates the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>There should be a yellow marker in the center of this map:
<div id="map-container"></div>
</body>
</pre>

=== Map with an initial open window ===

[[Image:Map_with_window.png|thumb|right|Map with a window]]

A Webmap ''window'' is a caption pointing to a specific point on the map, as shown in the screenshot at right. It looks something like a comic book dialog bubble.

Use the [[Webmap_API_Reference#MapWindow|MapWindow]] object to create a window.
For example, to create a window that opens initially when the page loads:
# Instantiate a [[Webmap_API_Reference#MapWindow|MapWindow]] object with the desired caption.
# Call the '''addMapWindow()''' method on the [[Webmap_API_Reference#SLMap|SLMap]] object to add the window to the map.
<br clear="all"/>
For example:

<pre>
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
</pre>

The code adds an open window to the map positioned again at (997, 1002), right above the welcome area fountain.

NOTE: after the user closes the window there is no way to bring it back. A subsequent example will show how to enable the user to reopen the window, by using markers with windows.
<br clear="all"/>

To make the map initially centered on the fountain, change the call to '''centerAndZoomAtSLCoord()''' as follows:

mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

'''Source code'''

This example shows how to create a map with a window. The code is the same as the first example, with the addition of some lines of Javascript after the initialization of the map, in the '''loadmap()''' function. In addition, the map is centered in a different location in order to make the window fully visible.

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

// Create window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<h1>Simple Map Example</h1>
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker that opens a window ===

[[Image:Map with marker and window.png|thumb|right|Map with marker that opens a window]]

This example shows how to create a map with a marker which opens a window when clicked. It is a combination of the previous two examples, because the code first creates a marker and a window.

The difference comes in adding the marker to the map: this time you provide the window object as well as the marker object in the call to '''addMarker()''':

mapInstance.addMarker(marker, mapWindow);

Doing this adds the marker and causes it to open the specified window when the user clicks it. If the user subsequently closes the window, s/he can open it again by clicking on the marker.

<br clear="all" />
'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// Create the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997.5, 1001.5), 2);

// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));

// Create a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='fountain.gif'>");

// Adds the marker to the map
mapInstance.addMarker(marker, mapWindow);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>This map shows a yellow marker on the welcome fountain. When you click the marker,
a window appears with a screenshot of the fountain.</p>
<div id="map-container"></div>
</body>
</pre>

== Accessing map images directly ==

The Second Life map images are stored on [http://aws.amazon.com/s3/ Amazon Simple Storage Service (Amazon S3)]. You can access the map images directly on the Amazon S3 servers using the following URL format:

<nowiki>http://map.secondlife.com/Z/XXXXX/YYYYY/map-Z-X-Y-objects.jpg</nowiki>

Note: Starting the week of February 9, 2009 tiles will be switching to newer, simpler URLs:

<nowiki>http://map.secondlife.com/map-Z-X-Y-objects.jpg</nowiki>

Where:
* Z - Zoom level desired:
** One (1) is the most zoomed-in view, showing individual region tiles.
** Eight (8) is the maximum zoom level, showing the entire world.
* X,Y - X and Y coordinates on the Second Life Grid of the region, for example, region Ahern is (997,1002).
** In the "directory path" (not the file name), pad the coordinate values to five characters with leading zeros; so for the previous coordinates, the path would be "00997/01002".
** The padding requirement will go away the week of February 9, 2009. [[User:James Linden|James Linden]]

Tiles with zoom greater than one are stored at the lower left corner coordinate of the tiles that are included in the image.
In other words, you can find the zoom tile containing region (X,Y) for zoom level Z at the directory Z/X'/Y' where:

X' = X - (X % (2<sup>Z - 1</sup>) )

and

Y' = Y - (Y % (2<sup>Z - 1</sup>) )

Note that 2<sup>Z - 1</sup> is the number of regions encompassed by the width of a tile at resolution Z.

=== Examples ===

For example: if Z = 1, the four region tiles are:

* http://map.secondlife.com/1/01000/01000/map-1-1000-1000-objects.jpg
* http://map.secondlife.com/1/01001/01000/map-1-1001-1000-objects.jpg
* http://map.secondlife.com/1/01000/01001/map-1-1000-1001-objects.jpg
* http://map.secondlife.com/1/01001/01001/map-1-1001-1001-objects.jpg

These four region tiles are compressed into the single tile:

http://map.secondlife.com/2/01000/01000/map-2-1000-1000-objects.jpg

The following shows the map zoomed all the way out, showing the entire Second Life world view:
http://map.secondlife.com/8/01024/00896/map-8-1024-896-objects.jpg

The following displays a single tile contained in the view above, zoomed all the way in:
http://map.secondlife.com/1/01027/01019/map-1-1027-1019-objects.jpg

===Implementation notes===

The map generation process is more scalable than the previous release, and is able to image the entire Second Life grid of about 30,000 regions in less than two days.

There is a "decay period" for offline regions. If a region is disabled, the tile will stay up for several days (in case it comes back or something else has gone wrong) before the tile disappears. That several-day period will be longer than the time it takes to update existing regions or put new regions on the map.

=== Getting a map URL from LSL ===

The following LSL script illustrates how to display a map of the current region to an avatar:

<lsl>
ShowMap(key avatar) {
string url = "http://map.secondlife.com.s3.amazonaws.com/1/";
vector sim_coord = llGetRegionCorner();
string x = (string)((integer)(sim_coord.x / 256.0));
string y = (string)((integer)(sim_coord.y / 256.0));
string x0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(x)), STRING_TRIM_HEAD) + x;
string y0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(y)), STRING_TRIM_HEAD) + y;
url += x0 + "/" + y0 + "/" + "map-1-" + x + "-" + y + "-objects.jpg";
llLoadURL(avatar, "View the sim map", url);
}
</lsl>

Contributed under GPL v3 license by [[User:Henri Beauchamp|Henri Beauchamp]] 09:00, 24 January 2009 (UTC)

Starting the week of February 9, 2009, I recommend switching to this:

<lsl>
ShowMap(key avatar) {
string url = "http://map.secondlife.com/";
vector sim_coord = llGetRegionCorner();
string x = (string)((integer)(sim_coord.x / 256.0));
string y = (string)((integer)(sim_coord.y / 256.0));
url += "map-1-" + x + "-" + y + "-objects.jpg";
llLoadURL(avatar, "View the sim map", url);
}
</lsl>

[[User:James Linden|James Linden]] 20:51, 7 February 2009 (UTC)

== Release notes ==

This section describes new features and known issues with the current release of the Map API. See also [http://blog.secondlife.com/2009/01/22/improvements-to-mapping-and-upgrade-to-slurlcom/ Philip Linden's blog post announcement].

The current release of the Map API was release on Jan 15, 2009.

=== New features ===

This release of the Map API provides significant performance improvements over the previous release, including:
* Map loads faster and operates more smoothly.
* Map images are updated more accurately and rapidly. Changes to the Second Life Grid or content will now be visible within about two days.
* Map images look smoother and are more accurate when compared to the actual in-world content.

Changes in functionality:
* You can now single-click on any location on the map and teleport directly there.
* Zoom levels go up to eight, so you can now zoom out and see how big SL has really become!
* More intuitive map tile image file naming convention.

The Map API now gets map tile images directly from [http://aws.amazon.com/s3/ Amazon S3], and the file naming convention will make it easier to develop other third party maps based on the tiles we are generating.

=== Known issues ===

These need to be confirmed.
--[[User:Rand Linden|Rand Linden]] 23:29, 6 February 2009 (UTC)

* Can't set Map object click and doubleclick handlers. They always have the default behavior.
* Method '''SLMap.clickMarker(marker)''' doesn't work.
* Marker options apparently not working:
** '''centerOnClick: true''' - This works, but does NOT work if you open a window onclicking the marker.
** '''autopanOnClick: false''' - Always autopans
** '''autopanPadding: n''' - No effect
* Setting a different marker image/icon for each zoom level doesn't work - always uses first icon.
* Window width option doesn't work.

'''Questions:'''
* Now that there are 8 zoom levels instead of 6, when you instantiate a Marker, do you use an array of images of size 8 instead of 6?
* Old docs said that Map object clickhandler and doubleclickhander have (x,y) passed to them. Is that true (or rather, will it be true when they work?)

Linden Lab Official:Map API

2009-02-07T20:47:48Z

James Linden: Bumping browser compatibility to FF 2 and up. We haven't tested with FF1 for a long time.

{{Help/Box|Update notice|<b>We've made improvements and changes to the Map API, effective January 15, 2009.<br>Some information here may be out of date as we update this wiki with the changes. Thanks for your patience.</b>}}

{{:API Portal/navigation}}
__TOC__

== Getting Started ==

The Second Life Map API is a set of Javascript objects and functions that enable you to embed Second Life maps onto your web pages. It is a purely client-side Javascript API. If needed, you can also [[#Accessing_map_images_directly|directly access]] the map images.

'''NOTE:'''
This API is still in beta. URLs and API signatures may change.

=== Map UI features ===

The Map API enables you to create web pages that have Google Maps functionality, using maps of Second Life, rather than Earth. In general, the default map interface looks as shown here.

[[Image:Map ui cropped.png|right]]

The main map display area shows the current map area. By default, the map provides the following features:

* Click and drag the mouse pointer to pan the map view up, down, left, and right. If desired, you can [[Map_API_Advanced_Examples#Disabling_and_enabling_dragging|disable this behavior]].
* Double-click to zoom in by one level (power of two) and display the teleport window.
* Click anywhere on the map to open a "teleport" window; see '''Teleport window''' below.
* Use the mouse wheel to zoom in and out. See [[#Zoom_levels|Zoom levels]] for more information about zoom levels.
* Use the zoom and pan controls at upper left to zoom the view in and out and to pan the view up, down, left, and right. If desired, you can easily [[Map_API_Advanced_Examples#Customizing_zoom_and_pan_controls|create your own custom zoom and pan controls]].
* Use the overview control to move the view around by clicking and dragging, or double-clicking. Close the overview control by clicking on the diagonal arrow at the very bottom right of the map. You can specify whether the map provides an overview control when you [[Map_API_Reference#MarkerOptions|create the map object]].

<br clear="all" />

'''Teleport window'''
[[Image:Teleport window.png|left]]
Clicking anywhere on the map opens a window, such as the one shown at left, indicating the point on which you clicked. Clicking on the teleport button in the window then starts the Second Life Viewer, automatically teleporting you to the window's location. This feature is implemented with the [[Map_API_Reference#Global_functions|gotoSLURL()]] global function.

<br clear="all" />

=== Using slurl.com and DirectSLurl ===

The website http://slurl.com uses the Map API to provide a mechanism to teleport directly to locations in Second Life from web pages.

For more information, see [[Using Second Life URLs (SLURLs)]].

=== Prerequisites ===

To use the Second Life Map API in a web page, you must first:

* [http://www.google.com/apis/maps/signup.html Sign up for a Google Maps API key]. This enables you to use the Google Maps API, which is required to use SLMAPI. See the [http://code.google.com/apis/maps/documentation/ Google Maps API documentation] for more information.
* Add the [[#Common_HTML_header|common header code]] at the beginning of each HTML file. This code loads the Google Maps and Webmap Javascript libraries, the Webmap cascading stylesheet (CSS), and some other basic code.

NOTE: In general, it is best to reference the Map API Javascript library and CSS files that are on http://slurl.com. Although you can download these files locally and modify them for your own use, if Linden Lab updates or changes these files, your applications will not get the benefit and may even stop working properly.

=== Common HTML header ===

To use the Map API, put the following lines at the beginning of each HTML page. This includes:
* Statements to load the required Second Life Map API and Google Maps Javascript libraries.
* Link to the Webmap cascading style sheet.
* Style declaration for the map div element. This defines the size and other layout attributes of the map display.

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}"
type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</pre>

Replace {GOOGLE MAPS KEY} with you Google Maps Key.

All the examples also require additional script statements in the HTML header.

'''Stylesheet'''

To use your own stylesheet, just include it AFTER the Webmap CSS, for example:

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<link rel="stylesheet" type="text/css" href="myStyleSheet.css" />

'''Body element'''

Use the following body element in your HTML document:

<body load="loadmap()" onunload="GUnload();">
...

The '''GUnload()''' function is a Google Maps API function that reduces memory leaks, particularly with Internet Explorer. For more information, see the [http://code.google.com/apis/maps/documentation/#Memory_Leaks Google Maps API documentation].

=== Browser compatibility ===
The Map API has been tested to work with the following browsers:
* Internet Explorer 6.0
* Internet Explorer 7.0
* Firefox 2.0 or greater
* Safari 2.0

Other browsers may work but little issues may appear. Unless otherwise noted, all features work in all supported browsers.

=== Comments and feedback ===

If you encounter problems or bugs or have feature requests, please email '''webmap@secondlife.com'''.

Happy coding from the Second Life Web team!

== Basic concepts ==

The Map API's fundamental class is [[Webmap_API_Reference#SLMap|SLMap]]. It is a Javascript object representing the map with a large number of methods, enabling you to zoom, pan the view, and so on.

Additionally, the API includes the following key classes:
* [[Webmap_API_Reference#Marker|Marker]] - represents an image to display at a specify (x,y) point on the map. You provide a set of images to display at each zoom level. Contains several event handlers and other properties. See [[#Map_with_a_marker|Map with a marker]] for a basic example.
* [[Webmap_API_Reference#MapWindow|Window]] - represents a captioned balloon pointing to a specified map location. See [[Webmap_API#Map_with_an_initial_open_window|Map with an initial open window]] for a basic example.
* [[Webmap_API_Reference#Img|Img]] and [[Webmap_API_Reference#Icon|Icon]] - represent an image to use for markers, controls, or in windows.

===About coordinates===

Map coordinates are based on the Second Life grid system for positioning regions.

[[Image:Webmap coords.jpg]]

As illustrated in the diagram above, the Map API maps the Second Life world to the upper right quadrant of the Google world map. A large scaling value
called slGridEdgeSizeInRegions (equal to 2<sup>20</sup> or 1,048,576) defines the largest region coordinate at the top and far right edge of the displayed area. This value creates a map area with room for one trillion sims.

The little blue square illustrates where the populated sims are in Second Life.

=== Zoom levels ===
There are eight zoom levels: one through eight, one being the closest and eight being the farthest. Each level zooms by a power of two. In other words, at zoom level five, each region is twice the width as it was at zoom level six.

== Basic Examples ==

=== Required image files ===

Some of the following examples use image files for markers. To run the examples with the code as shown, download the image files and save them in the same directory as the example HTML files. Alternatively, create the Img objects using the URLs listed in the table below that refer to the images stored on this wiki.

The following table lists the images used in the examples:

{| {{Prettytable}}
|-{{Hl2}}
! Image
! File name
! URL

|-
| [[Image:Yellow marker.gif]]
| b_map_yellow.gif
| <br>http://slurl.com/examples/b_map_yellow.gif

|-
| [[Image:Fountain.gif]]
| fountain.gif
| http://slurl.com/examples/fountain.gif

|-
| [[Image:Forsale.png]]
| forsale.png
| http://slurl.com/examples/forsale.png

|-
|[[Image:Forsale-shadow.png]]
| forsale-shadow.png
|http://slurl.com/examples/forsale-shadow.png
|}

=== Simple map ===

The first example is a map with basic panning and zooming capabilities. When you are done, it will look as shown here.

[[Image:MapAPI ex1.png|thumb|right|Simple map]]

You can pan the map and zoom in and out.

To create this example, follow these steps:

# Add common HTML header code.
# Add HTML body element.
# Add '''loadmap()''' function.
# Save and test.

<br clear="all"/>

'''1. Add common HTML header'''

First, include the [[Webmap_API#Common_HTML_header|common header code]], required by all Webmap applications.

<pre><nowiki>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</head>
</nowiki></pre>

Be sure to replace {GOOGLE MAPS KEY} with your Google Map key.

'''2. Add HTML body element'''

Next, add the HTML body element to contain your map. The body contains a Javascript onload event handler that calls the '''loadmap()''' function you will define in the next step.

<pre>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

The div element is passed to the SLMap object constructor, using the <code>document.getElementById('map-container')</code> DOM method call.

NOTE: If you want the position attribute of the div element to be absolute, either set it programmatically using Javascript or using the style attribute tag. Setting the position attribute of this element in the CSS stylesheet will not work.

'''3. Add loadmap() function'''

The body element you just added has a Javascript event handler for the "onload" event, called when the browser initially loads the page. You deifined this to call a '''loadmap()''' function. Now, define that Javascript function in the head of your page (after the code that is already there), as follows:

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);
}
</script>

The first line defines a new Map object from the HTML div element. The second line centers the map at a specific point, and zooms it to zoom level three.

'''4. Save and test'''

When you are done, save the file, and then load it into your web browser. Try panning the map by clicking and dragging the mouse cursor; you can also pan by clicking on the arrow icons on the four sides. Also try zooming the view in and out by clicking the "+" and "-" icons.

'''Complete source code'''

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key=[GOOGLE MAPS KEY]" type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);
}
</script>

</head>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker ===

[[Image:Map with Marker.png|thumb|right|Map with a marker]]

A ''marker'' is simply an image displayed at a specific location on the map. The Map API enables you to define an image for each zoom level, so the marker can appear differently at each zoom level if you wish.

This example shows how to make a map with a marker. The code is the same as the first example, with with addition of some Javascript after the initialization of the map in the page's onload event handler function, '''loadmap()'''.

To use the code below verbatim, you must download the marker image as described in [[#Required_image_files|Required image files]]; you can also use the URL of the wiki image if you prefer.

The code first creates the icon for the marker, then places it on the map at (997, 1002) at the welcome area fountain. Because the same icon is specified for every zoom level, it appears the same size regardless of zoom level.

<br clear="all"/>
<pre>
// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
</pre>

In this example, clicking on the marker does nothing. Subsequent examples illustrate adding some onClick behavior.

'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// creates the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);

// creates the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// creates the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>There should be a yellow marker in the center of this map:
<div id="map-container"></div>
</body>
</pre>

=== Map with an initial open window ===

[[Image:Map_with_window.png|thumb|right|Map with a window]]

A Webmap ''window'' is a caption pointing to a specific point on the map, as shown in the screenshot at right. It looks something like a comic book dialog bubble.

Use the [[Webmap_API_Reference#MapWindow|MapWindow]] object to create a window.
For example, to create a window that opens initially when the page loads:
# Instantiate a [[Webmap_API_Reference#MapWindow|MapWindow]] object with the desired caption.
# Call the '''addMapWindow()''' method on the [[Webmap_API_Reference#SLMap|SLMap]] object to add the window to the map.
<br clear="all"/>
For example:

<pre>
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
</pre>

The code adds an open window to the map positioned again at (997, 1002), right above the welcome area fountain.

NOTE: after the user closes the window there is no way to bring it back. A subsequent example will show how to enable the user to reopen the window, by using markers with windows.
<br clear="all"/>

To make the map initially centered on the fountain, change the call to '''centerAndZoomAtSLCoord()''' as follows:

mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

'''Source code'''

This example shows how to create a map with a window. The code is the same as the first example, with the addition of some lines of Javascript after the initialization of the map, in the '''loadmap()''' function. In addition, the map is centered in a different location in order to make the window fully visible.

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

// Create window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<h1>Simple Map Example</h1>
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker that opens a window ===

[[Image:Map with marker and window.png|thumb|right|Map with marker that opens a window]]

This example shows how to create a map with a marker which opens a window when clicked. It is a combination of the previous two examples, because the code first creates a marker and a window.

The difference comes in adding the marker to the map: this time you provide the window object as well as the marker object in the call to '''addMarker()''':

mapInstance.addMarker(marker, mapWindow);

Doing this adds the marker and causes it to open the specified window when the user clicks it. If the user subsequently closes the window, s/he can open it again by clicking on the marker.

<br clear="all" />
'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// Create the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997.5, 1001.5), 2);

// Create the icons
var yellow_dot_image = new Img("b_map_yellow.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));

// Create a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='fountain.gif'>");

// Adds the marker to the map
mapInstance.addMarker(marker, mapWindow);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>This map shows a yellow marker on the welcome fountain. When you click the marker,
a window appears with a screenshot of the fountain.</p>
<div id="map-container"></div>
</body>
</pre>

== Accessing map images directly ==

The Second Life map images are stored on [http://aws.amazon.com/s3/ Amazon Simple Storage Service (Amazon S3)]. You can access the map images directly on the Amazon S3 servers using the following URL format:

<nowiki>http://map.secondlife.com/Z/XXXXX/YYYYY/map-Z-X-Y-objects.jpg</nowiki>

Where:
* Z - Zoom level desired:
** One (1) is the most zoomed-in view, showing individual region tiles.
** Eight (8) is the maximum zoom level, showing the entire world.
* X,Y - X and Y coordinates on the Second Life Grid of the region, for example, region Ahern is (997,1002). In the "directory path" (not the file name), pad the coordinate values to five characters with leading zeros; so for the previous coordinates, the path would be "00997/01002".

Tiles with zoom greater than one are stored at the lower left corner coordinate of the tiles that are included in the image.
In other words, you can find the zoom tile containing region (X,Y) for zoom level Z at the directory Z/X'/Y' where:

X' = X - (X % (2<sup>Z - 1</sup>) )

and

Y' = Y - (Y % (2<sup>Z - 1</sup>) )

Note that 2<sup>Z - 1</sup> is the number of regions encompassed by the width of a tile at resolution Z.

=== Examples ===

For example: if Z = 1, the four region tiles are:

* http://map.secondlife.com/1/01000/01000/map-1-1000-1000-objects.jpg
* http://map.secondlife.com/1/01001/01000/map-1-1001-1000-objects.jpg
* http://map.secondlife.com/1/01000/01001/map-1-1000-1001-objects.jpg
* http://map.secondlife.com/1/01001/01001/map-1-1001-1001-objects.jpg

These four region tiles are compressed into the single tile:

http://map.secondlife.com/2/01000/01000/map-2-1000-1000-objects.jpg

The following shows the map zoomed all the way out, showing the entire Second Life world view:
http://map.secondlife.com/8/01024/00896/map-8-1024-896-objects.jpg

The following displays a single tile contained in the view above, zoomed all the way in:
http://map.secondlife.com/1/01027/01019/map-1-1027-1019-objects.jpg

===Implementation notes===

The map generation process is more scalable than the previous release, and is able to image the entire Second Life grid of about 30,000 regions in less than two days.

There is a "decay period" for offline regions. If a region is disabled, the tile will stay up for several days (in case it comes back or something else has gone wrong) before the tile disappears. That several-day period will be longer than the time it takes to update existing regions or put new regions on the map.

=== Getting a map URL from LSL ===

The following LSL script illustrates how to display a map of the current region to an avatar:

<lsl>
ShowMap(key avatar) {
string url = "http://map.secondlife.com.s3.amazonaws.com/1/";
vector sim_coord = llGetRegionCorner();
string x = (string)((integer)(sim_coord.x / 256.0));
string y = (string)((integer)(sim_coord.y / 256.0));
string x0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(x)), STRING_TRIM_HEAD) + x;
string y0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(y)), STRING_TRIM_HEAD) + y;
url += x0 + "/" + y0 + "/" + "map-1-" + x + "-" + y + "-objects.jpg";
llLoadURL(avatar, "View the sim map", url);
}
</lsl>

Contributed under GPL v3 license by [[User:Henri Beauchamp|Henri Beauchamp]] 09:00, 24 January 2009 (UTC)

== Release notes ==

This section describes new features and known issues with the current release of the Map API. See also [http://blog.secondlife.com/2009/01/22/improvements-to-mapping-and-upgrade-to-slurlcom/ Philip Linden's blog post announcement].

The current release of the Map API was release on Jan 15, 2009.

=== New features ===

This release of the Map API provides significant performance improvements over the previous release, including:
* Map loads faster and operates more smoothly.
* Map images are updated more accurately and rapidly. Changes to the Second Life Grid or content will now be visible within about two days.
* Map images look smoother and are more accurate when compared to the actual in-world content.

Changes in functionality:
* You can now single-click on any location on the map and teleport directly there.
* Zoom levels go up to eight, so you can now zoom out and see how big SL has really become!
* More intuitive map tile image file naming convention.

The Map API now gets map tile images directly from [http://aws.amazon.com/s3/ Amazon S3], and the file naming convention will make it easier to develop other third party maps based on the tiles we are generating.

=== Known issues ===

These need to be confirmed.
--[[User:Rand Linden|Rand Linden]] 23:29, 6 February 2009 (UTC)

* Can't set Map object click and doubleclick handlers. They always have the default behavior.
* Method '''SLMap.clickMarker(marker)''' doesn't work.
* Marker options apparently not working:
** '''centerOnClick: true''' - This works, but does NOT work if you open a window onclicking the marker.
** '''autopanOnClick: false''' - Always autopans
** '''autopanPadding: n''' - No effect
* Setting a different marker image/icon for each zoom level doesn't work - always uses first icon.
* Window width option doesn't work.

'''Questions:'''
* Now that there are 8 zoom levels instead of 6, when you instantiate a Marker, do you use an array of images of size 8 instead of 6?
* Old docs said that Map object clickhandler and doubleclickhander have (x,y) passed to them. Is that true (or rather, will it be true when they work?)

User:Rand Linden/Notes

2009-02-02T19:28:08Z

James Linden: /* Technical questions and issues: */

== Map API questions and issues ==

===Technical questions and issues:===
* I can't seem to set the Map object click and doubleclick handlers. They have the default behavior exhibited on slurl.com, but I'm supposed to be able to override or supplement that (which?). Also, is (x,y) passed to these event handlers?
* Now that there are 8 zoom levels instead of 6, when you instantiate a Marker, do you use an array of images of size 8 instead of 6?
* Had some problems with getCurrentZoomLevel() working at levels 7 and 8.
* I think someone needs to confirm that [[Webmap_API#Accessing_map_images_directly]] is correct. It's not clear to me, but it may be OK.
** The math section is correct. The example had a typo, which I fixed. [[User:James Linden|James Linden]]

===Other questions and issue: ===

* Thoughts about calling it "Map API" instead of "Webmap API"? Latter just seems awkward.
** Works for me. [[User:James Linden|James Linden]]
* Is the API still in beta? Are we going to put a version number on this, since the recent changes (e.g. 1.1?)
** I think we should number it, and use version 2.0 or 2.1 to match the underlying Google Map API version (which is 2). [[User:James Linden|James Linden]]
* Should we provide "Release Notes" listing new features and known bugs, etc?

User:Rand Linden/Notes

2009-02-02T19:27:38Z

James Linden: /* Other questions and issue: */

== Map API questions and issues ==

===Technical questions and issues:===
* I can't seem to set the Map object click and doubleclick handlers. They have the default behavior exhibited on slurl.com, but I'm supposed to be able to override or supplement that (which?). Also, is (x,y) passed to these event handlers?
* Now that there are 8 zoom levels instead of 6, when you instantiate a Marker, do you use an array of images of size 8 instead of 6?
* Had some problems with getCurrentZoomLevel() working at levels 7 and 8.
* I think someone needs to confirm that [[Webmap_API#Accessing_map_images_directly]] is correct. It's not clear to me, but it may be OK.

===Other questions and issue: ===

* Thoughts about calling it "Map API" instead of "Webmap API"? Latter just seems awkward.
** Works for me. [[User:James Linden|James Linden]]
* Is the API still in beta? Are we going to put a version number on this, since the recent changes (e.g. 1.1?)
** I think we should number it, and use version 2.0 or 2.1 to match the underlying Google Map API version (which is 2). [[User:James Linden|James Linden]]
* Should we provide "Release Notes" listing new features and known bugs, etc?

Linden Lab Official:Map API

2009-02-02T19:25:57Z

James Linden: Fix zoom level in example, use "map.secondlife.com" in URLs instead of including s3.amazonaws.com

{{Help/Box|Update notice|<b>We've made improvements and changes to the webmap, effective January 15, 2009.<br>Some information here may be out of date as we update this wiki with the changes. Thanks for your patience.</b>}}

{{:API Portal/navigation}}
__TOC__

== Getting Started ==

The Second Life Webmap API is a set of Javascript objects and functions that enable you to embed Second Life maps onto your web pages. It is a purely client-side Javascript API. If needed, you can also [[#Accessing_map_images_directly|directly access]] the webmap images.

'''NOTE:'''
This API is still in beta. URLs and API signatures may change.

=== Map UI Features ===

The Webmap API enables you to create web pages that have Google Maps functionality, using maps of Second Life, rather than Earth. In general, the default Webmap interface looks like the diagram at right.

[[Image:Map ui cropped.png|right]]

The main map display area shows the current map area. By default, the map provides the following features:

* Click anywhere on the map to open a "teleport" window that displays the name of the region where you clicked and a button you can click to launch Second Life and teleport to that location.
* Click and drag the mouse pointer to pan the map view up, down, left, and right. If desired, you can [[Webmap_API_Advanced_Examples#Disabling_and_enabling_dragging|disable this behavior]].
* Double-click to zoom in by one level (power of two) and display the teleport window.
* Use the mouse wheel to zoom in and out. See [[#Zoom_levels|Zoom levels]] for more information about zoom levels.
* Use the zoom and pan controls at upper left to zoom the view in and out and to pan the view up, down, left, and right. If desired, you can easily [[Webmap_API_Advanced_Examples#Customizing_zoom_and_pan_controls|create your own custom zoom and pan controls]].
* Use the overview control to move the view around by clicking and dragging, or double-clicking. Close the overview control by clicking on the diagonal arrow at the very bottom right of the map. You can specify whether the map provides an overview control when you [[Webmap_API_Reference#MarkerOptions|create the map object]].

<br clear="all" />

[[Image:Teleport window.png|left]]
When you click anywhere on the map, a teleport window opens, such as the one shown at left. Clicking on the teleport button in the window then starts the Second Life Viewer, automatically teleporting you to the window's location.
<br clear="all" />

=== Using slurl.com and DirectSLurl ===

The website http://slurl.com uses the Webmap API to provide a mechanism to teleport directly to locations in Second Life from web pages.

For more information, see [[Using Second Life URLs (SLURLs)]].

=== Prerequisites ===

To use the Second Life Webmap API in a web page, you must first:

* [http://www.google.com/apis/maps/signup.html Sign up for a Google Maps API key]. This enables you to use the Google Maps API, which is required to use SLMAPI. See the [http://code.google.com/apis/maps/documentation/ Google Maps API documentation] for more information.
* Add the [[#Common_HTML_header|common header code]] at the beginning of each HTML file. This code loads the Google Maps and Webmap Javascript libraries, the Webmap cascading stylesheet (CSS), and some other basic code.

NOTE: In general, it is best to reference the Webmap API Javascript library and CSS files that are on http://slurl.com. Although you can download these files locally and modify them for your own use, if Linden Lab updates or changes these files, your applications will not get the benefit and may even stop working properly.

=== Common HTML header ===

To use the Webmap API, put the following lines at the beginning of each HTML page. This includes:
* Statements to load the required Second Life Webmap API and Google Maps Javascript libraries.
* Link to the Webmap cascading style sheet.
* Style declaration for the map div element. This defines the size and other layout attributes of the map display.

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}"
type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</pre>

Replace {GOOGLE MAPS KEY} with you Google Maps Key.

All the examples also require additional script statements in the HTML header.

'''Stylesheet'''

To use your own stylesheet, just include it AFTER the Webmap CSS, for example:

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<link rel="stylesheet" type="text/css" href="myStyleSheet.css" />

'''Body element'''

Use the following body element in your HTML document:

<body load="loadmap()" onunload="GUnload();">
...

The '''GUnload()''' function is a Google Maps API function that reduces memory leaks, particularly with Internet Explorer. For more information, see the [http://code.google.com/apis/maps/documentation/#Memory_Leaks Google Maps API documentation].

=== Browser compatibility ===
The Webmap API has been tested to work with the following browsers:
* Internet Explorer 6.0
* Internet Explorer 7.0
* Firefox 1.0 or greater
* Safari 2.0

Other browsers may work but little issues may appear. Unless otherwise noted, all features work in all supported browsers.

=== Comments and feedback ===

If you encounter problems or bugs or have feature requests, please email '''webmap@secondlife.com'''.

Happy coding from the Second Life Web team!

== Basic concepts ==

The Webmap API's fundamental class is [[Webmap_API_Reference#SLMap|SLMap]]. It is a Javascript object representing the map with a large number of methods, enabling you to zoom, pan the view, and so on.

Additionally, the API includes the following key classes:
* [[Webmap_API_Reference#Marker|Marker]] - represents an image to display at a specify (x,y) point on the map. You provide a set of images to display at each zoom level. Contains several event handlers and other properties. See [[#Map_with_a_marker|Map with a marker]] for a basic example.
* [[Webmap_API_Reference#MapWindow|Window]] - represents a captioned balloon pointing to a specified map location. See [[Webmap_API#Map_with_an_initial_open_window|Map with an initial open window]] for a basic example.
* [[Webmap_API_Reference#Img|Img]] and [[Webmap_API_Reference#Icon|Icon]] - represent an image to use for markers, controls, or in windows.

===About coordinates===

Map coordinates are based on the Second Life grid system for positioning regions.

[[Image:Webmap coords.jpg]]

As illustrated in the diagram above, the Webmap API maps the Second Life world to the upper right quadrant of the Google world map. A large scaling value
called slGridEdgeSizeInRegions (equal to 2<sup>20</sup> or 1,048,576) defines the largest region coordinate at the top and far right edge of the displayed area. This value creates a map area with room for one trillion sims.

The little blue square illustrates where the populated sims are in Second Life.

=== Zoom levels ===
There are eight zoom levels: one through eight, one being the closest and eight being the farthest. Each level zooms by a power of two. In other words, at zoom level five, each region is twice the width as it was at zoom level six.

== Basic Examples ==

=== Required image files ===

Some of the following examples use image files for markers. To run the examples with the code as shown, download the image files and save them in the same directory as the example HTML files. Alternatively, create the Img objects using the URLs listed in the table below that refer to the images stored on this wiki.

The following table lists the images used in the examples:

{| {{Prettytable}}
|-{{Hl2}}
! Image
! File name
! URL

|-
| [[Image:Yellow marker.gif]]
| Yellow marker.gif
| https://wiki.secondlife.com/w/images/2/23/Yellow_marker.gif

|-
| [[Image:Fountain.gif]]
|Fountain.gif
| https://wiki.secondlife.com/w/images/6/60/Fountain.gif

|-
| [[Image:Forsale.png]]
| Forsale.png
| https://wiki.secondlife.com/wiki/Image:Forsale.png

|-
|[[Image:Forsale-shadow.png]]
|Forsale-shadow.png
|https://wiki.secondlife.com/w/images/d/d9/Forsale-shadow.png
|}

=== Simple map ===

The first example is a map with basic panning and zooming capabilities. When you are done, it will look as shown here.

[[Image:MapAPI ex1.png|thumb|right|Simple map]]

You can pan the map and zoom in and out.

To create this example, follow these steps:

# Add common HTML header code.
# Add HTML body element.
# Add '''loadmap()''' function.
# Save and test.

<br clear="all"/>

'''1. Add common HTML header'''

First, include the [[Webmap_API#Common_HTML_header|common header code]], required by all Webmap applications.

<pre><nowiki>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</head>
</nowiki></pre>

Be sure to replace {GOOGLE MAPS KEY} with your Google Map key.

'''2. Add HTML body element'''

Next, add the HTML body element to contain your map. The body contains a Javascript onload event handler that calls the '''loadmap()''' function you will define in the next step.

<pre>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

The div element is passed to the SLMap object constructor, using the <code>document.getElementById('map-container')</code> DOM method call.

NOTE: If you want the position attribute of the div element to be absolute, either set it programmatically using Javascript or using the style attribute tag. Setting the position attribute of this element in the CSS stylesheet will not work.

'''3. Add loadmap() function'''

The body element you just added has a Javascript event handler for the "onload" event, called when the browser initially loads the page. You deifined this to call a '''loadmap()''' function. Now, define that Javascript function in the head of your page (after the code that is already there), as follows:

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);
}
</script>

The first line defines a new Map object from the HTML div element. The second line centers the map at a specific point, and zooms it to zoom level three.

'''4. Save and test'''

When you are done, save the file, and then load it into your web browser. Try panning the map by clicking and dragging the mouse cursor; you can also pan by clicking on the arrow icons on the four sides. Also try zooming the view in and out by clicking the "+" and "-" icons.

'''Complete source code'''

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key=[GOOGLE MAPS KEY]" type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);
}
</script>

</head>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker ===

[[Image:Map with Marker.png|thumb|right|Map with a marker]]

A ''marker'' is simply an image displayed at a specific location on the map. The Webmap API enables you to define an image for each zoom level, so the marker can appear differently at each zoom level if you wish.

This example shows how to make a map with a marker. The code is the same as the first example, with with addition of some Javascript after the initialization of the map in the page's onload event handler function, '''loadmap()'''.

To use the code below verbatim, you must download the marker image as described in [[#Required_image_files|Required image files]]; you can also use the URL of the wiki image if you prefer.

The code first creates the icon for the marker, then places it on the map at (997, 1002) at the welcome area fountain. Because the same icon is specified for every zoom level, it appears the same size regardless of zoom level.

<br clear="all"/>
<pre>
// Create the icons
var yellow_dot_image = new Img("Yellow_marker.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
</pre>

In this example, clicking on the marker does nothing. Subsequent examples illustrate adding some onClick behavior.

'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// creates the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);

// creates the icons
var yellow_dot_image = new Img("Yellow_marker.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// creates the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>There should be a yellow marker in the center of this map:
<div id="map-container"></div>
</body>
</pre>

=== Map with an initial open window ===

[[Image:Map_with_window.png|thumb|right|Map with a window]]

A Webmap ''window'' is a caption pointing to a specific point on the map, as shown in the screenshot at right. It looks something like a comic book dialog bubble.

Use the [[Webmap_API_Reference#MapWindow|MapWindow]] object to create a window.
For example, to create a window that opens initially when the page loads:
# Instantiate a [[Webmap_API_Reference#MapWindow|MapWindow]] object with the desired caption.
# Call the '''addMapWindow()''' method on the [[Webmap_API_Reference#SLMap|SLMap]] object to add the window to the map.
<br clear="all"/>
For example:

<pre>
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
</pre>

The code adds an open window to the map positioned again at (997, 1002), right above the welcome area fountain.

NOTE: after the user closes the window there is no way to bring it back. A subsequent example will show how to enable the user to reopen the window, by using markers with windows.
<br clear="all"/>

To make the map initially centered on the fountain, change the call to '''centerAndZoomAtSLCoord()''' as follows:

mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

'''Source code'''

This example shows how to create a map with a window. The code is the same as the first example, with the addition of some lines of Javascript after the initialization of the map, in the '''loadmap()''' function. In addition, the map is centered in a different location in order to make the window fully visible.

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

// Create window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<h1>Simple Map Example</h1>
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker that opens a windows ===

[[Image:Map with marker and window.png|thumb|right|Map with marker that opens a window]]

This example shows how to create a map with a marker which opens a window when clicked. It is a combination of the previous two examples, because the code first creates a marker and a window.

The difference comes in adding the marker to the map: this time you provide the window object as well as the marker object in the call to '''addMarker()''':

mapInstance.addMarker(marker, mapWindow);

Doing this adds the marker and causes it to open the specified window when the user clicks it. If the user subsequently closes the window, s/he can open it again by clicking on the marker.

<br clear="all" />
'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// Create the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997.5, 1001.5), 2);

// Create the icons
var yellow_dot_image = new Img("Yellow_marker.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));

// Create a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='Fountain.gif'>");

// Adds the marker to the map
mapInstance.addMarker(marker, mapWindow);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>This map shows a yellow marker on the welcome fountain. When you click the marker,
a window appears with a screenshot of the fountain.</p>
<div id="map-container"></div>
</body>
</pre>

== Accessing map images directly ==

The Second Life map images are stored on [http://aws.amazon.com/s3/ Amazon Simple Storage Service (Amazon S3)]. You can access the map images directly on the Amazon S3 servers using the following URL format:

<nowiki>http://map.secondlife.com/Z/XXXXX/YYYYY/map-Z-X-Y-objects.jpg</nowiki>

Where:
* Z - Zoom level desired:
** One (1) is the most zoomed-in view, showing individual region tiles.
** Eight (8) is the maximum zoom level, showing the entire world.
* X,Y - X and Y coordinates on the Second Life Grid of the region, for example, region Ahern is (997,1002). In the "directory path" (not the file name), pad the coordinate values to five characters with leading zeros; so for the previous coordinates, the path would be "00997/01002".

Tiles with zoom greater than one are stored at the lower left corner coordinate of the tiles that are included in the image.
In other words, you can find the zoom tile containing region (X,Y) for zoom level Z at the directory Z/X'/Y' where:

X' = X - (X % (2<sup>Z - 1</sup>) )

and

Y' = Y - (Y % (2<sup>Z - 1</sup>) )

Note that 2<sup>Z - 1</sup> is the number of regions encompassed by the width of a tile at resolution Z.

=== Examples ===

For example: if Z = 1, the four region tiles are:

* http://map.secondlife.com/1/01000/01000/map-1-1000-1000-objects.jpg
* http://map.secondlife.com/1/01001/01000/map-1-1001-1000-objects.jpg
* http://map.secondlife.com/1/01000/01001/map-1-1000-1001-objects.jpg
* http://map.secondlife.com/1/01001/01001/map-1-1001-1001-objects.jpg

These four region tiles are compressed into the single tile:

http://map.secondlife.com/2/01000/01000/map-2-1000-1000-objects.jpg

The following shows the map zoomed all the way out, showing the entire Second Life world view:
http://map.secondlife.com/8/01024/00896/map-8-1024-896-objects.jpg

The following displays a single tile contained in the view above, zoomed all the way in:
http://map.secondlife.com/1/01027/01019/map-1-1027-1019-objects.jpg

=== Getting a map URL from LSL ===

The following LSL script illustrates how to display a map of the current region to an avatar:

<lsl>
ShowMap(key avatar) {
string url = "http://map.secondlife.com.s3.amazonaws.com/1/";
vector sim_coord = llGetRegionCorner();
string x = (string)((integer)(sim_coord.x / 256.0));
string y = (string)((integer)(sim_coord.y / 256.0));
string x0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(x)), STRING_TRIM_HEAD) + x;
string y0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(y)), STRING_TRIM_HEAD) + y;
url += x0 + "/" + y0 + "/" + "map-1-" + x + "-" + y + "-objects.jpg";
llLoadURL(avatar, "View the sim map", url);
}
</lsl>

Contributed under GPL v3 license by [[User:Henri Beauchamp|Henri Beauchamp]] 09:00, 24 January 2009 (UTC)

Linden Lab Official:Map API

2009-02-02T19:25:18Z

James Linden: /* Examples */

{{Help/Box|Update notice|<b>We've made improvements and changes to the webmap, effective January 15, 2009.<br>Some information here may be out of date as we update this wiki with the changes. Thanks for your patience.</b>}}

{{:API Portal/navigation}}
__TOC__

== Getting Started ==

The Second Life Webmap API is a set of Javascript objects and functions that enable you to embed Second Life maps onto your web pages. It is a purely client-side Javascript API. If needed, you can also [[#Accessing_map_images_directly|directly access]] the webmap images.

'''NOTE:'''
This API is still in beta. URLs and API signatures may change.

=== Map UI Features ===

The Webmap API enables you to create web pages that have Google Maps functionality, using maps of Second Life, rather than Earth. In general, the default Webmap interface looks like the diagram at right.

[[Image:Map ui cropped.png|right]]

The main map display area shows the current map area. By default, the map provides the following features:

* Click anywhere on the map to open a "teleport" window that displays the name of the region where you clicked and a button you can click to launch Second Life and teleport to that location.
* Click and drag the mouse pointer to pan the map view up, down, left, and right. If desired, you can [[Webmap_API_Advanced_Examples#Disabling_and_enabling_dragging|disable this behavior]].
* Double-click to zoom in by one level (power of two) and display the teleport window.
* Use the mouse wheel to zoom in and out. See [[#Zoom_levels|Zoom levels]] for more information about zoom levels.
* Use the zoom and pan controls at upper left to zoom the view in and out and to pan the view up, down, left, and right. If desired, you can easily [[Webmap_API_Advanced_Examples#Customizing_zoom_and_pan_controls|create your own custom zoom and pan controls]].
* Use the overview control to move the view around by clicking and dragging, or double-clicking. Close the overview control by clicking on the diagonal arrow at the very bottom right of the map. You can specify whether the map provides an overview control when you [[Webmap_API_Reference#MarkerOptions|create the map object]].

<br clear="all" />

[[Image:Teleport window.png|left]]
When you click anywhere on the map, a teleport window opens, such as the one shown at left. Clicking on the teleport button in the window then starts the Second Life Viewer, automatically teleporting you to the window's location.
<br clear="all" />

=== Using slurl.com and DirectSLurl ===

The website http://slurl.com uses the Webmap API to provide a mechanism to teleport directly to locations in Second Life from web pages.

For more information, see [[Using Second Life URLs (SLURLs)]].

=== Prerequisites ===

To use the Second Life Webmap API in a web page, you must first:

* [http://www.google.com/apis/maps/signup.html Sign up for a Google Maps API key]. This enables you to use the Google Maps API, which is required to use SLMAPI. See the [http://code.google.com/apis/maps/documentation/ Google Maps API documentation] for more information.
* Add the [[#Common_HTML_header|common header code]] at the beginning of each HTML file. This code loads the Google Maps and Webmap Javascript libraries, the Webmap cascading stylesheet (CSS), and some other basic code.

NOTE: In general, it is best to reference the Webmap API Javascript library and CSS files that are on http://slurl.com. Although you can download these files locally and modify them for your own use, if Linden Lab updates or changes these files, your applications will not get the benefit and may even stop working properly.

=== Common HTML header ===

To use the Webmap API, put the following lines at the beginning of each HTML page. This includes:
* Statements to load the required Second Life Webmap API and Google Maps Javascript libraries.
* Link to the Webmap cascading style sheet.
* Style declaration for the map div element. This defines the size and other layout attributes of the map display.

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}"
type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</pre>

Replace {GOOGLE MAPS KEY} with you Google Maps Key.

All the examples also require additional script statements in the HTML header.

'''Stylesheet'''

To use your own stylesheet, just include it AFTER the Webmap CSS, for example:

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<link rel="stylesheet" type="text/css" href="myStyleSheet.css" />

'''Body element'''

Use the following body element in your HTML document:

<body load="loadmap()" onunload="GUnload();">
...

The '''GUnload()''' function is a Google Maps API function that reduces memory leaks, particularly with Internet Explorer. For more information, see the [http://code.google.com/apis/maps/documentation/#Memory_Leaks Google Maps API documentation].

=== Browser compatibility ===
The Webmap API has been tested to work with the following browsers:
* Internet Explorer 6.0
* Internet Explorer 7.0
* Firefox 1.0 or greater
* Safari 2.0

Other browsers may work but little issues may appear. Unless otherwise noted, all features work in all supported browsers.

=== Comments and feedback ===

If you encounter problems or bugs or have feature requests, please email '''webmap@secondlife.com'''.

Happy coding from the Second Life Web team!

== Basic concepts ==

The Webmap API's fundamental class is [[Webmap_API_Reference#SLMap|SLMap]]. It is a Javascript object representing the map with a large number of methods, enabling you to zoom, pan the view, and so on.

Additionally, the API includes the following key classes:
* [[Webmap_API_Reference#Marker|Marker]] - represents an image to display at a specify (x,y) point on the map. You provide a set of images to display at each zoom level. Contains several event handlers and other properties. See [[#Map_with_a_marker|Map with a marker]] for a basic example.
* [[Webmap_API_Reference#MapWindow|Window]] - represents a captioned balloon pointing to a specified map location. See [[Webmap_API#Map_with_an_initial_open_window|Map with an initial open window]] for a basic example.
* [[Webmap_API_Reference#Img|Img]] and [[Webmap_API_Reference#Icon|Icon]] - represent an image to use for markers, controls, or in windows.

===About coordinates===

Map coordinates are based on the Second Life grid system for positioning regions.

[[Image:Webmap coords.jpg]]

As illustrated in the diagram above, the Webmap API maps the Second Life world to the upper right quadrant of the Google world map. A large scaling value
called slGridEdgeSizeInRegions (equal to 2<sup>20</sup> or 1,048,576) defines the largest region coordinate at the top and far right edge of the displayed area. This value creates a map area with room for one trillion sims.

The little blue square illustrates where the populated sims are in Second Life.

=== Zoom levels ===
There are eight zoom levels: one through eight, one being the closest and eight being the farthest. Each level zooms by a power of two. In other words, at zoom level five, each region is twice the width as it was at zoom level six.

== Basic Examples ==

=== Required image files ===

Some of the following examples use image files for markers. To run the examples with the code as shown, download the image files and save them in the same directory as the example HTML files. Alternatively, create the Img objects using the URLs listed in the table below that refer to the images stored on this wiki.

The following table lists the images used in the examples:

{| {{Prettytable}}
|-{{Hl2}}
! Image
! File name
! URL

|-
| [[Image:Yellow marker.gif]]
| Yellow marker.gif
| https://wiki.secondlife.com/w/images/2/23/Yellow_marker.gif

|-
| [[Image:Fountain.gif]]
|Fountain.gif
| https://wiki.secondlife.com/w/images/6/60/Fountain.gif

|-
| [[Image:Forsale.png]]
| Forsale.png
| https://wiki.secondlife.com/wiki/Image:Forsale.png

|-
|[[Image:Forsale-shadow.png]]
|Forsale-shadow.png
|https://wiki.secondlife.com/w/images/d/d9/Forsale-shadow.png
|}

=== Simple map ===

The first example is a map with basic panning and zooming capabilities. When you are done, it will look as shown here.

[[Image:MapAPI ex1.png|thumb|right|Simple map]]

You can pan the map and zoom in and out.

To create this example, follow these steps:

# Add common HTML header code.
# Add HTML body element.
# Add '''loadmap()''' function.
# Save and test.

<br clear="all"/>

'''1. Add common HTML header'''

First, include the [[Webmap_API#Common_HTML_header|common header code]], required by all Webmap applications.

<pre><nowiki>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>
...
</head>
</nowiki></pre>

Be sure to replace {GOOGLE MAPS KEY} with your Google Map key.

'''2. Add HTML body element'''

Next, add the HTML body element to contain your map. The body contains a Javascript onload event handler that calls the '''loadmap()''' function you will define in the next step.

<pre>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

The div element is passed to the SLMap object constructor, using the <code>document.getElementById('map-container')</code> DOM method call.

NOTE: If you want the position attribute of the div element to be absolute, either set it programmatically using Javascript or using the style attribute tag. Setting the position attribute of this element in the CSS stylesheet will not work.

'''3. Add loadmap() function'''

The body element you just added has a Javascript event handler for the "onload" event, called when the browser initially loads the page. You deifined this to call a '''loadmap()''' function. Now, define that Javascript function in the head of your page (after the code that is already there), as follows:

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);
}
</script>

The first line defines a new Map object from the HTML div element. The second line centers the map at a specific point, and zooms it to zoom level three.

'''4. Save and test'''

When you are done, save the file, and then load it into your web browser. Try panning the map by clicking and dragging the mouse cursor; you can also pan by clicking on the arrow icons on the four sides. Also try zooming the view in and out by clicking the "+" and "-" icons.

'''Complete source code'''

<pre>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key=[GOOGLE MAPS KEY]" type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<style>
div#map-container {
width: 500px;
height: 500px;
}
</style>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);
}
</script>

</head>
<body onload="loadmap()" onunload="GUnload()">
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker ===

[[Image:Map with Marker.png|thumb|right|Map with a marker]]

A ''marker'' is simply an image displayed at a specific location on the map. The Webmap API enables you to define an image for each zoom level, so the marker can appear differently at each zoom level if you wish.

This example shows how to make a map with a marker. The code is the same as the first example, with with addition of some Javascript after the initialization of the map in the page's onload event handler function, '''loadmap()'''.

To use the code below verbatim, you must download the marker image as described in [[#Required_image_files|Required image files]]; you can also use the URL of the wiki image if you prefer.

The code first creates the icon for the marker, then places it on the map at (997, 1002) at the welcome area fountain. Because the same icon is specified for every zoom level, it appears the same size regardless of zoom level.

<br clear="all"/>
<pre>
// Create the icons
var yellow_dot_image = new Img("Yellow_marker.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
</pre>

In this example, clicking on the marker does nothing. Subsequent examples illustrate adding some onClick behavior.

'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// creates the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 2);

// creates the icons
var yellow_dot_image = new Img("Yellow_marker.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// creates the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));
mapInstance.addMarker(marker);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>There should be a yellow marker in the center of this map:
<div id="map-container"></div>
</body>
</pre>

=== Map with an initial open window ===

[[Image:Map_with_window.png|thumb|right|Map with a window]]

A Webmap ''window'' is a caption pointing to a specific point on the map, as shown in the screenshot at right. It looks something like a comic book dialog bubble.

Use the [[Webmap_API_Reference#MapWindow|MapWindow]] object to create a window.
For example, to create a window that opens initially when the page loads:
# Instantiate a [[Webmap_API_Reference#MapWindow|MapWindow]] object with the desired caption.
# Call the '''addMapWindow()''' method on the [[Webmap_API_Reference#SLMap|SLMap]] object to add the window to the map.
<br clear="all"/>
For example:

<pre>
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
</pre>

The code adds an open window to the map positioned again at (997, 1002), right above the welcome area fountain.

NOTE: after the user closes the window there is no way to bring it back. A subsequent example will show how to enable the user to reopen the window, by using markers with windows.
<br clear="all"/>

To make the map initially centered on the fountain, change the call to '''centerAndZoomAtSLCoord()''' as follows:

mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

'''Source code'''

This example shows how to create a map with a window. The code is the same as the first example, with the addition of some lines of Javascript after the initialization of the map, in the '''loadmap()''' function. In addition, the map is centered in a different location in order to make the window fully visible.

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997, 1002), 3);

// Create window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<h1>Simple Map Example</h1>
<div id="map-container"></div>
</body>
</pre>

=== Map with a marker that opens a windows ===

[[Image:Map with marker and window.png|thumb|right|Map with marker that opens a window]]

This example shows how to create a map with a marker which opens a window when clicked. It is a combination of the previous two examples, because the code first creates a marker and a window.

The difference comes in adding the marker to the map: this time you provide the window object as well as the marker object in the call to '''addMarker()''':

mapInstance.addMarker(marker, mapWindow);

Doing this adds the marker and causes it to open the specified window when the user clicks it. If the user subsequently closes the window, s/he can open it again by clicking on the marker.

<br clear="all" />
'''Source code'''

Replace the first line comment below with the [[Webmap_API#Common_HTML_header|common header code]].

<pre>

<script>
function loadmap() {
// Create the map
var mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997.5, 1001.5), 2);

// Create the icons
var yellow_dot_image = new Img("Yellow_marker.gif", 9, 9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];

// Create the marker
var marker = new Marker(all_images, new XYPoint(997, 1002));

// Create a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='Fountain.gif'>");

// Adds the marker to the map
mapInstance.addMarker(marker, mapWindow);
}
</script>
</head>
<body onload="loadmap()" onunload="GUnload()">
<p>This map shows a yellow marker on the welcome fountain. When you click the marker,
a window appears with a screenshot of the fountain.</p>
<div id="map-container"></div>
</body>
</pre>

== Accessing map images directly ==

The Second Life map images are stored on [http://aws.amazon.com/s3/ Amazon Simple Storage Service (Amazon S3)]. You can access the map images directly on the Amazon S3 servers using the following URL format:

<nowiki>http://map.secondlife.com/Z/XXXXX/YYYYY/map-Z-X-Y-objects.jpg</nowiki>

Where:
* Z - Zoom level desired:
** One (1) is the most zoomed-in view, showing individual region tiles.
** Eight (8) is the maximum zoom level, showing the entire world.
* X,Y - X and Y coordinates on the Second Life Grid of the region, for example, region Ahern is (997,1002). In the "directory path" (not the file name), pad the coordinate values to five characters with leading zeros; so for the previous coordinates, the path would be "00997/01002".

Tiles with zoom greater than one are stored at the lower left corner coordinate of the tiles that are included in the image.
In other words, you can find the zoom tile containing region (X,Y) for zoom level Z at the directory Z/X'/Y' where:

X' = X - (X % (2<sup>Z - 1</sup>) )

and

Y' = Y - (Y % (2<sup>Z - 1</sup>) )

Note that 2<sup>Z - 1</sup> is the number of regions encompassed by the width of a tile at resolution Z.

=== Examples ===

For example: if Z = 1, the four region tiles are:

* http://map.secondlife.com/1/01000/01000/map-1-1000-1000-objects.jpg
* http://map.secondlife.com/1/01001/01000/map-1-1001-1000-objects.jpg
* http://map.secondlife.com/1/01000/01001/map-1-1000-1001-objects.jpg
* http://map.secondlife.com/1/01001/01001/map-1-1001-1001-objects.jpg

These four region tiles are compressed into the single tile:

http://map.secondlife.com/2/01000/01000/map-2-1000-1000-objects.jpg

The following shows the map zoomed all the way out, showing the entire Second Life world view:
http://map.secondlife.com.s3.amazonaws.com/8/01024/00896/map-8-1024-896-objects.jpg

The following displays a single tile contained in the view above, zoomed all the way in:
http://map.secondlife.com.s3.amazonaws.com/1/01027/01019/map-1-1027-1019-objects.jpg

=== Getting a map URL from LSL ===

The following LSL script illustrates how to display a map of the current region to an avatar:

<lsl>
ShowMap(key avatar) {
string url = "http://map.secondlife.com.s3.amazonaws.com/1/";
vector sim_coord = llGetRegionCorner();
string x = (string)((integer)(sim_coord.x / 256.0));
string y = (string)((integer)(sim_coord.y / 256.0));
string x0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(x)), STRING_TRIM_HEAD) + x;
string y0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(y)), STRING_TRIM_HEAD) + y;
url += x0 + "/" + y0 + "/" + "map-1-" + x + "-" + y + "-objects.jpg";
llLoadURL(avatar, "View the sim map", url);
}
</lsl>

Contributed under GPL v3 license by [[User:Henri Beauchamp|Henri Beauchamp]] 09:00, 24 January 2009 (UTC)

Windows Icon Test

2008-10-08T17:44:31Z

James Linden:

== Goal ==
Make sure Windows icon set is correct for installer and Second Life applications.

=== Installer Icons ===
# Uninstall all copies of SL from your machine
# Browse through C:\Program Files to make sure all SecondLife* directories are gone
## If you find a C:\Program Files\SecondLife* directory, delete it
# Download the test installer
# Put it in a folder
# Cycle through all icon views (Extra Large, Large, Medium, Small, List, Details, Tiles)
# Verify the installer icon looks sharp at each view

=== Application Icons ===
# Run the installer
# Verify the installer window icons are sharp
# Verify the SL shortcut on the desktop has a hand icon
# Verify the SL shortcut in the Start menu has a hand icon
# Browse to C:\Program Files\SecondLife
# Cycle through all icon views (Extra Large, Large, Medium, Small, List, Details, Tiles)
# Verify the application icon looks sharp at each view

=== Window Icons ===
# Launch SL
# Verify the window icon (top left) is sharp and is a hand
# Quit SL

=== Uninstaller Icons ===
# Go to Control Panels > Add/Remove Programs (on XP) or Uninstall Programs (Vista)
# Verify the uninstaller has an icon
# Run the uninstaller
# Verify the uninstaller window has sharp icons
[[Category:Test Scripts]]

Windows Icon Test

2008-10-08T17:44:15Z

James Linden: New page: == Goal == Make sure Windows icon set is correct for installer and Second Life applications. === Installer Icons === # Uninstall all copies of SL from your machine # Browse through C:\Pro...

Viewer URI Name Space

2008-09-15T21:50:35Z

James Linden:

{{ProtocolNav}}
aka Viewer URL Namespace

aka SLAPP URLs

aka Application SLURL

[[Category: Name Spaces]]
[[Category: Search]]

The SL client supports links of the format secondlife://Region/123/45/67/, which have traditionally specified a region name and x/y/z location. This means "open Second Life and show Region on the world map".

The new URL scheme has 3 slashes, and allows direct control of the user interface and login. For example, secondlife:///app/login

Most secondlife:///app URLs only work from browser instances running inside Second Life because of a denial-of-service attack using secondlife:///app/teleport links to force repeated teleports. SLURLs that work with external browsers include:
* secondlife://<region name>
* secondlife:///app/login

'''secondlife://'''
* <region_name> ''log in to this region or, if logged in, show information and offer teleport''
** /<local_x> ''optional X position, defaults to 128''
*** /<local_y> ''optional Y position, defaults to 128''
**** /<local_z> ''optional Z position, defaults to 0''

* /app
** /agent
*** /<agent_id>
**** /about ''open agent's profile, with 2nd Life tab selected''
** /login ''log in on launch. External and internal browsers.''
*** see below for query parameters, of course, values are URL escaped
** /event
*** /<event_id>
**** /about ''open floater describing event''
** /group
*** /<group_id>
**** /about ''open floater describing group''
*** /create ''open the create group dialog, added in 1.20''
*** /list
**** /show ''open the list of groups to which user belongs, added in 1.20''
** /parcel
*** /<parcel_id>
**** /about ''open floater describing place''
** /classified
*** /<classified_id>
**** /about ''open floater describing classified''
** /region
*** /<region_id>
**** /about ''information from database about that region? list of parcels? covenant?''
** /teleport
*** /<region_name> ''teleport instantly to this region, no dialog''
**** /<local_x> ''optional X position, defaults to 128''
***** /<local_y> ''optional Y position, defaults to 128''
****** /<local_z> ''optional Z position, defaults to 0''

This could be extended to things like:
* /app/event/<event_id>/subscribe to register for notifications
* /app/parcel/<parcel_id>/teleport to teleport to a specific location
* /app/agent/<agent_id>/im to start IM session

== Login Query Parameters ==
{| border="1"
|-
| first || the account first name
|-
| last || the account last name
|-
| session || the secure session id
|-
| location || login location, format TBD, optional
|}

Second Life Browser User Agent

2008-07-08T18:16:29Z

James Linden: New page: The embedded Mozilla browser in Second Life identifies itself with a special user agent string. The format of this string has changed over the years. The user agent strings in 1.20 RC13 ...

The embedded Mozilla browser in Second Life identifies itself with a special user agent string. The format of this string has changed over the years. The user agent strings in 1.20 RC13 and beyond should conform to the HTTP 1.1 specification ([http://www.w3.org/Protocols/rfc2616/rfc2616.html RFC 2616]).

<pre>
// As of 1.20.13
Mozilla/5.0 (Windows; U; Windows NT 5.1; chrome://navigator/locale/navigator.properties; rv:1.8.1.13) Gecko/20080314 SecondLife/1.20.13.0 (Second Life Release; default skin)

// As of 1.18.2.1
Mozilla/5.0 (Windows; U; Windows NT 5.1; chrome://navigator/locale/navigator.properties; rv:1.8.0.12) Gecko/20070605 [Second Life (Second Life Release) - 1.18.2.1]

// Prior to 1.18.2.1
Mozilla/5.0 (Windows; U; Windows NT 5.1; chrome://navigator/locale/navigator.properties; rv:1.8.0.12) Gecko/20070605 [Second Life 1.18.2.1]
</pre>

Web Browser

2008-07-08T18:13:14Z

James Linden:

SecondLife uses the Gecko engine from the Mozilla project to display web pages.

* [[LLMozLib2]] - The Linden Lab integration layer and modified version of Mozilla for OpenGL compatibility.
* [[Second Life Browser User Agent]] - the user agent strings reported by the embedded Mozilla browser in Second Life

Viewer URI Name Space

2008-05-13T22:57:19Z

James Linden: Removed app/help, as it is not supported in the current (1.20) code base.

{{ProtocolNav}}
aka Viewer URL Namespace

aka SLAPP URLs

aka Application SLURL

[[Category: Name Spaces]]
[[Category: Search]]

The SL client supports links of the format secondlife://Region/123/45/67/, which have traditionally specified a region name and x/y/z location. This means "open Second Life and show Region on the world map".

The new URL scheme has 3 slashes, and allows direct control of the user interface and login. For example, secondlife:///app/login

'''secondlife://'''
* <region_name> ''log in to this region or, if logged in, show information and offer teleport''
** /<local_x> ''optional X position, defaults to 128''
*** /<local_y> ''optional Y position, defaults to 128''
**** /<local_z> ''optional Z position, defaults to 0''

* /app
** /agent
*** /<agent_id>
**** /about ''open agent's profile, with 2nd Life tab selected''
** /login
*** log in on launch
*** see below for query parameters, of course, values are URL escaped
** /event
*** /<event_id>
**** /about ''open floater describing event''
** /group
*** /<group_id>
**** /about ''open floater describing group''
*** /create ''open the create group dialog, added in 1.20''
*** /list
**** /show ''open the list of groups to which user belongs, added in 1.20''
** /parcel
*** /<parcel_id>
**** /about ''open floater describing place''
** /classified
*** /<classified_id>
**** /about ''open floater describing classified''
** /region
*** /<region_id>
**** /about ''information from database about that region? list of parcels? covenant?''
** /teleport
*** /<region_name> ''teleport instantly to this region, no dialog''
**** /<local_x> ''optional X position, defaults to 128''
***** /<local_y> ''optional Y position, defaults to 128''
****** /<local_z> ''optional Z position, defaults to 0''

This could be extended to things like:
* /app/event/<event_id>/subscribe to register for notifications
* /app/parcel/<parcel_id>/teleport to teleport to a specific location
* /app/agent/<agent_id>/im to start IM session

== Login Query Parameters ==
{| border="1"
|-
| first || the account first name
|-
| last || the account last name
|-
| session || the secure session id
|-
| location || login location, format TBD, optional
|}

Viewer URI Name Space

2008-05-13T18:14:55Z

James Linden:

{{ProtocolNav}}
aka Viewer URL Namespace

aka SLAPP URLs

aka Application SLURL

[[Category: Name Spaces]]
[[Category: Search]]

The SL client supports links of the format secondlife://Region/123/45/67/, which have traditionally specified a region name and x/y/z location. This means "open Second Life and show Region on the world map".

The new URL scheme has 3 slashes, and allows direct control of the user interface and login. For example, secondlife:///app/login

'''secondlife://'''
* <region_name> ''log in to this region or, if logged in, show information and offer teleport''
** /<local_x> ''optional X position, defaults to 128''
*** /<local_y> ''optional Y position, defaults to 128''
**** /<local_z> ''optional Z position, defaults to 0''

* /app
** /agent
*** /<agent_id>
**** /about ''open agent's profile, with 2nd Life tab selected''
** /login
*** log in on launch
*** see below for query parameters, of course, values are URL escaped
** /event
*** /<event_id>
**** /about ''open floater describing event''
** /group
*** /<group_id>
**** /about ''open floater describing group''
*** /list
**** /show ''open the list of groups to which user belongs, added in 1.20''
*** /create ''open the create group dialog, added in 1.20''
** /parcel
*** /<parcel_id>
**** /about ''open floater describing place''
** /classified
*** /<classified_id>
**** /about ''open floater describing classified''
** /region
*** /<region_id>
**** /about ''information from database about that region? list of parcels? covenant?''
** /help ''open F1 help floater''
** /teleport
*** /<region_name> ''teleport instantly to this region, no dialog''
**** /<local_x> ''optional X position, defaults to 128''
***** /<local_y> ''optional Y position, defaults to 128''
****** /<local_z> ''optional Z position, defaults to 0''

This could be extended to things like:
* /app/event/<event_id>/subscribe to register for notifications
* /app/parcel/<parcel_id>/teleport to teleport to a specific location
* /app/agent/<agent_id>/im to start IM session

== Login Query Parameters ==
{| border="1"
|-
| first || the account first name
|-
| last || the account last name
|-
| session || the secure session id
|-
| location || login location, format TBD, optional
|}

Viewer URI Name Space

2008-05-13T18:14:23Z

James Linden:

{{ProtocolNav}}
aka Viewer URL Namespace

aka SLAPP URLs

aka Application SLURL

[[Category: Name Spaces]]
[[Category: Search]]

The SL client supports links of the format secondlife://Region/123/45/67/, which have traditionally specified a region name and x/y/z location. This means "open Second Life and show Region on the world map".

The new URL scheme has 3 slashes, and allows direct control of the user interface and login. For example, secondlife:///app/login

'''secondlife://'''
* <region_name> ''log in to this region or, if logged in, show information and offer teleport''
** /<local_x> ''optional X position, defaults to 128''
*** /<local_y> ''optional Y position, defaults to 128''
**** /<local_z> ''optional Z position, defaults to 0''

* /app
** /agent
*** /<agent_id>
**** /about ''open agent's profile, with 2nd Life tab selected''
** /login
*** log in on launch
*** see below for query parameters, of course, values are URL escaped
** /event
*** /<event_id>
**** /about ''open floater describing event''
** /group
*** /<group_id>
**** /about ''open floater describing group''
*** /create ''open the create group dialog, added in 1.20''
*** /list
**** /show ''open the list of groups to which user belongs, added in 1.20''
** /parcel
*** /<parcel_id>
**** /about ''open floater describing place''
** /classified
*** /<classified_id>
**** /about ''open floater describing classified''
** /region
*** /<region_id>
**** /about ''information from database about that region? list of parcels? covenant?''
** /help ''open F1 help floater''
** /teleport
*** /<region_name> ''teleport instantly to this region, no dialog''
**** /<local_x> ''optional X position, defaults to 128''
***** /<local_y> ''optional Y position, defaults to 128''
****** /<local_z> ''optional Z position, defaults to 0''

This could be extended to things like:
* /app/event/<event_id>/subscribe to register for notifications
* /app/parcel/<parcel_id>/teleport to teleport to a specific location
* /app/agent/<agent_id>/im to start IM session

== Login Query Parameters ==
{| border="1"
|-
| first || the account first name
|-
| last || the account last name
|-
| session || the secure session id
|-
| location || login location, format TBD, optional
|}

Viewer URI Name Space

2008-05-13T18:10:52Z

James Linden:

{{ProtocolNav}}
aka Viewer URL Namespace

aka SLAPP URLs

aka Application SLURL

[[Category: Name Spaces]]
[[Category: Search]]

The SL client supports links of the format secondlife://Region/123/45/67/, which have traditionally specified a region name and x/y/z location. This means "open Second Life and show Region on the world map".

The new URL scheme has 3 slashes, and allows direct control of the user interface and login. For example, secondlife:///app/login

'''secondlife://'''
* <region_name> ''log in to this region or, if logged in, show information and offer teleport''
** /<local_x> ''optional X position, defaults to 128''
*** /<local_y> ''optional Y position, defaults to 128''
**** /<local_z> ''optional Z position, defaults to 0''

* /app
** /agent
*** /<agent_id>
**** /about ''open agent's profile, with 2nd Life tab selected''
** /login
*** log in on launch
*** see below for query parameters, of course, values are URL escaped
** /event
*** /<event_id>
**** /about ''open floater describing event''
** /group
*** /<event_id>
**** /about ''open floater describing group''
** /parcel
*** /<parcel_id>
**** /about ''open floater describing place''
** /classified
*** /<classified_id>
**** /about ''open floater describing classified''
** /region
*** /<region_id>
**** /about ''information from database about that region? list of parcels? covenant?''
** /help ''open F1 help floater''
** /teleport
*** /<region_name> ''teleport instantly to this region, no dialog''
**** /<local_x> ''optional X position, defaults to 128''
***** /<local_y> ''optional Y position, defaults to 128''
****** /<local_z> ''optional Z position, defaults to 0''

This could be extended to things like:
* /app/event/<event_id>/subscribe to register for notifications
* /app/parcel/<parcel_id>/teleport to teleport to a specific location
* /app/agent/<agent_id>/im to start IM session

== Login Query Parameters ==
{| border="1"
|-
| first || the account first name
|-
| last || the account last name
|-
| session || the secure session id
|-
| location || login location, format TBD, optional
|}

Category:Design Documents

2008-02-11T19:47:29Z

James Linden: New page: Design for new features and large project descriptions should have the category "Design Documents"

Design for new features and large project descriptions should have the category "Design Documents"

Talk:Viewer URI Name Space

2008-01-09T01:12:54Z

James Linden: New page: Does this mean that no region can be named 'app'? Phoenix 17:27, 23 July 2007 (PDT) :Yes, no region can be named "app". I had to pick some prefix, this one seemed reasona...

Does this mean that no region can be named 'app'? [[User:Phoenix|Phoenix]] 17:27, 23 July 2007 (PDT)
:Yes, no region can be named "app". I had to pick some prefix, this one seemed reasonable. Unfortunately, also any string starting with secondlife:// can be legally parsed as a region name. [[User:James|James]] 08:54, 24 July 2007 (PDT)
::I think this is a really bad direction to start down -- it artificially limits our usable space. I think we should instead make a new protocol for local resources, or make a more general url syntax. For example:

slclient://locally/available/resource

or

secondlifegrid://localhost/locally/available/resource

[[User:Phoenix|Phoenix]] 09:39, 24 July 2007 (PDT)

I agree with Phoenix here. Extending the secondlife: scheme is a mistake, since it's already well defined what it means:

"Via the Second Life protocol I am access Region Foo at x,y,z"

Mozilla uses the uri scheme chrome for "locally accessable resources that are accessed without knowing their precise filesystem location".

secondlife:// as a region name is actually okay. In URI form, it would be secondlife://secondlife%3A%2F%2F/1/2/3

From what I can tell, something like slchrome:// or slui:// would be better.

[[User:Mark|Mark]] 10:07, 24 July 2007 (PDT)

Yes, I see your point and agree. I initially chose secondlife:// for expedience, as the installer already registered it on all platforms, the embedded mozilla already had callbacks for the links, etc. But we need a different protocol for this type of command.

I'm going to use slclient:// because the word "client" is probably more understandable to an end user (who might see the raw link in a browser warning dialog) than "chrome" or "ui".

[[User:James|James]] 10:30, 24 July 2007 (PDT)

----

Well, while it is ugly, and unfortunate, I don't think a "one-time" fix of inserting "/app" at the top level is that bad. I think there are plenty of downsides to creating another scheme identifier. A way to make this more palatable is to fix the top level of the path, so whereas before you had:
secondlife://Obscure/123/98
you'd now have:
secondlife://location/Obscure/123/98
The old one would be deprecated, and yes, regions with the name "app" or "location" or whatever else we put a the top level wouldn't work with the old style.

The primary reason for having a scheme is that it is the way to get an operating system to open up another application with a class of URIs. Hence, everything in such a URI namespace is really the name for something the running viewer can do. We shouldn't use the secondlife: scheme to address elements of our network at all. Hence, I don't think the need for a top level '/localhost' in the examples above.

Since the scheme is entirely for the purpose of directing the viewer, it is reasonable to think of all those resources named as actions or concepts in the viewer. In otherwords, the URI
secondlife://event/<uuid>
should be though of as the viewer's concept of that event in our system. And this should conceptually distinct from, say:
http://services.agni.lindenlab.com/event/<uuid>
which would be a reference to the event resource back at the grid.

As such, such URIs really should only imply viewer actions on those objects: I could see secondlife: URIs that open an event in the viewer (but one wonders why?), but not one that creates an event that way. For the most part, I think we should be steering such functionality to the web services.

Lastly, a big problem with the URI tree proposed is that it puts all content into global name spaces by type. In particular:
secondlife://app/parcel/<uuid>
implies that one can reach ANY parcel that way. This is bad as it forces us to think in terms of a single global list. Much better would be
secondlife://app/grid/agni/region-by-name/Obscure/parcels/<uuid>/view
Though, admittadly, the "/grid/agni" part may be overkilll.... but perhaps not...

[[User:ZeroLinden|ZeroLinden]] 10:38, 24 July 2007 (PDT)

----

The primary motivation for this is to make clicking on links in a Find All search results page (output by Google Search Appliance) show SL UI with details on that data. Even if we move that data display to HTML, we'll still need a way to have links/buttons that offer teleports, open the IM window, etc. So we need a commmand format.

At the time the parcel links in the HTML pages for search are made, I do not have access to the region name or other information other than the UUID of the parcel. For example, top picks only store the parcel UUIDs. I could thrash the database during the static HTML page generation for search to look up the region names for each parcel UUID I encountered, but that seems a waste of effort to me.

I could imagine having special links that opened, say, the event UI as a useful way to share references to information in our system, on outside web pages, in our own IM, and in tutorials. Since I have to do some internal link management for search, it seems reasonable to me to expose those URLs to the outside world.

I would prefer to reserve the words "event", "classified", "place", "parcel", "agent", "resident", "person" and "group" as being invalid region names. secondlife://agent/<agent_id> looks cleaner to me than secondlife://app/...

Without slclient://, all these links are working now. Do we really want slclient://? Also, our entire system for places/events/top picks currently stores only parcel ids. I'm not thrilled about embarking on a huge refactoring of this system just to get search to work.

[[User:James|James]] 10:56, 24 July 2007 (PDT)

== Non-Standard ==

Bah! I can't believe I didn't notice this before: Our syntax doesn't follow the recommended syntax for path based URI schemes! It should start with <b>three</b> slashes, not two, like file: does. This is because the thing after the double slash is the <i>authority</i> section, containing a hostname and port (and other stuff optionally as well...).

It might be worse - depending on one's reading of section 3 of RFC 3986, our use of double slashes without an authority section could be seen as illegal. Of course, we <i>could</i> claim that the region name or "app" was the authority (and hence host).... but I bet w don't follow all the proper conventions for host names. Fie!

See http://tools.ietf.org/html/rfc3986

[[User:ZeroLinden|ZeroLinden]] 15:33, 6 September 2007 (PDT)

----

<i>James writes:</i>

Looks like <code>secondlife:///</code> is what we want. My only concern would be
that crappy IRC clients and other programs that attempt to automatically
identify URLs in text would choke. Colloquy does it correctly. I will
try other clients in the office tomorrow.

Changing to <code>secondlife:///</code> is trivial in my code. Any reason I
shouldn't just do it?

----

Well, we have to continue to handle the existant URLs. So perhaps we take this moment to "fix" the whole scheme:

secondlife://<region name>/<x>/<y>/<z>
-- old style, still accepted

secondlife:///viewer/go/<region name/<x>/<y>/<z>
-- new style, with well defined rules about encoding region names

secondlife:///viewer/agent/<agent_id>
secondlife:///viewer/group/<group_id>
-- etc., the controls being added for search
-- (that these are an implicit "open a floater on this item" verb is a little odd,
what's the URL for "IM this line of text to this agent"?)

secondlife:///viewer/login/...
-- the login work for web site auth.

[[User:ZeroLinden|ZeroLinden]] 08:57, 7 September 2007 (PDT)

----

I will of course support legacy URLs. I see no strong reason to switch from "app" to "viewer". Likewise, my initial syntax for agents/groups/etc. is of the form:

secondlife:///app/agent/<agent_id>/about

Where "about" is the verb. Thus we can add "im", "offer-teleport", etc.

Any reason I should not just implement secondlife:///app/agent/<agent_id>/about ?

[[User:James|James]] 09:57, 7 September 2007 (PDT)

Viewer URI Name Space

2008-01-09T01:12:16Z

James Linden: New page: {{ProtocolNav}} aka Viewer URL Namespace aka SLAPP URLs Category: Name Spaces Category: Search The SL client supports links of the format secondlife://Region/123/45/67/, which h...

{{ProtocolNav}}
aka Viewer URL Namespace

aka SLAPP URLs

[[Category: Name Spaces]]
[[Category: Search]]

The SL client supports links of the format secondlife://Region/123/45/67/, which have traditionally specified a region name and x/y/z location. This means "open Second Life and show Region on the world map".

The new URL scheme has 3 slashes, and allows direct control of the user interface and login. For example, secondlife:///app/login

'''secondlife://'''
* <region_name> ''log in to this region or, if logged in, show information and offer teleport''
** /<local_x> ''optional X position, defaults to 128''
*** /<local_y> ''optional Y position, defaults to 128''
**** /<local_z> ''optional Z position, defaults to 0''

* /app
** /agent
*** /<agent_id>
**** /about ''open agent's profile, with 2nd Life tab selected''
** /login
*** log in on launch
*** see below for query parameters, of course, values are URL escaped
** /event
*** /<event_id>
**** /about ''open floater describing event''
** /parcel
*** /<parcel_id>
**** /about ''open floater describing place''
** /classified
*** /<classified_id>
**** /about ''open floater describing classified''
** /region
*** /<region_id>
**** /about ''information from database about that region? list of parcels? covenant?''
** /help ''open F1 help floater''
** /teleport
*** /<region_name> ''teleport instantly to this region, no dialog''
**** /<local_x> ''optional X position, defaults to 128''
***** /<local_y> ''optional Y position, defaults to 128''
****** /<local_z> ''optional Z position, defaults to 0''

This could be extended to things like:
* /app/event/<event_id>/subscribe to register for notifications
* /app/parcel/<parcel_id>/teleport to teleport to a specific location
* /app/agent/<agent_id>/im to start IM session

== Login Query Parameters ==
{| border="1"
|-
| first || the account first name
|-
| last || the account last name
|-
| session || the secure session id
|-
| location || login location, format TBD, optional
|}

Secondlife:// URL scheme

2008-01-09T01:09:22Z

James Linden:

This wiki page answers the question, "How does the secondlife:// URL scheme work?"

For details on special secondlife:///app/ URLs that control the user interface for login and search, see [[Viewer URI Name Space]]

== Windows ==
The Second Life client utilizes the windows registry to tell the browser which application to launch when it sees secondlife:// as the prefix to a URL. During installation of the client, if the channel is "Second Life Release" (the default channel for the client) and the grid the client is installed for is "agni", the register entry is replaced with the path to the executable. The register entry states that whenever a browser sees secondlife:// that particular installation of the Second Life client is invoked with the arguments -url <URL>.
=== No Client is Running ===
When there is no client already running, the executed client will parse the -url argument and execute according to how it is parsed.
=== There is already a Client Running ===
The client looks to see if any applications running with the class name (specific to windows) "Second Life" is up. If so, it serializes the <URL> and sends it across the other client.

== Macintosh ==
The Mac client registers a GURL handler as soon as the Second Life Application is dragged from another volume onto your startup volume.
=== No Client is Running ===
That client will be launched and its GURL handler will handle the GURL event issued by the operating system.
=== There is already a Client Running and it's the GURL Client ===
The client will handle the GURL event
=== There is already a Client Running and it's *not* the GURL Client ===
The GURL client will be launched and it will fail with the message "Another instance of Second Life is running."

== Linux ==
Coming soon!

Secondlife:// URL scheme

2008-01-09T01:08:27Z

James Linden:

{{TOCright}}
This wiki page answers the question, "How does the secondlife:// URL scheme work?"

For details on special secondlife:///app/ URLs that control the user interface for login and search, see [[Viewer URI Name Space]]

== Windows ==
The Second Life client utilizes the windows registry to tell the browser which application to launch when it sees secondlife:// as the prefix to a URL. During installation of the client, if the channel is "Second Life Release" (the default channel for the client) and the grid the client is installed for is "agni", the register entry is replaced with the path to the executable. The register entry states that whenever a browser sees secondlife:// that particular installation of the Second Life client is invoked with the arguments -url <URL>.
=== No Client is Running ===
When there is no client already running, the executed client will parse the -url argument and execute according to how it is parsed.
=== There is already a Client Running ===
The client looks to see if any applications running with the class name (specific to windows) "Second Life" is up. If so, it serializes the <URL> and sends it across the other client.

== Macintosh ==
The Mac client registers a GURL handler as soon as the Second Life Application is dragged from another volume onto your startup volume.
=== No Client is Running ===
That client will be launched and its GURL handler will handle the GURL event issued by the operating system.
=== There is already a Client Running and it's the GURL Client ===
The client will handle the GURL event
=== There is already a Client Running and it's *not* the GURL Client ===
The GURL client will be launched and it will fail with the message "Another instance of Second Life is running."

== Linux ==
Coming soon!

Adding a dialog

2007-10-07T16:42:04Z

James Linden: How to add file to linux build system

{{OSWikiLearnBox|parent=Viewer architecture}}
[[Category:Viewer Architecture]]

Windows and dialogs in Second Life are implemented as LLFloater objects. The class hierarchy is:

LLFloaterFoo - a "foo" dialog
LLFloater - generic window or dialog with close box, minimize box, etc.
LLPanel - rectangular area with dark background, has functions like childSetText(), childGetValue()
LLUICtrl - any widget that can take keyboard focus
LLView - base class, container for UI widget children

Create a new C++ header and source file to hold your new class. By convention these are called llfloaterfoo.h and .cpp. Place them in the newview directory.

Make the build system aware of your new files:
* Windows - add to Visual Studio "newview" project file
* Mac - add to macview.xcodeproj file
* Linux - add a line referencing the only the cpp file to newview/files.lst

You'll also need a new XML description file. These are found in the indra/newview/skins/xui/en-us directory. It's easiest to copy an existing file and modify it. Name the new file floater_foo.xml.

'''Important''' - Second Life UI uses OpenGL coordinates, so 0,0 is at the '''bottom''' left corner.

Let's make a floater that has a text label "bar", a text line input field "baz", and a button "hippo".

A basic floater header looks like this:

<pre>
#include "llfloater.h"

class LLFloaterFoo : public LLFloater
{
public:
LLFloaterFoo();

virtual ~LLFloaterFoo();

// by convention, this shows the floater and does instance management
static void show(void*);

private:
// when a line editor loses keyboard focus, it is committed.
// commit callbacks are named onCommitWidgetName by convention.
static void onCommitBaz(LLUICtrl* ctrl, void *userdata);

// by convention, button callbacks are named onClickButtonLabel
static void onClickHippo(void* userdata);

// no pointers to widgets here - they are referenced by name

//assuming we just need one, which is typical
static LLFloaterFoo* sInstance;

};

</pre>

The XML data definition should look like this:

<pre>
<?xml version="1.0" encoding="utf-8" standalone="yes"?>



<floater
name="foo_floater"
title="Foo"
can_resize="true"
can_minimize="true"
can_close="true"
can_drag_on_left="false"
width="275"
height="250"
min_width="80"
min_height="220"
>



<text name="bar_text"
font="SansSerifSmall"
left="10"
bottom_delta="-40"
width="260"
height="16"
follows="left|top"
>
bar is a generic programming identifier
</text>



<line_editor
name="baz_edit"
width="120"
height="20"
left="10"
bottom_delta="-30"
follows="left|bottom"
hidden="false"
mouse_opaque="true"
max_length="31"
font="SansSerif"
bevel_style="in"
border_style="line"
border_thickness="1"
select_all_on_focus_received="true"
/>



<button
name="hippo_btn"
label="Hippo"
font="SansSerifSmall"
left="10"
bottom_delta="-25"
width="100"
height="20"
follows="bottom|left"
/>
</floater>
</pre>

The C++ code for this floater looks like:

<pre>
#include "llviewerprecompiledheaders.h" // must be first include

#include "llfloaterfoo.h"

#include "llvieweruictrlfactory.h" // builds floaters from XML

// Statics
LLFloaterFoo* LLFloaterFoo::sInstance = NULL;

LLFloaterFoo::LLFloaterFoo()
: LLFloater("floater_foo")
{
gUICtrlFactory->buildFloater(this, "floater_foo.xml");

childSetCommitCallback("baz_edit", onCommitBaz, this);

childSetAction("hippo_btn", onClickHippo, this);
setDefaultBtn("hippo_btn");
}

// static
void LLFloaterFoo::show(void*)
{
if (!sInstance)
sInstance = new LLFloaterFoo();

sInstance->open();
}

LLFloaterFoo::~LLFloaterFoo()
{
sInstance=NULL;
}

// static
void LLFloaterFoo::onCommitBaz(LLUICtrl* ctrl, void* userdata)
{
LLFloaterFoo* self = (LLFloaterFoo*)userdata;
LLString text = self->childGetText("baz_edit");
llinfos << "baz contains: " << text << llendl;
}

// static
void LLFloaterFoo::onClickHippo(void* userdata)
{
LLFloaterFoo* self = (LLFloaterFoo*)userdata;
llinfos << "Hippo! from " << self->getName() << llendl;
}

</pre>

Finally, to test out this floater you'll need to add a menu item that calls the show() method. See [[Adding a menu item]].

====Hints:====
You will need to add <pre>#include "llfloaterfoo.h"</pre> to the file llviewermenu.cpp.
The show method is called with the following command: <pre>LLFloaterFoo::show(NULL);</pre>
Put that command in the class LLToolsFoo you made in the previous example, [[Adding a menu item]].

Adding a menu item

2007-10-07T16:37:41Z

James Linden: Changed to reflect updated initialize_menus() function

{{OSWikiLearnBox|parent=Viewer architecture}}
[[Category:Viewer Architecture]]

Menu items in the viewer are specified in XML files, located in the indra/newview/skins/xui/en-us/ directory.

There are separate XML files for various categories of menu. They are:
menu_viewer.xml - top of screen
menu_inventory.xml - right-click on inventory item
menu_pie_attachment.xml - right-click on your own attachment
menu_pie_avatar.xml - right-click on other avatar or their attachments
menu_pie_land.xml - right-click on land
menu_pie_self.xml - right-click on your avatar

The menu callbacks are set up in llviewermenu.cpp.

Let's add a menu item named "Foo" to the Tools menu.
* In menu_viewer.xml find the "Tools" menu item. It is inside a <menu> tag.
* Tear-off sub menus use the <tearoff_menu> tag.
* Find the "Reset Scripts in Selection" menu item.
* After it, add the following text:
<menu_item_call label="Foo" enabled="true" name="foo_menu">
<on_click function="Tools.Foo" userdata="" />
</menu_item_call>
* This sets up a menu item that will call a function. It can be referenced in C++ by the name "foo_menu". The user-visible label is "Foo". It defaults to enabled.
* Open newview/llviewermenu.cpp
* Create an event handler class for this menu item. By convention these are named after the menu name and item name.
class LLToolsFoo : public view_listener_t
{
bool handleEvent(LLPointer<LLEvent> event, const LLSD& userdata)
{
llinfos << "foo!" << llendl;
return true;
}
};
* This class will listen for events from a "view", the base class for all UI widgets. LLPointer is a reference counting smart pointer. LLSD is a structured data class similar to a Perl or Python variable - it can hold data of any type.
* llinfos is the output stream for informational messages. It goes to the ctrl-shift-4 debug console, stdout, and the log file.

* Now associate the "Tools.Foo" function with a C++ class. Open newview/llviewermenu.cpp.
* In the function initialize_menus() add the line:
addMenu(new LLToolsFoo(), "Tools.Foo");
* This associates your listener with the "Tools.Foo" event.

If you added a new source file to implement your new dialog, be sure to include it in newview/files.lst so the build system is aware of it.

Compile and run!

Viewer Architecture

2007-09-27T18:14:21Z

James Linden: /* Learn by Example */

{{OSWikiLearnBox}}
[[Category:Viewer Architecture]]

The Second Life client (also known as the "viewer") is a complex piece of software. It can be visualized as a streaming media client like RealPlayer, a game engine like Quake 3, or a web browser.

First you'll need to learn some terminology like "agent", "sim", and "region" in the [[glossary]].

== Learn by Example ==
* [[Adding a menu item]]
* [[Adding a dialog]]
* [[Adding a cursor]]
* [[How movement works]]
* [[How the camera works]]
* [[How login works]]
* [[Hegemons Login Analysis]]
* [[How keyboard processing works]]
* [[How scripts work]]
* [[The lifetime of a session]]
* [[How preferences work]]

== Major Systems ==
* [[Asset System]] - transport for animations, sounds, notecards, scripts, etc.
* [[Avatar Appearance]] - appearance is constructed from a mesh, parameters to deform the mesh, and textures to describe clothing
* [[Avatar Profiles]]
* [[Culling]] - octree and occlusion based culling to speed rendering
* [[Error Logging System]] - command and control of debugging output
* [[Groups]]
* [[Image System]] - prioritizes and decodes JPEG2000 images into OpenGL textures
** [[Texture cache]] - used for reading and writing texture data to the local disk cache
** [[Image Pipeline]] - fetches textures from the servers and decodes them
* [[Inventory]] - server-side storage of assets for each user
* [[L$ System]]
* [[Message System]] - reliable and unreliable transport over UDP
* [[Movie System]] - QuickTime-based video on object surfaces
* [[Muting Objects and Agents]] - How the viewer manages the muted object list
* [[Rendering System]] - from viewer object to drawable to face to vertices to graphics card
* [[Selection Manager]] - holds extended information for selected objects and allows editing
* [[Sound System]] - cross platform audio based on FMOD
* [[Tools]] - anything that takes effect when you click your mouse on the world view.
* [[UI Widgets]] - cross platform buttons, scroll bars, etc.
* [[UI Floaters]] - dialogs and windows built from XML files
* [[VFS]] - cached data is held in two "virtual file systems" in large files on the client
* [[Viewer Object System]] - objects in scene for rendering and editing
* [[Web Browser]] - the integration of the viewer with the web.

== Threads ==
The viewer is a single process with a few threads:
* Main thread -- The input/output main program function (including rendering).
* VFS thread -- Thread responsible for reading/writing to the local virtual file system.
* LFS thread -- Thread responsible for some reading/writing to the local native file system.
** Used by the {{OSWiki|Threaded_Image_Pipeline}} project
* Image thread -- Thread responsible for requesting and decoding image data
** Used by the {{OSWiki|Threaded_Image_Pipeline}} project
* Error Thread -- Thread responsible for catching exceptions, calling the (currently unused?) error handler, and retiring
* Worker Threads -- Threads designed to do cpu intensive background tasks
** These threads may be paused during rendering so as not to reduce performance (design in-progress)

== Program Flow ==
# Initialize - newview/viewer.cpp :: main()
# Loop - newview/viewer.cpp :: main_loop()
#* Gathers keyboard and mouse input
#* Pumps the TCP i/o
#* idle()
#* Render the frame
#* let filesystem and worker threads process
# Shutdown
One way to see what goes on in the main loop is to bring up the debug menus (Ctrl-Alt-D) then Client->Consoles->Fast Timers (or Ctrl-Shift-9) and expand the entries in the caption.

== Sources of Input ==
* The [[Message System]].
** Assets through the [[Asset System]], transmitted using the [[Transfer Manager]], and extracted from the [[VFS]].
** Files through [[Xfer Manager]].
* Files copied out of a [[VFS]] into local file store and read through c/c++/ll file API.
* XMLRPC calls such as [[Authentication Flow|login]] and [[Buying Land and Currency]].
* HTTP GET/POST to the [[Backbone]]. This is not yet in use.
* Streaming music and videos.
** Quicktime.
** FMOD.
* The web browser.

== User Guides ==

* [[Viewer coordinate frames]].
* Known [[Client_parameters]]
* Known Client Parameters on [http://lslwiki.net/lslwiki/wakka.php?wakka=newview&show_comments=1 LSLwiki.net]
* Known [[defines]]
* [[Godmode]] - what Lindens can do

Adding a cursor

2007-09-27T18:12:56Z

James Linden: New page: * Add new entry to enum ECursorType in llwindow.h ** For example, UI_CURSOR_STUFF === Windows === * Create art for Windows ** Go into indra/newview/res ** Duplicate toolopen.cur ** Name ne...

* Add new entry to enum ECursorType in llwindow.h
** For example, UI_CURSOR_STUFF
=== Windows ===
* Create art for Windows
** Go into indra/newview/res
** Duplicate toolopen.cur
** Name new file something like toolstuff.cur
** Visual Studio > View > Resource View
** Right-click newViewRes.rc > Cursor
** Add Resource...
** Import...
** Select toolstuff.cur
** Edit the cursor using Visual Studio bitmap tools
** Open Properties view
** Click on name IDC_CURSOR_6
** Rename to "TOOLSTUFF"
* Link to Windows code
** Add to llwindowwin32.cpp, LLWindowWin32::initCursors()
** mCursor[UI_CURSOR_TOOLSTUFF] = loadColorCursor(TEXT("TOOLSTUFF"));
=== Mac ===
* Create art for Mac
** indra/newview/cursors_mac
** duplicate UI_CURSOR_TOOLOPEN.tif
** Save cursor as 32-bit TIFF
* Link to Mac code
** Edit llwindowmacosx.cpp cursorIDToName()
** Add "UI_CURSOR_TOOLSTUFF"
=== Linux ===
* Create art for Linux
** indra/newview/res_sdl
** duplicate toolopen.BMP
** save as 24-bit BMP
** Alpha is color-keyed to 200, 200, 200
* Link to code
** Edit llwindowsdl.cpp LLWindowSDL::initCursors()
** mSDLCursors[UI_CURSOR_TOOLPLAY] = makeSDLCursorFromBMP("toolplay.BMP",0,0);
** Hot-spot is hard-coded in above function call

Mouse Navigation

2007-09-13T18:23:52Z

James Linden: New page: For a while I've been thinking about how to make SL easier for new users to navigate. In some user tests (circa 2005) I observed several users trying what I call "coffee cup" navigation -...

For a while I've been thinking about how to make SL easier for new users to navigate. In some user tests (circa 2005) I observed several users trying what I call "coffee cup" navigation -- hold something in their left hand and try to navigate SL using just the mouse.

This doesn't work for several reasons.
* Click-drag on avatar rotates camera, but doesn't move it.
* Arrow keys are on the right edge of the keyboard, meaning right handed users move their right hand back and forth between arrow keys and mouse.
* Users new to 3D environments don't discover AWSD navigation.
* Once they discover AWSD navigation they make frequent errors with typing navigation input into chat and vice versa.
* Alt-Zoom requires two-handed control, yet is important for getting good views of many pieces of content.

== Proposed Mouse Navigation ==

=== Primary Navigation ===
* Left click on avatar walks forward
* Drag left turns left, drag right turns right
* Drag slightly back stops walking
* Drag more back walks backward
* Drag forward starts running

To help users discover this:
* Hovering over your avatar changes cursor to special "walking" icon
* When mouse is down on avatar, transparent arrows appear on screen representing forward/back/turn with the currently active arrow highlighted
* Arrows surround cursor position, suggesting dragging towards the one you want
* Of course, arrows can be turned off by advanced users

=== Flying ===
* Flying is hard because the mouse is a 2D input device, but flying is 3D
* Maybe just navigate in 2D, with on-screen widgets to go up and down?

=== Alt-Zoom ===
* Show explicit "tool" icons in the toolbar for arrow vs. zoom vs. orbit
* Holding down Alt highlights the zoom icon
* Mouse wheel switches between tools
** Thus you can both move avatar and move camera using only a wheel mouse
* Tool tip for zoom and orbit icons shows keyboard shortcuts

=== Go To Point ===
* This is hard because the most interesting place to walk is right in front of you, which you can't click because the avatar is in the way
* Double-click on ground does a stupid walk-to-point autopilot
* Users can tag objects as being "walls"
* Double-clicking a "wall" walks toward it
* Auto-pilot doesn't try to walk around objects. It turns off if it gets stuck.
* Auto-pilot is driven by the server, so motion is smooth in the face of network latency

=== Object Selection ===
* Right now you must do right-click of objects to select them and issue a command
* This limits the commands to what fits in the right-click menu
* For non-wall objects:
** Single click selects and shows highlight
** Objects can specify an "info window" to appear on the edge of the screen
** Info window can contain:
*** Picture
*** Buttons that issue chat commands to a script in the object
*** HTML page?
*** Information about creator/owner/script status, etc.

User Interface Improvements

2007-09-13T18:03:11Z

James Linden: /* Movement components */

This page describes a proposed project to design and implement an improved User Interface for the Second Life Viewer. The intention of posting this proposal to the Wiki is to increase transparency by including Residents in the project definition and design.

=== Project Goal ===

The Second Life Viewer is a complex, multi-layered application, consisting of many sub-systems (such as Inventory, Building, Scripting). The current user interface (UI) is intimidating to new users and cumbersome even for power users. The goal of this project is to create a new Viewer UI that is less intimidating for new users yet still flexible enough for power users. The design objective is to improve access to frequently-used features while exposing advanced functionality in a task- or context-sensitive manner. Specific goals include:

* Eliminate the current menu system as the primary mechanism for accessing features
* Minimize the amount of UI "chrome" displayed at any given time to provide an uninterrupted view of the Second Life world
* Improve users' ability to learn and use avatar and camera movement controls

=== Project Scope ===

Recognizing that it is not feasible to address usability issues across the full range of the Viewer's sub-systems in the course of a single project, this project is limited to re-organizing existing Viewer functionality. Insofar as possible, the project will not affect the following:

* Existing "sub-applications" (Inventory, Search, Map, etc)
* Design and behavior of child windows ("floaters")
* Pop-up notification system
* "Out of box" experience (registration, download, orientation)

Visual design will be limited to new functionality as outlined below and should conform to the latest art assets and color palettes.

=== Proposed Solution ===

We propose a browser-like concept which has regions of the screen ("zones of control") that summon UI when the user moves the mouse to that area. The UI in these regions could be fixed using a gesture (such as a pushpin) or autohide such that they only appear when summoned. The preliminary design has five zones: Navigation, Search/Status, Communication, Movement, and Tools (for accessing the rest of the SL sub-applications - Inventory, Appearance, Map, Preferences, etc).

The concept is illustrated in this high-level mockup (note that the mockup is not intended to illustrate actual visual design or intended functionality):

[[Image:ZonesConcept.jpg|thumb|none|600px|Mockup of proposed design]]

=== Required Design & Development Work ===

===== Preliminary design tasks =====
* Stakeholder interviews/discovery
* User research/ethnography
* Personas/scenarios (as appropriate)
* Information architecture design

===== General components =====
* Interaction design for auto-hiding & pinning UI elements
* Visual design of pinning affordance
* Implementation of auto-hide behavior and pinning UI controls

===== Navigation components =====
* Interaction design for navigating between recent locations (History)
* Interaction design for bookmarking/organizing locations (Landmarks)
* Visual design of Navigation panel
** Back/Forward controls
** Location bar, region/parcel name, rating, etc
** Landmarks UI
* Implementation of History features
* Implementation of Landmarks features

===== Search/Status components =====
* Interaction design for Search bar (mostly complete)
* Visual design of Search/Status panel
** Search bar/icon
** Help button
** Visual design of status information (L$ balance, time, parcel state, etc)
* Implementation of overall panel layout

===== Communication components =====
* Interaction design for expanding in-world chat into full-featured chat console
* Visual design of panel and related elements
* Implementation of panel layout and new UI affordances (as required)

===== Movement components =====
* Interaction design for on-screen controls for moving avatar and camera
* Visual design of on-screen controls for each mode (walk, fly, camera)
* Implementation of on-screen movement panel and controls
* Possibility of purely mouse-driven [[Mouse Navigation]]

===== Tools/extensibility component =====
* Interaction design of mechanism for accessing tools as required by the user
* Visual design of minimized/hidden tools and expand/collapse affordances
* Implementation of UI behavior

[[Category:Feature Requests]]

Talk:Inventory UI Design

2007-03-12T23:40:20Z

James Linden:

I think the initial interface should not require the use of nested folders. I'd rather have a dialog that listed all my outfits and had buttons with the common operations to perform on each one. Creating nested folders is an advanced user operation.

Witness Microsoft and Apple's recent Save As... dialogs. Apple defaults you to selecting a name for the file and one item from a menu of recent destination directories, defaulting to the Documents folder.

[[User:James Linden|James Linden]] 16:40, 12 March 2007 (PDT)

How the camera works

2007-02-22T05:33:15Z

James Linden:

{{ViewerArchNav}}

The viewer is authoritative about camera position. The server uses the client's reported camera position to decide which objects to transmit to the client.

Second Life uses a different coordinate frame than OpenGL. Our frame is X-at, Y-right, Z-up.

The viewer camera is implemented in newview/llviewercamera.cpp based on llmath/llcamera.cpp.

The camera position and look-at vector is transmitted by send_agent_update() in llviewermessage.cpp. This function is called once per frame and can transmit packets up to 20 times per second. Note that it does not transmit unless the agent or camera position or rotation have changed.

Camera movement can be accomplished with the keyboard (Ctrl-Alt-AWSD) or mouse (Alt-drag). Movement commands call into LLAgent::cameraOrbitAround() and similar functions. This accumulates motion and rotation through the frame.

The camera has several "modes", including third person, first person ("mouselook"), appearance editing, etc. These are managed in LLAgent, not LLViewerCamera.

How the camera works

2006-11-04T00:52:28Z

James Linden:

The viewer is authoritative about camera position. The server uses the client's reported camera position to decide which objects to transmit to the client.

Second Life uses a different coordinate frame than OpenGL. Our frame is Z-at, X-up, Y-right.

The viewer camera is implemented in newview/llviewercamera.cpp based on llmath/llcamera.cpp.

The camera position and look-at vector is transmitted by send_agent_update() in llviewermessage.cpp. This function is called once per frame and can transmit packets up to 20 times per second. Note that it does not transmit unless the agent or camera position or rotation have changed.

Camera movement can be accomplished with the keyboard (alt-AWSD) or mouse (Alt-drag). Movement commands call into LLAgent::cameraOrbitAround() and similar functions. This accumulates motion and rotation through the frame.

The camera has several "modes", including third person, first person ("mouselook"), appearance editing, etc. These are managed in LLAgent, not LLViewerCamera.

How movement works

2006-11-04T00:00:06Z

James Linden:

{{OSWikiLearnBox|parent=Viewer architecture}}
The server is authoritative about agent position. The client is authoritative about camera position and rotation.

The viewer sends an upstream packet up to 20 times per second with information about movement keys (forward, backward, up, down). The message is named "AgentUpdate" and contains a U32 "ControlFlags". The control flag constants are in llagentconstants.h.

The agent is physically simulated on the simulator as a vertically stretched sphere. It is moved by application of impulses. In order to impart velocity with brief keypresses the viewer first sends a "nudge", then the normal key press. See AGENT_CONTROL_NUDGE_AT_POS.

The agent can be moved with the arrow keys or with ASWD when the chat bar is closed. The viewer maintains its own view of which keys are down during any particular frame. This is maintained in LLKeyboard (llkeyboard.cpp).

Every frame, LLKeyboard::scanKeys() is called, resulting in calls to functions like agent_push_forward() in llviewerkeyboard.cpp. The key to function mapping is provided in the file app_settings/keys.ini. These functions set variables in LLAgent indicating what keys have been pushed that frame by calling functions like LLAgent::moveAt() or LLAgent::moveYaw(). This sets an internal mControlFlags mask.

Once per frame, send_agent_update() in llviewermessage.cpp is called. This constructs the complete set of control flags for the agent and, if different, transmits the new set to the server. The server then handles computation of current position and transmits the position back through the ObjectUpdate pathway used for all object position transmission.

Note that agent positions are velocity and acceleration interpolated, so if there is a delay in network transmission the agent may appear to move through a wall or floor. The client does not perform collision detection.

How movement works

2006-11-03T23:25:07Z

James Linden:

The server is authoritative about agent position. The client is authoritative about camera position and rotation.

The viewer sends an upstream packet up to 20 times per second with information about movement keys (forward, backward, up, down). The message is named "AgentUpdate" and contains a U32 "ControlFlags". The control flag constants are in llagentconstants.h.

The agent is physically simulated on the simulator as a vertically stretched sphere. It is moved by application of impulses. In order to impart velocity with brief keypresses the viewer first sends a "nudge", then the normal key press. See AGENT_CONTROL_NUDGE_AT_POS.

The agent can be moved with the arrow keys or with ASWD when the chat bar is closed. The viewer maintains its own view of which keys are down during any particular frame. This is maintained in LLKeyboard (llkeyboard.cpp).

Every frame, LLKeyboard::scanKeys() is called, resulting in calls to functions like agent_push_forward() in llviewerkeyboard.cpp. The key to function mapping is provided in the file app_settings/keys.ini. These functions set variables in LLAgent indicating what keys have been pushed that frame by calling functions like LLAgent::moveAt() or LLAgent::moveYaw(). This sets an internal mControlFlags mask.

Once per frame, send_agent_update() in llviewermessage.cpp is called. This constructs the complete set of control flags for the agent and, if different, transmits the new set to the server. The server then handles computation of current position and transmits the position back through the ObjectUpdate pathway used for all object position transmission.

Note that agent positions are velocity and acceleration interpolated, so if there is a delay in network transmission the agent may appear to move through a wall or floor. The client does not perform collision detection.

Server architecture

2006-11-03T22:40:06Z

James Linden:

{{OSWikiLearnBox}}

This wiki is mainly focused on the viewer, since that is the portion of the system that is open source. However, because the viewer interacts with the Second Life servers in somewhat complicated ways, it is helpful to have an understanding of what components do what on the server side.

Much of what you'll need to understand is actually covered in the [[protocol|protocol documentation]]. In particular, take a look at [[Authentication Flow]], which outlines the process by which the viewer establishes connections with a number of components.

==== login server ====
CGI script running on login.agni.lindenlab.com. Handles verification of user name and password. Determines the login region based on home vs. last location vs. URL specified location. Finds the simulator process running that region and verifies user is allowed to connect there. Alerts the simulator to expect a connection. Informs the viewer of where to connect.

==== userserver ====
Historically, the user server handled login. Now it handles instant message sessions, particularly for groups.

==== spaceserver ====
Handles routing of messages based on grid x,y locations.

==== dataserver ====
Handles connections to the central database, log database, inventory database(s) and search database(s). Performs queries on behalf of the simulator process.

==== simulator ====
The primary SL server process. Each simulator process simulates one 256x256 meter region. As the viewer moves through the world it is handled off from one simulator to another. It handles storing object state, land parcel state, and terrain height-map state. It performs visibility calculations on objects and land and transmits the data to the client. It transmits image data in a prioritized queue. Physics simulation is handled with the Havok physics library. Chat and instant messages are processed here.

Server architecture

2006-11-03T22:39:16Z

James Linden:

{{OSWikiLearnBox}}

This wiki is mainly focused on the viewer, since that is the portion of the system that is open source. However, because the viewer interacts with the Second Life servers in somewhat complicated ways, it is helpful to have an understanding of what components do what on the server side.

Much of what you'll need to understand is actually covered in the [[protocol|protocol documentation]]. In particular, take a look at [[Authentication Flow]], which outlines the process by which the viewer establishes connections with a number of components.

==== login server ====
CGI script running on login.agni.lindenlab.com. Handles verification of user name and password. Determines the login region based on home vs. last location vs. URL specified location. Finds the simulator process running that region and verifies user is allowed to connect there. Alerts the simulator to expect a connection. Informs the viewer of where to connect.

==== userserver ====
Historically, the user server handled login. Now it handles instant message sessions, particularly for groups.

==== spaceserver ====
Handles routing of messages based on grid x,y locations.

=== dataserver ====
Handles connections to the central database, log database, inventory database(s) and search database(s). Performs queries on behalf of the simulator process.

==== simulator ====
The primary SL server process. Each simulator process simulates one 256x256 meter region. As the viewer moves through the world it is handled off from one simulator to another. It handles storing object state, land parcel state, and terrain height-map state. It performs visibility calculations on objects and land and transmits the data to the client. It transmits image data in a prioritized queue. Physics simulation is handled with the Havok physics library. Chat and instant messages are processed here.

Documentation

2006-11-03T20:20:42Z

James Linden:

{{OSWikiLearnBox}}
A lot of the documentation below is geared toward developers. However, many aspects of the system don't require a deep technical background to learn. Much of this is still a work in progress, but since this is a wiki, you can help fill in the blanks!

* '''[[Features]]''' - An overview of the major components of the system as seen from an end user's perspective. Links to specifications, test plans and other documentation can be found here.
* '''[[Glossary]]''' - System terminology
* '''[[Viewer architecture]]''' - Overview of the viewer from a developer's perspective.
* '''[[Protocol]]''' - In-depth documentation of the protocol.
* '''[[Third Party Libraries]]''' - The third party libraries used by the viewer.
* '''[[Server architecture]]''' - Brief description of server processes with which the viewer communicates.

Adding a dialog

2006-11-03T20:09:41Z

James Linden:

{{OSWikiLearnBox|parent=Viewer architecture}}
Windows and dialogs in Second Life are implemented as LLFloater objects. The class hierarchy is:

LLFloaterFoo - a "foo" dialog
LLFloater - generic window or dialog with close box, minimize box, etc.
LLPanel - rectangular area with dark background, has functions like childSetText(), childGetValue()
LLUICtrl - any widget that can take keyboard focus
LLView - base class, container for UI widget children

Create a new C++ header and source file to hold your new class. By convention these are called llfloaterfoo.h and .cpp. Place them in the newview directory.

You'll also need a new XML description file. These are found in the indra/newview/skins/xui/en-us directory. It's easiest to copy an existing file and modify it. Name the new file floater_foo.xml.

'''Important''' - Second Life UI uses OpenGL coordinates, so 0,0 is at the '''bottom''' left corner.

Let's make a floater that has a text label "bar", a text line input field "baz", and a button "hippo".

A basic floater header looks like this:

<pre>
#include "llfloater.h"

class LLFloaterFoo : public LLFloater
{
public:
LLFloaterFoo();

// by convention, this shows the floater and does instance management
static void show(void*);

private:
// when a line editor loses keyboard focus, it is committed.
// commit callbacks are named onCommitWidgetName by convention.
void onCommitBaz(LLUICtrl* ctrl, void *userdata);

// by convention, button callbacks are named onClickButtonLabel
void onClickHippo(void* userdata);

// no pointers to widgets here - they are referenced by name
};

The XML data definition should look like this:

<pre>
<?xml version="1.0" encoding="utf-8" standalone="yes"?>



<floater
name="foo_floater"
title="Foo"
can_resize="true"
can_minimize="true"
can_close="true"
can_drag_on_left="false"
width="275"
height="250"
min_width="80"
min_height="220"
>



<text name="bar_text"
font="SansSerifSmall"
left="10"
bottom_delta="-40"
width="260"
height="16"
follows="left|top"
>
bar is a generic programming identifier
</text>



<line_editor
name="baz_edit"
width="120"
height="20"
left="10"
bottom_delta="-30"
follows="left|bottom"
hidden="false"
mouse_opaque="true"
max_length="31"
font="SansSerif"
bevel_style="in"
border_style="line"
border_thickness="1"
select_all_on_focus_received="true"
/>



<button
name="hippo_btn"
label="Hippo"
font="SansSerifSmall"
left="10"
bottom_delta="-25"
width="100"
height="20"
follows="bottom|left"
/>
</floater>
</pre>

The C++ code for this floater looks like:

<pre>
#include "llviewerprecompiledheaders.h" // must be first include

#include "llfloaterfoo.h"

#include "llvieweruictrlfactory.h" // builds floaters from XML

LLFloaterFoo::LLFloaterFoo()
: LLFloater("floater_foo")
{
gUICtrlFactory->buildFloater(this, "floater_foo.xml");

childSetCommitCallback("baz_edit", onCommitBaz, this);

childSetAction("hippo_btn", onClickHippo, this);
setDefaultBtn("hippo_btn");
}

// static
void LLFloaterFoo::show(void*)
{
LLFloaterFoo* self = new LLFloaterFoo();
self->open();
}

// static
void LLFloaterFoo::onCommitBaz(LLUICtrl* ctrl, void* userdata)
{
LLFloaterFoo* self = (LLFloaterFoo*)userdata;
LLString text = self->childGetText("baz_edit");
llinfos << "baz contains: " << text << llendl;
}

// static
void LLFloaterFoo::onClickHippo(void* userdata)
{
LLFloaterFoo* self = (LLFloaterFoo*)userdata;
llinfos << "Hippo! from " << self->getName() << llendl;
}

</pre>

Finally, to test out this floater you'll need to add a menu item that calls the show() method. See [Adding a menu item].

Adding a dialog

2006-11-03T18:45:09Z

James Linden:

Windows and dialogs in Second Life are implemented as LLFloater objects. The class hierarchy is:

LLFloaterFoo - a "foo" dialog
LLFloater - generic window or dialog with close box, minimize box, etc.
LLPanel - rectangular area with dark background, has functions like childSetText(), childGetValue()
LLUICtrl - any widget that can take keyboard focus
LLView - base class, container for UI widget children

Create a new C++ header and source file to hold your new class. By convention these are called llfloaterfoo.h and .cpp. Place them in the newview directory.

You'll also need a new XML description file. These are found in the indra/newview/skins/xui/en-us directory. It's easiest to copy an existing file and modify it. Name the new file floater_foo.xml.

'''Important''' - Second Life UI uses OpenGL coordinates, so 0,0 is at the '''bottom''' left corner.

Let's make a floater that has a text label "bar", a text line input field "baz", and a button "hippo".

A basic floater header looks like this:

#include "llfloater.h"

class LLFloaterFoo : public LLFloater
{
public:
LLFloaterFoo();
virtual ~LLFloaterFoo();

// by convention, this shows the floater and does instance management
static void show(void*);

private:
// when a line editor loses keyboard focus, it is committed.
// commit callbacks are named onCommitWidgetName by convention.
void onCommitBaz(LLUICtrl* ctrl, void *userdata);

// by convention, button callbacks are named onClickButtonLabel
void onClickHippo(void* userdata);

// no points to widget here - they are referenced by name
};

The XML data definition should look like this:

<pre>
<?xml version="1.0" encoding="utf-8" standalone="yes"?>



<floater
name="foo_floater"
title="Foo"
can_resize="true"
can_minimize="true"
can_close="true"
can_drag_on_left="false"
width="275"
height="250"
min_width="80"
min_height="220"
>



<text name="bar_text"
font="SansSerifSmall"
left="10"
bottom_delta="-40"
width="260"
height="16"
follows="left|top"
>
bar is a generic programming identifier
</text>



<button
name="hippo_btn"
label="Hippo"
font="SansSerifSmall"
left="10"
bottom_delta="-25"
width="100"
height="20"
follows="top|left"
/>
</floater>
</pre>

Adding a dialog

2006-11-03T18:27:09Z

James Linden:

Adding a menu item

2006-11-01T20:21:59Z

James Linden:

Menu items in the viewer are specified in XML files, located in the indra/newview/skins/xui/en-us/ directory.

There are separate XML files for various categories of menu. They are:
menu_viewer.xml - top of screen
menu_inventory.xml - right-click on inventory item
menu_pie_attachment.xml - right-click on your own attachment
menu_pie_avatar.xml - right-click on other avatar or their attachments
menu_pie_land.xml - right-click on land
menu_pie_self.xml - right-click on your avatar

The menu callbacks are set up in llviewermenu.cpp.

Let's add a menu item named "Foo" to the Tools menu.
* In menu_viewer.xml find the "Tools" menu item. It is inside a <menu> tag.
* Tear-off sub menus use the <tearoff_menu> tag.
* Find the "Reset Scripts in Selection" menu item.
* After it, add the following text:
<menu_item_call label="Foo" enabled="true" name="foo_menu">
<on_click function="Tools.Foo" userdata="" />
</menu_item_call>
* This sets up a menu item that will call a function. It can be referenced in C++ by the name "foo_menu". The user-visible label is "Foo". It defaults to enabled.
* Open newview/llviewermenu.cpp
* Create an event handler class for this menu item. By convention these are named after the menu name and item name.
class LLToolsFoo : public view_listener_t
{
bool handleEvent(LLPointer<LLEvent> event, const LLSD& userdata)
{
llinfos << "foo!" << llendl;
return true;
}
};
* This class will listen for events from a "view", the base class for all UI widgets. LLPointer is a reference counting smart pointer. LLSD is a structured data class similar to a Perl or Python variable - it can hold data of any type.
* llinfos is the output stream for informational messages. It goes to the ctrl-shift-4 debug console, stdout, and the log file.

* Now associate the "Tools.Foo" function with a C++ class. Open newview/llviewermenu.cpp.
* In the function initialize_menu_actions() add the line:
(new LLToolsFoo())->registerListener(gMenuHolder, "Tools.Foo");
* This makes your LLToolsFoo class listen to events from the gMenuHolder, a view which contains all the menu UI widgets.
* It also associates this listener with the "Tools.Foo" event.

Compile and run!

Glossary

2006-11-01T18:48:58Z

James Linden:

==== SL ====
Common abbreviation for Second Life

==== Viewer ====
Client software, written in C++, that runs on the user’s Windows, Macintosh, or Linux computer. The process is named “newview” for historical reasons.

==== Simulator ====
The primary SL server process. Each simulator process simulates one 256x256 meter region. As the viewer moves through the world it is handled off from one simulator to another. Multiple simulator processes run on each server host, currently 2 to 16.

==== Sim ====
Server host machine, for example sim1234.agni.lindenlab.com. The SL server grid consists of 2000+ sims. Sometimes “sim” is used incorrectly to mean simulator process or region.

==== Host ====
Any server computer, but usually a sim.

==== Region ====
Data set for a region of the world, like “Orientation Island” or “Ahern”. A region can be run by any simulator process, and regions move from sim to sim as the hosts are shut down, crash, etc.

==== Grid ====
A collection of sims. Linden Lab runs several grids for internal and external testing.

==== Farm ====
synonym for grid.

==== Agni ====
The primary SL grid to which users connect.

==== Parcel ====
An area of land owned by a single user or group. Parcels are composed of square blocks measuring 4x4 meters, but the blocks do not have to be contiguous. Parcels have both an integer local id and a global UUID.

==== Estate ====
A collection of regions with a particular set of rules, such as banned users, sun position, etc. Each estate has an owner, either a user or “Governor Linden”. Most privately owned regions are in their own estates. Estates have integer identifiers. The “mainland” is estate id 1.

==== Avatar ====
The graphical representation of a user. Implemented in the class LLVOAvatar on the viewer.

==== Agent ====
The data representation of the current user. In general “agent” means you and “avatar” means someone else. Identified by a UUID, usually called “agent_id” in the code.

==== Asset ====
A data resource such as an image, sound, script, object, etc. Assets can be downloaded to the viewer or uploaded into a central asset store. Assets are identified by UUID and type. Types are in llassettype.h.

==== Texture ====
An image applied to the surface of an object.

==== Floater ====
A dialog or window appearing in the user interface. Implemented in classes titled “LLFloater*”

==== Vector ====
An array of floating point values used to represent positions, colors, etc. Implemented in LLVector3, LLVector4, LLColor4, etc.

==== Quaternion ====
Representation of a rotation. SL uses unit quaternions represented in four floats. This allows only three floats to be transmitted and the remaining value reconstructed on the viewer. See GameDev article on [http://www.gamedev.net/reference/articles/article1095.asp quaternions].

==== Message Template ====
The protocol description for UDP packet communication between the viewer and servers. Described in the text file app_settings/message_template.msg.

==== LSL ====
Linden Scripting Language, a C-like language used for server-side scripting of objects.

==== Primitive ====
3D object in the world. Each prim is represented by a set of parameters, including position, scale, rotation, shape, cut, hollow, etc. Prims can be linked together into link sets. They can also be attached to avatars, but this process is separate from linking. Primitives are implemented in LLPrimitive, with vertex generation performed in LLVolume and rendering in LLVOVolume.

==== Prim ====
Abbreviation for primitive.

==== Task ====
Server-side representation of a primitive or link set. Since primitives can contain scripts or be physically simulated each task adds load to the server process. The agent is also represented as a task on the server, but has extensive additional processing.

==== FMOD ====
Cross-platform audio library. Used to play decompressed sound effects and stream MP3 music to users on particular parcels. See [http://www.fmod.org/ FMOD.org].

==== JPEG2000 ====
Wavelet based image compression format. Inherently progressive, so images can be displayed with only partial data available, without increases in file size. See the Wikipedia entry on [http://en.wikipedia.org/wiki/JPEG_2000 JPEG2000].

==== Kakadu ====
Cross-platform high-performance JPEG2000 library. Linden Lab does not have redistribution rights to Kakadu so the open source viewer ships with [http://www.openjpeg.org/ OpenJPEG].

==== Ogg Vorbis ====
Open source audio compression library. Sound effects are stored as .ogg files in the asset system. See Ogg Vorbis.

==== UUID ====
Globally unique identifier, a 128-bit number represented as a 16-byte binary value or 36-byte hexadecimal string. UUIDs can be generated by any part of the system and are guaranteed to be unique.

Glossary

2006-11-01T18:34:04Z

James Linden:

Second Life Terminology

== SL ==
Common abbreviation for Second Life

=== Viewer ===
Client software, written in C++, that runs on the user’s Windows, Macintosh, or Linux computer. The process is named “newview” for historical reasons.

==== Simulator ====
The primary SL server process. Each simulator process simulates one 256x256 meter region. As the viewer moves through the world it is handled off from one simulator to another. Multiple simulator processes run on each server host, currently 2 to 16.

Sim – Server host machine, for example sim1234.agni.lindenlab.com. The SL server grid consists of 2000+ sims. Sometimes “sim” is used incorrectly to mean simulator process or region.

Host – Any server computer, but usually a sim.

Region – Data set for a region of the world, like “Orientation Island” or “Ahern”. A region can be run by any simulator process, and regions move from sim to sim as the hosts are shut down, crash, etc.

Grid – A collection of sims. Linden Lab runs several grids for internal and external testing.

Farm – synonym for grid.

Agni – The primary SL grid to which users connect.

Parcel – An area of land owned by a single user or group. Parcels are composed of square blocks measuring 4x4 meters, but the blocks do not have to be contiguous. Parcels have both an integer local id and a global UUID.

Estate – A collection of regions with a particular set of rules, such as banned users, sun position, etc. Each estate has an owner, either a user or “Governor Linden”. Most privately owned regions are in their own estates. Estates have integer identifiers. The “mainland” is estate id 1.

Avatar – The graphical representation of a user. Implemented in the class LLVOAvatar on the viewer.

Agent – The data representation of the current user. In general “agent” means you and “avatar” means someone else. Identified by a UUID, usually called “agent_id” in the code.

Asset – A data resource such as an image, sound, script, object, etc. Assets can be downloaded to the viewer or uploaded into a central asset store. Assets are identified by UUID and type. Types are in llassettype.h.

Texture – An image applied to the surface of an object.

Floater – A dialog or window appearing in the user interface. Implemented in classes titled “LLFloater*”

Vector – An array of floating point values used to represent positions, colors, etc. Implemented in LLVector3, LLVector4, LLColor4, etc.

Quaternion – Representation of a rotation. SL uses unit quaternions represented in four floats. This allows only three floats to be transmitted and the remaining value reconstructed on the viewer. See GameDev article on [[http://www.gamedev.net/reference/articles/article1095.asp quaternions]].

Message Template – The protocol description for UDP packet communication between the viewer and servers. Described in the text file app_settings/message_template.msg.

LSL – Linden Scripting Language, a C-like language used for server-side scripting of objects.

Prim/Primitive – 3D object in the world. Each prim is represented by a set of parameters, including position, scale, rotation, shape, cut, hollow, etc. Prims can be linked together into link sets. They can also be attached to avatars, but this process is separate from linking. Primitives are implemented in LLPrimitive, with vertex generation performed in LLVolume and rendering in LLVOVolume.

Task – Server-side representation of a primitive or link set. Since primitives can contain scripts or be physically simulated each task adds load to the server process. The agent is also represented as a task on the server, but has extensive additional processing.

FMOD – Cross-platform audio library. Used to play decompressed sound effects and stream MP3 music to users on particular parcels. See FMOD.

JPEG2000 – Wavelet based image compression format. Inherently progressive, so images can be displayed with only partial data available, without increases in file size. See JPEG2000.

Kakadu – Cross-platform high-performance JPEG2000 library. Linden Lab does not have redistribution rights to Kakadu so the open source viewer ships with OpenJPEG.

Ogg Vorbis – Open source audio compression library. Sound effects are stored as .ogg files in the asset system. See Ogg Vorbis.

UUID – Globally unique identifier, a 128-bit number represented as a 16-byte binary value or 36-byte hexadecimal string. UUIDs can be generated by any part of the system and are guaranteed to be unique.

Glossary

2006-11-01T18:19:45Z

James Linden:

Second Life Terminology

SL – Common abbreviation for Second Life

Viewer – Client software, written in C++, that runs on the user’s Windows, Macintosh, or Linux computer. The process is named “newview” for historical reasons.

Simulator – The primary SL server process. Each simulator process simulates one 256x256 meter region. As the viewer moves through the world it is handled off from one simulator to another. Multiple simulator processes run on each server host, currently 2 to 16.

Sim – Server host machine, for example sim1234.agni.lindenlab.com. The SL server grid consists of 2000+ sims. Sometimes “sim” is used incorrectly to mean simulator process or region.

Host – Any server computer, but usually a sim.

Region – Data set for a region of the world, like “Orientation Island” or “Ahern”. A region can be run by any simulator process, and regions move from sim to sim as the hosts are shut down, crash, etc.

Grid – A collection of sims. Linden Lab runs several grids for internal and external testing.

Farm – synonym for grid.

Agni – The primary SL grid to which users connect.

Parcel – An area of land owned by a single user or group. Parcels are composed of square blocks measuring 4x4 meters, but the blocks do not have to be contiguous. Parcels have both an integer local id and a global UUID.

Estate – A collection of regions with a particular set of rules, such as banned users, sun position, etc. Each estate has an owner, either a user or “Governor Linden”. Most privately owned regions are in their own estates. Estates have integer identifiers. The “mainland” is estate id 1.

Avatar – The graphical representation of a user. Implemented in the class LLVOAvatar on the viewer.

Agent – The data representation of the current user. In general “agent” means you and “avatar” means someone else. Identified by a UUID, usually called “agent_id” in the code.

Asset – A data resource such as an image, sound, script, object, etc. Assets can be downloaded to the viewer or uploaded into a central asset store. Assets are identified by UUID and type. Types are in llassettype.h.

Texture – An image applied to the surface of an object.

Floater – A dialog or window appearing in the user interface. Implemented in classes titled “LLFloater*”

Vector – An array of floating point values used to represent positions, colors, etc. Implemented in LLVector3, LLVector4, LLColor4, etc.

Quaternion – Representation of a rotation. SL uses unit quaternions represented in four floats. This allows only three floats to be transmitted and the remaining value reconstructed on the viewer. See Quaternion.

Message Template – The protocol description for UDP packet communication between the viewer and servers. Described in the text file app_settings/message_template.msg.

LSL – Linden Scripting Language, a C-like language used for server-side scripting of objects.

Prim/Primitive – 3D object in the world. Each prim is represented by a set of parameters, including position, scale, rotation, shape, cut, hollow, etc. Prims can be linked together into link sets. They can also be attached to avatars, but this process is separate from linking. Primitives are implemented in LLPrimitive, with vertex generation performed in LLVolume and rendering in LLVOVolume.

Task – Server-side representation of a primitive or link set. Since primitives can contain scripts or be physically simulated each task adds load to the server process. The agent is also represented as a task on the server, but has extensive additional processing.

FMOD – Cross-platform audio library. Used to play decompressed sound effects and stream MP3 music to users on particular parcels. See FMOD.

JPEG2000 – Wavelet based image compression format. Inherently progressive, so images can be displayed with only partial data available, without increases in file size. See JPEG2000.

Kakadu – Cross-platform high-performance JPEG2000 library. Linden Lab does not have redistribution rights to Kakadu so the open source viewer ships with OpenJPEG.

Ogg Vorbis – Open source audio compression library. Sound effects are stored as .ogg files in the asset system. See Ogg Vorbis.

UUID – Globally unique identifier, a 128-bit number represented as a 16-byte binary value or 36-byte hexadecimal string. UUIDs can be generated by any part of the system and are guaranteed to be unique.

Viewer Architecture

2006-10-31T00:52:45Z

James Linden:

{{OSWikiLearnBox}}

The Second Life client (also known as the "viewer") is a complex piece of software. It can be visualized as a streaming media client like RealPlayer, a game engine like Quake 3, or a web browser.

First you'll need to learn some [[Second Life Terminology]], like "agent", "sim", and "region".

If you like to learn by example, you can learn about:
* [[Adding a menu item]]
* [[Adding a dialog]]
* [[How movement works]]
* [[How the camera works]]
* [[How login works]]
* [[How keyboard processing works]]
* [[How scripts work]]

If you prefer a more hierarchical approach, the viewer is built from:
* [[Message System]] - reliable and unreliable transport over UDP
* [[Image System]] - prioritizes and decodes JPEG2000 images into OpenGL textures
* [[Viewer Object System]] - objects in scene for rendering and editing
* [[Rendering System]] - from viewer object to drawable to face to vertices to graphics card
* [[Culling]] - octree and occlusion based culling to speed rendering
* [[UI Widgets]] - cross platform buttons, scroll bars, etc.
* [[UI Floaters]] - dialogs and windows built from XML files
* [[Asset System]] - transport for animations, sounds, notecards, scripts, etc.
* [[Inventory]] - server-side storage of assets for each user
* [[Sound System]] - cross platform audio based on FMOD
* [[Movie System]] - QuickTime-based video on object surfaces
* [[VFS]] - cached data is held in two "virtual file systems" in large files on the client
* [[Selection Manager]] - holds extended information for selected objects and allows editing
* [[Avatar Appearance]] - appearance is constructed from a mesh, parameters to deform the mesh, and textures to describe clothing
* [[Avatar Profiles]]
* [[Groups]]
* [[Money]]

== Threads ==
The viewer is a single process with a few threads:
* Main thread -- The input/output main program function.
* VFS Thread -- Thread responsible for reading/writing to the virtual file system.
* LFS Thread -- Thread responsible for some reading/writing to the local file system. Not sure if this is actually used anywhere.

== Program Flow ==
* Initialize
* Loop
** Gathers input
** Pumps the TCP i/o
** Render the frame
**
* Shutdown

Documentation

2006-10-31T00:36:59Z

James Linden:

{{OSWikiLearnBox}}
A lot of the documentation below is geared toward developers. However, many aspects of the system don't require a deep technical background to learn. Much of this is still a work in progress, but since this is a wiki, you can help fill in the blanks!

* '''[[Features]]''' - An overview of the major components of the system as seen from an end user's perspective. Links to specifications, test plans and other documentation can be found here.
* '''[[Viewer architecture]]''' - Overview of the viewer from a developer's perspective.
* '''[[Protocol]]''' - In-depth documentation of the protocol.
* '''[[Third Party Libraries]]''' - The third party libraries used by the viewer.

Documentation

2006-10-31T00:36:37Z

James Linden:

{{OSWikiLearnBox}}
A lot of the documentation below is geared toward developers. However, many aspects of the system don't require a deep technical background to learn. Much of this is still a work in progress, but since this is a wiki, you can help fill in the blanks!

* '''[[Features]]''' - An overview of the major components of the system as seen from an end user's perspective. Links to specifications, test plans and other documentation can be found here.
* '''[[Viewer Architecture]]''' - Overview of the viewer from a developer's perspective.
* '''[[Protocol]]''' - In-depth documentation of the protocol.
* '''[[Third Party Libraries]]''' - The third party libraries used by the viewer.