Second Life Wiki - User contributions [en]

LSL HTTP server

2022-11-16T09:54:20Z

Fenchurch Oh: Previous text "Testing this have it has been found that..." made ZERO sense.

{{LSL Header|ml=*}}

= Introduction =

This is the counterpart to [[llHTTPRequest]]. While [[llHTTPRequest]] enables [[Script|LSL scripts]] to request data from HTTP-accessible sources, HTTP-in enables outside sources to request data from [[Script|LSL scripts]] in Second Life. The key difference is that [[llHTTPRequest]] exchanges data when the script in SL wants; HTTP-in allows outside sources to determine when they need to communicate with [[Script|LSL scripts]] in SL.

Prior to HTTP-in, similar functionality could be achieved by [[HTTP Polling|polling]] with [[llHTTPRequest]], [[llEmail]] and [[:Category:LSL_XML-RPC|XML-RPC]]. All three are cumbersome and the latter two have serious scalability bottlenecks.

It is important to note that [[LSL HTTP server|LSL HTTP servers]] cannot use [[llSetContentType]] with [[CONTENT_TYPE_HTML]] for an [[llHTTPResponse]] except in very limited circumstances. See [[#Other_Limitations|Other Limitations]] for details.

'''This section forms the [[:Category:LSL HTTP#Understanding_LSL_HTTP_Communications | Incoming]] HTTP pipeline.'''

= Uses =

* Easily get data from [[Script|LSL scripts]] to outside viewers, [[Script|LSL scripts]] or servers.
** Web front end for a visitor counter or other statistics accumulator.
* Easily get data into [[Script|LSL scripts]] from outside viewers, [[Script|LSL scripts]] or servers.
** A store with a web front end that communicates to an in-world object to exchange L$ and inventory items.
** Inworld game for which an external program handles the primary game logic that needs to manipulate inworld items.
* HUD UI when used with [[llSetContentType]]. See [[HTML HUD Demo]].
Gory Technical Details follow. Or jump straight to the [[LSL_http_server/examples | Script Examples]].

= Script API =

== Events ==
* '''[[http_request|http_request(key id, string method, string body)]]'''
: Event triggered when an URL is hit:
:* id is unique to this request
:* Supported methods are <code>"GET"</code>, <code>"POST"</code>, <code>"PUT"</code>, <code>"DELETE"</code>
:* body: The body of the request.
: Event also triggered with response to [[llRequestURL]] and [[llRequestSecureURL]]
:* id matches the key returned by [[llRequestURL]] or [[llRequestSecureURL]]
:* method == [[URL_REQUEST_GRANTED]] for success, [[URL_REQUEST_DENIED]] for failure to get an URL
:* body is the public URL. If unable to get a public URL body will be empty.
* '''[[Changed|changed(integer change)]]'''
:* [[CHANGED_REGION_START]]: New [[changed]] [[event]] triggered on region startup.
:* [[CHANGED_REGION]]: New [[changed]] [[event]] triggered when crossing regions or teleporting. Please read [[CHANGED_REGION]] for more info.
:* [[CHANGED_TELEPORT]]: New [[changed]] [[event]] triggered when the avatar teleports. Please read [[CHANGED_TELEPORT]] for more info.

== Functions ==
{{LSL Function/Head
|func_id=345|func_sleep=0.0|func_energy=10.0
|func=llRequestURL
|func_desc=Requests one HTTP:// url for use by the script. The [[http_request]] [[event]] is triggered with the result of the request. HTTP-in uses port 12046.
|return_type=key|return_text=that is the handle used for identifying the result in the [[http_request]] [[event]].
|func_footer
|caveats=none
}}
{{LSL Function/Head
|func_id=346|func_sleep=0.0|func_energy=10.0
|func=llRequestSecureURL
|func_desc=Requests one HTTPS:// (SSL) url for use by the script. The [[http_request]] [[event]] is triggered with the result of the request. HTTPS-in uses port 12043.
|return_type=key|return_text=that is the handle used for identifying the result in the [[http_request]] [[event]].
|func_footer
|caveats=none
}}
{{LSL Function/Head
|func_id=347|func_sleep=0.0|func_energy=10.0
|func=llReleaseURL
|p1_type=string|p1_name=url|p1_desc=URL to release
|func_desc=Releases the specified URL, it will no longer be usable.
|func_footer
|caveats=none
}}
{{LSL Function/Head
|func_id=348|func_sleep=0.0|func_energy=10.0
|func=llHTTPResponse
|p1_type=key|p1_name=request_id|p1_desc=A valid HTTP request key
|p2_type=integer|p2_name=status|p2_desc=[http://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP_Status] (200, 400, 404, etc)
|p3_type=string|p3_name=body|p3_desc=Contents of the response.
|func_desc=Responds to {{LSLP|request_id}} with {{LSLP|status}} and {{LSLP|body}}.
|func_footer=The response need not be made inside the [[http_request]] [[event]] but if it does not happen in a timely fashion the request will time out (within 25 seconds).
|caveats=none
}}
{{LSL Function/Head
|func_id=344|func_sleep=0.0|func_energy=10.0
|func=llGetFreeURLs
|return_type=integer|return_text=that is the number of available URLs.
|caveats=none
}}
{{LSL Function/Head
|func_id=349|func_sleep=0.0|func_energy=10.0
|func=llGetHTTPHeader
|p1_type=key|p1_name=request_id|p1_desc=A valid HTTP request key
|p2_type=string|p2_name=header|p2_desc=Lower case header value name
|return_type=string|return_text=that is the value for {{LSLP|header}} for {{LSLP|request_id}}.
|func_footer=Returns an empty [[string]] if the {{LSLP|header}} is not found or if the headers can no longer be accessed. Headers can only be accessed before [[llHTTPResponse]] is called and with-in the first 30 seconds after the [[http_request]] [[event]] is queued.

====Generated Headers====
These headers are automatically generated by the simulator, they were not actually sent by the requesting client. They supply information about the request to make parsing easier.

Sample URL: [https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322/foo/bar?arg=gra {{HoverTextStyle|style=color:green;|<nowiki>https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322</nowiki>|2={{String|x-script-url}} = {{String|https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322}}}}{{HoverTextStyle|style=color:blue;|/foo/bar|2={{String|x-path-info}} = {{String|/foo/bar}}}}?{{HoverTextStyle|style=color:red;|1=arg=gra|2={{String|x-query-string}} = {{String|1=arg=gra}}}}]

{{{!}} class="lltable" border="1"
! header
! description
! example
{{!}}-
{{!}} style="white-space: nowrap;" {{!}} "x-script-url"
{{!}} The base url, as originally received from [[llRequestURL]]/[[llRequestSecureURL]]
{{!}} <nowiki>https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322</nowiki>
{{!}}-
{{!}} style="white-space: nowrap;" {{!}} "x-path-info"
{{!}} Any trailing path information from the requested url
{{!}} /foo/bar
{{!}}-
{{!}} style="white-space: nowrap;" {{!}} "x-query-string"
{{!}} Any query arguments, the text past the first "?" in the url
{{!}} arg=gra
{{!}}-
{{!}} style="white-space: nowrap;" {{!}} "x-remote-ip"
{{!}} IP address of the host that made the request
{{!}}
{{!}}}

====Common Headers====

{{{!}} class="lltable" border="1"
! header
! description
! example
{{!}}-
{{!}} style="white-space: nowrap;" {{!}} "user-agent"
{{!}} The user-agent header as reported by the requester
{{!}}
{{!}}}

====[[llHTTPRequest]] Headers====
{{LSL_Constants/HTTP_Headers|lower-case=*}}
|caveats=none
}}

= URL Lifetime Limitations =
* URLs are '''temporary'''!
* URLs will be lost in the following cases, all detectable by the script events listed with them.
** On object derez/rez: [[on_rez]]
** On script save/reset: ''[[default]] [[state_entry]] (trickier in multi-state [[Script|LSL scripts]])
** On region cross or TP(attachments): [[changed]] {{LSLGC|Events|event}}, [[CHANGED_REGION]] and [[CHANGED_TELEPORT]]. Testing the latter event, it has been found that teleports within a region DO NOT cause a URL to be lost, therefore you do not need to request a new URL on [[CHANGED_TELEPORT]], because [[CHANGED_REGION]] will handle a teleport to a different region. If you choose to request a URL after a teleport, it is recommended to release the old URL to be sure you don't have too many used. (Stone Tremont Aug 8th 2010)
** On region restart: [[changed]] [[event]], flag [[CHANGED_REGION_START]]
* When urls are 'lost' it means that all public urls for that script are gone, new ones will need to be requested and the new urls will '''not''' resemble the old ones.
* Maintaining persistent URLs will require building or using an external service similar to how [http://en.wikipedia.org/wiki/Dynamic_DNS Dynamic DNS] services work for tying domain names to dynamic IP addresses.

Contributed HTTP-in URL mapping implementations and services:
* A Dynamic DNS service running on Google App Engine (contributed as an example) can be found in the forums [http://wiki.secondlife.com/wiki/User:Darien_Caldwell/HTTP-DNS here].
* Yet another one, running on GAE, with password protected and private domains. http://wiki.secondlife.com/wiki/Public_Object_DNS
* The [http://www.silverday.net/sqndns SilverDay ObjectDNS] is an easy to use dns-mapping-service with many configurable options (password protection, write protection, etc.) and an optional web-interface. The [[Script|LSL scripts]] are available here on the wiki (LSL-Script Library/[[Silverday ObjectDNS]]).

= Resource Limitations =
* There are a limited number of URLs available in each [[region]], split by land ownership exactly like prim limits.
** Use [[llGetFreeURLs]] to get the exact number of available URLs for the script.
** The number of allowed URLs is the same as the number of allowed [[prim|prims]] on the [[Land#Parcel|parcel]] the [[object]] is over.
**: ''Object owner does not matter, all objects over a [[Land#Parcel|parcel]] will use the resource pool for that [[Land#Parcel|parcel]].''
**: ''Like [[prim|prims]], all the [[Land#Parcel|parcels]] owned by the same owner and in the same [[region]] share the same pool of resources.''
**: ''If you have two [[Land#Parcel|parcels]] in a [[region]] that each support 100 URLs, then you could use all 200 in object(s) on a single [[Land#Parcel|parcel]].''
** The [[region]]'s [[object]] bonus factor does not apply to available URLs.
**: ''If a [[Land#Parcel|parcel]] has a max of 300 [[prim|prims]] in a [[region]] with a 2x bonus factor there will only be 150 urls allowed.''
* Each resident has their own unique pool of available URLs with a max of 38 URLs per resident.
** This is 1 per attachment point, but all 38 could be used by a single attachment for example.
* Vehicles are special and lazily moved to resident pools by the following logic:
** Any [[object]] that has a resident sitting on it is a 'vehicle'
** Vehicles will use the url resources from the [[Land#Parcel|parcel]] they are over until the cross a [[Land#Parcel|parcel]] border.
**: ''Specifically this prevents anyone from breaking your vending machine by sitting on it and making it a 'vehicle'.''
** When any [[object]] using URL resources with a resident sitting on it crosses a [[Land#Parcel|parcel]] boundary the resources will switch to the first sitting resident with enough resources. If no sitting agents have enough resources then the resources from the [[Land#Parcel|parcel]] being moved onto will be used. If even then there are not enough resources to use then the vehicle will be blocked from moving.
**: ''In short we do everything we can to find a pool to host the resources needed by the vehicle, but will block movement if we can't.''
* Parcel Sale: When a [[Land#Parcel|parcel]] is sold such that it changes the total available URLs in the [[region]] for either resident (seller or buyer) such that more URLs are being used than are available some objects will be returned.
** The objects returned will be from youngest [[object]] to oldest [[object]] of those using URLs in each category in order of [[object]] category: Temporary, Other, Group, Owner, Selected/Sat upon.
**: ''The '''only''' time objects are possibly returned is when [[Land#Parcel|parcels]] change owner, and only if more resources are being used than allowed.''
**: ''We return youngest temporary objects before older temporary objects before younger 'other' (owned by non-group, non-[[Land#Parcel|parcel]]-owner) objects etc.''

= Other Limitations =
* Size of the body of requests on the '''[[:Category:LSL HTTP#Understanding_LSL_HTTP_Communications | Incoming pipeline]]''' will be [[limit]]ed to 2k [[bytes]], and cannot currently be changed.
* Size of headers of requests will be limited to 255 bytes per header, not total.
* The size of responses to requests is not currently limited, but this is subject to review during testing.
* By default the content type of the returned data is always <code>"text/plain; charset=utf-8"</code>, this however can be changed via [[llSetContentType]] for all subsequent responses via [[llHTTPResponse]].
* There is a cap of 64 in flight requests per script. This is based on the maximum number of pending [[event|events]] in LSL. After hitting the 64 request limit, the simulator cap server returns <code>{{String|503 Service Unavailable}}</code> to the inbound request.
* ''We may throttle the rate we accept hits at the CAP server level as well. This is possible, but has not yet been decided.''
* HTML can be used to in-client browser, including media on a prim, with some restrictions. See [[llSetContentType]] and [[CONTENT_TYPE_HTML]] for further details.
* If making a parser, remember that you should probably restrict access to only Linden Lab HTML URLs as to not have your bandwith stolen. See [[Simulator_IP_Addresses]] for details.
* It is important to note that when appending a query string to a cap URL there '''MUST''' be a trailing slash between the cap guid and the query string token <code>"?"</code>. For example: [https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322?arg=gra {{HoverTextStyle|style=color:green;|<nowiki>https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322</nowiki>|2={{String|x-script-url}} = {{String|https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322}}}}?{{HoverTextStyle|style=color:red;|1=arg=gra|2={{String|x-query-string}} = {{String|1=arg=gra}}}}] will return a 500 HTTP status {{Wikipedia|List_of_HTTP_status_codes#5xx_Server_Error|Server Error code}}, but [https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322/?arg=gra {{HoverTextStyle|style=color:green;|<nowiki>https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322</nowiki>|2={{String|x-script-url}} = {{String|https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322}}}}{{HoverTextStyle|style=color:blue;|/|2={{String|x-path-info}} = {{String|/}}}}?{{HoverTextStyle|style=color:red;|1=arg=gra|2={{String|x-query-string}} = {{String|1=arg=gra}}}}] will succeed.

= Links =
* [[LSL_http_server/examples | Script Examples]]
* [[LSL_http_server/design | Design Document]]
* Design Jira:{{jira|SVC-1086}}

{{LSLC|HTTP}}
{{LSLC|Communications}}

LlSetRemoteScriptAccessPin

2021-03-04T20:41:25Z

Fenchurch Oh: Typo correction.

{{LSL Function
|func_id=252|func_sleep=0.2|func_energy=10.0
|func=llSetRemoteScriptAccessPin
|p1_type=integer|p1_name=pin|p1_desc=zero disables (ie [[llRemoteLoadScriptPin]] will fail), non-zero enables.
|func_desc=Allows a prim to have scripts remotely loaded via [[llRemoteLoadScriptPin]] when it is passed the correct pin and the prim is set mod.
|func_footnote
|spec
|caveats=*A prim has only one pin for remotely loading scripts.
**By changing the pin, a script can deny other scripts the ability to load scripts into the prim.
***This could result in unintentionally breaking a products ability to be updated by an upstream creator.
***This can be used to intentionally stop an upstream creator from updating a product.
|constants
|examples
|helpers
|also_functions={{LSL DefineRow||[[llRemoteLoadScriptPin]]|Used to load a script into a remote prim}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Script
|cat2
|cat3
|cat4
|}}

Rotation

2021-02-13T00:03:34Z

Fenchurch Oh: Removed link to domain isner.com - page no longer exists.

{{LSL Header|ml=*}}{{RightToc}}
==Rotation==

A [[rotation]] is a data {{LSLGC|Types|type}} that contains a set of four [[float]] vlaues.

Each element can be accessed individually by appending <code>.x</code>, <code>.y</code>, <code>.z</code>, or <code>.s</code> to the variable name.
<source lang="lsl2">rotation rot;
float x = rot.x;
float y = rot.y;
float z = rot.z;
float s = rot.s;</source>

The LSL '''rotation''' type is one of several ways to represent an orientation in 3D. (Note that we try to write the type name in '''bold'''.)

The '''rotation''' can be viewed as a discrete twist in three dimensional space, and the orientation of an object is how much it has been twisted around from whichever axes we are using - normally the region's axes.

It is a mathematical object called a [[quaternion]]. You can think of a quaternion as four numbers, three of which represent the direction an object is facing and a fourth that represents the object's banking left or right around that direction. The main advantage of using
quaternions is that they are not susceptible to [http://en.wikipedia.org/wiki/Gimbal_Lock gimbal lock].
For the complex inner workings of quaternion mathematics, see {{LSLG|quaternion}}.
For a list of functions and events related to rotations see {{LSLG|LSL Rotation Synopsis}}.
There is also information about causing textures to rotate in {{LSLG|texture}}s.

Rotations are often regarded a very confusing subject, where scripters use trial-and-error to get it right. The reasons for this confusion are:
* Nobody really knows what a [[quaternion]] is, or how to think about it (not entirely true, the brain just isn't good at thinking in 4 geometric dimensions).
* There are actually several different types of vectors ('dir', 'vec' and 'pos') that need to acted upon differently.
* The order in which translation and rotations need to be applied can vary from case to case.
* There is confusion about the difference between an applied rotation and the rotation 'offset' between coordinate systems.
To master rotations it is therefore essential to use a good naming system for your variables. Such a system is described in the excellent article [[User:Timmy_Foxclaw/About_Coordinate_Systems_and_Rotations|About Coordinate Systems and Rotations]] by [[User:Timmy_Foxclaw|Timmy Foxclaw]].

==Other representations==
===Euler vector===
Another way to represent a 3D angle is using three numbers, <X, Y, Z>, which represent the amount which the object is rotated around each axis. This is used in the Edit window, for example, and is generally easy for people to visualize. It is easy to adjust the Rotation <x, y, z> numbers in the Edit window and see how the object behaves. Note that in the Edit window, the numbers are in degrees, that is, a right angle is 90.

In LSL, these three angles are expressed in [[radians]] instead of degrees, that is, a right angle is PI/2. (A radian is sort of a very fat degree.)
Note that these three numbers are a '''vector''' type and not a '''rotation''' type, though it can represent the same information. This is called the ''Euler'' representation of a 3D angle. '''In LSL the rotation around z is done first, then around y, and finally around x'''.

===Axis plus Angle===
In this method you define an axis of rotation, like defining the axis about which the earth spins, and use that together with the angle of rotation about the axis, which defines the amount of turn, to give the '''rotation'''.

So if you want to define a '''rotation''' about an axis at 45 degrees in the x-y plane (North East in region coordinates), you'd need to point the axis with the same amount of x and y, but with no z. The axis could be <1.0, 1.0, 0.0>. The absolute size of the numbers defining the axis don’t matter in this representation; <2.0, 2.0, 0.0> would work just as well. The angle of rotation is a separate number given in radians, eg. PI/3 = 60 degrees. Together they define a global '''rotation''' of 60 degrees about the North East axis.

Like a quaternion Axis plus Angle uses four numbers, but it doesn't need to be "normalized".

===FWD, LEFT, UP===
Another way to represent the same 3D angle is to use three vectors, showing what the front is pointing at (fwd), what the top is pointing at (up), and what the left side is pointing at (left). Actually, only two of the three are needed, because any two determines the third.

For good reasons, such as being able to easily combine rotations, the four number version, the quaternion '''rotation''', is better, though perhaps harder for a beginner to grasp. Fortunately it's very seldom necessary to do anything with the actual internal representation of ''rotations'' and there are functions for converting easily back and forth between the three LSL types, and between degrees and radians.

==Right hand rule==
In LSL all rotations are done according to the '''right hand rule'''. With your right hand, extend the first finger in the direction of the positive direction of the x-axis. Extend your second finger at right angles to your first finger, it will point along the positive y-axis, and your thumb, extended at right angles to both will point along the positive z-axis. When you're editing an object, the three colored axis arrows point in the positive direction for each axis (X: red, Y: green, Z: blue).

http://en.wikipedia.org/wiki/Right_hand_rule

Now, don't remove your right hand just yet, there is another use for it, determining the direction of a positive rotation. Make a fist with your right hand, thumb extended and pointing in the positive direction of the axis you are interested in. Your fingers curl around in the direction of positive rotation. Rotations around the X, Y, and Z axis are often referred to as Roll, Pitch, and Yaw, particularly for vehicles.

[http://en.wikipedia.org/wiki/Tait-Bryan_angles Roll Pitch Yaw]

== Combining Rotations ==
'
Suppose you have two rotations. ''r1'' is rotate 90 degrees to the left, and ''r2'' is rotate 30 degrees to the right. (Any rotations will work; these are just an example.)
You can combine ''r1'' and ''r2'' to make ''r3'' using the '''*''' operator. It doesn't really multiply them, it ''composes'' them.
<source lang="lsl2">
rotation r3 = r1 * r2;
</source>
The result in this case is that ''r3'' means rotate 60 degrees to the left.

In other words, to combine '''rotations''', you use the '''multiply''' and '''divide''' operators. Don't try to use addition or subtraction operators on '''rotations''', as they will not do what you expect. The '''multiply''' operation applies the rotation in the positive direction, the '''divide''' operation does a negative rotation. You can also negate a rotation directly, just negate the s component, e.g. X.s = -X.s.

Unlike other types such as {{LSLG|float}}, the order in which the operations are done,
[http://en.wikipedia.org/wiki/Commutative non-commutative], is important.
The reason for this is simple: the order you do rotations in is important in RL. For example, if you had a dart with four feathers, started from rotation <0, 0, 0> with its tail on the origin, it would lie on the X axis with its point aimed in the positive X direction, its feathers along the Z and Y axes, and the axes of the dart and the axes of the world would be aligned. We're going to rotate it 45 degrees around X and 30 degrees around Y, but in different orders.

First, after rotating 45 deg around X the dart would still be on the X axis, unmoved, just turned along its long axis, so the feathers would be at 45 deg to the axes. Then rotating 30 deg around Y would move it in the XZ plane to point down 30 deg from the X axis (remember the right hand rule for rotations means a small positive rotation around Y moves the point down). The dart winds up pointing 30 deg down, in the same vertical plane it started in, but turned around its own long axis so the feathers are no longer up and down.

If you did it the other way, first rotating 30 deg in Y, the dart would rotate down in the XZ plane, but notice that it no longer is on the X axis; its X axis and the world's aren't aligned any more. Now a 45 degree rotation around the X axis would pivot the dart around its tail, the point following a 30 deg cone whose axis is along the positive world X axis, for 45 degrees up and to the right. If you were looking down the X axis, it would pivot from pointing 30 deg below the X axis, up and to the right, out of the XZ plane, to a point below the 1st quadrant in the XY plane, its feathers rotating as it went.

Clearly this is a different result from the first rotation, but the order of rotation is the only thing changed.

To do a constant rotation you need to define a '''rotation''' value which can be done by creating a {{LSLG|vector}} with the X, Y, Z angles in radians as components (called an Euler angle), then converting that to a '''rotation''' by using the {{LSLG|llEuler2Rot}} function. To go from a rotation to an Euler angle {{LSLG|vector}} use {{LSLG|llRot2Euler}}.

If you want an axial rotation you insert the axis of rotation and the turn angle into the {{LSLG|llAxisAngle2Rot}} function, and this will return the '''rotation'''. To go from a rotation back to axis and angle, use {{LSLG|llRot2Axis}} and {{LSLG|llRot2Angle}} respectively.

You can alternately create the native rotation directly: the real part is the cosine of half the angle of rotation, and the vector part is the normalized axis of rotation multiplied by the sine of half the angle of rotation.

'''NOTE:''' angles in LSL are in radians, not degrees, but you can easily convert by using the built-in constants [[#RAD_TO_DEG|RAD_TO_DEG]] and [[#DEG_TO_RAD|DEG_TO_RAD]]. For a 30 degree '''rotation''' around the X axis you might use:

<source lang="lsl2">
rotation rot30X = llEuler2Rot(<30, 0, 0>*DEG_TO_RAD); // convert the degrees to radians, then convert that vector into a rotation, rot30x
vector vec30X = llRot2Euler(rot30X); // convert the rotation back to a vector (the values will be in radians)
rotation rot30X = llAxisAngle2Rot(<1, 0, 0>, 30.0*DEG_TO_RAD); // convert the degrees to radians, then convert into a rotation, rot30x
</source>

== Differences between math's quaternions and LSL rotations ==

There are a few differences between LSL and maths that have little consequences while scripting, but that might puzzle people with prior mathematical knowledge. So we thought it would be good to list them here:

* In LSL, all quaternions are normalized (the dot product of '''R''' by '''R''' is always '''1'''), and therefore represent ways to rotate objects without changing their size. In maths, generic quaternions might be not normalized, and they represent ''affinities'', i.e. a way to rotate '''and''' change the size of objects.
* In LSL, the '''s''' term is the fourth member of the rotation: '''<x, y, z, s>'''. In maths, the '''s''' term, also called "real part", is written as the first coordinate of the quaternion: '''(s, x, y, z)'''.
* Multiplication is written in reverse order in LSL and in maths. In LSL, you would write '''R * S''', where in maths you would write '''S . R'''.

== Order of rotation for Euler Vectors ==

From the above discussion, it's clear that when dealing with rotations around more than one axis, the order they are done in is critical. In the ''Euler'' discussion above this was kind of glossed over a bit, the individual rotations around the three axis define an overall ''rotation'', but that begs the question: What axis order are the rotations done in? The answer is '''Z, Y, X''' in global coordinates. If you are trying to rotate an object around more than one axis at a time using the ''Euler'' representation, determine the correct ''Euler'' {{LSLG|vector}} using the Z, Y, X rotation order, then use the {{LSLG|llEuler2Rot}} function to get the '''rotation''' for use in combining rotations or applying the rotation to the object.

== Local vs Global (World) rotations ==

It is important to distinguish between the '''rotation''' relative to the world, and the '''rotation''' relative to the local object itself. In the editor, you can switch back and forth from one to the other. In a script, you must convert from one to the other to get the desired behavior.

'''Local''' rotations are ones done around the axes embedded in the object itself forward/back, left/right, up/down, irrespective of how the object is rotated in the world. '''Global''' rotations are ones done around the world axes, North/South, East/West, Higher/Lower. You can see the difference by rotating a prim, then edit it and change the axes settings between local and global, notice how the colored axes arrows change.

In LSL, the difference between doing a '''local''' or '''global''' rotation is the order the '''rotations''' are evaluated in the statement.

This does a '''local''' 30 degree rotation by putting the constant 30 degree '''rotation''' to the left of the object's starting '''rotation''' (myRot). It is like the first operation in the first example above, just twisting the dart 30 degrees around its own long axis.

<source lang="lsl2">
rotation localRot = rot30X * myRot;// do a local rotation by multiplying a constant rotation by a world rotation
</source>

To do a '''global''' rotation, use the same '''rotation''' values, but in the opposite order. This is like the second operation in the second example, the dart rotating up and to the right around the world X axis. In this case, the existing rotation (myRot) is rotated 30 degrees around the global X axis.

<source lang="lsl2">
rotation globalRot = myRot * rot30X;// do a global rotation by multiplying a world rotation by a constant rotation
</source>

== Another way to think about combining rotations ==

You may want to think about this '''local''' vs '''global''' difference by considering that '''rotations''' are done in evaluation order, that is left to right except for parenthesized expressions.

In the localRot case, what happened was that starting from <0, 0, 0>, the rot30X was done first, rotating the prim around the world X axis, but since when it's unrotated, the local and global axes are identical it has the effect of doing the rotation around the object's local X axis. Then the second '''rotation''' myRot was done which rotated the prim to its original rotation, but now with the additional X axis rotation baked in. What this looks like is that the prim rotated in place, around its own X axis, with the Y and Z rotations unchanged, a '''local''' rotation.

In the globalRot case, again starting from <0, 0, 0>, first the object is rotated to its original rotation (myRot), but now the object's axes and the world's axes are no longer aligned! So, the second '''rotation''' rot30x does exactly what it did in the local case, rotates the object 30 degrees around the world X axis, but the effect is to rotate the object through a cone around the world X axis since the object's X axis and the world's X axis aren't the same this time. What this looks like is that the prim pivoted 30 degrees around the world X axis, hence a '''global''' rotation.

'''Division''' of '''rotations''' has the effect of doing the rotation in the opposite direction, multiplying by a 330 degree '''rotation''' is the same as dividing by a 30 degree '''rotation'''.

==Using Rotations ==

You can access the individual components of a '''rotation''' '''R''' by '''R.x, R.y, R.z, & R.s''' ('''not''' R.w). The scalar part R.s is the cosine of half the angle of rotation. The vector part (R.x,R.y,R.z) is the product of the normalized axis of rotation and the sine of half the angle of rotation. You can generate an inverse '''rotation''' by negating the x,y,z members (or by making the s value negative). As an aside, you can also use a '''rotation''' just as a repository of [[float]] values, each '''rotation''' stores four of them and a [[list]] consisting of '''rotation''' is more efficient than a [[list]] consisting of [[float]]s, but there is overhead in unpacking them.

<source lang="lsl2">
rotation rot30X = llEuler2Rot(<30, 0, 0> * DEG_TO_RAD );// Create a rotation constant
rotation rotCopy = rot30X; // Just copy it into rotCopy, it copies all 4 float components
float X = rotCopy.x; // Get out the individual components of the rotation
float Y = rotCopy.y;
float Z = rotCopy.z;
float S = rotCopy.s;
rotation anotherCopy = <X, Y, Z, S>; // = <rotCopy.x, rotCopy.y, rotCopy.y, rotCopy.s>
</source>

There is a built in constant for a zero '''rotation''' [[#ZERO_ROTATION|ZERO_ROTATION]] which you can use directly or, if you need to invert a '''rotation R''', divide [[#ZERO_ROTATION|ZERO_ROTATION]] by '''R'''. As a reminder from above, this works by first rotating to the zero position, then because it is a divide, rotating in the opposite sense to the original '''rotation''', thereby doing the inverse rotation.
<source lang="lsl2">
rotation rot330X = <-rot30X.x, -rot30X.y, -rot30X.z, rot30X.s>;// invert a rotation - NOTE the s component isn't negated
rotation another330X = ZERO_ROTATION / rot30X; // invert a rotation by division, same result as rot330X
rotation yetanother330X = <rot30X.x, rot30X.y, rot30X.z, -rot30X.s>; // not literally the same but works the same.
</source>

==Single or Root Prims vs Linked Prims vs Attachments ==

The reason for talking about single or linked prim rotations is that for things like doors on vehicles, the desired motion is to move the door relative to the vehicle, no matter what the rotation of the overall vehicle is. While possible to do this with global rotations, it would quickly grow tedious.
There are generally three coordinate systems a prim can be in: all alone, part of a {{LSLG|linkset}}, or part of an {{LSLG|attachment}}. When a prim is alone, i.e., not part of a {{LSLG|linkset}}, it acts like a root prim; when it is part of an {{LSLG|attachment}}, it acts differently and is a bit broken.

{{LSLRotGetSet}}

==Rotating Vectors ==

In LSL, rotating a [[vector]] is very useful if you want to move an object in an arc or circle when the center of rotation isn't the center of the object.

This sounds very complex, but there is much less here than meets the eye. Remember from the above discussion of rotating the [[#Combining Rotations|dart]], and replace the physical dart with a [[vector]] whose origin is the tail of the dart, and whose components in X, Y, and Z describe the position of the tip of the dart. Rotating the dart around its tail moves the tip of the dart through and arc whose center of rotation is the tail of the dart. In exactly the same way, rotating a [[vector]] which represents an offset from the center of a prim rotates the prim through the same arc. What this looks like is the object rotates around a position offset by the [[vector]] from the center of the prim.
=== Position of Object Rotated Around A Relative Point ===
<source lang="lsl2">rotation vRotArc = llEuler2Rot( <30.0, 0.0, 0.0> * DEG_TO_RAD );
//-- creates a rotation constant, 30 degrees around the X axis

vector vPosOffset = <0.0, 1.0, 0.0>;
//-- creates an offset one meter in the positive Y direction

vector vPosRotOffset = vPosOffset * vRotArc;
//-- rotates the offset to get the motion caused by the rotation

vector vPosOffsetDiff = vPosOffset - vPosRotOffset;
//-- gets the local difference between the current offset and the rotated one

vector vPosRotDiff = vPosOffsetDiff * llGetRot();
//-- rotates the difference in the offsets to be relative to the global rotation.

vector vPosNew = llGetPos() + vPosRotDiff;
//-- finds the prims new position by adding the rotated offset difference

rotation vRotNew = vRotArc * llGetRot();
//-- finds rot to continue facing offset point</source>
:in application, the same action as:
<source lang="lsl2">llSetPrimitiveParams( [PRIM_POSITION, llGetPos() + (vPosOffset - vPosOffset * vRotArc) * llGetRot(),
PRIM_ROTATION, vRotArc * llGetRot()] );</source>
* The above method results in the orbiting object always having the same side facing the center. An alternative that preserves the orbiters rotation is as follows
<source lang="lsl2">llSetPrimitiveParams( [PRIM_POSITION, llGetPos() + (vPosOffset - vPosOffset * vRotArc) * llGetRot()];
vPosOffset = vPosOffset * vRotArc;</source>
'''Nota Bene:''' Doing this is a move, so don't forget about issues of moving a prim off world, below ground, more than 10 meters etc. Also to get a full orbit, you'll need to repeat the listed steps (in a [[timer]] perhaps).

'''Notice:''' These apply to objects (or root prims if you prefer), child prims should use [[PRIM_POS_LOCAL]] for position, and [[PRIM_ROT_LOCAL]] or [[llGetLocalRot]] for rotation, and the point being rotated around should be relative to the root.

=== Position of Relative Point Around Rotated Object ===
To get a point relative to the objects current facing (such as used in rezzors)
<source lang="lsl2">vector vPosOffset = <0.0, 0.0, 1.0>;
//-- creates an offset one meter in the positive Z direction.

vector vPosRotOffset = vPosOffset * llGetRot();
//-- rotate the offset to be relative to objects rotation

vector vPosOffsetIsAt = llGetPos() + vPosRotOffset;
//-- get the region position of the rotated offset</source>
:in application, the same action as:
<source lang="lsl2">llRezAtRoot( "Object", llGetPos() + vPosOffset * llGetRot(), ZERO_VECTOR, ZERO_ROTATION, 0 );</source>

==Normalizing a Rotation ==
When you need precision, it is often important -- even necessary -- to work with normalized rotations, which means scaling each quaternion so that its ''x, y,'' and ''z'' values are equal to 1. Some operations in LSL will actually generate a run-time error if you do not do this. Looking at it another way, you need to express the rotation in a way that applies an angle of rotation to a vector <1.0,1.0,1.0>. Mathematically, normalizing rotation '''Q''' means calculating

'''Normalized Q = Q / Sqrt( Q.x^2 + Q.y^2 + Q.z^2 + Q.s^2)'''

Putting that in LSL terms:
<source lang="lsl2">rotation NormRot(rotation Q)
{
float MagQ = llSqrt(Q.x*Q.x + Q.y*Q.y +Q.z*Q.z + Q.s*Q.s);
return <Q.x/MagQ, Q.y/MagQ, Q.z/MagQ, Q.s/MagQ>;
}</source>
: '''Note''': The only methods in LSL for obtaining a de-normalized rotations are [[llAxes2Rot]] (''via inputs which are not mutually orthogonal, or via inputs of different magnitude''), or direct manipulation of the rotation's elements. All other ll* functions return normalized rotations. Use of the preceding example may introduce small floating point errors into normalized rotations due to limited precision.

==Useful Snippets==
<source lang="lsl2">integer IsRotation(string s)
{
list split = llParseString2List(s, [" "], ["<", ">", ","]);
if(llGetListLength(split) != 9)//we must check the list length, or the next test won't work properly.
return FALSE;
return !((string)((rotation)s) == (string)((rotation)((string)llListInsertList(split, ["-"], 7))));
//it works by trying to flip the sign on the S element of the rotation,
//if it works or breaks the rotation then the values won't match.
//if the rotation was already broken then the sign flip will have no affect and the values will match
//we cast back to string so we can catch negative zero which allows for support of <0,0,0,0>
}//Strife Onizuka</source>

{{CopyAsComment|Calculate a point at distance d in the direction the avatar id is facing}}
<source lang="lsl2">vector point_in_front_of( key id, float d )
{
list pose = llGetObjectDetails( id, [ OBJECT_POS, OBJECT_ROT ] );
return ( llList2Vector( pose, 0 ) + < d, 0.0, 0.0 > * llList2Rot( pose, 1 ) );
}// Mephistopheles Thalheimer</source>

{{CopyAsComment|Rez an object o at a distance d from the end of the z axis. 
The object is rezzed oriented to the rezzer}}

<source lang="lsl2">rez_object_at_end( string o, float d )
{
vector s = llGetScale();

if( llGetInventoryType( o ) == INVENTORY_OBJECT )
{
llRezObject( o, llGetPos() + llRot2Up( llGetRot() ) * ( s.z / 2.0 + d ) , ZERO_VECTOR, llGetRot(), 0 );
}
}// Mephistopheles Thalheimer</source>

{{CopyAsComment|Scale a rotation:}}
<source lang="lsl2">rotation ScaleQuat(rotation source, float ratio)
{
return llAxisAngle2Rot(llRot2Axis(source), ratio * llRot2Angle(source));
}</source>

{{CopyAsComment|Constrain a rotation to a given plane, defined by its normal, very useful for vehicles that remain horizontal in turns: 
Note that there is a flaw somewhere in this function, it gives incorrect results in some circumstances.}}
<source lang="lsl2">rotation ConstrainQuat2Plane(rotation source, vector normal)
{
return llAxisAngle2Rot(normal, <source.x, source.y, source.z> * normal * llRot2Angle(source));
} // Jesrad Seraph</source>

{{CopyAsComment|Slerp (rotation combination) function from [[Slerp]]:}}
<source lang="lsl2">rotation BlendQuats(rotation a, rotation b, float ratio)
{
return llAxisAngle2Rot(llRot2Axis(b /= a), ratio * llRot2Angle(b)) * a;
}</source>

== Constants ==
=== [[ZERO_ROTATION]] ===
ZERO_ROTATION = <0.0, 0.0, 0.0, 1.0>; 
A rotation constant representing a Euler angle of <0.0, 0.0, 0.0>.

=== [[DEG_TO_RAD]] ===
DEG_TO_RAD = 0.01745329238f; 
A float constant that when multiplied by an angle in degrees gives the angle in radians.

=== [[RAD_TO_DEG]] ===
RAD_TO_DEG = 57.29578f; 
A float constant when multiplied by an angle in radians gives the angle in degrees.

[[Category:LSL_Types|Rotation]][[Category:LSL_Math]][[Category:LSL_Math/3D]][[Category:LSL Rotation]]

Template:LSL Function/negative index/range

2020-12-28T18:37:03Z

Fenchurch Oh: typo correction. "Then" vs "Than".

{{#if:

TODO: --FIXME--
* Figure out how to support {{{noExclude|}}} for llListListStride.

{{#vardefine:p_{{{1|start}}}_desc|{{{1|start}}} index}}

{{#vardefine:p_{{{2|end}}}_desc|{{{2|end}}} index}}

{{#vardefine:notes|{{#var:notes}}{{PBR}}
=== Ranges & Indexes ===
The easiest way to explain how ranges work is to make all indexes positive. Negative indexes are just a way of counting from the tail end instead of the beginning, all negative indexes have a corresponding equivalent positive index (assuming they are in range). Positive indexes past length (after the last index), or negative indexes past the beginning (before the first index) are valid and the effects are predictable and reliable: the entries are treated as if they were there but were removed just before output.

*If {{LSLP|{{{1}}}}} <= {{LSLP|{{{2}}}}} then the range operated on starts at {{LSLP|{{{1}}}}} and ends at {{LSLP|{{{2}}}}}. [{{LSLP|{{{1}}}}}, {{LSLP|{{{2}}}}}]
*Exclusion range: If {{LSLP|{{{1}}}}} > {{LSLP|{{{2}}}}} then the range operated on starts at {{LSLP|0}} and goes to {{LSLP|{{{2}}}}} and then starts again at {{LSLP|{{{1}}}}} and goes to {{LSLP|-1}}. [{{LSLP|0}}, {{LSLP|{{{2}}}}}] + [{{LSLP|{{{1}}}}}, {{LSLP|-1}}]
**If {{LSLP|{{{2}}}}} is a negative index past the beginning, then the operating range would be [{{LSLP|{{{1}}}}}, {{LSLP|-1}}].
**If {{LSLP|{{{2}}}}} is a positive index past the end, then the operating range would be [{{LSLP|0}}, {{LSLP|{{{2}}}}}].
**If both {{LSLP|{{{1}}}}} and {{LSLP|{{{2}}}}} are out of bounds then the function would have no operating range (effectively inverting what the function is supposed to do).

See {{LSLGC|Negative_Index#Range Functions|negative indexes}} for more information.
}}

}}<noinclude>
{| {{Prettytable}}
|-{{Hl2}}
! #var
! value
|-
{{VarPair|p_{{{1|start}}}_desc}}
|-
{{VarPair|p_{{{1|end}}}_desc}}
|-
{{VarPair|spec}}
|-
{{VarPair|notes}}
|-
{{VarPair|caveats}}
|}
</noinclude>

Project:Editing Guidelines

2020-12-15T23:16:41Z

Fenchurch Oh: /* How can I contribute? */ - updated to current procedure how to request wiki edit permissions. (Dec 2020)

{{Help|Wiki=*}} {{TOCright}}

== Why should I contribute to the Wiki? ==

'''Just like Second Life itself, this wiki is powered by user generated content''', whether it's a brief tip you want to share or an extensive how-to guide on a given topic. Plus, it's convenient for your own reference. Many valuable contributions are exactly that: you solved a problem for yourself, which in turn benefits fellow Residents.

Not a techy geek? Don't worry, '''Residents from all walks of "Second Life"''' contribute here, and having diverse perspectives on a single help page can truly be more than the "sum of its parts". '''Need reassurance? See [[wiki myths busted]].'''

Just like you didn't go from being a baby to a grownup in a day, knowledge on this wiki evolves gradually. There's no rush. Enjoy checking back and becoming more comfortable over time, learning from others' contributions so you become more confident to make your own.

== How can I contribute? ==

'''Every Resident can create new pages and add to many existing pages.''' There's no obligation to, but Linden lab welcomes ''your'' awesome contributions! Before you edit, we recommend being familiar with browsing this wiki, so you understand [[Style_Guide|style]], structure, and content. While there are similarities to other wikis out there, certain specifics apply here.

'''2019:''' ''For some time who can create in and edit the wiki has been limited due to general abuse of the privileges. You might build cred attending [https://wiki.secondlife.com/wiki/Linden_Lab_Official:User_Groups user group meetings]. If you log into the wiki and see you do not have edit privileges, you'll need to request them by emailing letmein@lindenlab.com. Please send them a polite email asking for editing permission.
''
=== Editing pages ===

Editing an existing page is super-easy. You may want to start by correcting a typo or other small change:

# Click '''Log in''' in the upper right.
# Enter your Second Life username and password.
# Click '''Log in'''.
# Go to the page you want to edit.
# Click the '''edit''' tab near the top.
# Make changes, then scroll to the bottom and click '''Show preview'''.
# If happy with your changes, scroll to the bottom and click '''Save page'''.

This video shows you how to do it in action:

: {{KBvideo|VJFGUv5KnG8|640|385|type=youtube}}

{{KBtip|If you'd like to see a help page edited/created but aren't confident enough to do it yourself and don't know a more experienced friend who could help, feel free to [http://bit.ly/contactsl ask Torley Linden].}}

=== Creating pages ===

To create a new page which can be edited by you and others, '''[[Quickie Wiki Intro|read the "Quickie Wiki Intro"]]'''.

When creating a new page:

* Help prevent wiki sprawl by editing existing pages rather than creating new pages when possible.
* Use the simplest, most obvious name. You can always create a redirect and/or disambiguation page later if needed.
* When a page is aimed at a specific audience, please include a brief introduction for people who aren't familiar with the content, or link to further information.

=== [[#"User" namespace|What's a "User" page?]] ===

^ Click to learn more.

=== See also ===

* '''[[Style Guide]]''' - Essential reading if you're planning to edit the '''[[Extended Knowledge Base]]''', but highly recommended in general.
* ''[http://www.mediawiki.org/wiki/Help:Contents MediaWiki's Help]''' - wiki.secondlife.com is powered by MediaWiki, and while we don't use ''all'' the stuff here, a great deal does apply. There are many techniques that have been ported over here.

== Content ==

We appreciate any info that benefits our Second Life community. This ''excludes'' blatant ads and spam. All content must be [[Maturity#General|suitable for general consumption]] ({{Mrg}} in terms of inworld ratings), and compliant with our [[LL:Second Life Community Standards|Community Standards]] as well as the [[LL:Second Life Terms of Service|Terms of Service]]. While the wiki is a different tool than the blogs and forums, [https://blogs.secondlife.com/community/features/blog/2009/02/25/second-life-discussion-guidelines their discussion guidelines] are also relevant here.

'''All content added to the Second Life Wiki ''must'' be compatible with our [[Project:Terms of Use|Terms of Use]] and [[Project:Contribution Agreement|Contribution Agreement]].'''

Besides that, [http://en.wikipedia.org/wiki/Wikipedia:Be_bold '''be bold'''].

=== Point of View ===

Articles should generally be written in the [http://en.wikipedia.org/wiki/Third-person_narrative#Third-person_view third person] unless there's an exceptional benefit, commonly the attribution and accountability that comes with sharing personal experiences. Always consider context: for example, a legal document from Linden Lab must be presented in much more formal language than a subjective guide to creating art.

Second Life has a unique [[culture]], so while we've been inspired by others' practices, this wiki's ultimate authority is Linden Lab, not rules made elsewhere. Specific moderation is done at the discretion of [[Project:About|these Lindens]]. Note that while [http://en.wikipedia.org/wiki/Wikipedia:Neutral_point_of_view Wikipedia's NPOV] can be a useful guideline, we don't strictly enforce it, and when it comes to comprehension, are more generous to include information, akin to [http://tvtropes.org/pmwiki/pmwiki.php/Main/HomePage TVTropes].

This wiki is for people helping build Second Life, ''not'' for complaints about Second Life or Linden Lab. Criticism which supports a feature requests or proposal is acceptable (e.g., "Here's problem X. Implementing Y will solve X."), but refrain from un-useful complaints. A page history's contains its complete list of contributions, so there's no need to sign articles — conversation should go in a page's accompanying Talk page (accessed by clicking the Discussion tab near the top of the screen).

=== "Edits by proxy" aren't allowed ===

Making edits on another Resident's behalf isn't allowed because it confuses accountability and is prone to [http://en.wikipedia.org/wiki/Drama_triangle drama] which wastes everyone's time. Furthermore, your wiki editing privileges could be revoked. For example, Bob can't add a paragraph to an article and claim that Alice made him do that. This becomes especially troublesome if the edit is abusive. Rather, the correct path of action is for Alice to edit the page herself as best as she can, then Bob makes further edits. It only takes a few clicks for even a new Resident to begin editing the wiki [http://www.youtube.com/watch?v=VJFGUv5KnG8 as shown in this video], and while you can certainly seek help, '''you are responsible for all wiki edits made under your Second Life account name'''.

This relates to [http://secondlife.com/corporate/tos.php#tos3 3.2 in the Second Life Terms of Service]:

: 3.2 You agree to use an Account Name in Second Life that is not misleading, offensive or infringing. You are responsible for activities related to your Account Name, and for keeping your password for this Account secure.

=== Localization ===

See [[Project:Languages]] for localization guidelines.

=== Removal of content ===

[[Resident|Residents]] can't permanently remove content from the wiki. Use redirects for merged or accidentally-created pages. Articles can be tagged with [[Template:Delete]] where redirects seem inappropriate (e.g., where the wiki is used in an abusive manner or where it violates copyright).

=== Linking of content ===

Please link pages to related resources to facilitate learning. Link the first appearance in text of a term in need of explanation (like [[avatar]], [[grid]], [[OGP]], etc.).

Categorize your pages where appropriate. [http://wiki.secondlife.com/wiki/Special:AllPages?namespace=14 See the full list of available categories.]

It's also awesome to have a "See also" section at the end of an article linking to related articles that the reader may wish to learn from next. [[Marketplace/Sellers_guide#See_also|See an example.]]

If a single article feels "too long", dividing it into smaller, focused articles and linking them is often the more accessible way to go. Articles are expected to evolve fluidly, so there's so single rule here — use your best judgment and keep learning by doing.

== Namespaces ==

Geeky but good-to-know.

=== Main ===

The Main [http://www.mediawiki.org/wiki/Namespaces namespace] is intended to hold most of the Second Life Wiki's content.

=== Linden Lab Official ===

The [http://wiki.secondlife.com/w/index.php?title=Special%3AAllPages&from=&to=&namespace=100 Linden Lab Official namespace] is for official Second Life policy information and other information from Linden Lab, such as official supported API documentation, safety and security guidelines, and information related to billing and payments. Only Linden Lab employees may edit these articles, though the talk namespace is open for general editing.

There are also localized official namespaces:
* French - [http://wiki.secondlife.com/w/index.php?title=Special%3AAllPages&from=&to=&namespace=104 Article officiel de Linden Lab]
* Japanese - [http://wiki.secondlife.com/w/index.php?title=Special%3AAllPages&from=&to=&namespace=106 Linden Lab公認]
* Italian - [http://wiki.secondlife.com/w/index.php?title=Special%3AAllPages&from=&to=&namespace=108 Articolo ufficiale Linden Lab]
* Portuguese - [http://wiki.secondlife.com/w/index.php?title=Special%3AAllPages&from=&to=&namespace=110 Artigo oficial da Linden Lab]
* Spanish - [http://wiki.secondlife.com/w/index.php?title=Special%3AAllPages&from=&to=&namespace=112 Artículo oficial de Linden Lab]
* German - [http://wiki.secondlife.com/w/index.php?title=Special%3AAllPages&from=&to=&namespace=114 Linden Lab Offiziell]

=== Viewer Help ===

The [https://wiki.secondlife.com/w/index.php?title=Special%3AAllPages&from=&to=&namespace=102 Viewerhelp namespace] contains content provided via the Viewer 2 Online Help system. Only Linden Lab employees may edit these articles, though the talk namespace is open for general editing.

=== "Project" namespace ===

The "Project" namespace is reserved for meta-information about the wiki itself, such as these editing guidelines, rather than about Second Life.

=== "Help" namespace ===

The "Help:" namespace is reserved for wiki-related help articles, like editing manuals. SL-related help should be added to the Main namespace.

=== "User" namespace ===

Every wiki contributor has their own, personal namespace.

Once you login, you can also view and edit your User: page by clicking your name towards the top right (to the left of the "my talk") link. For example, [[User:Torley_Linden]] and [[User:Zai Lynch]].

Think of it as an extended profile compared to the one inworld. What can you do with it? Just about anything you wish, from expressing who you are to others, to tracking links to wiki pages you regularly edit for your own reference. Customizing your User: page is totally optional, but as you grow on the wiki, helps others understand who you are.

Obviously, the [[#Point of View|Point of View guideline]] doesn't need to be followed here.

Any content abiding by the wiki guidelines can be included in the "User" namespace as a subpage. For example, [[User:Torley Linden/Contact]].

=== "Talk" namespace ===

See [[Project:Talk Page Guidelines]] for more info.

== Templates ==

* Use inclusion templates to ensure consistent navigation.
* See [[Help:Editors Toolbox]] for a list of useful templates for editors.
* See [http://wiki.secondlife.com/w/index.php?title=Special%3AAllPages&from=&namespace=10 the list of all available templates].

== See also ==

* '''[[Project:Terms of Use]]'''
* '''[[Project:Contribution Agreement]]'''
* '''[[Template:Ediquette]]''' - Editing etiquette
* '''[[Project:Talk Page Guidelines]]'''
* '''[[Project:Languages]]''' - Guidelines on localizing wiki pages
* '''[[:Category:Help/Wiki]]''' - All wiki-related articles
* '''[[Wiki myths busted]]''' - Fear is the mind-killer!

Template:LSL Function/group

2020-12-15T22:35:25Z

Fenchurch Oh: typo correction

{{LSL Injection Test}}{{#if:

{{Issues/VWR-5044}}

{{#vardefine:notes|{{#var:notes}}{{PBR}}
==== Child Prims ====
It is possible for the group of a child prim to differ from that of the root prim. To build such an object it must first be unlinked, the groups set, and then relinked. Rezzing an object resets the group of the object to that of the group that the user currently has activated. Changing the group of an object changes the group for the entire object. This may only be an artifact or manifestation of [[#VWR-5044|VWR-5044]].}}

}}<noinclude>{{#vardefine:notes}}
{| {{Prettytable}}
|+<code><nowiki>{{{{FULLPAGENAMEE}}|}}</nowiki></code>{{{{FULLPAGENAMEE}}|}}
|-{{Hl2}}
! #var
! value
|-
{{VarPair|notes}}
|-
{{VarPairTable|issues}}
|-
{{VarPair|BugCounter}}
|-
{{VarPair|IssueCounter}}
|}
</noinclude>

LlEmail

2020-12-15T21:40:54Z

Fenchurch Oh: Updated relevant issues list; Added note about potential workaround to prevent email queue from gettung stuck.

{{LSL_Function
|inject-2={{Issues/SVC-23}}{{Issues/SVC-391}}{{Issues/SVC-412}}{{Issues/SCR-499}}{{Issues/BUG-229767}}
|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 {{LSLP|address}} with {{LSLP|subject}} and {{LSLP|message}}.
|return_text
|spec=The {{LSLP|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=* If you're sending to the object owner, prefer the [[llTargetedEmail]] method
* 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 {{User|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.
* Due to bug {{JIRA|BUG-229767}}, an object's email queue can still become suspended until the object crosses a region border (neither a region restart nor a script reset helps). First analysis has revealed a potential workaround, by implementing a delay of about 30 seconds before first trying to send email to a freshly rezzed script - apparently registering the email(...) event handler can take quite some time, and emails arriving prior to said registry process is what gets the entire queue stuck. Official Linden response still pending.
* Due to the bug {{Jira|SVC-391}} llEmail will silently fail (no mail will arrive) when non-ascii characters are present in the subject. However, non-ascii characters in the message body will be replaced by "?".
|constants
|examples=
<source lang="lsl2">
string emailAddress = "somebody@example.com";
string emailHeader = "Someone touched me!";

default
{
touch_start(integer num_detected)
{
// llSay(PUBLIC_CHANNEL, "Sending eMail report now, this will take ~20 seconds.");

key id = llDetectedKey(0);
string name = llDetectedName(0);

llEmail(emailAddress, emailHeader,
"I was touched by: '" + name + "' (" + (string)id + ").");

// llSay(PUBLIC_CHANNEL, "Email has been sent.");
}
}
</source>
|also_functions=
{{LSL DefineRow||[[llGetNextEmail]]}}
{{LSL DefineRow||[[llMessageLinked]]}}
|also_events=
{{LSL DefineRow||[[email]]}}
{{LSL DefineRow||[[link message]]}}
|also_tests={{LSL DefineRow|[https://osiris.lindenlab.com/mediawiki/index.php/Email_Test internal test]}}
|also_articles={{LSL DefineRow||[[IM to email]]}}
{{LSL DefineRow||[[Postcards]]}}
|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"

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

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

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

This application uses email to have objects check with a central server to see if the owner has the latest version. In the objects:
<source lang="lsl2">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);
}
}</source>
The server:
<source lang="lsl2">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("","");
}
}</source>
|helpers=
<source lang="lsl2">
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);
}
</source>
|permission
|negative_index
|cat1=Communications
|cat2=Email
|cat3
|cat4
}}

Email

2020-12-15T21:38:45Z

Fenchurch Oh: Updated relevant issues list; Added note about potential workaround to prevent email queue from gettung stuck.

{{LSL_Event
|inject-2={{Issues/SVC-23}}{{Issues/SVC-391}}{{Issues/SVC-412}}{{Issues/SCR-499}}{{Issues/BUG-229767}}
|event_id=21|event_delay
|event=email
|p1_type=string|p1_name=time|p1_desc=In the <code>(string)[[llGetUnixTime]]</code> format|p1_hover=In the (string)llGetUnixTime format
|p2_type=string|p2_name=address|p2_desc
|p3_type=string|p3_name=subject|p3_desc
|p4_type=string|p4_name=message|p4_desc
|p5_type=integer|p5_name=num_left|p5_desc=The number of emails remaining in the email queue.{{Footnote|The email being processed is not counted as it has already been popped from the queue.}}|p5_hover=The number of emails left in the email queue.
|event_desc=Triggered as a result of calling [[llGetNextEmail]] where there is a matching email in the email queue.
|event_footnote=The email queue is associated with the prim and any script in the prim can access it. The prim's email address is its key with "@lsl.secondlife.com" appended, <code>[[llGetKey]]() + "@lsl.secondlife.com"</code>{{Footnote|1=Preview grid email address are constructed differently: <code style="font-size: 123%;">[[llGetKey]]() + "@lsl." + grid + ".lindenlab.com"</code>; for the main beta grid set grid to {{String|aditi}}.|2=Beta grid email address are constructed differently: llGetKey() + {{String|@lsl.}} + grid + {{String|.lindenlab.com}}; for the main beta grid set grid to {{String|aditi}}.}}.
|constants
|spec=The email event is triggered as a result of calling [[llGetNextEmail]] when there is an email that matches [[llGetNextEmail]]'s optional filters. The first email that matches the filters is removed from the email queue and its data is used as the parameters for this event. If no email matches the filters but the queue is not empty this event is not triggered. Besides the effects of filtering, the email queue is {{HoverText|FIFO|First In First Out}}.
|caveats=
* The email queue is limited to 100 emails, any email after that is bounced.
* The message field may have a maximum of 1000 single-byte characters. This count includes the header information ('''address''', '''subject''', etc).
* [[llEmail|Emails sent from within SL]] will have their message body prefixed with a header detailing the originating prim. See [[llEmail]] for more details.
* Due to 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).
* Due to bug {{JIRA|BUG-229767}}, an object's email queue can still become suspended until the object crosses a region border (neither a region restart nor a script reset helps). First analysis has revealed a potential workaround, by implementing a delay of about 30 seconds before first trying to send email to a freshly rezzed script - apparently registering the email(...) event handler can take quite some time, and emails arriving prior to said registry process is what gets the entire queue stuck. Official Linden response still pending.

|constants
|examples=
<source lang="lsl2">
default
{
state_entry()
{
llSetTimerEvent(5.0);
}

timer()
{
// get next email, don't filter by sender or subject
llGetNextEmail("", "");
}

email( string time, string address, string subject, string message, integer num_left )
{
// if we received an email from an object within Second Life
if (llGetSubString(address, -19, -1) == "@lsl.secondlife.com")
// {
message = llDeleteSubString(message, 0, llSubStringIndex(message, "\n\n") + 1);
// }

// PUBLIC_CHANNEL has the integer value 0
llSay(PUBLIC_CHANNEL, message);

// if there's another email in the queue waiting
// get next email, don't filter by sender or subject
if(num_left)
llGetNextEmail("", "");
}
}
</source>
|helpers
|also_header
|also_events
|also_functions={{LSL DefineRow||[[llEmail]]|}}
{{LSL DefineRow||[[llGetNextEmail]]|}}
|also_articles
|also_footer
|notes=
For tips on how to process emails sent from within SL, see the entry on [[llEmail#Prim2Prim_Email|llEmail]].
|mode
|deprecated
|cat1=Email
|cat2
|cat3
|cat4
}}

Template:Issues/BUG-229767

2020-12-15T21:16:10Z

Fenchurch Oh: Added new JIRA entry

{{Issues|BUG-229767|Object-to-object email sporadically fails|type=bug|resolution=unres}}