Second Life Wiki - User contributions [en]

LlAtan2

2016-06-15T15:32:35Z

Kayaker Magic: Adding a haiku

{{LSL Function
|func_id=3|func_sleep=0.0|func_energy=10.0
|func=llAtan2|sort=Atan2
|p1_type=float|p1_name=y|p1_desc
|p2_type=float|p2_name=x|p2_desc
|return_type=float
|return_text=that is the {{wikipedia|Atan2|arctangent2}} of {{LSLP|y}}, {{LSLP|x}}.
|func_footnote=Similar to the <span class="plainlinks">{{wikipedia|Inverse_trigonometric_functions|arctangent}}</span>({{LSLP|y}}/{{LSLP|x}}) except it utilizes the signs of {{LSLP|x}} & {{LSLP|y}} to determine the quadrant and avoids division by zero. <br />
|spec=
If {{LSLP|x}} is positive zero and...
* {{LSLP|y}} is zero, '''zero''' is returned.
* {{LSLP|y}} is positive, '''PI/2''' is returned.
* {{LSLP|y}} is negative, '''-PI/2''' is returned.
If {{LSLP|x}} is negative zero and...
* {{LSLP|y}} is positive zero, '''PI''' is returned.
* {{LSLP|y}} is negative zero, '''-PI''' is returned.
* {{LSLP|y}} is positive, '''PI/2''' is returned.
* {{LSLP|y}} is negative, '''-PI/2''' is returned.

Or
<source lang="lsl2">
if((string)x != (string)0.0 && y == 0.0)//negative zero
return PI * ~-2*((string)y != (string)0.0));
return ((y > 0) - (y < 0)) * PI_BY_TWO;
</source>
The returned value is in the range {{Interval|gte=-[[PI]]|gteh=-PI|lte=PI|center=return}}{{Interval/Footnote}}.
|caveats
|constants
|examples=<source lang="lsl2">default
{
state_entry()
{
float num1 = llFrand(100.0);
float num2 = llFrand(100.0);

llOwnerSay("y = " + (string)num1);
llOwnerSay("x = " + (string)num2);

llOwnerSay("The arctangent of y divided by x is " + (string)llAtan2(num1, num2));
}
}</source><source lang="lsl2">//Function with input of a vector determining the position of a target and returning
//a string with the literal compass-direction of that target towards your position
//by Ramana Sweetwater 2009/01, any use allowed license :-)
//corrected by Patrick Muggins

string compass (vector target)
{
vector source = llGetPos();
list DIRS =["W","NW","N","NE","E","SE","S","SW","W"];
integer index = llCeil(3.5 - (4 * llAtan2(target.y - source.y, target.x - source.x) / PI));
return llList2String(DIRS, index);
}</source>
[[/Compass QA]]
|helpers
|also_functions=
{{LSL DefineRow|[[llSin]]|[[llAsin]]|sine & inverse Sine}}
{{LSL DefineRow|[[llCos]]|[[llAcos]]|cosine & inverse cosine}}
{{LSL DefineRow|[[llTan]]||tangent}}
|also_articles=
{{LSL DefineRow||{{wikipedia|Atan2}}|}}
{{LSL DefineRow||{{wikipedia|Inverse trigonometric function}}|}}
|notes
|haiku=
{{Haiku|An analog clock|passes through infinity|twice every single hour}}
|cat1=Math/Trigonometry
|cat2
|cat3
|cat4
}}

LlAxes2Rot

2016-03-07T12:10:09Z

Kayaker Magic: Added a Haiku

{{LSL_Function
|func_id=17|func_sleep=0.0|sort=Axes2Rot|func_energy=10.0
|func=llAxes2Rot|sort=Axes2Rot
|func_footnote=All three vectors must be mutually orthogonal unit vectors.
|return_type=rotation
|p1_type=vector|p1_name=fwd
|p2_type=vector|p2_name=left
|p3_type=vector|p3_name=up
|return_text=that is defined by the 3 coordinate axes
|notes=Technically, only the first two vectors are needed to define this rotation, which can be done by calling any of these:
<source lang="lsl2">llAxes2Rot(fwd, left, fwd % left);
llAxes2Rot(left % up, left, up);
llAxes2Rot(fwd, up % fwd, up);</source>
|spec
|caveats
|examples=<source lang="lsl2">default
{
state_entry()
{
vector i = < 1.0, 0.0, 0.0>;
vector j = < 0.0, 1.0, 0.0>;
vector k = < 0.0, 0.0, 1.0>;

rotation rot = llAxes2Rot( j, -i, k );

llSay(0, (string) (llRot2Euler(rot) * RAD_TO_DEG) );
}
}</source>

This script displays:
Object: <-0.00000, 0.00000, 90.00000>
which shows that ('''j''', '''-i''', '''k''') is obtained by rotating ('''i''', '''j''', '''k''') 90 degrees around z direction.
|helpers
|also_functions
|also_events
|also_tests=
{{LSL_DefineRow||[[User:Dora_Gustafson/llAxes2Rot_right_and_wrong|Visual illustration]]|Importance of mutually orthogonal unit vectors}}
|also_articles
|cat1=Math/3D
|cat2=Rotation
|cat3
|cat4
|haiku={{Haiku|quaternions rule|the whole world spins at your whim|or crashes and burns}}
}}

LlCastRay

2016-01-14T22:53:19Z

Kayaker Magic: caveats for the cases where the cast ray starts inside a prim and detecting the prim the script is in

{{LSL_Function
|inject-2={{Issues/VWR-1331}}
|func=llCastRay
|func_id=?
|func_sleep
|func_energy

|func_desc=Cast a ray from {{LSLP|start}} to {{LSLP|end}} and report collision data for intersections with objects

|return_type=list
|return_text=of strided values with an additional integer [[#status_code|status_code]] on the end. Each stride consists of two mandatory values {[[key]] {{LSLP|uuid}}, [[vector]] {{LSLP|position}}} and possibly some optional values {[[integer]] {{LSLP|link_number}}, [[vector]] {{LSLP|normal}}} see [[#RC_DATA_FLAGS|RC_DATA_FLAGS]] for details. The {{LSLP|status_code}} if it is negative is an [[#error_code|error code]], otherwise it is the number of hits (and strides) returned.
|func_footnote

|p1_type=vector|p1_name=start|p1_desc=starting location
|p2_type=vector|p2_name=end|p2_desc=ending location
|p3_type=list|p3_subtype=instructions|p3_name=options|p3_desc=can consists of any number of [[#options|option flag]]s and their parameters.
|constants
|caveats=*Depending upon the value of {{LSLP|flags}} (provided via [[#RC_DATA_FLAGS|RC_DATA_FLAGS]]), the number and types of values in the strides will vary. See [[#RC_DATA_FLAGS|RC_DATA_FLAGS]] for details.
*[[llGetRot]] will not return an avatar's exact visual rotation because the viewer doesn't update the avatar's rotation under a threshold (see {{jira|VWR-1331}}). To get an avatar's exact looking direction while in mouselook, use [[llGetCameraRot]] instead.
*[[llCastRay]] will not detect prims having no physics shape ([[PRIM_PHYSICS_SHAPE_TYPE]] = [[PRIM_PHYSICS_SHAPE_NONE]]).
*[[llCastRay]] will not detect a prim if the ray starts inside the prim. This makes it safe to use the prim position as the start location.
*[[llCastRay]] can detect the prim the script is in, if the start location is outside the prim.
|spec=
===={{LSL Param|status_code}}====

{{LSLP|status_code}} is a number tacked onto the end of the strided list to give you extra information about the ray cast. If the cast succeeded, it will be >=0 and will indicate the number of hits. If the ray cast failed (which should only happen right now if the simulator performance is running low), you'll get a negative status code. [[RCERR_SIM_PERF_LOW]] will be used as the status code if the overall physics time in the simulator is too high to perform raycasts. The idea is that you will know to try your cast again in a few frames.

<table class="lltable" border="1" id="error_code">
<caption>'''status_code''' error codes and their meanings.</caption>
<tr>
<th>Status Code</th>
<th title='Value'>V</th>
<th>Description</th>
</tr>
<tr><td>{{LSL Const|RCERR_UNKNOWN|integer|-1}}</td><td>{{#var:value}}</td><td>The raycast failed for an unspecified reason. Please submit a bug report.</td></tr>
<tr><td>{{LSL Const|RCERR_SIM_PERF_LOW|integer|-2}}</td><td>{{#var:value}}</td><td>The raycast failed because simulator performance is low. Wait a while and then try again. If possible reduce the scene complexity.</td></tr>
<tr><td>{{LSL Const|RCERR_CAST_TIME_EXCEEDED|integer|-3}}</td><td>{{#var:value}}</td><td>The raycast failed because the parcel or agent has exceeded the maximum time allowed for raycasting. This resource pool is continually replenished, so waiting a few frames and retrying is likely to succeed.</td></tr>
</table>

=====[[RCERR_CAST_TIME_EXCEEDED]]=====
Ray casts are throttled by the amount of time actually taken to perform the cast. Full regions are each allotted a 4ms pool, divided proportionally over parcels the same way prim limits are. Homestead and Openspace regions behave similarly, except that their pool size is limited to 1ms. Each agent is allotted 200us. All scripts in attachments and, scripts in vehicles, use the agent pool whereas all other scripts use the parcel pool. For the purpose of ray cast accounting (and script limits in general), a 'vehicle' is defined as an object which had one or more avatars seated on it when it entered the parcel. A ray cast can be performed if at least 30us of raycast time remain in the appropriate pool. If there is insufficient time remaining, [[RCERR_CAST_TIME_EXCEEDED]] is returned as the status code. The exact time used by the ray cast is measured when it is performed and that number (in microseconds) is subtracted from the pool. (The time remaining can be a negative number.) Over time, the pool is automatically replenished (at a rate of 25% of the max time per frame).

For example, if you start out with 100us and perform a 50us raycast, 50us will be remain. If you then a 70us raycast during the same frame, you will have -20us remaining. Subsequent calls to llCastRay that frame will fail with status code [[RCERR_CAST_TIME_EXCEEDED]]. At the start of the next frame, you will have 5us available (25us are restored each frame) and any attempt to call llCastRay will again fail as you need 30us to execute a raycast. One frame after that, 30us will be available and a raycast can once again be performed.

This method of throttling puts the scripter "closer to the machine". That is, you're only being charged for what you use, and more efficient raycast techniques will automatically be charged less than less efficient ones. The exact throttle values are subject to change at any time. To ensure robust results, be sure to check for [[RCERR_CAST_TIME_EXCEEDED]] and [[RCERR_SIM_PERF_LOW]] and sleep or do other work for a while before trying again.

'''Tips for Efficient Raycasts:'''
*Keep the max number of hits returned as small as possible
*Set as many [[RC_REJECT_TYPES]] as possible (of factors you can control, this will likely have the largest impact). For example, if you only want to know where the nearest agent is along a ray, use <code>[[RC_REJECT_LAND]] {{!}} [[RC_REJECT_PHYSICAL]] {{!}} [[RC_REJECT_NONPHYSICAL]]</code>
*When possible, avoid raycasting through piles of prims and avoid raycasting against concave physics objects (anything with cut, hollow, twist, and so on, and any mesh object that has no decomposition and has physics type "prim"). Obviously this can't always be avoided, so some casts may take significantly longer than others. Plan for that with robust scripts that handle [[RCERR_CAST_TIME_EXCEEDED]] responsibly, namely by sleeping briefly after the call and waiting for a few frames to go by before trying again.

'''Note:''' [https://jira.secondlife.com/browse/SCR-199 SCR-199] indicates that pools have been removed from the main grid, so this return code should not appear.

==== {{LSL Param|options}} parameter ====

<table class=lltable border=1 id="options">
<caption>{{LSLP|options}} flags and their parameters</caption>
<tr>
<th>Flag</th>
<th title='Value'>V</th>
<th>Parameters</th>
<th>Default Value</th>
<th>Description</th>
</tr>
<tr><td>[ {{LSL Const|RC_REJECT_TYPES|integer|0}} ] </td>
<td>{{#var:value}}</td>
<td>[ [[integer]] {{LSLPT|filter}} ]</td>
<td>[ 0 ]</td>
<td> Mask used to ignore specific types of objects (and avatars). </td>
</tr>
<tr><td>[ {{LSL Const|RC_DATA_FLAGS|integer|2}} ] </td>
<td>{{#var:value}}</td>
<td>[ [[integer]] {{LSLPT|flags}} ]</td>
<td>[ 0 ]</td>
<td> Described in the [[#RC_DATA_FLAGS|RC_DATA_FLAGS]] section. </td>
</tr>
<tr><td>[ {{LSL Const|RC_MAX_HITS|integer|3}} ] </td>
<td>{{#var:value}}</td>
<td>[ [[integer]] {{LSLPT|max_hits}} ]</td>
<td>[ 1 ]</td>
<td> Maximum number of hits to return. Maximum value is 256. ''To avoid performance issues, keep it small.''</td>
</tr>
<tr><td>[ {{LSL Const|RC_DETECT_PHANTOM|integer|1}} ] </td>
<td>{{#var:value}}</td>
<td>[ [[integer]] {{LSLPT|detect_phantom}} ]</td>
<td>[ [[FALSE]] ]</td>
<td>Set to [[TRUE]] (or nonzero) to detect phantom AND volume detect objects. It is not possible to detect only phantom objects or only volume detect objects. If set to [[TRUE]], phantom and volume detect objects will always be detected, even if [[RC_REJECT_NONPHYSICAL]] and [[RC_REJECT_PHYSICAL]] are set in [[RC_REJECT_TYPES]].</td>
</tr>
</table>

=====[[RC_REJECT_TYPES]]=====

{{LSLP|filter}} is a bitwise-or combination of the following constants: [[RC_REJECT_AGENTS]], [[RC_REJECT_PHYSICAL]], [[RC_REJECT_NONPHYSICAL]], and [[RC_REJECT_LAND]] except that if you select all four of them, a script runtime error will be generated (it makes no sense to cast a ray and reject everything!). Note that phantom and volume detect objects are never returned and that seated agents are treated like unseated agents. I.e., you either get seated and unseated agents in your results, or you use [[RC_REJECT_AGENTS]] and get neither. Using 0 as the filter value will return all hits.

=====[[RC_DATA_FLAGS]]=====

{{LSLP|flags}} is a bitwise-or combination of: [[RC_GET_NORMAL]], [[RC_GET_ROOT_KEY]], and [[RC_GET_LINK_NUM]]. These select whether you want link numbers and hit normals in your results list. By default, you will get the UUID ('key') of the exact child prim hit. If instead you want the key of the root prim, set [[RC_GET_ROOT_KEY]]. A terrain hit will register as [[NULL_KEY]].

|examples=
<source lang="lsl2">
integer filter;// default is 0

default
{
state_entry()
{
string ownerName = llKey2Name(llGetOwner());
llOwnerSay("Hello, " + ownerName + "!");
}

touch_start(integer total_number)
{
vector start = llGetPos();
vector end = start - <0.0, -25.0, 0.0>;

if ( filter > 8 )
filter = 0;

llOwnerSay("Filter " + (string)filter);

list results = llCastRay(start, end, [RC_REJECT_TYPES, filter, RC_MAX_HITS, 4] );

integer hitNum = 0;
// Handle error conditions here by checking llList2Integer(results, -1) >= 0
while (hitNum < llList2Integer(results, -1))
{
// Stride is 2 because we didn't request normals or link numbers
key uuid = llList2Key(results, 2*hitNum);

string name = "Land"; // if (uuid == NULL_KEY)

if (uuid != NULL_KEY)
name = llKey2Name(uuid);

llOwnerSay("Hit " + name + ".");

++hitNum;
}

++filter;
}
}</source>
<source lang="lsl2">

// Fire a weapon at a target, report a hit

integer gTargetChan = -9934917;

default
{
attach(key id)
{
if (id != NULL_KEY)
{
llRequestPermissions(id,PERMISSION_TAKE_CONTROLS|PERMISSION_TRACK_CAMERA);
}
}

run_time_permissions (integer perm)
{
if (perm & PERMISSION_TAKE_CONTROLS|PERMISSION_TRACK_CAMERA)
{
llTakeControls(CONTROL_LBUTTON|CONTROL_ML_LBUTTON,TRUE,FALSE);
}
}

control (key id, integer level, integer edge)
{
// User must be in mouselook to aim the weapon
if (level & edge & CONTROL_LBUTTON)
{
llSay(0,"You must be in Mouselook to shoot. Type \"CTRL + M\" or type \"Esc\" and scroll your mouse wheel forward to enter Mouselook.");
}
// User IS in mouselook
if (level & edge & CONTROL_ML_LBUTTON)
{
vector start = llGetCameraPos();
// Detect only a non-physical, non-phantom object. Report its root prim's UUID.
list results = llCastRay(start, start+<60.0,0.0,0.0>*llGetCameraRot(),[RC_REJECT_TYPES,RC_REJECT_PHYSICAL|RC_REJECT_AGENTS|RC_REJECT_LAND,RC_DETECT_PHANTOM,FALSE,RC_DATA_FLAGS,RC_GET_ROOT_KEY,RC_MAX_HITS,1]);
llTriggerSound(llGetInventoryName(INVENTORY_SOUND,0),1.0);
llSleep(0.03);
key target = llList2Key(results,0);
// Tell target that it has been hit.
llRegionSayTo(target,gTargetChan,"HIT");
// Target, scripted to listen on gTargetChan, can explode, change color, fall over .....
}
}
}
</source>
|notes=
Use [[llDumpList2String]] to see what the output looks like when you try a new set of flags.

To quickly get the status code use <code>[[llList2Integer]](result, -1)</code>.

'''Ideas for uses''':

* '''Weapons''' - Raycasts are the traditional tool used in game development for simulating projectile weapons. They are orders of magnitude more efficient than rezzing a prim and launching it from a weapon.
* '''AI Objects''' - Line-of-sight detection of avatars and other objects, or for navigating an environment by tracing rays about themselves. For example; casting rays directly downwards to determine the height and angle (normal) of the current floor surface, useful for non-physical object movement.
* '''Intelligent Object Placement''' - Static objects can be placed in-scene, but adjust themselves to their environment. For example; an object rezzed too high up may adjust its height to floor-level, or a computer console placed low down may cause an avatar to kneel to use it rather than standing.
* '''Environment Analysis''' - Can be used to determine the limitations of a surrounding area, such as determining if an object has been placed within a closed room. Not a test to be performed frequently due to quantity of rays required, but could be used by objects to switch off effects if unobserved (no-one within the room). Auto-adjusting furniture or objects to snap to walls, floors, and ceilings.
|cat1=Physics
|cat2=Light
|history = *Date of Release [[ Release_Notes/Second_Life_Server/11#11.09.23.241511 | 23/09/2011 ]]
* {{jira|SCR-199}} - fixed - The throttle was too low and thus rendered the function not as useful as it could be.
}}

LlGroundNormal

2012-06-16T08:21:47Z

Kayaker Magic: changed the caveat to say "unit normal" instead of just normal

{{LSL_Function
|func_id=222|func_sleep=0.0|func_energy=10.0
|func=llGroundNormal
|return_type=vector|p1_type=vector|p1_name=offset
|func_footnote=The requested position needs to be in the same sim.
|func_desc
|return_text=that is the ground normal from the current [[llGetPos|position]] + '''offset'''.
|spec=This function is defined as:
<lsl>
vector llGroundNormal(vector offset)
{
vector slope = llGroundSlope(offset);
return <slope.x, slope.y, 1.0>;
}
</lsl>
|caveats=*Despite the name, [[llGroundNormal]] DOES NOT RETURN A NORMAL UNIT VECTOR!!! If your calculation requires a unit normal (for example if you are using the result as an argument to [[llAxes2Rot]]) then you must force it to be a unit normal with [[llVecNorm]]([[llGroundNormal]](offset));
|constants
|examples
|helpers
|also_functions={{LSL DefineRow||[[llGround]]|Gets the ground height}}
{{LSL DefineRow||[[llGroundContour]]|Gets the ground contour}}
{{LSL DefineRow||[[llGroundSlope]]|Gets the ground slope}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Ground
|cat2=Region
|cat3
|cat4
}}

LlGroundNormal

2012-06-16T08:19:58Z

Kayaker Magic: marking references to llGroundNormal itself as links, so they are formatted to show up better in the text

{{LSL_Function
|func_id=222|func_sleep=0.0|func_energy=10.0
|func=llGroundNormal
|return_type=vector|p1_type=vector|p1_name=offset
|func_footnote=The requested position needs to be in the same sim.
|func_desc
|return_text=that is the ground normal from the current [[llGetPos|position]] + '''offset'''.
|spec=This function is defined as:
<lsl>
vector llGroundNormal(vector offset)
{
vector slope = llGroundSlope(offset);
return <slope.x, slope.y, 1.0>;
}
</lsl>
|caveats=*Despite the name, [[llGroundNormal]] DOES NOT RETURN A NORMAL VECTOR!!! If your calculation requires a normal (for example if you are using the result as an argument to [[llAxes2Rot]]) then you must force it to be a normal with [[llVecNorm]]([[llGroundNormal]](offset));
|constants
|examples
|helpers
|also_functions={{LSL DefineRow||[[llGround]]|Gets the ground height}}
{{LSL DefineRow||[[llGroundContour]]|Gets the ground contour}}
{{LSL DefineRow||[[llGroundSlope]]|Gets the ground slope}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Ground
|cat2=Region
|cat3
|cat4
}}

LlGroundNormal

2012-06-16T08:14:38Z

Kayaker Magic: fixing the links I just added

{{LSL_Function
|func_id=222|func_sleep=0.0|func_energy=10.0
|func=llGroundNormal
|return_type=vector|p1_type=vector|p1_name=offset
|func_footnote=The requested position needs to be in the same sim.
|func_desc
|return_text=that is the ground normal from the current [[llGetPos|position]] + '''offset'''.
|spec=This function is defined as:
<lsl>
vector llGroundNormal(vector offset)
{
vector slope = llGroundSlope(offset);
return <slope.x, slope.y, 1.0>;
}
</lsl>
|caveats=*Despite the name, llGroundNormal DOES NOT RETURN A NORMAL VECTOR!!! If your calculation requires a normal (for example if you are using the result as an argument to [[llAxes2Rot]]) then you must force it to be a normal with [[llVecNorm]](llGroundNormal(offset));
|constants
|examples
|helpers
|also_functions={{LSL DefineRow||[[llGround]]|Gets the ground height}}
{{LSL DefineRow||[[llGroundContour]]|Gets the ground contour}}
{{LSL DefineRow||[[llGroundSlope]]|Gets the ground slope}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Ground
|cat2=Region
|cat3
|cat4
}}

LlGroundNormal

2012-06-16T08:13:33Z

Kayaker Magic: Putting links in my recent change

{{LSL_Function
|func_id=222|func_sleep=0.0|func_energy=10.0
|func=llGroundNormal
|return_type=vector|p1_type=vector|p1_name=offset
|func_footnote=The requested position needs to be in the same sim.
|func_desc
|return_text=that is the ground normal from the current [[llGetPos|position]] + '''offset'''.
|spec=This function is defined as:
<lsl>
vector llGroundNormal(vector offset)
{
vector slope = llGroundSlope(offset);
return <slope.x, slope.y, 1.0>;
}
</lsl>
|caveats=*Despite the name, llGroundNormal DOES NOT RETURN A NORMAL VECTOR!!! If your calculation requires a normal (for example if you are using the result as an argument to [llAxes2Rot]) then you must force it to be a normal with [llVecNorm](llGroundNormal(offset));
|constants
|examples
|helpers
|also_functions={{LSL DefineRow||[[llGround]]|Gets the ground height}}
{{LSL DefineRow||[[llGroundContour]]|Gets the ground contour}}
{{LSL DefineRow||[[llGroundSlope]]|Gets the ground slope}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Ground
|cat2=Region
|cat3
|cat4
}}

LlGroundNormal

2012-06-16T08:09:40Z

Kayaker Magic: I wish I had known 8 hours ago that llGroundNormal does not return a normal

{{LSL_Function
|func_id=222|func_sleep=0.0|func_energy=10.0
|func=llGroundNormal
|return_type=vector|p1_type=vector|p1_name=offset
|func_footnote=The requested position needs to be in the same sim.
|func_desc
|return_text=that is the ground normal from the current [[llGetPos|position]] + '''offset'''.
|spec=This function is defined as:
<lsl>
vector llGroundNormal(vector offset)
{
vector slope = llGroundSlope(offset);
return <slope.x, slope.y, 1.0>;
}
</lsl>
|caveats=*Despite the name, llGroundNormal DOES NOT RETURN A NORMAL VECTOR!!! If your calculation requires a normal (for example if you are using the result as an argument to llAxes2Rot) then you must force it to be a normal with llVecNorm(llGroundNormal(offset));
|constants
|examples
|helpers
|also_functions={{LSL DefineRow||[[llGround]]|Gets the ground height}}
{{LSL DefineRow||[[llGroundContour]]|Gets the ground contour}}
{{LSL DefineRow||[[llGroundSlope]]|Gets the ground slope}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Ground
|cat2=Region
|cat3
|cat4
}}

Collision end

2010-08-23T21:17:55Z

Kayaker Magic: Listed caveats about when collsions do not trigger.

{{Issues/SVC-3306}}{{LSL_Event|event_id=7|event_delay|event=collision_end
|p1_type=integer|p1_name=num_detected|p1_desc
|event_desc=Triggered when task stops colliding with another task
|constants
|spec
|caveats=*This event does not always trigger reliably.
* Phantom objects can never receive trigger collision events.
* llVolumeDetect(TRUE) objects get trigger collision_start and collision_end but not collision() events.
* A collision with a hovering avatar does not trigger collisions, unless the avatar turns or moves.
* Only a physical object will get collision events from colliding with a non-physical object.

|examples=<lsl>collision_end(integer total_number)
{
llOwnerSay("The collision I've had with " + llDetectedName(0) + "has ended.");
}</lsl>
|helpers
|also_header
|also_events={{LSL DefineRow||[[collision_start]]|}}
{{LSL DefineRow||[[collision]]|}}
|also_functions={{LSL DefineRow||[[llPassCollisions]]|}}
{{LSL DefineRow||[[llCollisionFilter]]|}}
{{LSL DefineRow||[[llCollisionSound]]|}}
{{LSL DefineRow||[[llCollisionSprite]]|}}
{{LSL DefineRow||[[llVolumeDetect]]|}}
|also_articles
|also_footer
|notes
|issues
|cat1=Collision
|cat2=Detected
|cat3=Collision Events
|cat4}}

Collision

2010-08-23T21:15:27Z

Kayaker Magic: Added caveats for more times when collisions do not work.

{{Issues/SVC-3306}}{{LSL_Event|event_id=6|event_delay|event=collision
|p1_type=integer|p1_name=num_detected|p1_desc
|event_desc=Triggered while task is [[colliding]] with another task.
|constants
|spec
|caveats=
* Will not detect collisions with [[ground]]; use [[land_collision]] instead.
* Will not detect collisions between an avatar sitting on the task and the task itself (avatars are linked to objects they sit on so there is no collision, use the [[changed]] event to detect sits).
* Phantom objects can never receive trigger collision events.
* llVolumeDetect(TRUE) objects get trigger collision_start and collision_end but not collision() events.
* A collision with a hovering avatar does not trigger collisions, unless the avatar turns or moves.
* Only a physical object will get collision events from colliding with a non-physical object.
|examples=<lsl>//Will turn phantom when someone bumps into it if on the list

list access_list = ["Governor Linden"];

default
{
collision(integer num_detected)
{
if(~llListFindList(access_list, (list)llDetectedName(0)))
{
llSetStatus(STATUS_PHANTOM, TRUE);
}
}
}</lsl>
|helpers
|also_header
|also_events=
{{LSL DefineRow||[[collision_start]]|}}
{{LSL DefineRow||[[collision_end]]|}}
|also_functions={{LSL DefineRow||[[llPassCollisions]]|}}
{{LSL DefineRow||[[llCollisionFilter]]|}}
{{LSL DefineRow||[[llCollisionSound]]|}}
{{LSL DefineRow||[[llCollisionSprite]]|}}
{{LSL DefineRow||[[llVolumeDetect]]|}}
|also_articles
|also_footer
|notes
|issues
|cat1=Collision
|cat2=Detected
|cat3=Collision Events
|cat4}}

Collision start

2010-08-23T21:13:21Z

Kayaker Magic: oops, missed one bullet

{{Issues/SVC-3306}}{{LSL_Event|event_id=5|event_delay|event=collision_start
|p1_type=integer|p1_name=num_detected|p1_desc
|event_desc=Triggered when task starts colliding with another task
|constants
|spec
|caveats=
* Will not detect collisions with ground. Use [[land_collision_start]] instead.
* Phantom objects can never receive trigger collision events.
* llVolumeDetect(TRUE) objects get trigger collision_start and collision_end but not collision() events.
* A collision with a hovering avatar does not trigger collisions, unless the avatar turns or moves.
* Only a physical object will get collision events from colliding with a non-physical object.
|examples=<lsl>default
{
collision_start(integer num)
{
llSay(0,"No pushing.");
}
}</lsl>
|helpers
|also_header
|also_events={{LSL DefineRow||[[collision]]|}}
{{LSL DefineRow||[[collision_end]]|}}
|also_functions={{LSL DefineRow||[[llPassCollisions]]|}}
{{LSL DefineRow||[[llCollisionFilter]]|}}
{{LSL DefineRow||[[llCollisionSound]]|}}
{{LSL DefineRow||[[llCollisionSprite]]|}}
{{LSL DefineRow||[[llVolumeDetect]]|}}
|also_articles
|also_footer
|notes
|mode
|issues
|cat1=Collision
|cat2=Detected
|cat3=Collision Events
|cat4
}}

Collision start

2010-08-23T21:12:13Z

Kayaker Magic: Listed times when collisions will won't work in the caveats.

{{Issues/SVC-3306}}{{LSL_Event|event_id=5|event_delay|event=collision_start
|p1_type=integer|p1_name=num_detected|p1_desc
|event_desc=Triggered when task starts colliding with another task
|constants
|spec
|caveats=
* Will not detect collisions with ground. Use [[land_collision_start]] instead.
* Phantom objects can never receive trigger collision events.
llVolumeDetect(TRUE) objects get trigger collision_start and collision_end but not collision() events.
* A collision with a hovering avatar does not trigger collisions, unless the avatar turns or moves.
* Only a physical object will get collision events from colliding with a non-physical object.
|examples=<lsl>default
{
collision_start(integer num)
{
llSay(0,"No pushing.");
}
}</lsl>
|helpers
|also_header
|also_events={{LSL DefineRow||[[collision]]|}}
{{LSL DefineRow||[[collision_end]]|}}
|also_functions={{LSL DefineRow||[[llPassCollisions]]|}}
{{LSL DefineRow||[[llCollisionFilter]]|}}
{{LSL DefineRow||[[llCollisionSound]]|}}
{{LSL DefineRow||[[llCollisionSprite]]|}}
{{LSL DefineRow||[[llVolumeDetect]]|}}
|also_articles
|also_footer
|notes
|mode
|issues
|cat1=Collision
|cat2=Detected
|cat3=Collision Events
|cat4
}}

LlSitTarget

2010-08-23T02:36:00Z

Kayaker Magic:

{{LSL_Function
|func_id=238|func_sleep=0.0|func_energy=10.0
|sort=SitTarget
|func=llSitTarget
|p1_type=vector|p1_name=offset|p1_desc=Additional position for the sit target in local prim coordinates.
|p2_type=rotation|p2_name=rot|p2_desc=Additional rotation for the sit target relative to the prim rotation.
|func_footnote=If '''offset''' == [[ZERO_VECTOR|{{LSL VR|0.0|0.0|0.0}}]] then the sit target is removed.
|func_desc=Set the sit location for the prim. The sit location is relative to the prim's position and rotation.
|return_text
|spec=llSitTarget sets the position for the Agent Target (Advanced -> Character -> View Agent Target). The position of the target is based on '''rot''' and the '''offset'''{{Footnote|It is widely considered that the '''rot''' should not affect the position, unfortunately the sit target code is a {{Wikipedia|Lava_flow_(programming)|lava-flow}}. ~ {{JIRA|SVC-2277}}|It is widely considered that the '''rot''' should not affect the position, unfortunately the sit target code is a lava-flow. - SVC-2277|handle=rot-offset}}.
|caveats=*Once a sit target is removed [[llAvatarOnSitTarget]] will only return {{LSL_Constant/NULL_KEY}}.
*Removing or deactivating the script that sets the sit target will not remove the prim's sit target.
**Sit target is a prim property and not dependent on a script for its continued existence.
*To remove sit target, use the following:
<lsl>llSitTarget(ZERO_VECTOR,ZERO_ROTATION);</lsl>
*Shift-copying a prim with a sit target, without a script that will set the sit target again, will not keep the sit target on the copy. (The copy is in the original location when shift-copying.)
*There is no way to remove the Sit option from the pie menu.
**It will appear to be removed if the [[llSetSitText]] is set to a space " " or similar transparent string.
*Attachments cannot be sat upon.
*'''rot''' affects the position of the sit-target in a buggy way way.
**To correct for the ''rot'' bug, simply subtract <0,0,0.4> from the position when ''rot'' is zero. See example below.
**[[llSetLinkPrimitiveParams]] is a more difficult work-around.
**Animations are relative to the Agent Target, but the Agent Target isn't described by the animation.
*[[llSitTarget]] does not update position of an already seated avatar.
**[[#UpdateSitTarget|UpdateSitTarget]] described below works around this problem. It works by converting the sit target information into a link position that is passed along to [[llSetLinkPrimitiveParams]].
* '''offset''' is limited to 300.0 meters on each axis. The x, y and z components must be in the range {{Interval|lte=300.0|gte=-300}}{{Footnote|handle=interval}}.
** If they are outside the acceptable range they are rounded to the closest limit.
|constants
|examples=
<lsl>default
{
state_entry()
{
llSitTarget(<0.0, 0.0, 1.0>, ZERO_ROTATION); //The vector's components must not all be set to 0 for effect to take place.
}
}</lsl>
<lsl>default //example with work-around for llSetTarget rot bug
{ //place in any prim large enough to sit on at any angle
//click once to choose a place to sit, a second time to sit there
touch_start(integer num)
{
vector pos=llDetectedTouchPos(0); //use touch to set sit target
vector lft=llDetectedTouchBinormal(0); //use normals to rotate avatar to
vector up=llDetectedTouchNormal(0); //sit upright
rotation rot=llAxes2Rot(lft%up,lft,up)/llGetRot(); //rotate avatar to stand there
vector siz=llGetAgentSize(llDetectedKey(0));
pos += 0.65*siz.z*up; //this places MY avatars feet close to the surface
pos = (pos-llGetPos())/llGetRot(); //llSetTarget expects local co-ordinates
if (rot!=ZERO_ROTATION) pos -=<0,0,0.4>; //here is the work around
llSitTarget(pos,rot);
llSetClickAction(CLICK_ACTION_SIT); //switch to sit for second click
}
changed(integer change)
{
if (llAvatarOnSitTarget()==NULL_KEY) //if they unsit,
llSetClickAction(CLICK_ACTION_TOUCH); //go back to click mode
}
}</lsl>
|helpers= ===UpdateSitTarget===
<lsl>//Sets / Updates the sit target moving the avatar on it if necessary.
UpdateSitTarget(vector pos, rotation rot)
{//Using this while the object is moving may give unpredictable results.
llSitTarget(pos, rot);//Set the sit target
key user = llAvatarOnSitTarget();
if(user)//true if there is a user seated on the sittarget, if so update their position
{
vector size = llGetAgentSize(user);
if(size)//This tests to make sure the user really exists.
{
//We need to make the position and rotation local to the current prim
rotation localrot = ZERO_ROTATION;
vector localpos = ZERO_VECTOR;
if(llGetLinkNumber() > 1)//only need the local rot if it's not the root.
{
localrot = llGetLocalRot();
localpos = llGetLocalPos();
}
pos.z += 0.4;
integer linkNum = llGetNumberOfPrims();
do{
if(user == llGetLinkKey( linkNum ))//just checking to make sure the index is valid.
{
llSetLinkPrimitiveParams(linkNum,
[PRIM_POSITION, ((pos - (llRot2Up(rot) * size.z * 0.02638)) * localrot) + localpos,
PRIM_ROTATION, rot * localrot / llGetRootRotation()]);
jump end;//cheaper but a tad slower then return
}
}while( --linkNum );
}
else
{//It is rare that the sit target will bork but it does happen, this can help to fix it.
llUnSit(user);
}
}
@end;
}//Written by Strife Onizuka, size adjustment provided by Escort DeFarge</lsl>
===GetSitTarget===
<lsl>list GetSitTarget(integer prim, key av)
{//WARNING: llGetObjectDetails can introduce an error that goes as far as the 5th decimal place!
//This is highly unlikely to be ever noticed unless compounded over time.
//Do not use while moving (like in a moving vehicle)!!!
vector tp = llGetAgentSize(av);
if(tp)
{
if(prim == LINK_THIS)//llGetLinkKey doesn't like LINK_THIS
prim = llGetLinkNumber();

list details = [OBJECT_POS, OBJECT_ROT];
rotation f = llList2Rot(details = (llGetObjectDetails(llGetLinkKey(prim), details) + llGetObjectDetails(av, details)), 1);
rotation r = llList2Rot(details, 3) / f;

return [((llList2Vector(details, 2) - llList2Vector(details, 0)) / f) + (llRot2Up(r) * tp.z * 0.02638) - <0.0, 0.0, 0.4>, r];
}
return [];
}//Written by Strife Onizuka</lsl>
|also_functions={{LSL DefineRow||[[llSetSitText]]|}}
{{LSL DefineRow||[[llAvatarOnSitTarget]]|}}
{{LSL DefineRow||[[llUnSit]]|}}
|also_events={{LSL DefineRow||[[changed]]|}}
|also_articles
|notes
|cat1=Sit
|cat2=Vehicle
|cat3=Prim
|cat4=Effects
|cat5=Teleport
|cat6=Stop
}}

LlGetLinkName

2009-08-20T02:08:03Z

Kayaker Magic: Most of the LINK_* constants do not apply, and LINK_THIS does not work properly.

{{LSL_Function/link|linknum|}}{{LSL_Function/limits}}
{{LSL_Function
|func_id=145|func_sleep=0.0|func_energy=10.0
|func=llGetLinkName
|return_type=string|p1_type=integer|p1_name=linknum
|func_footnote
|func_desc
|return_text=that is the name of '''linknum''' in link set
|spec
|caveats=*The prim name attribute is limited to 63 bytes, any string longer then that will be truncated. This truncation does not always happen when the attribute is set or read.
*The only LINK_* flag that '''linknum''' currently supports is [[LINK_ROOT]]. [[#SVC-3510|SVC-3510]]
**Use [[llGetLinkNumber]]() as the parameter to retreive the prim's name, not [[LINK_THIS]].
|constants
|examples=Listen on channel 10 for a name; check if a prim with that name is part of this object
<lsl>
integer check_for_prim(string name)
{
integer i = llGetNumberOfPrims();
for (; i >= 0; --i)
{
if (llGetLinkName(i) == name)
{
return TRUE;
}
}
return FALSE;
}
default
{
state_entry()
{
llListen(10, "", llGetOwner(), "");
}
listen(integer chan, string obj, key id, string msg)
{
if (check_for_prim(msg))
{
llOwnerSay("found a linked prim named \"" + msg + "\"");
}
else
{
llOwnerSay("this object does not have any linked prims named \"" + msg + "\"");
}
}
}</lsl>
|helpers
|also_functions=
{{LSL DefineRow||[[llGetLinkKey]]|Gets the instance UUID of the link}}
{{LSL DefineRow||[[llGetObjectName]]|Get the prims name}}
{{LSL DefineRow||[[llSetObjectName]]|Set the prims name}}
{{LSL DefineRow||[[llGetObjectDesc]]|Get the prims description}}
{{LSL DefineRow||[[llSetObjectDesc]]|Set the prims description}}
{{LSL DefineRow||[[llGetObjectDetails]]}}
|also_tests
|also_events
|also_articles=
{{LSL DefineRow||[[Prim Attribute Overloading]]}}
|notes
|cat1=Link
|cat2=Link/Get
|cat3
|cat4
}}

LlBreakLink

2008-12-10T06:12:04Z

Kayaker Magic: changing order of caveats

{{LSL_Function/link|linknum}}
{{LSL_Function/permission|PERMISSION_CHANGE_LINKS|grant=the owner}}
{{LSL_Function|func_id=142|func_sleep=0.0|func_energy=10.0|func=llBreakLink
|p1_type=integer|p1_name=linknum
|func_desc=Delinks the prim with the given link number in a linked object set
|func_footnote
|return_text
|spec
|caveats=*This function removes sitting avatars from the object, even if not sitting on the unlinked prim.
*This function silently fails if called from a script inside an attachment.
*This function fails if the owner does not have edit permissions on the object containing the script, the system message "''Delink failed because you do not have edit permission''" is received by the owner.
*A prim with PERMISSION_CHANGE_LINKS can delink any prim in the linked object set even itself or the root
*LINK_ROOT delinks only the root prim, even if that is this prim
*LINK_THIS does not unlink this prim: It delinks the root prim, unless the root prim is this one. In that case LINK_THIS unlinks the first child prim
*Use llGetLinkNumber() as the parameter to unlink this prim, not LINK_THIS
*Link_ALL_CHILDREN, LINK_SET and LINK_ALL_OTHERS behave exactly the same as LINK_THIS
|constants
|examples=
<lsl>//-- requests permission to change links, then breaks the link
//-- between the prim and the rest of the object, on touch.
default{
state_entry(){
llRequestPermissions( llGetOwner(), PERMISSION_CHANGE_LINKS );
}

touch_start( integer vIntTouched ){
llBreakLink( llGetLinkNumber() );
}
}</lsl>
|helpers
|also_functions={{LSL DefineRow||[[llBreakAllLinks]]|Break all links}}
{{LSL DefineRow||[[llCreateLink]]|Link to another object}}
|also_tests
|also_events={{LSL DefineRow||[[changed]]|[[CHANGED_LINK]]}}
|also_articles
|notes
|permission
|cat1=Link
|cat2=Link/Management
|cat3
|cat4
}}

LlBreakLink

2008-12-10T06:07:36Z

Kayaker Magic: some spelling and capitalization

{{LSL_Function/link|linknum}}
{{LSL_Function/permission|PERMISSION_CHANGE_LINKS|grant=the owner}}
{{LSL_Function|func_id=142|func_sleep=0.0|func_energy=10.0|func=llBreakLink
|p1_type=integer|p1_name=linknum
|func_desc=Delinks the prim with the given link number in a linked object set
|func_footnote
|return_text
|spec
|caveats=*This function removes sitting avatars from the object, even if not sitting on the unlinked prim.
*This function silently fails if called from a script inside an attachment.
*This function fails if the owner does not have edit permissions on the object containing the script, the system message "''Delink failed because you do not have edit permission''" is received by the owner.
*A prim with PERMISSION_CHANGE_LINKS can delink any prim in the linked object set even itself or the root
*Use llGetLinkNumber() as the parameter to unlink this prim
*LINK_ROOT delinks only the root prim, even if that is this prim
*LINK_THIS does not unlink this prim: It delinks the root prim, unless the root prim is this one. In that case LINK_THIS unlinks the first child prim
*Link_ALL_CHILDREN, LINK_SET and LINK_ALL_OTHERS behave exactly the same as LINK_THIS
|constants
|examples=
<lsl>//-- requests permission to change links, then breaks the link
//-- between the prim and the rest of the object, on touch.
default{
state_entry(){
llRequestPermissions( llGetOwner(), PERMISSION_CHANGE_LINKS );
}

touch_start( integer vIntTouched ){
llBreakLink( llGetLinkNumber() );
}
}</lsl>
|helpers
|also_functions={{LSL DefineRow||[[llBreakAllLinks]]|Break all links}}
{{LSL DefineRow||[[llCreateLink]]|Link to another object}}
|also_tests
|also_events={{LSL DefineRow||[[changed]]|[[CHANGED_LINK]]}}
|also_articles
|notes
|permission
|cat1=Link
|cat2=Link/Management
|cat3
|cat4
}}

LlBreakLink

2008-12-10T06:05:22Z

Kayaker Magic: Clariffying the behavior of the LINK_* flags

{{LSL_Function/link|linknum}}
{{LSL_Function/permission|PERMISSION_CHANGE_LINKS|grant=the owner}}
{{LSL_Function|func_id=142|func_sleep=0.0|func_energy=10.0|func=llBreakLink
|p1_type=integer|p1_name=linknum
|func_desc=Delinks the prim with the given link number in a linked object set
|func_footnote
|return_text
|spec
|caveats=*This function removes sitting avatars from the object, even if not sitting on the unlinked prim.
*This function silently fails if called from a script inside an attachment.
*This function fails if the owner does not have edit permissions on the object containing the script, the system message "''Delink failed because you do not have edit permission''" is received by the owner.
*A prim with PERMISSION_CHANGE_LINKS can delink any prim in the linked object set even itself or the root
*Use llGetLinkNumber() as the parameter to unlink this prim
*LINK_ROOT delinks only the root prim, even if that is this prim
*LINK_THIS does not unlink this prim: Tt delinks the root prim, unless the root prim is this one. In that case LINK_This unlinks the first child prim
*Link_ALL_CHILDREN, LINK_SET and LINK_ALL_OTHERS behave exactly the same as LINK_THIS
|constants
|examples=
<lsl>//-- requests permission to change links, then breaks the link
//-- between the prim and the rest of the object, on touch.
default{
state_entry(){
llRequestPermissions( llGetOwner(), PERMISSION_CHANGE_LINKS );
}

touch_start( integer vIntTouched ){
llBreakLink( llGetLinkNumber() );
}
}</lsl>
|helpers
|also_functions={{LSL DefineRow||[[llBreakAllLinks]]|Break all links}}
{{LSL DefineRow||[[llCreateLink]]|Link to another object}}
|also_tests
|also_events={{LSL DefineRow||[[changed]]|[[CHANGED_LINK]]}}
|also_articles
|notes
|permission
|cat1=Link
|cat2=Link/Management
|cat3
|cat4
}}

LlBreakLink

2008-12-10T05:52:59Z

Kayaker Magic: Simplifying example, the run_time_permissions state is not necessary if you grant before touching

{{LSL_Function/link|linknum}}
{{LSL_Function/permission|PERMISSION_CHANGE_LINKS|grant=the owner}}
{{LSL_Function|func_id=142|func_sleep=0.0|func_energy=10.0|func=llBreakLink
|p1_type=integer|p1_name=linknum
|func_desc=Delinks the prim with the given link number in a linked object set
|func_footnote
|return_text
|spec
|caveats=*This function removes sitting avatars from the object, even if not sitting on the unlinked prim.
*This function silently fails if called from a script inside an attachment.
*This function fails if the owner does not have edit permissions on the object containing the script, the system message "''Delink failed because you do not have edit permission''" is received by the owner.
|constants
|examples=
<lsl>//-- requests permission to change links, then breaks the link
//-- between the prim and the rest of the object, on touch.
default{
state_entry(){
llRequestPermissions( llGetOwner(), PERMISSION_CHANGE_LINKS );
}

touch_start( integer vIntTouched ){
llBreakLink( llGetLinkNumber() );
}
}</lsl>
|helpers
|also_functions={{LSL DefineRow||[[llBreakAllLinks]]|Break all links}}
{{LSL DefineRow||[[llCreateLink]]|Link to another object}}
|also_tests
|also_events={{LSL DefineRow||[[changed]]|[[CHANGED_LINK]]}}
|also_articles
|notes
|permission
|cat1=Link
|cat2=Link/Management
|cat3
|cat4
}}

VEHICLE HOVER HEIGHT

2008-11-14T20:56:40Z

Kayaker Magic: set to zero to disable hover

{{LSL Constant
|name=VEHICLE_HOVER_HEIGHT
|type=integer
|value=24
|desc=height the vehicle will try to hover above ground. Set to zero to disable hover.

|functions=
{{LSL DefineRow||[[llSetVehicleFloatParam]]|}}
|events=

|also_articles={{LSL DefineRow||[[Linden Vehicle Tutorial]]}}
|cat1
|cat2
|cat3
|cat4
}}