Second Life Wiki - User contributions [en]

LlSetTextureAnim

2008-12-17T18:29:51Z

Ralph Doctorow: What is a frame, no repeats or rotations

{{LSL_Function/negative index|true|start}}{{#vardefine:spec|}}{{LSL_Function/face|face}}{{LSL_Function
|func_id=211
|func_sleep=0.0
|func_energy=10.0
|sort=SetTextureAnim
|func=llSetTextureAnim
|p1_type=integer|p1_name=mode|p1_desc=mask of Mode flags
|p2_type=integer|p2_name=face
|p3_type=integer|p3_name=sizex|p3_desc=horizontal frames (ignored for [[ROTATE]] and [[SCALE]])
|p4_type=integer|p4_name=sizey|p4_desc=vertical frames (ignored for [[ROTATE]] and [[SCALE]])
|p5_type=float|p5_name=start|p5_desc=Start position/frame number (or radians for [[ROTATE]])
|p6_type=float|p6_name=length|p6_desc=number of frames to display (or radians for [[ROTATE]])
|p7_type=float|p7_name=rate|p7_desc=frames per second (must not be zero)
|func_footnote=Frames are numbered from left to right, top to bottom, starting at 0.<br/>
'''Frames''' are sub-rectangles within the texture. A set of frames with 2 horizontal and 3 vertical means the overall texture is divided into 3 rows of 2 columns of images, each of which is a frame. llSetTextureAnim will animate across these 6 starting with the top left image and going across and down, optionally repeating. If [[SMOOTH]] is set the frames slide smoothly from one to the next, if off, each frame is displayed in turn centered on the face.
<br/>If '''rate''' is negative, has the same effect as using the [[REVERSE]] flag.
|func_desc=Animate the texture on the specified face/faces by setting the texture scale and offset.
|return_text
|spec
|caveats=*You can only have one texture animation on a prim
**Calling llSetTextureAnim more than once on a prim will reset it.
*You cannot combine ROTATE and SCALE
*'''sizex''' & '''sizey''' are both limited to a range of 0 to 255
*llSetTextureAnim when on shows the texture with 1 repeat in X and Y and 0 rotation and offset.
|constants={{{!}} class="sortable collapsible" {{Prettytable|style=margin-top:0;}}
{{!}}-{{Hl2}}
! Modes
! title="Value" {{!}}
! class="unsortable" {{!}} Description
{{!}}-
{{!}}[[ANIM_ON]]
{{!}}{{LSL Hex||1|chars=2}}
{{!}}Texture animation is on. This must be set to start the animation, cleared to stop it.
{{!}}-
{{!}}[[LOOP]]
{{!}}{{LSL Hex||2|chars=2}}
{{!}}Loop the texture animation.
{{!}}-
{{!}}[[REVERSE]]
{{!}}{{LSL Hex||4|chars=2}}
{{!}}Play animation in reverse direction.
{{!}}-
{{!}}[[PING_PONG]]
{{!}}{{LSL Hex||8|chars=2}}
{{!}}Play animation going forwards, then backwards.
{{!}}-
{{!}}[[SMOOTH]]
{{!}}{{LSL Hex||16|chars=2}}
{{!}}Slide in the X direction, instead of playing separate frames.<br/>In both [[SCALE]] and [[ROTATE]] modes, causes smooth transitions.
{{!}}-
{{!}}[[ROTATE]]
{{!}}{{LSL Hex||32|chars=2}}
{{!}}Animate texture rotation.<br>Does not work with [[SCALE]]
{{!}}-
{{!}}[[SCALE]]
{{!}}{{LSL Hex||64|chars=2}}
{{!}}Animate the texture scale.<br>Does not work with [[ROTATE]]
{{!}}}
|examples=
This slides a texture smoothly and loops it when it gets to the end.
<lsl>llSetTextureAnim(ANIM_ON | SMOOTH | LOOP , ALL_SIDES, 1, 1, 1, 1, 1);</lsl>

This slides a texture smoothly in the opposite direction
<lsl>llSetTextureAnim(ANIM_ON | SMOOTH | LOOP , ALL_SIDES, 1, 1, 1, 1, -1);</lsl>

This divides a texture into 64 "cells", 8 across, and 8 down, and flips through them, left to right, top to bottom. This is useful for cell animation.
<lsl>llSetTextureAnim( ANIM_ON | LOOP, ALL_SIDES, 8, 8, 0, 64, 6.4 );</lsl>

This rotates a texture counter-clockwise at 2 revolutions per second. Change the last value to -2*TWO_PI to rotate clockwise.
<lsl>llSetTextureAnim(ANIM_ON | SMOOTH | ROTATE | LOOP, ALL_SIDES,1,1,0, TWO_PI, 2*TWO_PI);</lsl>

This scales a texture larger and smaller.
<lsl>llSetTextureAnim(ANIM_ON | SMOOTH | SCALE | PING_PONG | LOOP, ALL_SIDES, 1, 1, 1, 3, 2);</lsl>

This turns off all texture animations
<lsl>llSetTextureAnim(FALSE, ALL_SIDES, 0, 0, 0.0, 0.0, 1.0);</lsl>

|helpers
|also_functions
|also_events
|also_articles
|notes
|permission
|negative_index
|cat1=Media
|cat2=Effects
|cat3=Texture
|cat4=Video
}}

Rotation

2008-12-08T04:47:05Z

Ralph Doctorow: Link to rotation

{{LSL Header|ml=*}}{{RightToc}}
=Rotations=
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'''.)
It is a mathematical object called a {{LSLG|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.

==Other representations==
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.

Another way to represent the same 3D angle is to use three vectors, showing what the front is pointing at, what the top is pointing at, and what the left side is pointing at. 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 '''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 ==

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. 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. To go from a rotation to an Euler angle {{LSLG|vector}} use {{LSLG|llRot2Euler}}.

'''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:

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|- valign="top"
| style="white-space: nowrap" |rotation rot30X
| style="white-space: nowrap" |= [[llEuler2Rot]](<30, 0, 0> * [[DEG_TO_RAD]]);
||// convert the degrees to radians, then convert that [[vector]] into a rotation, rot30x
|- valign="top"
| style="white-space: nowrap" |[[vector]] vec30X
| style="white-space: nowrap" |= [[llRot2Euler]](rot30X );
||// convert the rotation back to a [[vector]] (the values will be in radians)
|}
</div></div>

== 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.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|- valign="top"
| style="white-space: nowrap" |rotation localRot =
| style="white-space: nowrap" |rot30X * myRot;
||// do a local rotation by multiplying a constant rotation by a world rotation
|}
</div></div>

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.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|- valign="top"
| style="white-space: nowrap" |rotation globalRot
| style="white-space: nowrap" | = myRot * rot30X;
||// do a global rotation by multiplying a world rotation by a constant rotation
|}
</div></div>

== 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.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|- valign="top"
| style="white-space: nowrap" |rotation rot30X
| style="white-space: nowrap" |= [[llEuler2Rot]](<30, 0, 0> * [[#DEG_TO_RAD|DEG_TO_RAD]] );
||// Create a rotation constant
|- valign="top"
| style="white-space: nowrap" |rotation rotCopy
| style="white-space: nowrap" |= rot30X;
||// Just copy it into rotCopy, it copies all 4 float components
|- valign="top"
| style="white-space: nowrap" |float X
| style="white-space: nowrap" |= rotCopy.x;
||// Get out the individual components of the rotation
|- valign="top"
| style="white-space: nowrap" |float Y
| style="white-space: nowrap" |= rotCopy.y;
||
|- valign="top"
| style="white-space: nowrap" |float Z
| style="white-space: nowrap" |= rotCopy.z;
||
|- valign="top"
| style="white-space: nowrap" |float S
| style="white-space: nowrap" |= rotCopy.s;
||
|- valign="top"
| style="white-space: nowrap" |rotation anotherCopy
| style="white-space: nowrap" |= <X, Y, Z, S>;
||// Make another rotation out of the components
|}
</div></div>

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.
<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|- valign="top"
| style="white-space: nowrap" |rotation rot330X
| style="white-space: nowrap" |= <-rot30X.x, -rot30X.y, -rot30X.z, rot30X.s>;
||// invert a rotation - NOTE the s component isn't negated
|- valign="top"
| style="white-space: nowrap" |rotation another330X
| style="white-space: nowrap" |= [[#ZERO_ROTATION|ZERO_ROTATION]] / rot30X;
||// invert a rotation by division, same result as rot330X
|- valign="top"
| style="white-space: nowrap" |rotation yetanother330X
| style="white-space: nowrap" |= <rot30X.x, rot30X.y, rot30X.z, -rot30X.s>;
||// not literally the same but works the same.
|}
</div></div>

==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.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|- valign="top"
| style="white-space: nowrap" |rotation rot6X
| style="white-space: nowrap" |= [[llEuler2Rot]](<30, 0, 0> * [[#DEG_TO_RAD|DEG_TO_RAD]] );
||// create a rotation constant, 30 degrees around the [[Viewer_coordinate_frames#Local|local]] X axis
|- valign="top"
| style="white-space: nowrap" |vector offset
| style="white-space: nowrap" |= <0, 1, 0>;
||// create an offset one meter in the [[Viewer_coordinate_frames#Local|local]] positive Y direction
|- valign="top"
| style="white-space: nowrap" |vector rotatedOffset
| style="white-space: nowrap" |= offset * rot6X;
||// rotate the offset to get the motion caused by the rotations
|- valign="top"
| style="white-space: nowrap" |vector newPos
| style="white-space: nowrap" |= [[llGetPos]]() + (offset - rotatedOffset) * [[llGetRot]]();
||// move the prim position by the rotated offset amount
|- valign="top"
| style="white-space: nowrap" |rotation newRot
| style="white-space: nowrap" |= rot6X * [[llGetRot]]();
||// change rot to continue facing offset point
|}
</div></div>
<lsl>
//-- same as:
llSetPrimitiveParams( [PRIM_POSITION, llGetPos() + (gPosOffset - gPosOffset * gRotArc) * llGetRot(),
PRIM_ROTATION, gRotArc * llGetRot()] );
</lsl>
'''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.

To get a point relative to the objects current facing (such as used in rezzors)
<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|- valign="top"
| style="white-space: nowrap" |rotation rotFacing
| style="white-space: nowrap" |= [[llGetRot]]();
||// get the objects current rotation
|- valign="top"
| style="white-space: nowrap" |vector offset
| style="white-space: nowrap" |= <0, 0, 1>;
||// create an offset one meter in the [[Viewer_coordinate_frames#Local|local]] positive Z direction
|- valign="top"
| style="white-space: nowrap" |vector rotatedOffset
| style="white-space: nowrap" | = offset * rotFacing;
||// rotate the offset to be relative to object rotation
|- valign="top"
| style="white-space: nowrap" |vector correctOffset
| style="white-space: nowrap" | = [[llGetPos]]() + rotatedOffset;
||// get the [[Viewer_coordinate_frames#Region|region]] position of the local offset
|}
</div></div>
<lsl>
//-- same as:
vector correctOffset = llGetPos() + offset * llGetRot();
</lsl>

==Useful Snippets==
<lsl>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 0;
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</lsl>

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

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

=== [[RAD_TO_DEG]] ===
RAD_TO_DEG = 57.29578f;<br/>
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_Constants]][[Category:LSL Rotation]]

LlTargetOmega

2008-12-04T04:02:34Z

Ralph Doctorow: Linked to Prim

{{LSL Function
|func_id=133
|func_sleep=0.0
|func_energy=10.0
|func=llTargetOmega
|p1_type=vector|p1_name=axis|p1_desc=arbitrary axis to rotate the object around
|p2_type=float|p2_name=spinrate|p2_desc=rate of rotation in radians per second
|p3_type=float|p3_name=gain|p3_desc=also modulates the final spinrate and disables the rotation behavior if zero
|func_footnote
|func_desc=Rotates the object around '''axis''' at '''spinrate''' * [[llVecMag]]('''axis''') in radians per second with strength '''gain'''.
|examples=<lsl>//rotates the x axis once per second,
// rotates the y axis 3 times per second,
// rotates the z axis once every two seconds.
// combined the rate is about 3.20156 revolutions per second

llTargetOmega(<1.0,3.0,0.5>,TWO_PI,1.0);</lsl>
|spec=
===Physics===
*If the object is not physical then the effect is entirely client side. The rotation experienced by the user '''cannot''' be detected or queried by script.
*If the object is physical then the physical representation is updated regularly. The rotation experienced by the user '''can''' be detected or queried by script.
===Link Sets===
*If the script is attached to the root prim, the entire object rotates around the [[Viewer coordinate frames#Region|region]] '''axis'''
**If the object is attached then it rotates around the attachment '''axis'''
*If the script is attached to a child prim, the prim rotates around the [[Viewer coordinate frames#Local|local]] '''axis'''
**A Child prim can rotate around its own '''axis''' while the entire object rotates around another '''axis'''.
|caveats=*If the object is not physical then the rotation is only a client side effect and it will collide as non-moving geometry.
|constants
|helpers
|also_functions
|also_tests
|also_events
|also_articles
|also_tests={{LSL DefineRow||[[llTargetOmega test]]|}}
|notes=* Use [[llVecNorm]] on '''axis''' so that '''spinrate''' actually represents the rate of rotation.
* Set the gain to zero to disable and remove the rotation behavior, eg llTargetOmega(ZERO_VECTOR, 0, 0);
** A spinrate of 0 with a nonzero gain causes the object to try to stop all spin, rather than simply clearing a previous llTargetOmega() call.
|cat1=Physics
|cat2=Effects
|cat3=Rotation
|cat4=Prim
}}

LlGetRot

2008-11-29T02:19:26Z

Ralph Doctorow: Linked to Prim

{{LSL_Function
|func=llGetRot
|sort=GetRot
|func_id=62|func_sleep=0.0|func_energy=10.0
|func_desc
|func_footnote
|return_type=rotation
|return_text=that is the prim's rotation relative to the [[Viewer coordinate frames#Region|region]] plane.
|constants
|spec
|caveats
|examples=
<lsl> //-- rotates an object to face the nearest cardinal direction (N,E,S,W)
//-- assumes build is aligned to root object facing

default{
state_entry()
{
llSay( 0, "Rotate me in edit, then touch to make me face the nearest compass point" );
}

touch_start( integer vIntTouches )
{
//-- convert our rotation to x/y/z radians
vector vRadBase = llRot2Euler( llGetRot() );
//-- round the z-axis to the nearest 90deg (PI_BY_TWO = 90deg in radians)
llSetRot( llEuler2Rot( <0.0, 0.0, llRound( vRadBase.z / PI_BY_TWO ) * PI_BY_TWO > ) );
}
}</lsl>
|helpers
|also_header
|also_functions=
{{LSL DefineRow||[[llGetLocalRot]]|}}
{{LSL DefineRow||[[llGetRootRotation]]|}}
{{LSL DefineRow||[[llGetPrimitiveParams]]|}}
{{LSL DefineRow||[[llSetRot]]|}}
{{LSL DefineRow||[[llSetLocalRot]]|}}
{{LSL DefineRow||[[llSetPrimitiveParams]]|}}
{{LSL DefineRow||[[llSetLinkPrimitiveParams]]|}}
|also_tests
|also_events
|also_articles
|also_footer
|notes=llGetRot in [[Mouselook]] (see [[llForceMouselook]]) for an attachment returns the angle the avatar is looking in.
The tooltip in the in-client editor is incorrect, it will work in scripts in objects that are physical.
|mode
|deprecated
|location
|cat1=Movement
|cat2=Rotation
|cat3=Prim
|cat4
|cat5
|cat6
}}

LlGetRootRotation

2008-11-29T02:15:48Z

Ralph Doctorow: Linked to Prim

{{LSL_Function
|func_id=269|func_sleep=0.0|func_energy=10.0
|func=llGetRootRotation|return_type=rotation
|func_footnote
|func_desc
|return_text=that is the [[Viewer coordinate frames#Region|region]] rotation of the root object of the prim the script is attached to.
|spec
|caveats
|constants
|examples
|helpers
|also_functions=
{{LSL DefineRow||[[llGetLocalRot]]|}}
{{LSL DefineRow||[[llGetRot]]|}}
|also_events
|also_tests
|also_articles
|notes
|permission
|negative_index
|cat1=Movement
|cat2=Rotation
|cat3=Prim
|cat4
}}

LlGetRootPosition

2008-11-29T01:42:33Z

Ralph Doctorow: Linked to Prim

{{LSL_Function
|func_id=268|func_sleep=0.0|func_energy=10.0
|func=llGetRootPosition|return_type=vector
|func_footnote
|func_desc
|return_text=that is the [[Viewer coordinate frames#Region|region]] position of the root object of the object script is attached to
|spec
|caveats
|constants
|examples=
<lsl>
default{
touch_start( integer vIntTouched ){
string vStrMessage = "The prim with this scipt is ";
if (llGetPos() != llGetRootPosition()){
vStrMessage += "NOT ";
}
llSay( PUBLIC_CHANNEL, vStrMessage + "centered on the root prim." );
}
}
</lsl>
|helpers=
<lsl>
//-- there is no llSetLocalPos, this adds the functionality
//-- to match llGetLocalPos() in a child prim
fSetLocalPos( vector vPosOffset ){
llSetPos( llGetRootPosition() + vPosOffset );
}
//-- this will move a root prim by the offset, or set the
//-- position of a child prim relative to the root.
</lsl>
|also_functions=
{{LSL DefineRow||[[llGetLocalPos]]|Gets the child prims position relative to the root}}
{{LSL DefineRow||[[llGetPos]]|Gets the prims global position}}
{{LSL DefineRow||[[llSetPos]]|Sets the prims global position}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Movement
|cat2=Prim
|cat3
|cat4
}}

LlSitTarget

2008-11-29T01:18:53Z

Ralph Doctorow:

{{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
|caveats=*Once a sit target is removed [[llAvatarOnSitTarget]] will only return {{LSL_Constant/NULL_KEY}}.
*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 " ".
*Attachments cannot be sat upon.
*Sit Target sets the position for the Agent Target, Advanced -> Character -> View Agent Target, and has a displacement that will require a bit of examination.
**llSetLinkPrimitiveParams seems to be the easy work-around.
**Animation is 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 can be passed along to [[llSetLinkPrimitiveParams]].
|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>
|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
}}

LlSetClickAction

2008-11-28T22:47:46Z

Ralph Doctorow: Removed inventory as a catagory

{{LSL_Function
|func_id=333|func_sleep=0.0|func_energy=10.0
|func=llSetClickAction
|p1_type=integer|p1_name=action|p1_desc=CLICK_ACTION_* flag
|func_desc=Sets the action performed when a prim is clicked upon.
|func_footnote=When the cursor is hovers over the prim the cursor image changes to reflect the action.
|caveats
|examples
|spec
|constants=<div id="box">
==Constants==
<div style="padding: 0.5em;">
{{{!}} class="sortable" {{Prettytable}}
{{!}}- {{Hl2}}
! {{!}} Flag
! title="Value" {{!}}
! class="unsortable" {{!}} Description
! class="unsortable" {{!}} Cursor
{{!}}-
{{!}}{{LSL Const|CLICK_ACTION_NONE|integer|0|c=Performs the default action: when the prim is touched, touch events are triggered}}
{{!}}{{#var:value}}
{{!}}{{#var:comment}}
{{!}}
{{!}}-
{{!}}{{LSL Const|CLICK_ACTION_TOUCH|integer|0|c=When the prim is touched, touch events are triggered}}
{{!}}{{#var:value}}
{{!}}{{#var:comment}}
{{!}}
{{!}}-
{{!}}{{LSL Const|CLICK_ACTION_SIT|integer|1|c=When the prim is touched, the avatar sits upon it}}
{{!}}{{#var:value}}
{{!}}{{#var:comment}}
{{!}}[[Image:Toolsit.png‎]]
{{!}}-
{{!}}{{LSL Const|CLICK_ACTION_BUY|integer|2|c=When the prim is touched, the buy dialog is opened}}
{{!}}{{#var:value}}
{{!}}{{#var:comment}}
{{!}}[[Image:Toolbuy.png]]
{{!}}-
{{!}}{{LSL Const|CLICK_ACTION_PAY|integer|3|c=When the prim is touched, the pay dialog is opened}}
{{!}}{{#var:value}}
{{!}}{{#var:comment}}
{{!}}[[Image:Toolpay.png]]
{{!}}-
{{!}}{{LSL Const|CLICK_ACTION_OPEN|integer|4|c=When the prim is touched, the object inventory dialog is opened}}
{{!}}{{#var:value}}
{{!}}{{#var:comment}}
{{!}}[[Image:Toolopen.png]]
{{!}}-
{{!}}{{LSL Const|CLICK_ACTION_PLAY|integer|5|c=When the prim is touched, html-on-a-prim is enabled?}}
{{!}}{{#var:value}}
{{!}}{{#var:comment}}
{{!}}[[Image:Toolplay.png]]
{{!}}-
{{!}}{{LSL Const|CLICK_ACTION_OPEN_MEDIA|integer|6|c=When the prim is touched, the web media dialog is opened}}
{{!}}{{#var:value}}
{{!}}{{#var:comment}}
{{!}}[[Image:Toolmediaopen.png]]
{{!}}}
</div></div>
|helpers
|also_functions={{LSL DefineRow||[[llPassTouches]]}}
|also_tests
|also_events=
{{LSL DefineRow||[[touch_start]]}}
{{LSL DefineRow||[[touch]]}}
{{LSL DefineRow||[[touch_end]]}}
|also_articles={{LSL DefineRow||{{LSLGC|Detected}}}}
|notes
|history=Introduced in SL 1.19.1(0)
|cat1=Prim
|cat2=Touch
|cat3=Sit
|cat4=Money
|cat5=Media
|cat6=Effects
|cat7=
|cat8
}}

LlRezObject

2008-11-28T22:43:47Z

Ralph Doctorow:

{{LSL_Function/inventory|inventory|uuid=false|type=object}}
{{LSL_Function
|func_id=104|func_sleep=0.1|func_energy=200.0
|func=llRezObject|sort=RezObject
|p1_type=string|p1_name=inventory
|p2_type=vector|p2_name=pos|p2_desc=position (in [[Viewer coordinate frames#Region|region coordinates]])|p2_hover=position (in region coordinates)
|p3_type=vector|p3_name=vel|p3_desc=velocity (max [[llVecMag|magnitude]] is 250)
|p4_type=rotation|p4_name=rot|p4_desc=rotation
|p5_type=integer|p5_name=param|p5_desc=[[on_rez]] event parameter and value returned by [[llGetStartParameter]] in the rezzed object.|p5_hover=on_rez event parameter and value returned by llGetStartParameter in the rezzed object.
|func_footnote=The root of '''inventory''' is not at '''pos''' but the center of '''inventory''' is.<br/>To have the root prim at '''pos''' use [[llRezAtRoot]] instead.
|func_desc=Instantiate '''inventory''' object at '''pos''' with velocity '''vel''' and rotation '''rot''' with start parameter '''param'''
|return_text
|spec
|caveats=
*In addition to the normal function delay, there is an additional delay based on the mass and velocity of the object rezzed.
**<code>rez_delay = mass * llVecMag(velocity) / 10;</code> [http://forums.secondlife.com/showthread.php?t=82659]
*Silently fails to rez '''inventory''' if '''pos''' is more than 10 meters away from the prim trying to rez '''inventory'''. So if your script is mysteriously failing to rez things, make sure you haven't (say) written "<0,0,1>" for the '''pos''' parameter rather than (say) "llGetPos() + <0,0,1>".
* If the owner of the object does not have copy permission on '''inventory''', the object will no longer be present in inventory after it is rezzed (so another attempt to rez it is likely to fail); if the owner does have copy permission, then a copy is rezzed, and the original '''inventory''' remains in inventory.
*Silently fails if you don't have offline building rights on the land. Which means that you need to either: Own the land yourself. Be in the group that owns it, and the allow group to build parcel flag has to be enabled. Or everyone should be allowed to build. You can also deed the object to the group that owns the land, this will always work.
|constants
|examples=<lsl>default
{
touch_start(integer param)
{
llRezObject("Object", llGetPos() + <0.0,0.0,1.0>, <0.0,0.0,0.0>, <0.0,0.0,0.0,1.0>, 0);
}
}</lsl>
|helpers
|also_functions=
{{LSL DefineRow||[[llRezAtRoot]]|Rezzes the object at the requested position}}
{{LSL DefineRow||[[llGetStartParameter]]|}}
{{LSL DefineRow||[[llGodLikeRezObject]]|}}
|also_tests
|also_events=
{{LSL DefineRow||[[object_rez]]|triggered when this object rezzes an object from inventory}}
|also_articles
|notes
|permission
|inventory
|negative_index
|cat1=Rez
|cat2=Object
|cat3=Inventory
|cat4
}}

LlSetLinkPrimitiveParams

2008-11-28T16:26:28Z

Ralph Doctorow: Can get rot and pos using llGetObjectDetails

{{LSL Function/link|linknumber}}{{LSL Function
|func_id=328|func_sleep=0.2|func_energy=10.0
|func=llSetLinkPrimitiveParams|sort=SetLinkPrimitiveParams
|p1_type=integer|p1_name=linknumber
|p2_type=list|p2_name=rules
|func_desc=Set primitive parameters for '''linknumber''' based on '''rules'''.
|spec
|caveats=*Applying an operation to [[LINK_SET]] is applied first to the root prim, then to each child prim.
*The sim will clamp attributes before storing them.
*The client will clamp attributes before rendering.
*There is currently no corresponding [[llGetLinkPrimitiveParams]] although [[llGetObjectDetails]] can get the position and rotation of a linked prim identified by its key.
**The only way to get many parameters from linked prims is to put a separate script in each child and use [[llMessageLinked|linked messages]].
|constants={{LSL Constants/PrimitiveParams|set|remote=true}}
|examples =
A simple script to light up a prim in a [[linkset]] when touched, and unlight the others using llSetLinkPrimitiveParams, when script is installed in the root prim of the linkset.
<lsl>
default
{
touch_start(integer total_number)
{
// Turn off all prims
llSetLinkPrimitiveParams(LINK_SET,[PRIM_FULLBRIGHT,ALL_SIDES,FALSE]);
// Turn on the one that was touched
llSetLinkPrimitiveParams(llDetectedLinkNumber(0),[PRIM_FULLBRIGHT,ALL_SIDES,TRUE]);
}
}
</lsl>
|helpers
|also_functions=
{{LSL DefineRow||[[llSetPrimitiveParams]]|Set many primitive parameters}}
{{LSL DefineRow||[[llGetPrimitiveParams]]|Get many primitive parameters}}
{{LSL DefineRow||[[llSetLinkAlpha]]|}}
{{LSL DefineRow||[[llSetLinkColor]]|}}
{{LSL DefineRow||[[llSetLinkTexture]]|}}
|also_tests
|also_events
|also_articles
|notes=
Note that avatars sitting on the object can be moved with this function as well. See [[llSitTarget#Useful_Snippets]] for an example of this.

The Mis-feature of using this function to move avatars 54 meters is now officialy supported according to Andrew Linden (see jira Link http://jira.secondlife.com/browse/SVC-3408?focusedCommentId=88574#action_88574 )

The below example moves avatar to x,y,z without moving the prim they are sitting on. If x,y,z is more than 54 meters away the function will silently fail. Remember x,y,z is in object ralative coordinates just like any other linked prim in a set.

Agents are always the last prim in the set, so using llGetNumberOfPrims() for a single agent sitting on a vehicle is usefull.

Example Code : llSetLinkPrimitiveParams(llGetNumberOfPrims(), [PRIM_POSITION, <x,y,z>]);

Darling Brody (27/11/2008)

|cat1=Prim
|cat2=Movement
|cat3=Status
|cat4=Texture
|cat5=Object
|cat6=Teleport
|cat7=Link/Set
|cat8
}}

LlGetObjectDetails

2008-11-28T16:17:07Z

Ralph Doctorow: Linked to Link functions

{{LSL_Function/limits}}{{LSL_Function/object|id|prim or avatar|sim=*}}
{{LSL_Function
|func_id=332|func_sleep=0.0|func_energy=10.0
|func=llGetObjectDetails
|p1_type=key|p1_name=id
|p2_type=list|p2_name=params|p2_desc=OBJECT_* flags
|return_type=list|return_text=of the details specified in '''params''' for the object with key '''id'''.
|func_footnote={{LSL Const|OBJECT_UNKNOWN_DETAIL|integer|-1|c=}} is returned when passed an invalid integer parameter.
|caveats=
*Items in '''params''' that are not integers are silently ignored, {{LSL Const|OBJECT_UNKNOWN_DETAIL|integer|-1|c=}} is not returned.
*If an object represented by '''id''' is not in the sim an empty list is returned.
*An empty list is also returned if the key given was an item in inventory (object or agent).
*If '''id''' represents an agent, this function will continue to return information for approximately 45 seconds after they have left the sim (but the information is not updated).
*[[llTargetOmega]] will only effect the return of [[OBJECT_ROT]] if the object is [[STATUS_PHYSICS|physical]]. If the object is not physical then the original start rotation is returned, [[llTargetOmega]] is a {{LSLGC|Effects|client side effect}}.
|examples=
<lsl>default
{
collision_start(integer i)
{
list a = llGetObjectDetails(llDetectedKey(0), ([OBJECT_NAME,
OBJECT_DESC, OBJECT_POS, OBJECT_ROT, OBJECT_VELOCITY,
OBJECT_OWNER, OBJECT_GROUP, OBJECT_CREATOR]));
llWhisper(0,"UUID: " + (string)llDetectedKey(0) +
"\nName: \"" + llList2String(a,0) + "\"" +
"\nDecription: \"" + llList2String(a,1) + "\"" +
"\nPosition: " + llList2String(a,2) +
"\nRotation: " + llList2String(a,3) +
"\nVelocity: " + llList2String(a,4) +
"\nOwner: " + llList2String(a,5) +
"\nGroup: " + llList2String(a,6) +
"\nCreator: " + llList2String(a,7));
}
}</lsl>
|spec
|constants={{LSL Constants/Object Details}}
|helpers=See {{LSLGC|Link/Get}} for some {{LSLGC|Link|link}} related helper functions. Since there is no function to get linked prim parameters, this can be useful if you need to get the position and rotation of a linked prim.
|also_functions={{LSL DefineRow||[[llKey2Name]]}}
{{LSL DefineRow||[[llGetPrimitiveParams]]}}
{{LSL DefineRow||[[llSetLinkPrimitiveParams]]}}
{{LSL DefineRow||[[llSetPrimitiveParams]]}}
{{LSL DefineRow||[[llGetParcelDetails]]}}
|also_tests
|also_events
|also_articles={{LSL DefineRow||{{LSLGC|Detected}}}}
{{LSL DefineRow||[[Prim Attribute Overloading]]}}
|notes
|history=Introduced in SL 1.18.3(2)
|cat1=Object
|cat2=Prim
|cat3=Avatar
|cat4=Owner
|cat5=Creator
|cat6=Group
|cat7=Link
|cat8
}}

LlGetStatus

2008-09-28T22:39:29Z

Ralph Doctorow:

{{LSL_Function
|func_id=46|func_sleep=0.0|func_energy=10.0
|func=llGetStatus
|return_type=integer|p1_type=integer|p1_name=status|p1_desc=STATUS_* flag
|func_footnote
|func_desc
|return_text=boolean equal to the '''status''' of the object.
|spec
|caveats=Status is an object attribute; all prims in an object share the same status.
|constants={{LSL Constants/Status}}
|examples=<lsl>default
{
touch_start(integer total_number)
{
if (llGetStatus(STATUS_PHYSICS))
{
llSay(0, "This object is physical");
}
else
{
llSay(0, "This object is not physical");
}
}
}</lsl>
|helpers
|also_functions=
{{LSL DefineRow||{{LSLG|llSetStatus}}|Sets the object status.}}
|also_tests
|also_events
|also_articles
|notes
|cat1
|cat2=Status
|cat3=Physics
|cat4
}}

LlSetStatus

2008-09-28T22:38:11Z

Ralph Doctorow:

{{LSL_Function
|func_id=45|func_sleep=0.0|func_energy=10.0
|func=llSetStatus
|p1_type=integer|p1_name=status|p1_desc=bit mask, STATUS_* flags
|p2_type=integer|p2_name=value|p2_desc=boolean
|func_footnote
|func_desc=Sets the object status attributes indicated in the '''status''' mask to '''value'''
|return_text
|spec
|caveats=*Status is an object attribute; all prims in an object share the same status.
** Except for STATUS_BLOCK_GRAB, this only affects the prim the script is in, child prims in linked objects will not be affected.
|constants={{LSL Constants/Status}}
|examples=<lsl>default
{
state_entry()
{
llSetStatus( STATUS_DIE_AT_EDGE | STATUS_PHYSICS, TRUE);
llSetStatus( STATUS_ROTATE_X | STATUS_ROTATE_Y, FALSE);
}
}</lsl>
|helpers
|also_functions=
{{LSL DefineRow||[[llGetStatus]]|Gets the object status.}}
|also_tests
|also_events
|also_articles
|notes
|cat1
|cat2=Status
|cat3=Physics
|cat4
}}

Talk:LlGetTimeOfDay

2008-09-28T22:12:42Z

Ralph Doctorow: New page: There's been talk about allowing estate managers to change the day/night cycle, but currently it's still 4 hours.

There's been talk about allowing estate managers to change the day/night cycle, but currently it's still 4 hours.

LlGetTimeOfDay

2008-09-28T22:11:05Z

Ralph Doctorow:

{{LSL_Function
|func=llGetTimeOfDay
|func_id=80
|func_sleep=0.0
|func_energy=10.0
|return_type=float
|func_footnote=Second Life days cycles are 4 hours long (3 hours of light, 1 hour of dark). The sunrise and sunset time varies slowly (following the seasons?).
|func_desc
|return_text=that is the time in seconds with subsecond precision since Second Life server midnight (or since server boot; whichever is smaller).
|spec
|caveats
|constants
|examples
|helpers
|also_functions=
{{LSL DefineRow||[[llGetSunDirection]]|}}
|also_events
|also_tests
|also_articles
|notes
|cat1=Time
|cat2=Region
|cat3
|cat4
}}

LlGetTimeOfDay

2008-09-27T23:13:58Z

Ralph Doctorow:

{{LSL_Function
|func=llGetTimeOfDay
|func_id=80
|func_sleep=0.0
|func_energy=10.0
|return_type=float
|func_footnote
|func_desc
|return_text=that is the time in seconds with subsecond precision since Second Life server midnight (or since server up-time; whichever is smaller)
|spec
|caveats
|constants
|examples
|helpers
|also_functions=
{{LSL DefineRow||[[llGetSunDirection]]|}}
|also_events
|also_tests
|also_articles
|notes
|cat1=Time
|cat2=Region
|cat3
|cat4
}}

LlGetTime

2008-09-27T23:12:33Z

Ralph Doctorow:

{{LSL_Function
|func_id=82|func_sleep=0.0|func_energy=10.0
|func=llGetTime|sort=GetTime
|return_type=float
|return_text=that is script time in seconds with subsecond precision since the last sim reset, script reset or call to either [[llResetTime]] or [[llGetAndResetTime]].
|func_footnote
|spec=Script time differs from normal time, it is affected by time dilation. See [[llGetRegionTimeDilation]] for details.
|caveats=
*Script time resets when...
**Script reset (user or [[llResetScript]] or [[llResetOtherScript]])
**Simulator reset (admin or crash)
**Call to either [[llResetTime]] or [[llGetAndResetTime]]
*Script time doesn't measure real world time, it is affected by time dilation.
|examples=<lsl>
default {
state_entry()
{
llResetTime();
}
touch_start(integer num_touch)
{
float time = llGetTime(); //Instead getting, and then resetting the time, we could use llGetAndReset() to accomplish the same thing.
llResetTime();
llSay(0,(string)time + " seconds have elapsed since the last touch." );
}
}
</lsl>
|helpers
|also_functions={{LSL DefineRow||[[llResetTime]]}}
{{LSL DefineRow||[[llGetAndResetTime]]}}
{{LSL DefineRow||[[llGetRegionTimeDilation]]}}
|also
|notes=Script time does not measure time dilation.
To measure elapsed calendar time, call [[llGetTimestamp]] instead, since time dilation and resets often make dilated time intervals differ from calendar time intervals.
|cat1=Time
|cat2=Script
|cat3
|cat4
}}

LlGetWallclock

2008-09-27T23:10:30Z

Ralph Doctorow:

{{LSL_Function
|func_id=81|func_sleep=0.0|func_energy=10.0
|func=llGetWallclock|return_type=float
|func_footnote=For GMT use [[llGetGMTclock]]
|func_desc
|return_text=that is the time in seconds since midnight Pacific time (PST/PDT), truncated to whole seconds.
|spec
|caveats
|constants
|examples=<lsl>// Real World Sun
integer set;

default
{
state_entry()
{
llSetTimerEvent(0.1);
set = -1;
}

timer()
{
float time = llGetWallclock();
if(set == -1)
llSetTimerEvent(60.0);
if(time < 21600)
{
if(set)
{
llSetText("The Sun is coming! :)", <1,1,0>, 1.0);
set = 0;
}
}
else if(time < 64800)
{
if(set != 1)
{
llSetText("Sun has risen. :(", <1,0,0>, 1.0);
set = 1;
}
}
else if(set != 2)
{
llSetText("Goodbye Sun. :(", <1,0,0>, 1.0);
set = 2;
}
}
}</lsl>
|helpers
|also_functions=
{{LSL DefineRow||[[llGetGMTclock]]|Seconds since midnight GMT}}
|also_events
|also_tests
|also_articles
|notes
|permission
|negative_index
|sort=GetWallclock
|cat1=Time
|cat2
|cat3
|cat4
}}

LlGetGMTclock

2008-09-27T23:09:41Z

Ralph Doctorow:

{{LSL_Function
|func_id=282|func_sleep=0.0|func_energy=10.0
|func=llGetGMTclock|return_type=float
|func_footnote=For SL time, which is the same as California time, use [[llGetWallclock]]
|func_desc
|return_text=that is the time in seconds since midnight GMT. Value appears to be truncated to the second.
|spec
|caveats
|constants
|examples=
<lsl>
//--// GMT function with local offsets in 12hr format //--//

integer gIntMinute = 60; //-- 1 minute in seconds
integer gIntHour = 3600; //-- 1 hour in seconds
integer gInt12Hr = 43200; //-- 12hrs in seconds
integer gIntDay = 86400; //-- 1 day in seconds

string fStrGMTwOffset( integer vIntLocalOffset ){
//-- get the correct time in seconds for the given offset
integer vIntBaseTime = ((integer)llGetGMTclock() + gIntDay + vIntLocalOffset * gIntHour) % gIntDay;
string vStrReturn;

//-- store morning or night and reduce to 12hour format if needed
if (vIntBaseTime < gInt12Hr){
vStrReturn = " AM";
}else{
vStrReturn = " PM";
vIntBaseTime = vIntBaseTime % gInt12Hr;
}

//-- get and format minutes
integer vIntMinutes = (vIntBaseTime % gIntHour) / gIntMinute;
vStrReturn = (string)vIntMinutes + vStrReturn;
if (10 > vIntMinutes){
vStrReturn = "0" + vStrReturn;
}

//-- add in the correct hour, force 0 to 12
if (vIntBaseTime < gIntHour){
vStrReturn = "12:" + vStrReturn;
}else{
vStrReturn = (string)(vIntBaseTime / gIntHour) + ":" + vStrReturn;
}
return vStrReturn;
}

default{
touch_start( integer vIntTouched ){
//-- '-8' is california time, no adjustment for DST
llSay( 0, "The time is now " + fStrGMTwOffset( -8 ) );
}
}
</lsl>
<lsl>
// Gets the number of milliseconds since midnight UTC.
integer GetGMTmsclock()
{
string stamp = llGetTimestamp();
return
(integer) llGetSubString(stamp, 11, 12) * 3600000 +
(integer) llGetSubString(stamp, 14, 15) * 60000 +
llRound((float) llGetSubString(stamp, 17, -2) * 1000.0);
}
</lsl>
|helpers
|also_functions=
{{LSL DefineRow||[[llGetWallclock]]|Seconds since midnight PST}}
|also_events
|also_tests
|also_articles
|notes
|permission
|negative_index
|cat1=Time
|cat2
|cat3
|cat4
}}

LlSetScriptState

2008-08-11T00:56:03Z

Ralph Doctorow: Adding other reset conditions not mentioned in the bug report.

{{LSL_Function/inventory|name|uuid=false|type=script}}
{{LSL_Function
|func_id=148|func_sleep=0.0|func_energy=10.0
|func=llSetScriptState
|p1_type=string|p1_name=name
|p2_type=integer|p2_name=run|p2_desc=boolean, if {{LSLG|FALSE}} the script will be disabled.
|func_footnote
|func_desc=Set the running state of the script '''name'''.
|return_text
|spec
|caveats=*Cannot be used to restart a script that has encoutered a {{LSLGC|Error|run-time error}}.
*The script appears to stop when its time slice ends, not sooner. If a script tries to stop itself then some LSL code following the llSetScriptState call may be executed before the script stops.
|constants
|examples=
<lsl>//Stops the Script, at some non-deterministic time later, until invoked with TRUE, in another script
llSetScriptState(llGetScriptName(),FALSE);
// Stall until end of time slice
llSleep(0.1);</lsl>
<lsl>//Starts Another Script
llSetScriptState("somescript",TRUE);</lsl>
|helpers
|also_functions=
{{LSL DefineRow||[[llGetScriptState]]|}}
{{LSL DefineRow||[[llResetOtherScript]]|}}
|also_events
|also_tests
|also_articles
|notes
|issues=
{{Bug|SVC-1853|Scripts deactivated by [[llSetScriptState]] are reset when the region is reset, when they are taken into inventory and re-rezzed and when crossing sim boundaries.}}
|cat1=Script
|cat2
|cat3
|cat4
}}

Talk:LlSetScriptState

2008-08-11T00:55:07Z

Ralph Doctorow: New page: Please do not remove content when making edits. The important point with llSetScriptState is that relying on an inactive script to keep its state is unwise. It can loose it in many ways o...

Please do not remove content when making edits. The important point with llSetScriptState is that relying on an inactive script to keep its state is unwise. It can loose it in many ways of which resetting the sim in only one. This is a trap for programmers attempting to use it and I fail to see how minimizing that helps users of the Wiki.

LlSetScriptState

2008-07-28T01:06:58Z

Ralph Doctorow:

{{LSL_Function/inventory|name|uuid=false|type=script}}
{{LSL_Function
|func_id=148|func_sleep=0.0|func_energy=10.0
|func=llSetScriptState
|p1_type=string|p1_name=name
|p2_type=integer|p2_name=run|p2_desc=boolean, if {{LSLG|FALSE}} the script will be disabled.
|func_footnote
|func_desc=Set the running state of the script '''name'''.
|return_text
|spec
|caveats=*Cannot be used to restart a script that has encoutered a {{LSLGC|Error|run-time error}}.
*The script appears to stop when its time slice ends, not sooner. If a script tries to stop itself then some LSL code following the llSetScriptState call may be executed before the script stops.
*This function has a major problem if a script needs to keep any state information. If the server is reset, or the object taken into inventory and re-rezzed and possibly when crossing a sim boundary, all state information for all inactive scripts is lost. As of 25/07/2008 according to Scouse Linden the server reset bug will not be fixed.
|constants
|examples=
<lsl>
//Stops the Script, at some non-deterministic time later, until invoked with TRUE, in another script
llSetScriptState(llGetScriptName(),FALSE);
// Stall until end of time slice
llSleep(0.1);
</lsl>
<lsl>
//Starts Another Script
llSetScriptState("somescript",TRUE);
</lsl>
|helpers
|also_functions=
{{LSL DefineRow||[[llGetScriptState]]|}}
{{LSL DefineRow||[[llResetOtherScript]]|}}
|also_events
|also_tests
|also_articles
|notes
|sort=SetScriptState
|cat1=Script
|cat2
|cat3
|cat4
}}

LlSetPrimitiveParams

2008-06-15T20:58:36Z

Ralph Doctorow:

{{LSL Function
|func_id=259|func_sleep=0.2|func_energy=10.0|func=llSetPrimitiveParams|sort=SetPrimitiveParams
|p1_type=list|p1_name=rules
|func_desc=Sets the prims parameters according to '''rules'''.
|spec
|caveats=
*The sim will clamp attributes before storing them.
*The client will clamp attributes before rendering.
*Scripts written before September 2004 that use [[PRIM_TYPE]] depend on PRIM_TYPE to have the value 1; if these scripts are recompiled, the new value of {{HoverText|PRIM_TYPE|Value: 9}} will be used causing errors at runtime.
**To fix this replace the PRIM_TYPE flag with the value 1 or updated to the newer PRIM_TYPE syntax.
|constants={{LSL Constants/PrimitiveParams|set}}
|examples=<lsl>
// To color all sides of a prim black, except side 3 white
llSetPrimitiveParams([PRIM_COLOR, ALL_SIDES, <0.0,0.0,0.0>, 1.0]);
llSetPrimitiveParams([PRIM_COLOR, 3, <1.0,1.0,1.0>, 1.0]);

// To render on side 3
// the picture with the UUID...
// and the repeats per face as vector,
// the texture offset as second vector,
// and the texture rotation as float
llSetPrimitiveParams([PRIM_TEXTURE, 3, "4d304955-2b01-c6c6-f545-c1ae1e618288", <1.0,1.0,0.0>, <0.0,0.0,0.0>, 0.0]);

// To set the prim "Full Bright" on sides 3
llSetPrimitiveParams([PRIM_FULLBRIGHT,3,TRUE]);

// And to make it all in one breath,
llSetPrimitiveParams([PRIM_COLOR, ALL_SIDES, <0.0,0.0,0.0>, 1.0,
PRIM_COLOR, 3, <1.0,1.0,1.0>, 1.0,
PRIM_TEXTURE, 3, "4d304955-2b01-c6c6-f545-c1ae1e618288", <1.0,1.0,0.0>, <0.0,0.0,0.0>, 0.0,
PRIM_FULLBRIGHT, 3, TRUE]);

//And If you want to place it above you bed, to make you sleep well, and the coords of that place are for example <x, y, z>
llSetPrimitiveParams([PRIM_COLOR, ALL_SIDES, <0.0,0.0,0.0>, 1.0,
PRIM_COLOR, 3, <1.0,1.0,1.0>, 1.0,
PRIM_TEXTURE, 3, "4d304955-2b01-c6c6-f545-c1ae1e618288", <1.0,1.0,0.0>, <0.0,0.0,0.0>,0.0,
PRIM_FULLBRIGHT, 3, TRUE,
PRIM_POSITION, <x, y, z>]);</lsl>

[[User:Anylyn Hax|Anylyn Hax]] 04:38, 10 July 2007 (PDT)
|helpers
|also_functions={{LSL DefineRow||[[llGetPrimitiveParams]]|Get many primitive parameters}}
{{LSL DefineRow||[[llSetLinkPrimitiveParams]]|Set parameters on other prims in linkset}}
{{LSL DefineRow||[[llSetAlpha]]|Simpler way to set alpha (transparency)}}
{{LSL DefineRow||[[llSetTexture]]|Simpler way to set texture}}
{{LSL DefineRow||[[llSetColor]]|Simpler way to set color}}
|also_tests
|also_events
|also_articles
|notes=The old PRIM_TYPE interface (labeled PRIM_TYPE_LEGACY) while technical retired can still be used.
|cat1=Prim
|cat2=Movement
|cat3=Status
|cat4=Texture
|cat5=Object
|cat6=
}}

LlSetPrimitiveParams

2008-06-15T20:56:46Z

Ralph Doctorow: Getting this into catagory list

{{LSL Function
|func_id=259|func_sleep=0.2|func_energy=10.0|func=llSetPrimitiveParams|sort=llSetPrimitiveParams
|p1_type=list|p1_name=rules
|func_desc=Sets the prims parameters according to '''rules'''.
|spec
|caveats=
*The sim will clamp attributes before storing them.
*The client will clamp attributes before rendering.
*Scripts written before September 2004 that use [[PRIM_TYPE]] depend on PRIM_TYPE to have the value 1; if these scripts are recompiled, the new value of {{HoverText|PRIM_TYPE|Value: 9}} will be used causing errors at runtime.
**To fix this replace the PRIM_TYPE flag with the value 1 or updated to the newer PRIM_TYPE syntax.
|constants={{LSL Constants/PrimitiveParams|set}}
|examples=<lsl>
// To color all sides of a prim black, except side 3 white
llSetPrimitiveParams([PRIM_COLOR, ALL_SIDES, <0.0,0.0,0.0>, 1.0]);
llSetPrimitiveParams([PRIM_COLOR, 3, <1.0,1.0,1.0>, 1.0]);

// To render on side 3
// the picture with the UUID...
// and the repeats per face as vector,
// the texture offset as second vector,
// and the texture rotation as float
llSetPrimitiveParams([PRIM_TEXTURE, 3, "4d304955-2b01-c6c6-f545-c1ae1e618288", <1.0,1.0,0.0>, <0.0,0.0,0.0>, 0.0]);

// To set the prim "Full Bright" on sides 3
llSetPrimitiveParams([PRIM_FULLBRIGHT,3,TRUE]);

// And to make it all in one breath,
llSetPrimitiveParams([PRIM_COLOR, ALL_SIDES, <0.0,0.0,0.0>, 1.0,
PRIM_COLOR, 3, <1.0,1.0,1.0>, 1.0,
PRIM_TEXTURE, 3, "4d304955-2b01-c6c6-f545-c1ae1e618288", <1.0,1.0,0.0>, <0.0,0.0,0.0>, 0.0,
PRIM_FULLBRIGHT, 3, TRUE]);

//And If you want to place it above you bed, to make you sleep well, and the coords of that place are for example <x, y, z>
llSetPrimitiveParams([PRIM_COLOR, ALL_SIDES, <0.0,0.0,0.0>, 1.0,
PRIM_COLOR, 3, <1.0,1.0,1.0>, 1.0,
PRIM_TEXTURE, 3, "4d304955-2b01-c6c6-f545-c1ae1e618288", <1.0,1.0,0.0>, <0.0,0.0,0.0>,0.0,
PRIM_FULLBRIGHT, 3, TRUE,
PRIM_POSITION, <x, y, z>]);</lsl>

[[User:Anylyn Hax|Anylyn Hax]] 04:38, 10 July 2007 (PDT)
|helpers
|also_functions={{LSL DefineRow||[[llGetPrimitiveParams]]|Get many primitive parameters}}
{{LSL DefineRow||[[llSetLinkPrimitiveParams]]|Set parameters on other prims in linkset}}
{{LSL DefineRow||[[llSetAlpha]]|Simpler way to set alpha (transparency)}}
{{LSL DefineRow||[[llSetTexture]]|Simpler way to set texture}}
{{LSL DefineRow||[[llSetColor]]|Simpler way to set color}}
|also_tests
|also_events
|also_articles
|notes=The old PRIM_TYPE interface (labeled PRIM_TYPE_LEGACY) while technical retired can still be used.
|cat1=Prim
|cat2=Movement
|cat3=Status
|cat4=Texture
|cat5=Object
|cat6=
}}

LlCreateLink

2008-02-21T19:30:01Z

Ralph Doctorow: Added external link to Andrew Linden's post on max link distances

{{LSL_Function/permission|PERMISSION_CHANGE_LINKS|grant=the owner}}{{LSL_Function
|func_id=141|func_sleep=1.0|func_energy=10.0
|func=llCreateLink|sort=CreateLink
|p1_type=key|p1_name=target|p1_desc=A prim in the same region.
|p2_type=integer|p2_name=parent|p2_desc=If [[FALSE]], then '''target''' becomes the root.
|func_footnote='''target''' must be modifiable and have the same owner.<br/>
This object must also be modifiable.
|func_desc=Attempt to link the script's object with '''target'''.
|spec
|caveats=*Shouts an error on [[DEBUG_CHANNEL]] if '''target''' isn't in the region or an object.
*If either the object or the '''target''' are not modifiable or of different owners, then an error is shouted on [[DEBUG_CHANNEL]].
*The maximum distance between linkable objects depends on the size of the objects as explained by Andrew Linden in this [http://forums.secondlife.com/showthread.php?t=11883 post].
|constants
|examples
|helpers
|also_functions={{LSL DefineRow||[[llBreakLink]]|Break a link}}
{{LSL DefineRow||[[llBreakAllLinks]]|Break all links}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Link
|cat2
|cat3
|cat4
}}

Template:LSL Function/link

2008-02-18T17:06:46Z

Ralph Doctorow:

{{#vardefine:constants_nb|{{LSL_Constants/Link}}
{{#var:constants_nb}}}} <includeonly>[[Category:LSL Link]]</includeonly>{{#vardefine:p_{{{1|}}}_desc|link number (0: unlinked, 1: root prim, >1: other prims) or a LINK_* flag }}{{#vardefine:also_functions|{{#var:also_functions}}
{{LSL DefineRow||[[llGetLinkNumber]]|Returns the link number of the prim the script is in.}}
}}

Template:LSL Function/link

2008-02-18T17:03:34Z

Ralph Doctorow: Added link number values

{{#vardefine:constants_nb|{{LSL_Constants/Link}}
{{#var:constants_nb}}}} <includeonly>[[Category:LSL Link]]</includeonly>{{#vardefine:p_{{{1|}}}_desc|link number (0: unlinked, 1 root prim, >1 other prims) or a LINK_* flag }}{{#vardefine:also_functions|{{#var:also_functions}}
{{LSL DefineRow||[[llGetLinkNumber]]|Returns the link number of the prim the script is in.}}
}}

Template:LSL Constants/Link

2008-02-18T16:40:01Z

Ralph Doctorow: Changed "task" to "prim" for consistancy

{{{!}}
{{!}}- valign="top"
{{!}}
{{{!}} {{Prettytable}}
{{!}}-{{Hl2}}
! colspan="2" {{!}}Flag
!Description
{{!}}-
{{!}} {{LSL Const|LINK_ROOT|integer|1|c=sends to root prim in a linked set}}
{{!}} {{#var:value}}
{{!}} {{#var:comment}}
{{!}}-
{{!}} {{LSL Const|LINK_SET|integer|-1|c=sends to all prims}}
{{!}} {{#var:value}}
{{!}} {{#var:comment}}
{{!}}-
{{!}} {{LSL Const|LINK_ALL_OTHERS|integer|-2|c=sends to all other prims}}
{{!}} {{#var:value}}
{{!}} {{#var:comment}}
{{!}}}
{{!}}
{{{!}} {{Prettytable}}
{{!}}-{{Hl2}}
! colspan="2" {{!}}Flag
!Description
{{!}}-
{{!}} {{LSL Const|LINK_ALL_CHILDREN|integer|-3|c=sends to all children}}
{{!}} {{#var:value}}
{{!}} {{#var:comment}}
{{!}}-
{{!}} {{LSL Const|LINK_THIS|integer|-4|c=sends to the prim the script is in}}
{{!}} {{#var:value}}
{{!}} {{#var:comment}}
{{!}}}
{{!}}}

Talk:Viewer Visual Update

2008-01-25T15:33:03Z

Ralph Doctorow: Support for multiple monitors

== Thanx for the feedback thus far... ==
Hello and thanks for the comments! I'm involved with this project, codename "Dazzle", insofar as helping the Rx Team get the word out to our community. I haven't read all of these comments in close detail yet, but I appreciate not just the content, but the presentation too.

LordJason Kiesler — thanks for embedding that graphic to communicate what you think of about the button gradients. If anyone else wants to contribute screenshot mockups, please, you're more than welcome. Since this is a ''visual'' update, those type of aids help.

I also had [http://www.flickr.com/photos/torley/1801183618/ some nice comments on my Flickr photostream], and will be encouraging more... and responding in kind. Appreciatively yours! --[[User:Torley Linden|Torley Linden]] 16:28, 1 November 2007 (PDT)

Great, [http://torley.com/introducing-second-lifes-dazzle-user-interface-update even more Dazzle feedback on my personal blog!] --[[User:Torley Linden|Torley Linden]] 08:04, 5 November 2007 (PST)

i love the new version :O is fantastic <br>
the near me bug is fixed exellent <br>
now i'm bugfixing my purple version<br>
really a good job benjamin :D --[[User:Aliceinwire Bleac|Aliceinwire Bleac]] 04:56, 12 November 2007 (PST)

== Feedback and Ideas ==
*As far as I'm concerned, one of the gold standard issues for interface usability in this or any other application is the ability to pull pop up menus off the interface. If one can't do that, it doesn't matter how pretty they look; they block content and make working in the interface overly difficult. Gotta be able to pull stuff off the interface or it's more of the same with new candy colors. [Professor Beliveau/5:18SL 10/30/07]
* In the Mac instructions, if you start with 'Make a copy of the Second Life application with "Duplicate" and rename it "Second Life Visual Update"...' and move on from there then the "uninstall" step won't be needed, and people can more easily compare the two. -- [[User:Argent Stonecutter|Argent Stonecutter]] 06:14, 22 October 2007 (PDT)

* Great work on the graphics! Definitely shows off the potential for what can be done.

Well how novel: ripping off the Mac OS X metallic buttons and giving them an Aqua feel... Well, don't stop there. Read Apple's Human Interface Guidelines and implement them. Then we'll not only have the feel too, but then the whole thing may work as standard instead of being buggy, bloated, roll your own code. We would have international settings and keyboards that worked, standard window behaviour, one menu bar not two, and text editing handling that worked properly, and properly transposed keyboard shorcuts. Get that stuff sorted first then you can think of moving on to skinning.
: I would like to point out, that SecondLife client is Cross-Platform. If they stuck to the Mac guidelines, then it wouldn't fit windows or linux. To be honest, as SecondLife is effectively a game, the interface has to be a roll your own (Read Apples guidelines, it actually says that somewhere) --[[User:Nik Woodget|Nik Woodget]] 02:37, 22 October 2007 (PDT)

* Just to introduce the conservative voice *8) while I greatly appreciate thought going into the viewer and all, I wouldn't say that making the colors prettier and the buttons and icons slicker-looking would be where I'd focus efforts if it was me. Give me back a tearoffable friends list, let me tear off and move around llDialog() / GroupNotice style dropdowns, make the viewer notice and tell me something useful when packets-in-per-second drops to zero, and other actual functional enhancements would do me a world more good than shinier-looking buttons... [[User:Dale Innis|Dale Innis]] 11:06, 13 November 2007 (PST)

* Great look, how ever the big problems in the gui layout are net even addressed in this preview. Friends and group was so much more easier to use before the voice release. I really like to get that in the 18.4 viewer nice Linux bug fixes but no working friends list yet in that version. Voice i guess that will come some ware around 2010 at best. I'm not asking for much just two patches from nicholaz. (and probably a hard admittance from someone onside Linden that new look with friends inside the IM window was a bad idea.) --[[User:Balp Allen|Balp Allen]] 00:36, 14 November 2007 (PST)

== Feedback on the style itself ==

*The problem I'm having is with the fact that most of the text in search results is white on a bright blue/gray background, which makes it hard to read. Also, text in profiles and (non-editable) group descriptions is difficult to read for the same reason. I think that adding more contrast would definitely improve the usability (not to mention the accessibility) of this skin. -- ????

The theme seems to be mostly based on one of a variety of "glossy" 3d themes that have become popular in UNIX/X11 environments. I would much rather see the glossiness eliminated and something less overpowering being used as inspiration.

Specific points:
:* With a light background ALL the text needs to be dark.
:* The window close and minimize buttons look smaller in this style, even if they aren't, and I keep slowing down to hit them more precisely.
:* The translucent menu bar is an improvement. It needs to extend under the menus themselves, of course. The backdrop for the button bars on the bottom should be translucent as well, for symmetry... and with the new style I don't think the little "loops" over the buttons above the chat bar are really useful.
:* The glossiness of the buttons is a problem, and they also look more like tabs than buttons. A flatter more "matte" style would work better.
:* The slight border around the chat and nametags is VERY nice.
:* The 3d look of hover text is not so good, I think because it's light. The light colored pie menu is ''really'' a problem.
:* The inventory and appearance editor seem significantly less professional.
:At the moment I think the original style is preferrable. I would say that the dark color scheme works better, particularly for translucent windows... if the ghosted windows could turn dark (but with light text) that would work, but that's probably more than XUI can handle. -- [[User:Argent Stonecutter|Argent Stonecutter]] 06:25, 22 October 2007 (PDT)

*I'm not a fan of square buttons.
*Like Argent I struggle with some of the light backgrounds
*Would it be possible to have an instruction page? This file does... for all the images. I know its possible to open them all, and I will, but pointers for how to tweak what be nice. I'm going to try a nicer (for my eyes) skin with greens, similar to the theme I've got on my mac menus, and hack some buttons, but it will take a while to get right because I'm flying blind (particularly for .j2c's that don't automatically preview for me). --[[User:Eloise Pasteur|Eloise Pasteur]] 06:53, 22 October 2007 (PDT)
:* Good print, J2Cs aren't well supported in bitmap editors yet. -- [[User:Argent Stonecutter|Argent Stonecutter]] 09:14, 22 October 2007 (PDT)
:* In the textures folder is a textures.xml file. This is the mapping {purpose}.tga -> UUID.{any extension} --[[User:Thraxis Epsilon|Thraxis Epsilon]] 11:51, 22 October 2007 (PDT)

I too struggle with the chat history and permission/worn status in inventory, as it's light text on a light background, but I hope you'll correct this by darkening the text. I like dark text on a light background very much... but OTOH I can understand how in a dark environment, you might want the opposite, sort of like the dashboard on your car... can it be made skinnable, so people can have what they prefer? (Changing with time of day or ambient lighting is probably a bit much to ask for, but would be very cool.) --[[User:Melissa Yeuxdoux|Melissa Yeuxdoux]] 16:23, 2 November 2007 (PDT)

=== Similarity to Mac/Aqua ===
Well how novel: ripping off the Mac OS X metallic buttons and giving them an Aqua feel... Well, don't stop there. Read Apple's Human Interface Guidelines and implement them. Then we'll not only have the feel too, but then the whole thing may work as standard instead of being buggy, bloated, roll your own code. We would have international settings and keyboards that worked, standard window behaviour, one menu bar not two, and text editing handling that worked properly, and properly transposed keyboard shorcuts. Get that stuff sorted first then you can think of moving on to skinning.
: I would like to point out, that SecondLife client is Cross-Platform. If they stuck to the Mac guidelines, then it wouldn't fit windows or linux. To be honest, as SecondLife is effectively a game, the interface has to be a roll your own (Read Apples guidelines, it actually says that somewhere) --[[User:Nik Woodget|Nik Woodget]] 02:37, 22 October 2007 (PDT)
:: I don't think it looks Mac-like at all. In fact while Apple popularized the glossy look the "shiny metallic" look isn't really their schtick, and they have been moving away from the aggressive glossiness of the early OS X versions to a smoother and more professional look in Panther and Tiger. -- [[User:Argent Stonecutter|Argent Stonecutter]] 18:02, 22 October 2007 (PDT)
:::I personally wouldn’t complain if they implemented as much of Apple’s HIG as possible. I wouldn’t expect them to get rid of the in-window menubar, but it would be nice if things like keyboard layouts worked properly. —[[User:Frungi Stastny|Frungi Stastny]] 06:53, 23 October 2007 (PDT)

=== Icons ===

The icons representing prims in the object builder are too small. It is quite difficult to distinguish between similar prims as, for example, the cone and the semicone.--[[User:Eadoin Welles|Eadoin Welles]] 10:22, 22 October 2007 (PDT)

I'm not loving it... Although I do like some of the icons but color wise and color balance theme are killing my eyes. The whole "gloss jem" buttons from Window Vista and OS Mac got really really old so fast. For me, I'd like a dark theme. Something more like this theme. [[http://www.wincustomize.com/zoom.aspx?skinid=4617&libid=1]] --[[User:Vincent Nacon|Vincent Nacon]] 12:32, 22 October 2007 (PDT)

I don't think the icons on the map or in other windows should be changed from the standard client unless absolutely necessary... and again I don't think that encapsulating the icons is really a good idea. -- [[User:Argent Stonecutter|Argent Stonecutter]] 18:06, 22 October 2007 (PDT)

I really like the new icons in the inventory, they look much nicer than the old ones, however, the icons on the map, and the new ones in the title bar are really hard to read. Even from 5 inches away I still can't tell what that thing in the classifieds icon is supposed to be. It looks like two bars and a clock or a lip. The title bar land for sale icon is also really hard to read since you can't really see the $ unless you get really close to the screen. And I think the telehub icon might have too much detail in it for being so small. When you zoom all the way out on the map and see them all it gets really messy. --[[User:Kevin Susenko|Kevin Susenko]] 08:42, 8 December 2007 (PST)

I have to say I am underwhelmed by the icon set. Have you considered the [http://en.wikipedia.org/wiki/Tango_Desktop_Project Tango Desktop Project]? The Tango Project seeks to create a consistent graphical user interface experience across applications and platforms. IMHO, the quality of their icon sets is very high. Have a look at the icon sets and [http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines style guidelines on their website]. — [[User:Yuu Nakamichi|Yuu Nakamichi]] 15:21, 2 November 2007 (PDT)

== Additional suggestions ==
This section should be kept for suggestions that are really beyond the scope of a theme change.

=== Multiple Monitor Support ===

Would like more than anything to see the UI windows capable of being moved onto a second monitor off the main viewer window. Now that would be very cool and make life a whole lot easier.
:This would also mean making that the second life viewer would have to use system controls. Again its a pain for cross-platform software. Though not impossible. --[[User:Nik Woodget|Nik Woodget]] 02:38, 22 October 2007 (PDT)
::Why would this require using system controls ?
::[[User:SignpostMarv Martin|SignpostMarv Martin]] 06:59, 22 October 2007 (PDT)
:::The UI in Second Life is part of the OpenGL rendering pipeline. In order for the controls to be seperated from the main window they would have to be contained in seperate OS controls. Maybe not system independent controls, perhaps custom controls rendered into borderless windows might work. --[[User:Nik Woodget|Nik Woodget]] 02:08, 28 November 2007 (PST)
:::: Aren't there free open-source cross platform systems already out there to do stuff like that?--[[User:TigroSpottystripes Katsu|TigroSpottystripes Katsu]] 05:32, 13 November 2007 (PST)
::::: Possibly, do you have any you can suggest? --[[User:Nik Woodget|Nik Woodget]] 02:08, 28 November 2007 (PST)
:Let me add my support for multiple monitors with one dedicated to menus and controls to keep the main view screen wide open. This would be huge. [[User:Ralph Doctorow|Ralph Doctorow]] 07:33, 25 January 2008 (PST)

=== Mac Support ===

For the Mac port, at least, the way that command and control are reversed is really hard to deal with. It would be nice if there was an option to reverse the command and control keys ''for XUI only''. -- [[User:Argent Stonecutter|Argent Stonecutter]] 06:07, 22 October 2007 (PDT)

Whilst we're talking about this - can we add a request for a proper implementation of the Mac GUIs, without the irritating internal menus as well please. Swap the menu bar menus the way the GUI guidelines suggest. It's a different code base after all. I may have got used to this structure, but it's one bit of muscle memory I'd be very happy to get rid of! --[[User:Eloise Pasteur|Eloise Pasteur]] 15:56, 22 October 2007 (PDT)

=== Widgets ===

I like the new interface. It is surely better than the black one but, by the way, the real value would be to have a choice of skins which, in my understanding, is the main goal of this test. I think that another improvement might be to have the possibility to add gadgets. For example, I would like to have, close to the PDT time, also the local time, since most of events that I prepare are located in my country, and I prefer to use local time rather than useless PDT time. Rather than adding this feature, which may be of no interest to USA people and surely not at all to California people, you may give us the possibility to create gadgets, like in Google or Vista. So I could develop a small gadget to see time in various timezones, another one that automatically convert Linden dollars to various currencies, and so forth. By facilitating the development of user gadgets, you would dramatically improve the SL interface without having to develop them yourself. IMHO Greetings from Rome, Italy --[[User:Eadoin Welles|Eadoin Welles]] 10:19, 22 October 2007 (PDT)

==== Vector Graphics Widgets ====

Would like to see a flash layer, where flash widgets could communicate to the UI via an API and either replace or partially replace bits and pieces of it. This could be a big market for companies wishing to have customized clients but still take advantage of Linden Labs robust source.
:I would actively NOT want to see a layer that can only be programmed with a closed system like flash. -- [[User:Argent Stonecutter|Argent Stonecutter]] 06:07, 22 October 2007 (PDT)
::SVG + Javascript would work- uBrowser would be the place to start with that.
::[[User:SignpostMarv Martin|SignpostMarv Martin]] 06:59, 22 October 2007 (PDT)
:::That's one approach. Javascript based controls are used in a number of programs: Firefox (XUL), Mac OS (Dashboard), Yahoo Widgets (for that matter Adobe's Actionscript has converged on Javascript). I'm not sure that SVG is the way to go, but that's not an objection... I just don't know wnough about SVG. Another possibility is to use Tk, since that has bindings for several scripting languages already. All this is somewhat out of the scope of a theme change. -- [[User:Argent Stonecutter|Argent Stonecutter]] 08:47, 22 October 2007 (PDT)
::::SVG would provide an "open" system for vector graphics where flash provides a "closed" system.
::::[[User:SignpostMarv Martin|SignpostMarv Martin]] 12:41, 22 October 2007 (PDT)

=== Skin Support ===
I'd like to suggest Hue changer for quick custom theme color for users.... However, for graphic artist like myself, I would like to able customize the skin with ease. Just think more like WinAmp 5. --[[User:Vincent Nacon|Vincent Nacon]] 12:32, 22 October 2007 (PDT)

is also good to make a little program in php for the second life site or a executable for create new skin in more simple way

this is my purple skin :)
[[Image:Dazzle_purple_version.JPG|thumb|300px|Purple Skin]]

--[[User:Aliceinwire Bleac|Aliceinwire Bleac]] 04:56, 7 November 2007 (PST)

* Purple skin made me smile a lot! Thanx for sharing that with Ben and I, Aliceinwire! /me open-secretly hopes for a green-and-pink skin. :D --[[User:Torley Linden|Torley Linden]] 11:26, 7 November 2007 (PST)

===Too Little===
Just looking at the pic...except for the icons, which are probably needed, I'm underwhelmed. It's the same old interface except for being white and shinier (IMO, too shiny), and the consensus among people I know tends torward the opinion that the UI needs to be reinvented, not just polished, and I'd rather see development time being taken on that. Take as an example the work being done by e-Sheep with their new custom client. I'm not saying they've done things that I necescarily want to see but they've got their goals in the right place. I could list a number of UI suggestions and pet peeves but this isn't the place for it...some day I wil actualy get around to putting them on the JIRA. That said, I agree with the people who mentioned skins and even just being able to set UI color preferences from the preferences menu; that by itself would address a lot of issues. [[User:Elle Pollack|Elle Pollack]] 15:00, 22 October 2007 (PDT)

===Enhancement?===
I would love to beable to collect a Landmark while viewing another resident's profile picks. --[[User:Sabina Stenvaag] , 1 nov 2007 (PDT)

== Buttons. ==

The gradient effect on the buttons need to weigh one way or the other. Having the 'line' go right through the text with as much contrast as it has, is distracting, and hard on the eyes.
I would suggest more smoothing to it as well.
Here is a mock up of what I mean. The lower left button is the only one modified.
[[Image:NewViewer_button_mockup.jpg|mock up]]

== what is wrong with light text on dark background? ==

for me, light text on dark background is way more comfortable for my eyes, I find light backgrounds kinda too aggressive :/

why not continue with the dark backgrounds? imitating rl paper on software is kinda lame on my opinion :\ --[[User:TigroSpottystripes Katsu|TigroSpottystripes Katsu]] 01:08, 13 November 2007 (PST)

LlEuler2Rot

2007-12-24T22:11:24Z

Ralph Doctorow: Added order of rotation in Euler vector

{{LSL_Function
|func_id=16|func_sleep=0.0|func_energy=10.0
|func=llEuler2Rot|return_type=rotation|p1_type=vector|p1_name=v
|func_footnote
|func_desc
|return_text=representation of Euler Angles '''v'''.
|spec=The Euler angle vector is converted to a rotation by doing the rotations around the 3 axes in Z, Y, X order. So llRot2Euler(<1.0, 2.0, 3.0> * DEG_TO_RAD) generates a rotation by taking the zero rotation, a vector pointing along the X axis, first rotating it 3 degrees around the global Z axis, then rotating the resulting vector 2 degrees around the global Y axis, and finally rotating that 1 degree around the global X axis.
|caveats
|constants
|examples=<pre>
default
{
state_entry()
{
vector input = <73.0, -63.0, 20.0> * DEG_TO_RAD;//not advised to make your own quaternion
rotation rot = llEuler2Rot(input);
llSay(0,"The Euler2Rot of "+(string)input+" is: "+(string)rot );
}
}
</pre>
|helpers
|also_functions={{LSL DefineRow||[[llRot2Euler]]|}}
|also_events
|also_tests
|also_articles={{LSL DefineRow||{{Wikipedia|Euler_Angles}}|}}
|notes
|permission
|negative_index
|cat1=Math/3D
|cat2=Rotation
|cat3=Euler
|cat4
}}

Rotation

2007-12-24T22:00:11Z

Ralph Doctorow: Attempting to clarify the local and global rotation examples

{{Multi-lang}}
{{LSL Header}}{{RightToc}}
=Rotations=
The LSL '''rotation''' type is used to represent an orientation in 3D. (Note that we try to write the type name in '''bold'''.)
An orientation, or 3D angle, is represented by a mathematical object called a {{LSLG|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|Rotation Synopsis}}.
There is also information about causing textures to rotate in {{LSLG|texture}}s.

==Other representations==
Another way to represent a rotation is using three numbers, <X, Y, Z>, which represent the amount (in [[radians]]) 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. Note that these three numbers are a '''vector''' and not a '''rotation''' type, though it can represent the same information. This is called the ''Euler'' representation of a rotation.

A third way is to use three vectors, showing what the front is pointing at, what the top is pointing at, and what the left side is pointing at. Actually, only two of the three are needed, because any two determines the third.

For good reasons, such as being able to combine rotations, the four number version, the '''rotation''', is better, though 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.

==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 ==

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. 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. To go from a rotation to an Euler angle {{LSLG|vector}} use {{LSLG|llRot2Euler}}.

'''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:

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation rot30X ||= {{LSLG|llEuler2Rot}}(<30, 0,0> * DEG_TO_RAD);||// convert the degrees to radians, then convert that {{LSLG|vector}} into a rotation, rot30x
|-
|{{LSLG|vector}} vec30X ||= {{LSLG|llRot2Euler}}(rot30X );||// convert the rotation back to a {{LSLG|vector}} (the values will be in radians)
|}
</div></div>

== 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.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation localRot = ||rot30X * myRot;||// do a local rotation by multiplying a constant rotation by a world rotation
|}
</div></div>

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.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation globalRot || = myRot * rot30X;||// do a global rotation by multiplying a world rotation by a constant rotation
|}
</div></div>

== 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 {{LSLG|float}} values, each '''rotation''' stores four of them and a {{LSLG|list}} consisting of '''rotation''' is more efficient than a {{LSLG|list}} consisting of {{LSLG|float}}s, but there is overhead in unpacking them.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation rot30X ||= {{LSLG|llEuler2Rot}}(<30, 0,0> * [[#DEG_TO_RAD|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>;||// Make another rotation out of the components
|}
</div></div>

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.
<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation rot330X ||= <-rot30X.x, -rot30X.y, -rot30X.z, rot30X.s>;||// invert a rotation - NOTE the s component isn't negated
|-
|rotation another330X ||= [[#ZERO_ROTATION|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.
|}
</div></div>

==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 {{LSLG|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 {{LSLG|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 {{LSLG|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 {{LSLG|vector}} from the center of the prim.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation rot30X ||= {{LSLG|llEuler2Rot}}(<30, 0,0> * [[#DEG_TO_RAD|DEG_TO_RAD]] );||// create a rotation constant, 30 degrees around the X axis
|-
|vector offset ||= <0, 1, 0>;||// create an offset one meter in the global positive Y direction
|-
|vector rotatedOffset || = offset * rot30X;||// rotate the offset to get the motion caused by the rotations
|-
|vector newPos || = {{LSLG|llGetPos}}() + rotatedOffset;||// move the prim position by the rotated offset amount
|}
</div></div>

'''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.

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

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

=== [[RAD_TO_DEG]] ===
RAD_TO_DEG = 57.29578f;<br/>
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_Constants]]

Rotation

2007-12-24T21:40:09Z

Ralph Doctorow: Added order of rotation in Euler vectors discussion, combined Local vs World rotation paragraph with existing section.

{{Multi-lang}}
{{LSL Header}}{{RightToc}}
=Rotations=
The LSL '''rotation''' type is used to represent an orientation in 3D. (Note that we try to write the type name in '''bold'''.)
An orientation, or 3D angle, is represented by a mathematical object called a {{LSLG|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|Rotation Synopsis}}.
There is also information about causing textures to rotate in {{LSLG|texture}}s.

==Other representations==
Another way to represent a rotation is using three numbers, <X, Y, Z>, which represent the amount (in [[radians]]) 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. Note that these three numbers are a '''vector''' and not a '''rotation''' type, though it can represent the same information. This is called the ''Euler'' representation of a rotation.

A third way is to use three vectors, showing what the front is pointing at, what the top is pointing at, and what the left side is pointing at. Actually, only two of the three are needed, because any two determines the third.

For good reasons, such as being able to combine rotations, the four number version, the '''rotation''', is better, though 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.

==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 ==

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. 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. To go from a rotation to an Euler angle {{LSLG|vector}} use {{LSLG|llRot2Euler}}.

'''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:

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation rot30X ||= {{LSLG|llEuler2Rot}}(<30, 0,0> * DEG_TO_RAD);||// convert the degrees to radians, then convert that {{LSLG|vector}} into a rotation, rot30x
|-
|{{LSLG|vector}} vec30X ||= {{LSLG|llRot2Euler}}(rot30X );||// convert the rotation back to a {{LSLG|vector}} (the values will be in radians)
|}
</div></div>

== 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''' rotation by putting the constant 30 degree '''rotation''' to the left of the object's '''rotation'''. It is like the first operation in the first example above, just twisting the dart around its own long axis.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation localRot = ||rot30X * myRot;||// do a local rotation by multiplying a constant rotation by a world rotation
|}
</div></div>

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.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation globalRot || = myRot * rot30X;||// do a global rotation by multiplying a world rotation by a constant rotation
|}
</div></div>

== 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, a '''local''' rotation.

In the globalRot case, again starting from <0, 0, 0>, first the object is rotated to its original rotation, but the object's axes and the world's axes are no longer aligned! So, now 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 {{LSLG|float}} values, each '''rotation''' stores four of them and a {{LSLG|list}} consisting of '''rotation''' is more efficient than a {{LSLG|list}} consisting of {{LSLG|float}}s, but there is overhead in unpacking them.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation rot30X ||= {{LSLG|llEuler2Rot}}(<30, 0,0> * [[#DEG_TO_RAD|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>;||// Make another rotation out of the components
|}
</div></div>

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.
<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation rot330X ||= <-rot30X.x, -rot30X.y, -rot30X.z, rot30X.s>;||// invert a rotation - NOTE the s component isn't negated
|-
|rotation another330X ||= [[#ZERO_ROTATION|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.
|}
</div></div>

==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 {{LSLG|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 {{LSLG|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 {{LSLG|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 {{LSLG|vector}} from the center of the prim.

<div id="box"><div style="padding: 0.5em">
{| cellpadding=0 cellspacing=0
|-
|rotation rot30X ||= {{LSLG|llEuler2Rot}}(<30, 0,0> * [[#DEG_TO_RAD|DEG_TO_RAD]] );||// create a rotation constant, 30 degrees around the X axis
|-
|vector offset ||= <0, 1, 0>;||// create an offset one meter in the global positive Y direction
|-
|vector rotatedOffset || = offset * rot30X;||// rotate the offset to get the motion caused by the rotations
|-
|vector newPos || = {{LSLG|llGetPos}}() + rotatedOffset;||// move the prim position by the rotated offset amount
|}
</div></div>

'''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.

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

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

=== [[RAD_TO_DEG]] ===
RAD_TO_DEG = 57.29578f;<br/>
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_Constants]]

LlLookAt

2007-10-07T16:21:43Z

Ralph Doctorow:

{{LSL Function/damping|damping}}{{LSL_Function
|func_id=105|func_sleep=0.0|func_energy=10.0
|func=llLookAt|p1_type=vector|p1_name=target|p2_type=float|p2_name=strength|p3_type=float|p3_name=damping
|func_footnote=To stop the object from maintaining the '''target''' positions use {{LSLG|llStopLookAt}}<br/>
To change the position in the same manner use {{LSLG|llMoveToTarget}}.
|func_desc=Cause object name to point its '''up''' axis (positive z) towards '''target'''

If the object isn't physical, the settings don't seem to have any effect except the force must be > 0. For physical objects, the strength seems to be something like viscosity, not the rotating strength, so the weaker it is the faster the rotation happens. The damping value controls how fast the rotation damps out. Low values relative to the strength make it bouncy, often overshooting the target, high values sluggish. The strength and damping values seem to have no relation to the mass of the object.

|return_text
|spec
|caveats=This does not guarantee that physical objects will wind up pointing at the target. Depending on the shape of the object, the strength and the damping, it may well settle out at a different rotation pointing in a different direction if the damping stops the rotation before the final position is reached.

If the object is physical and not symmetrical it may cause a recoil effect where the object winds up drifting away from it's original position as well as making the final rotation it settles on less accurate.
|constants
|examples
|helpers
|also_functions=*{{LSLG|llRotLookAt}}
|also_events
|also_tests
|also_articles
|notes
|permission
|negative_index
|sort=LookAt
|cat1=Physics
|cat2=Target
|cat3
|cat4
}}

LlLookAt

2007-10-07T03:24:26Z

Ralph Doctorow:

{{LSL Function/damping|damping}}{{LSL_Function
|func_id=105|func_sleep=0.0|func_energy=10.0
|func=llLookAt|p1_type=vector|p1_name=target|p2_type=float|p2_name=strength|p3_type=float|p3_name=damping
|func_footnote=To stop the object from maintaining the '''target''' positions use {{LSLG|llStopLookAt}}<br/>
To change the position in the same manner use {{LSLG|llMoveToTarget}}.
|func_desc=Cause object name to point its '''up''' axis (positive z) towards '''target'''

If the object isn't physical, the settings don't seem to have any effect except the force must be > 0. For physical objects, the strength seems to be something like viscosity, not the rotating strength, so the weaker it is the faster the rotation happens. The damping value controls how fast the rotation damps out. Low values relative to the strength make it bouncy, high values more damped. The strength and tau values seem to have no relation to the mass of the object.

|return_text
|spec
|caveats=This does not guarantee that physical objects will wind up pointing at the target. Depending on the shape of the object, the strength and the tau, it may well settle out at a different rotation pointing in a different direction.

If the object is physical and not symmetrical it may cause a recoil effect where the object winds up drifting away from it's original position as well as making the final rotation it settles on less accurate.
|constants
|examples
|helpers
|also_functions=*{{LSLG|llRotLookAt}}
|also_events
|also_tests
|also_articles
|notes
|permission
|negative_index
|sort=LookAt
|cat1=Physics
|cat2=Target
|cat3
|cat4
}}

LlLookAt

2007-10-05T05:44:14Z

Ralph Doctorow:

LlSetText

2007-09-29T16:33:11Z

Ralph Doctorow: Prim catagory

{{LSL_Function
|func_id=152
|func_sleep=0.0
|func_energy=10.0
|func=llSetText
|sort=SetText
|p1_type=string|p1_name=text|p1_desc=text to display between the quotes
|p2_type=vector|p2_name=color
|p3_type=float|p3_name=alpha
|func_desc=Displays '''text''' over a prim with specific '''color''' and transparency (specified with '''alpha''').
|return_text
|spec=
|caveats=*The floating text is a property of the prim and not the script, thus the text will remain if the script is deactivated or removed.
**To remove floating text, one must assign an empty string with llSetText("", <1.0, 1.0, 1.0>, 1.0);
*Vertical whitespace is removed from the end of the text string, so if you want vertical whitespace put any character (like a space) on the last line.
**Bad: llSetText("Monkeys\n\n\n\n\n", <1.0, 1.0, 1.0>, 1.0);
**Good: llSetText("Monkeys\n\n\n\n\n ", <1.0, 1.0, 1.0>, 1.0);
|examples=
Example colors:
<pre>
vector white = <1.0, 1.0, 1.0>;
vector red = <1.0, 0.0, 0.0>;
vector green = <0.0, 1.0, 0.0>;
vector blue = <0.0, 0.0, 1.0>;
vector grey = <0.5, 0.5, 0.5>;
vector black = <0.0, 0.0, 0.0>;
</pre>
<pre>
llSetText("I am on", <1.0, 1.0, 1.0>, 1.0);
</pre>
<1.0, 1.0, 1.0> represents the values for red, green, and blue. <1.0, 1.0, 1.0>, means "white" and <0.0, 0.0, 0.0> means "black".
<pre>
llSetText("I am off", <0.0, 0.0, 0.0>, 1.0);
</pre>
The 1.0 is the alpha setting. 1.0 means fully opaque, and 0.0 would be completely transparent (invisible).

Example of how llSetText could be included in default code:

default
{
state_entry()
{
llSay(0, "Hello, Avatar!");
llSetText("Prize Box", <0.0, 1.0, 0.0>, 1.0);
}

touch_start(integer total_number)
{
llSay(0, "Touched.");
}
}

By default the floating text will appear on a single line. However, the floating text can be spread over multiple lines by using a line break "\n".

<pre>
llSetText("I am \n on two lines!", <0.0, 1.0, 0.0>, 1.0);
</pre>

|helpers
|also_functions
|also

|cat1=Effects
|cat2=Prim
|cat3
|cat4
}}

LlSetText

2007-09-29T16:29:13Z

Ralph Doctorow: Removed extra LSL function calls to try to get it to index correctly

User:Tree Kyomoon/Use Cases

2007-09-28T01:24:57Z

Ralph Doctorow:

==Login-less Viewing of Regions==

I (and I am sure others before me) had proposed a login-less grid viewer for example, where interactive/non interactive 3d models and environments within second life could be viewed from a web browser or hardware device without requiring the presence of an avatar. It is my hope that this kind of extensibility will enable developers in world to utilize the grid as a platform for web content that could be embedded in any webpage like videos on youtube or mini apps on facebook. Based on what I saw it seems that this kind of application could be possible.

==Rich Internet Application Development==

I have also made several proposals that would make the grid more rich internet application development capable, such as support for [[User:Zero_Linden/Office_Hours/Discussion#llHTTPRequest.28.29| cookies in the llHTTPRequest]] or similar LSL function, and an object oriented language supporting actual objects and arrays similar to how they are in flash. I think that this will greatly increase the ability for the massive Flash development community to quickly realize their skills in the 3d world of SL, rather than being stuck with 2d in flash for GUI and content/game dev.

==E-Learning==

E-Learning (Web Based Training or WBT) is usually delivered to large corporations via a Learning Management System that usually serves at least three purposes, one to limit access to a certain group of people, two to distribute content to those people under a particular schedule or course, and three to track the progress and performance of those people (learners). Literally millions of corporate employees worldwide log into some kind of learning management system every day to take what usually amounts to html based "page turner" courses. I believe that there is a huge market potential to utilize existing LMS reporting and back end user / content management tools that already exist and make much of that content available with vast enhancement on the SL Grid, and feel that cookie support for the llHTTPRequest script is very central to that possiblity, as well as the R.I.A. enhancements described above.

=== Comments ===
If it were possible to write arbitrarily complex scripts I'd think there'd be a huge market for 3D training courses to produce much more interesting and richer learning environments, not to mention obvious 3D applications like machinery and plant maintenance. Except for the simplest cases though, this will only work with orders of magnitude more scripting capability - 50 to 1000 times more I'd think. Lowering the SL learning curve, grid reliability and guaranteed responsiveness would be key to this and many other corporate applications too. --[[User:Ralph Doctorow|Ralph Doctorow]] 18:24, 27 September 2007 (PDT)

[[Category:Architecture Working Group]]

Talk:LSL Editing Primer

2007-09-27T15:07:38Z

Ralph Doctorow:

== Code Tag? ==
What's the suggested tag for code examples? I tried <nowiki> <lsl></lsl> but it doesn't seem to work so I've been using <pre></pre></nowiki> but it's not great. --[[User:Ralph Doctorow|Ralph Doctorow]] 20:42, 26 September 2007 (PDT)

Well, <nowiki><pre></pre></nowiki> is the common tag for code. For very short code samples you can use <nowiki><code></code></nowiki>.

What are you missing? Code highlighting? It's not available yet, AFAIK.<br/>
--[[User:Huney Jewell|Huney Jewell]] 03:04, 27 September 2007 (PDT)

With <nowiki><pre></pre></nowiki> the font is too small and you can't put links into the code and it would be nice to have code all tagged the same way so it could be automatically reformatted. <nowiki><code></code></nowiki> doesn't keep line breaks and also has a small point size. --[[User:Ralph Doctorow|Ralph Doctorow]] 08:07, 27 September 2007 (PDT)

Talk:LSL Editing Primer

2007-09-27T15:06:32Z

Ralph Doctorow:

Talk:LSL Editing Primer

2007-09-27T03:42:11Z

Ralph Doctorow: New page: == Code Tag? == What's the suggested tag for code examples? I tried <nowiki> <lsl></lsl> but it doesn't seem to work so I've been using <pre></pre></nowiki> but it's not great. --~~~~

Talk:LSL Portal

2007-09-27T00:28:01Z

Ralph Doctorow:

{{LSL Header}}{{Talk}}
= Please do not copy content from LSLwiki =

From [http://forums.secondlife.com/showpost.php?p=1392697&postcount=44 Rob Linden's post to the forum]:
:Hi folks, sorry for dropping into this conversation late. I haven't read through everything here, but I'd like to present an alternative.

:There have been several requests that Linden Lab take on the hosting of the LSL wiki. There are several problems with us doing this work. The primary problem is the question of ownership of the material. Since, to the best of our knowledge, there was never an explicit, consistent notice of ownership of this material throughout its creation, nor a clear assignment/license associated with contributing more material, it would seem the only safe way to license this content would be to contact every single contributor throughout the life of the wiki and get an explicit license or copyright assignment from them. Note that I said "safe", not "practical".

:We're not in a position to go down that road. However, we do have wiki.secondlife.com, which has had, since day one, a very clear notice about the license under which contributions are made and distributed. We would be very happy to see the community collaborate on newly created content on wiki.secondlife.com. As long as you author the content (not cut and paste from sources you are not the sole author of), we welcome your contribution. -- [[User:Rob Linden|Rob Linden]] 14:30, 24 January 2007 (PST)

----

OK, so let's talk about formatting rules for entries.

(Moved to [[LSL Portal Guidelines]], so that this talk doesn't get too cluttered.) -- [[User:Talarus Luan|Talarus Luan]] 16:32, 24 January 2007 (PST)

[[User:Talarus Luan|Talarus Luan]] 14:28, 24 January 2007 (PST)

----

=Other Discussion=

Should we make this the front page to the LSL reference, or put that one more level down? I kinda lean toward the former. [[User:Gigs Taggart|Gigs Taggart]] 14:09, 24 January 2007 (PST)

----

Yeah i think so... (Unsigned by Dimentox Travanti}
:Remember to sign your post with four tildes. [[User:Gigs Taggart|Gigs Taggart]] 14:26, 24 January 2007 (PST)

I used a modified version of the [http://meta.wikimedia.org/wiki/User:Ajqnic:GeSHiHighlight GeSHiHighlight] plugin for MediaWiki. With an LSL syntax file. The license for the plugin and for [http://qbnz.com/highlighter/ GeSHi] is GPL, it also requires another plugin [http://meta.wikimedia.org/wiki/User:Ajqnic:purgePage purgePage].
--[[User:Thraxis Epsilon|Thraxis Epsilon]] 15:00, 24 January 2007 (PST)

== Regarding copying content from the existing Wiki ==

This isn't clear from Rob's post, but it should be made clear: we CAN copy our OWN content from the existing wiki. IE, I plan to copy/paste my XML-RPC notes from the existing one. Does that present an issue? If so, why?
[[User:Talarus Luan|Talarus Luan]] 16:03, 24 January 2007 (PST)
:If you are the sole author, it wouldn't. Just be careful and check the page history. [[User:Gigs Taggart|Gigs Taggart]] 16:10, 24 January 2007 (PST)

== Syntax Highlighting ==

Updated info on the syntax highlighting is available here [[http://rpgstats.com/wiki/index.php?title=GeSHiHiLight.php GeSHiHiLight]]
--[[User:Thraxis Epsilon|Thraxis Epsilon]] 16:10, 24 January 2007 (PST)

:Lets hope they include it soon ^^ [[User:Strife Onizuka|Strife Onizuka]] 21:21, 24 January 2007 (PST)
:Is there anyone we can ask? [[User:Dimentox Travanti|Dimentox Travanti]] 10:50, 25 January 2007 (PST)
:any news or update on this? [[User:Blueman Steele|Blueman Steele]] 6:12, 10 February 2007 (PST)

::We tried to use start using this on Thursday, but ran into some problems. Thraxis, it'll help if you can contact me privately to discuss some of the issues. -- [[User:Rob Linden|Rob Linden]] 00:37, 11 February 2007 (PST)

:What's the status of syntax highlighting? --[[User:Mokelembembe Mokeev|Mokelembembe Mokeev]] 15:11, 24 April 2007 (PDT)

::No one has made any efforts recently to get the highlighter included in the wiki. If you are going to post highlighted code, it would be good to have it output in such a way that keywords link to their appropriate pages. -- [[User:Strife Onizuka|Strife Onizuka]] 16:53, 24 April 2007 (PDT)

:Talked with Rob Liden - The concern with the script is about security and the possiblity of injecting PHP code into the script hilighting. Since its a possible security issue he would like somebody at Linden to look into and fix it. I'm going to look into the script and tell Rob what I found also. --[[User:Mokelembembe Mokeev|Mokelembembe Mokeev]] 15:29, 4 May 2007 (PDT)

== Let's refer to this simply as the "LSL portal" ==

Since there's already something out there called the "LSLwiki", let's refer to this as the LSL Portal to distinguish it. If there's no objection, I'll move the pages with "LSL Wiki" in the title to some other appropriate name -- [[User:Rob Linden|Rob Linden]] 17:09, 24 January 2007 (PST)
:No objections here. :) I just updated [[LSL Wiki To-do]] with some assignment tables. I went ahead and moved it to [[LSL Portal To-do]] [[User:Talarus Luan|Talarus Luan]] 18:12, 24 January 2007 (PST)
:: Simple, consistent messaging: I've gotten into the habit of using "LSL Portal" regularly myself.
:: --[[User:Torley Linden|Torley Linden]] 10:40, 31 January 2007 (PST)

== A way back... ==

Every page should have a header that goes back to the portal index not the wiki index.
if we could even geta link in the left hand would be great.

[[User:Dimentox Travanti|Dimentox Travanti]] 10:47, 25 January 2007 (PST)

: I second the idea of a link in the main Navigation list. It makes it a lot easier to access the LSL Portal.
: [[User:Cron Stardust|Cron Stardust]] 11:25, 5 March 2007 (PST)

== Transitions ==
Encouraging to see this happening — and to see [http://www.lslwiki.org/ a second mirror] for the [http://www.lslwiki.com LSL wiki] too; hopefully I haven't come too late, because these developments look like they've transpired over the last few days.

Just wanted to let you know I've added a link to our LSL Portal from our blog's Notices; it'll be up for some time. I'm also going to add a simple article to the [http://secondlife.com/knowledgebase/ Knowledge Base] directing to this LSL Portal, since it's important to get more contributors aware, interested, and involved.

I'd like to personally be more active in this wiki... great things are afoot. I've been spread across too many [http://secondlife.com/knowledgebase/article.php?id=357 communication channels] lately, so I've been rotating between focuses (foci?); hopefully next week I'll have more hands-on energy here.

Thanx to each and all of you building up this resource so far!

--[[User:Torley Linden|Torley Linden]] 10:21, 26 January 2007 (PST)

== LSL Header/Footer ==
Below is the header/footer template: <nowiki>{{LSL Header}}</nowiki>
{{LSL Header}}
Also, since <nowiki><lsl></lsl></nowiki> tags don't seem to work yet, I used <nowiki><pre></pre></nowiki>... hope that's alright, I know nothing about wikis except what I've taught myself tonight. --[[User:DoteDote Edison|DoteDote Edison]] 20:45, 27 January 2007 (EST)
:Actually, go ahead and use the <nowiki><lsl></lsl></nowiki> tags. Even though it may look like crap right this minute, as soon as the module is installed, it will instantly be perfect. :) [[User:Talarus Luan|Talarus Luan]] 14:59, 29 January 2007 (PST)

== LSL wiki-namespace ==

All the LSL pages are prefixed with "LSL ", like "LSL Portal", "LSL LLRand", etc. It would seem more justly to use the wiki-namespace "LSL:". Change the names from "LSL LLRand" to "LSL:LLRand". My 2 lindens. [[User:Dzonatas Sol|Dzonatas Sol]] 00:28, 2 February 2007 (PST)
:Just thought about this little more. We could use subpages instead of namespaces, then the talk pages will fully work. "LSL/LLRand" for example [[User:Dzonatas Sol|Dzonatas Sol]] 00:41, 2 February 2007 (PST)
::I'm not going to make a big fuss about it, but I'd prefer if, per the [[Editing Guidelines]], that the page just be called "LLRand". -- [[User:Rob Linden|Rob Linden]] 01:06, 2 February 2007 (PST)

== LSL conformance test ==

Hi folks, we're planning to consolidate a lot of our scattered LSL conformance tests on this wiki. I created two rather crude templates: [[Template:LSL conformance test]] and [[Template:LSL conformance script]], which were created for adding our conformance suite. See [[LSL llGetUnixTime test]] for an example. I'd like to get a sense from people if this is a sensible way to do this. The idea is to get these templates stabilized, and that will provide us a mechanism for those of us at LL to consolidate our tests. Of course, if the community wants to chip in, that's great too...having items in our standard LSL conformance suite makes it less likely that we'll break an LSL feature that's important to you. -- [[User:Rob Linden|Rob Linden]] 22:53, 7 February 2007 (PST)

== LSL Categories List ==
What about a vertical list of categories down the right side of the LSL Portal front page? The right-side list on the original wiki was my primary source of navigation, but maybe I'm odd. I could add it myself, but I'm not sure how to make it automatically update the list as new categories are added. --[[User:DoteDote Edison|DoteDote Edison]] 20:20, 9 February 2007 (EST)
:Oops... right after I posted this, I noticed that it's item #4 on the "To-Do" list. I went ahead and modified the front page to add a cetagories list. If you don't like it, feel free to revert. --[[User:DoteDote Edison|DoteDote Edison]] 20:55, 9 February 2007 (EST)
:The names all start with "LSL" and the names are not optimal for listing... The names could be changed though. I'll dig though the MediaWiki commands later and see if I can find any that would work well in this case. I don't have high hopes in this case. [[User:Strife Onizuka|Strife Onizuka]] 18:59, 9 February 2007 (PST)
Is the 200 articles per category page a mediawiki limit, or can we change it to 400 per page in a configuration somewhere? [[User:DoteDote Edison|DoteDote Edison]] 21:50, 22 February 2007 (EST)

:If there's an issue with seeing all the pages, I can add the alphabetical navigation template later.
:[[User:SignpostMarv Martin|SignpostMarv Martin]] 06:16, 23 February 2007 (PST)

== Internationalizing ==

How do we want to go about internationalizing the LSL wiki. It should probably be tied into the global wiki effort. [[User:Strife Onizuka|Strife Onizuka]] 07:20, 11 February 2007 (PST)

:With modular templates (e.g. the way I do them) vs monolithic templates (e.g. the way you do them), the templates won't need to be changed, only the content going into them. Regarding [[User talk:SignpostMarv Martin/Sandbox/Project:Internationalisation#multi-lingual articles|Project:Internationalisation#multi-lingual articles]], I have some freaky ideas to make maintenance of the LSL-specific multi-lingual articles a little easier to maintain.<br /><br />p.s. I'm not sure whether Internationalisation of the LSL articles should be discussed here or [[User talk:SignpostMarv Martin/Sandbox/Project:Internationalisation#multi-lingual articles|there]].<br />[[User:SignpostMarv Martin|SignpostMarv Martin]] 08:05, 11 February 2007 (PST) [[Talk:LSL_Function_Style|Moved from Talk:LSL_Function_Style]]

::But your idea on templates don't provide structure, it requires the user to provide the structure and if we want to change the layout of the pages we need to go through and change ever single page. I'm pretty sure I can put together template-templates that should make translating the templates easy as setting a few variables. We wouldn't be using the template-template directly for rendering but use [http://meta.wikimedia.org/wiki/Help:Substitution substitution]. Changing a dozen monolithic templates is better then changing a dozen * 328 pages. Also means that you get the same translation ever single time.<br/>I've been thinking i could modify the LSLC, LSLG, LSLGC templates to support automated linking in language specific subpages. So if the page you are on is in Spanish, the links will lead to pages in Spanish if they exist. No special modifications to the links needed.[[User:Strife Onizuka|Strife Onizuka]] 06:43, 13 February 2007 (PST)
:::''But your idea on templates don't provide structure, it requires the user to provide the structure''
:::* That's kinda the point. Look at what information will need to be reused over and over again, and put it into a small template. Then those templates can be used directly, or as part of a wrapper template.
:::''I'm pretty sure I can put together template-templates that should make translating the templates easy as setting a few variables.''
:::* The templates don't need translating, just the content.
:::''I've been thinking i could modify the LSLC, LSLG, LSLGC templates to support automated linking in language specific subpages. So if the page you are on is in Spanish, the links will lead to pages in Spanish if they exist.''
:::* That would be bad.
:::* Better idea to follow.
:::[[User:SignpostMarv Martin|SignpostMarv Martin]] 13:13, 13 February 2007 (PST)
:::[[Template:Multi-lang]] I've given up fixing the bugs in that, but you get the idea behind it's intent. Include [[Help:Getting_started_in_Second_Life/langs]] in your test page and <nowiki>{{#vardefine:article-lang}}</nowiki> to either '''spa'' or '''eng'''.
:::Please fork the code into your own userspace if you're going to work on it (unless you know of an instant fix) to prevent edit collisions.
:::I've also started work on [[Template:ISO_639-3/native]] to save a bit of time with entering languages that one browser might not be configured for (e.g. the higher-end UTF-8 characters)
:::[[User:SignpostMarv Martin|SignpostMarv Martin]] 22:08, 19 February 2007 (PST)

== phasing out of [[Template:LSLG]] ==

Since the need to prefix almost everything with LSL_ is now being removed, all articles that are calling [[Template:LSLG]] should be edited to use a Wiki link, as the template is now rather redundant.

The list of articles calling [[Template:LSLG|LSLG]] can be viewed via [https://wiki.secondlife.com/w/index.php?title=Special:Whatlinkshere&target=Template%3ALSLG Special:Whatlinkshere].
<br />[[User:SignpostMarv Martin|SignpostMarv Martin]] 22:08, 19 February 2007 (PST)

:I think the pages in the {{LSLGC|FixMe}} category should be of a higher priority. Phasing out usage is reasonable, going through every page that uses it on the other hand just to remove it would be a waste of resources. I'm a bit nervous about stopping using it at present, the metaphoric paint hasn't even dried on the move yet. Considering it doesn't effect the rendering, phasing it's usage out is appropriate. [[User:Strife Onizuka|Strife Onizuka]] 23:20, 20 February 2007 (PST)
::Waste of resources ?
::Isn't it a waste of resources to use a template that in most cases is entirely redundant ?
::[[User:SignpostMarv Martin|SignpostMarv Martin]] 02:23, 21 February 2007 (PST)
:::We haven't even finihed moving the function pages to the new names and template yet. You could help with that instead of worrying about templates, you know. [[User:Gigs Taggart|Gigs Taggart]] 07:35, 21 February 2007 (PST)

== The original LSL Wiki is back! ==
Catherine Omega's [http://www.lslwiki.net original LSL Wiki] is back. She mentioned:

: ''"This is DEFINITELY back. And it's definitely permanent. It's all editable. And it's the 'official', Catherine-Omega-approved one."''

[http://www.catherineomega.com/2007/37/the-lsl-wiki-finds-a-new-home Further context can be found @ her blog.] --[[User:Torley Linden|Torley Linden]] 13:41, 28 February 2007 (PST)

== Table ==

I've been playing with the table (again). I've tried to get it so it looks decent in both IE and Firefox. I've been trying to get it to put all the extra space into the last section, which I managed in Firefox but haven't figured out the correct permutation of parameters for IE. I'm content at this moment to leave it be (I use Firefox). [[User:Strife Onizuka|Strife Onizuka]] 08:49, 17 March 2007 (PDT)

== Warning notice? ==

Might it be an idea to include a short warning on the top of this page that the LSL Portal is as yet incomplete?

I just spent a while trying to find a list function I knew existed, but couldn't remember the exact name of, which hasn't made it here yet before realising that not all functions are listed yet.
--[[User:Nick Shatner|Nick Shatner]], 02:56, 2 May 2007 (PDT)

:The vast majority of functions have been catagorized so if you had started from the {{LSLGC|List|list category page}} you probably would have found it. There are a small handful of functions that haven't been catagorized beyond the {{LSLGC|Functions}} category. I'm not sure if a warning is warranted but I do recognize there are gaps in the LSL information. -- [[User:Strife Onizuka|Strife Onizuka]] 13:31, 2 May 2007 (PDT)

llSetText page

which is here

http://wiki.secondlife.com/wiki/LlSetText

is missing from page listing all the functions. Can't quite figure out how that page gets its info, so not going to touch it.

== Conspiracy? ==

I whould like to know if <br/>
a) this is a public wiki, where everybody can contribute so the LSL gets better known, or if it is a private viki with conspirativ charakter<br/>
b) why it is kept so spartanik with information<br/>
c) why no lindens who wrote LSL document their work<br/>
d) why some private persons are called administrators, what rights do they have, and if they have ever signed a paper that makes them not abuse theyr position<br/>
e) why linden lab employees never fisicaly work and only give "precios advises"<br/>
dont dare to delete this.<br/>
{{User|Anylyn Hax}} 04:09, 8 August 2007 (PDT)

:I shall try to answer:
:a) It is a public wiki but not everyone can contribute, you must have an SL account to contribute.
:b) No one has added more information.
:c) They did, it's in the LSL manual that ships with the client (it's common knowledge that it sucks).
:d) I don't know of any non-linden administrators on the wiki.
:e) The design of LSL is stable and there are very few LSL bugs that haven't been vetted; it would surprise me if there were any full time LSL devs. Just because we don't see them working doesn't mean they aren't working; the SL code base is huge.
:-- [[User:Strife Onizuka|Strife Onizuka]] 12:56, 8 August 2007 (PDT)

== Vehicle Tutorial ==

Could we get the original vehicle tutorial added to this wiki. I realize it's not in the correct format, but it's a place to start. There was a wikified version too in the old wiki someone did, but they'd have to contribute it themselves I'd think. I can't find the original tutorial outside the old wiki.

:The tutorial was part of the LSL manual that ships with the client. LL has given permission to post it on the wiki. -- [[User:Strife Onizuka|Strife Onizuka]] 16:37, 8 September 2007 (PDT)

::I found an old copy I had and wikified it. This is pretty much the original version, so it's probably a bit whacked, please fix any problems you're aware of [[User:Ralph Doctorow|Ralph Doctorow]]

== color ==

It would be very helpful if I could use different colored text when writing my articles. Could buttons be added for black text, red text, green text, and one other color of text? Or could someone list the codes that can be used to change text color?

Just as an example of what I intend to use color for:

''black''rotation ''red''variable''black''=<''red''%,%,%,''green''#.#''black''>;

Linden Vehicle Tutorial

2007-09-26T21:54:46Z

Ralph Doctorow:

{{LSL_Header}}

== Vehicles ==

Vehicles are a new feature now available for use through LSL. This chapter will cover the basics of how vehicles
work, the terms used when describing vehicles, and a more thorough examination of the api available.

There are several ways to make scripted objects move themselves around. One way is to turn the object into a
"vehicle". This feature is versatile enough to make things that slide, hover, fly, and float. Some of the behaviors
that can be enabled are:

*deflection of linear and angular velocity to preferred axis of motion
*asymmetric linear and angular friction
*hovering over terrain/water or at a global height
*banking on turns
*linear and angular motor for push and turning

== Overview ==

Each scripted object can have one vehicle behavior that is configurable through the[[llSetVehicleType]],
llSetVehicleFloatParam,llSetVehicleVectorParam,llSetVehicleRotationParam,llSetVehicleFlags, and
llRemoveVehicleFlags library calls.

These script calls are described in more detail below, but the important thing to notice here is that the vehicle
behavior has several parameters that can be adjusted to change how the vehicle handles. Depending on the values
chosen the vehicle can veer like a boat in water, or ride like a sled on rails.

Setting the vehicle flags allow you to make exceptions to some default behaviors. Some of these flags only have
an effect when certain behaviors are enabled. For example, the [[VEHICLE_FLAG_HOVER_WATER_ONLY]] will
make the vehicle ignore the height of the terrain, however it only makes a difference if the vehicle is hovering.

== Warnings ==

Vehicles are new in Second Life 1.1 and some of the details of their behavior may be changed as necessary to
ensure stability and user safety. In particular, many of the limits and defaults described in the appendices will
probably change and should not be relied upon in the long term.

It is not recommended that you mix vehicle behavior with some of the other script calls that provide impulse and
forces to the object, especially[[llSetBuoyancy]],[[llSetForce]],[[llSetTorque]], and[[llSetHoverHeight]].

While the following methods probably don’t cause any instabilities, their behavior may conflict with vehicles
and cause undesired and/or inconsistent results, so use[[llLookAt]],[[llRotLookAt]],[[llMoveToTarget]], and
[[llTargetOmega]] at your own risk.

If you think you have found a bug relating to how vehicle’s work, one way to submit the problem is to give a
copy of the vehicle and script to Andrew Linden with comments or a notecard describing the problem. Please
name all submissions "Bugged Vehicle XX" where XX are your Second Life initials. The vehicle and script will
be examined at the earliest convenience.

== Definitions ==

The terms "roll", "pitch", and "yaw" are often used to describe the modes of rotations that can happen to a
airplane or boat. They correspond to rotations about the local x-, y-, and z-axis respectively.
z-axis .

http://en.wikipedia.org/wiki/Tait-Bryan_angles

The right-hand-rule, often introduced in beginning physics courses, is used to define the direction of positive
rotation about any axis. As an example of how to use the right hand rule, consider a positive rotation about the
roll axis. To help visualize how such a rotation would move the airplane, place your right thumb parallel to the
plane’s roll-axis such that the thumb points in the positive x-direction, then curl the four fingers into a fist. Your
fingers will be pointing in the direction that the plane will spin.

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

Many of the parameters that control a vehicle’s behavior are of the form:

VEHICLE_'''BEHAVIOR'''_TIMESCALE

A '''BEHAVIOR''' ’s "timescale" can usually be understood as the time for the
behavior to push, twist, or otherwise affect the vehicle such that the difference between what it is doing, and
what it is supposed to be doing, has been reduced to 1/e of what it was, where "e" is the natural exponent
(approximately 2.718281828). In other words, it is the timescale for exponential decay toward full compliance to
the desired behavior. When you want the vehicle to be very responsive use a short timescale of one second or
less, and if you want to disable a behavior then set the timescale to a very large number like 300 (5 minutes) or
more. Note, for stability reasons, there is usually a limit to how small a timescale is allowed to be, and is usually
on the order of a tenth of a second. Setting a timescale to zero is safe and is always equivalent to setting it to its
minimum. Any feature with a timescale can be effectively disabled by setting the timescale so large that it would
take them all day to have any effect.

== Setting the Vehicle Type ==

Before any vehicle parameters can be set the vehicle behavior must first be enabled. It is enabled by calling
[[llSetVehicleType]] with any '''VEHICLE_TYPE_*''', except [[VEHICLE_TYPE_NONE]] which will disable the
vehicle. See the {{LSLGC|Vehicle|vehicle types}} constants section for currently available types. More types will be available soon.

Setting the vehicle type is necessary for enabling the vehicle behavior and sets all of the parameters to its default
values. For each vehicle type listed we provide the corresponding equivalent code in long format. Is is important
to realize that the defaults are not the optimal settings for any of these vehicle types and that they will definitely
be changed in the future. Do not rely on these values to be constant until specified.

Should you want to make a unique or experimental vehicle you will still have to enable the vehicle behavior with
one of the default types first, after which you will be able to change any of the parameters or flags within the
allowed ranges.

Setting the vehicle type does not automatically take controls or otherwise move the object. However should you
enable the vehicle behavior while the object is free to move and parked on a hill then it may start to slide away.

We’re looking for new and better default vehicle types. If you think you’ve found a set of parameters that make a
better car, boat, or any other default type of vehicle then you may submit your proposed list of settings to
Andrew Linden via a script or notecard.

== Linear and Angular Deflection ==

A common feature of real vehicles is their tendency to move along "preferred axes of motion". That is, due to
their wheels, wings, shape, or method of propulsion they tend to push or redirect themselves along axes that are
static in the vehicle’s local frame. This general feature defines a class of vehicles and included in this category a
common dart is a "vehicle": it has fins in the back such that if it were to tumble in the air it would eventually
align itself to move point-forward -- we’ll call this alignment effect angular deflection.

A wheeled craft exhibits a different effect: when a skateboard is pushed in some direction it will tend to redirect
the resultant motion along that which it is free to roll -- we’ll call this effect linear deflection.

So a typical Second Life vehicle is an object that exhibits linear and/or angular deflection along the "preferential
axes of motion". The default preferential axes of motion are the local x- (at), y- (left), and z- (up) axes of the
local frame of the vehicle’s root primitive. The deflection behaviors relate to the x-axis (at): linear deflection will
tend to rotate its velocity until it points along it’s positive local x-axis while the angular deflection will tend to
reorient the vehicle such that it’s x-axis points in the direction that it is moving. The other axes are relevant to
vehicle behaviors that are described later, such as the vertical attractor which tries to keep a vehicle’s local z-axis
pointed toward the world z-axis (up). The vehicle axes can be rotated relative to the object’s actual local axes by
using the [[VEHICLE_REFERENCE_FRAME]] parameter, however that is an advanced feature and is covered in
detail in a later section of these documents.

Depending on the vehicle it might be desirable to have lots of linear and/or angular delfection or not. The speed
of the deflections are controlled by setting the relevant parameters using the[[llSetVehicleFloatParam]] script call.

Each variety of deflection has a "timescale" parameter that determines how quickly a full deflection happens.

Basically the timescale it the time coefficient for exponential decay toward full deflection. So, a vehicle that
deflects quickly should have a small timescale. For instance, a typical dart might have a angular deflection
timescale of a couple of seconds but a linear deflection of several seconds; it will tend to reorient itself before it
changes direction. To set the deflection timescales of a dart you might use the lines below:
<pre>
llSetVehicleFloatParam(VEHICLE_ANGULAR_DEFLECTION_TIMESCALE, 2.0);
llSetVehicleFloatParam(VEHICLE_LINEAR_DEFLECTION_TIMESCALE, 6.0);
</pre>
Each variety of deflection has an "efficiency" parameter that is a slider between 0.0 and 1.0. Unlike the other
efficiency parameter of other vehicle behaviors, the deflection efficiencies do not slide between "bouncy" and
"damped", but instead slide from "no deflection whatsoever" (0.0) to "maximum deflection" (1.0). That is, they
behave much like the deflection timescales, however they are normalized to the range between 0.0 and 1.0.

== Moving the Vehicle ==

Once enabled, a vehicle can be pushed and rotated by external forces and/or from script calls such as
[[llApplyImpulse]], however linear and angular motors have been built in to make motion easier and smoother.
Their directions can be set using the[[llSetVehicleVectorParam]] call. For example, to make the vehicle try to move
at 5 meters/second along its local x-axis (the default look-at direction) you would put the following line in your
script:
<pre>
llSetVehicleVectorParam(VEHICLE_LINEAR_MOTOR_DIRECTION, <5, 0, 0>);
</pre>
To prevent vehicles from moving too fast the magnitude of the linear motor is clamped to be no larger than about
30 meters/second. Note that this is clamped mostly because of limitations of the physics engine, and may be
raised later when possible.

Setting the motor speed is not enough to enable all interesting vehicles. For example, some will want a car that
immediately gets up to the speed they want, while others will want a boat that slowly climbs up to its maximum
velocity. To control this effect you can use the [[VEHICLE_LINEAR_MOTOR_TIMESCALE]] parameter.

Basically the "timescale" of a motor is the time constant for the vehicle to exponentially accelerate toward its full
speed.

What would happen if you were to accidentally set the vehicle’s linear velocity to maximum possible speed and
then let go? It would run away and never stop, right? Not necessarily: an automatic "motor decay" has been built
in such that all motors will gradually decrease their effectiveness after being set.

Each time the linear motor’s vector is set its "grip" immediately starts to decay exponentially with a timescale
determined by the [[VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE]], such that after enough time the
motor ceases to have any effect. This decay timescale serves two purposes. First, since it cannot be set longer
than 120 seconds, and is always enabled it gaurantees that a vehicle will not push itself about forever in the
absence of active control (from keyboard commands or some logic loop in the script). Second, it can be used to
push some vehicles around using a simple impulse model. That is, rather than setting the motor "on" or "off"
depending on whether a particular key is pressed "down" or "up" the decay timescale can be set short and the
motor can be set "on" whenever the key transitions from "up" to "down" and allowed to automatically decay.

Since the motor’s effectiveness is reset whenever the motor’s vector is set, then setting it to a vector of length
zero is different from allowing it to decay completely. The first case will cause the vehicle to try to reach zero
velocity, while the second will leave the motor impotent.

The two motor timescales have very similar names, but have different effects, so try not to get them confused.

::[[VEHICLE_LINEAR_MOTOR_TIMESCALE]] is the time for motor to "win", and

::[[VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE]] is the time for the motor’s "effectiveness" to decay
toward zero. If you set one when you think you are changing the other you will have frustrating results. Also, if
the motor’s decay timescale is shorter than the regular timescale, then the effective magnitude of the motor
vector will be diminished.

== Steering the Vehicle ==

Much like the linear motor, there is also an angular motor that is always on, and whose direction and magnitude
can be set. For example, to make a vehicle turn at 5 degrees/sec around it’s local z-axis (its up-axis) you might
add the following lines to its script:
<pre>
vector angular_velocity = <0, 0, 5 * PI / 180>;
llSetVehicleVectorParam(VEHICLE_ANGULAR_MOTOR_DIRECTION, angular_velocity);
</pre>
The magnitude of the angular motor is capped to be no more than two rotations per second (4*PI radians/sec).

Also like the linear motor it has an efficiency parameter, [[VEHICLE_ANGULAR_MOTOR_TIMESCALE]], and a
motor decay parameter, [[VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE]], which is set to themaximum possible value of 120 seconds by default.

When steering a vehicle you probably don’t want it to turn very far or for very long. One way to do it using the
angular motor would be to leave the decay timescale long, enable a significant amount of angular friction (to
quickly slow the vehicle down when the motor is turned off) then set the angular motor to a large vector on a key
press, and set it to zero when the key is released. Another way to do it is to set the
[[VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE]] to a short value and push the vehicle about with a
more impulsive method that sets the motor fast on a key press down (and optionally setting the motor to zero on
a key up) relying on the automatic exponential decay of the motor’s effectiveness rather than a constant angular
friction.

Setting the angular motor to zero magnitude is different from allowing it to decay. When the motor completely
decays it no longer affects the motion of the vehicle, however setting it to zero will reset the "grip" of the vehicle
and will make the vehicle try to achieve zero angular velocity.

For some vehicles it will be possible to use the "banking feature" to turn. "Banking" is what airplanes and
motorcycles do when they turn. When a banking vehicle twists about its roll-axis there is a resultant spin around
its yaw-axis. Banking is only available when using the "vertical attractor" which is described below.

== The Vertical Attractor ==

Some vehicles, like boats, should always keep their up-side up. This can be done by enabling the "vertical
attractor" behavior that springs the vehicle’s local z-axis to the world z-axis (a.k.a. "up"). To take advantage of
this feature you would set the [[VEHICLE_VERTICAL_ATTRACTION_TIMESCALE]] to control the period of
the spring frequency, and then set the [[VEHICLE_VERTICAL_ATTRACTION_EFFICIENCY]] to control the
damping. An efficiency of 0.0 will cause the spring to wobble around its equilibrium, while an efficiency of 1.0
will cause the spring to reach it’s equilibrium with exponential decay.
<pre>
llSetVehicleVectorParam(VEHICLE_VERTICAL_ATTRACTION_TIMESCALE, 4.0);
llSetVehicleVectorParam(VEHICLE_VERTICAL_ATTRACTION_EFFICIENCY, 0.5);
</pre>
The vertical attractor is disabled by setting its timescale to anything larger than 300 seconds.

Note that by default the vertical attractor will prevent the vehicle from diving and climbing. So, if you wanted to
make a airplane you would probably want to unlock the attractor around the pitch axis by setting the
[[VEHICLE_FLAG_LIMIT_ROLL_ONLY]] bit:
<pre>
llSetVehicleFlags(VEHICLE_FLAG_LIMIT_ROLL_ONLY);
</pre>

== Banking ==

The vertical attractor feature must be enabled in order for the banking behavior to function. The way banking
works is this: a rotation around the vehicle’s roll-axis will produce a angular velocity around the yaw-axis,
causing the vehicle to turn. The magnitude of the yaw effect will be proportional to the

::[[VEHICLE_BANKING_COEF]], the angle of the roll rotation, and sometimes the vehicle’s velocity along it’s
preferred axis of motion.

::The [[VEHICLE_BANKING_COEF]] can vary between -1 and +1. When it’s positive then any positive rotation (by
the right-hand rule) about the roll-axis will effect a (negative) torque around the yaw-axis, making it turn to the
right -- that is the vehicle will lean into the turn, which is how real airplanes and motorcycle’s work. Negating
the banking coefficient will make it so that the vehicle leans to the outside of the turn (not very "physical" but
might allow interesting vehicles so why not?).

::The [[VEHICLE_BANKING_MIX]] is a fake (i.e. non-physical) parameter that is useful for making banking
vehicles do what you want rather than what the laws of physics allow. For example, consider a real motorcycle...
it must be moving forward in order for it to turn while banking, however video-game motorcycles are often
configured to turn in place when at a dead stop -- because they’re often easier to control that way using the
limited interface of the keyboard or game controller. The [[VEHICLE_BANKING_MIX]] enables combinations of
both realistic and non-realistic banking by fuctioning as a slider between a banking that is correspondingly
totally static (0.0) and totally dynamic (1.0). By "static" we mean that the banking effect depends only on the
vehicle’s rotation about it’s roll-axis compared to "dynamic" where the banking is also proportional to it’s
velocity along it’s roll-axis. Finding the best value of the "mixture" will probably require trial and error.

The time it takes for the banking behavior to defeat a pre-existing angular velocity about the world z-axis is
determined by the [[VEHICLE_BANKING_TIMESCALE]]. So if you want the vehicle to bank quickly then give it
a banking timescale of about a second or less, otherwise you can make a sluggish vehicle by giving it a timescale
of several seconds.

== Friction Timescales ==

[[VEHICLE_LINEAR_FRICTION_TIMESCALE]] is a vector parameter that defines the timescales for the vehicle
to come to a complete stop along the three local axes of the vehicle’s reference frame. The timescale along each
axis is independent of the others. For example, a sliding ground car would probably have very little friction along
its x- and z-axes (so it can easily slide forward and fall down) while there would usually significant friction along
its y-axis:
<pre>
llSetVehicleVectorParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, <1000, 1000, 3>);
</pre>
Remember that a longer timescale corresponds to a weaker friction, hence to effectively disable all linear friction
you would set all of the timescales to large values.

Setting the linear friction as a scalar is allowed, and has the effect of setting all of the timescales to the same
value. Both code snippets below are equivalent, and both make friction negligible:
<pre>
// set all linear friction timescales to 1000
llSetVehicleVectorParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, <1000, 1000, 1000>);
// same as above, but fewer characters
llSetVehicleFloatParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, 1000);
</pre>
/[[VEHICLE_ANGULAR_FRICTION_TIMESCALE]] is also a vector parameter that defines the timescales for the
vehicle to stop rotating about the x-, y-, and z-axes, and are set and disabled in the same way as the linear friction.

== Buoyancy ==

The vehicle has a built-in buoyancy feature that is independent of the[[llSetBuoyancy]] call. It is recommended that
the two buoyancies do not mix! To make a vehicle buoyant, set the [[VEHICLE_BUOYANCY]] parameter to
something between 0.0 (no buoyancy whatsoever) to 1.0 (full anti-gravity).

The buoyancy behavior is independent of hover, however in order for hover to work without a large offset of the
[[VEHICLE_HOVER_HEIGHT]], the [[VEHICLE_BUOYANCY]] should be set to 1.0.

It is not recommended that you mix vehicle buoyancy with the[[llSetBuoyancy]] script call. It would probably
cause the object to fly up into space.

== Hover ==

The hover behavior is enabled by setting the [[VEHICLE_HOVER_TIMESCALE]] to a value less than 300
seconds; larger timescales totally disable it. Most vehicles will work best with short hover timescales of a few
seconds or less. The shorter the timescale, the faster the vehicle will slave to is target height. Note, that if the
values of [[VEHICLE_LINEAR_FRICTION_TIMESCALE]] may affect the speed of the hover.

Hover is independent of buoyancy, however the [[VEHICLE_BUOYANCY]] should be set to 1.0, otherwise the
vehicle will not lift itself off of the ground until the [[VEHICLE_HOVER_HEIGHT]] is made large enough to
counter the acceleration of gravity, and the vehicle will never float all the way to its target height.

The [[VEHICLE_HOVER_EFFICIENCY]] can be thought of as a slider between bouncy (0.0) and smoothed (1.0).

When in the bouncy range the vehicle will tend to hover a little lower than its target height and the
[[VEHICLE_HOVER_TIMESCALE]] will be approximately the oscillation period of the bounce (the real period
will tend to be a little longer than the timescale).

For performance reasons, until improvements are made to the Second Life physics engine the vehicles can only
hover over the terrain and water, so they will not be able to hover above objects made out of primitives, such as
bridges and houses. By default the hover behavior will float over terrain and water, however this can be changed
by setting some flags:

If you wanted to make a boat you should set the [[VEHICLE_HOVER_WATER_ONLY]] flag, or if you wanted to
drive a hover tank under water you would use the [[VEHICLE_HOVER_TERRAIN_ONLY]] flag instead. Finally,
if you wanted to make a submarine or a balloon you would use the [[VEHICLE_HOVER_GLOBAL_HEIGHT]].

Note that the flags are independent of each other and that setting two contradictory flags will have undefined
behavor. The flags are set using the script call[[llSetVehicleFlags()]].

The [[VEHICLE_HOVER_HEIGHT]] determines how high the vehicle will hover over the terrain and/or water, or
the global height, and has a maximum value of 100 meters. Note that for hovering purposes the "center" of the
vehicle is its "center of mass" which is not always obvious to the untrained eye, and it changes when avatar’s sit
on the vehicle.

== Reference Frame ==

The vehicle relies on the x- (at), y- (left), and z- (up) axes in order to figure out which way it preferres to move
and which end is up. By default these axes are identical to the local axes of the root primitive of the object,
however this means that the vehicle’s root primitive must, by default, be oriented to agree with the designed at,
left, and up axes of the vehicle. But, what if the vehicle object was already pre-built with the root primitive in
some non-trivial orientation relative to where the vehicle as a whole should move? This is where the

[[VEHICLE_REFERENCE_FRAME]] parameter becomes useful; the vehicle’s axes can be arbitrarily reoriented
by setting this parameter.

As an example, suppose you had built a rocket out of a big cylinder, a cone for the nose, and some stretched cut
boxes for the fins, then linked them all together with the cylinder as the root primitive. Ideally the rocket would
move nose-first, however the cylinder’s axis of symmetry is its local z-axis while the default "at-axis" of the
vehicle, the axis it will want to deflect to forward under angular deflection, is the local x-axis and points out from
the curved surface of the cylinder. The script code below will rotate the vehicle’s axes such that the local z-axis
becomes the "at-axis" and the local negative x-axis becomes the "up-axis":
<pre>
// rotate the vehicle frame -PI/2 about the local y-axis (left-axis)
rotation rot =llEuler2Rot(0, PI/2, 0);
llSetVehicleRotationParam(VEHICLE_REFERENCE_FRAME, rot);
</pre>
Another example of how the reference frame parameter could be used is to consider flying craft that uses the
vertical attractor for stability during flying but wants to use VTOL (vertical takeoff and landing). During flight
the craft’s dorsal axis should point up, but during landing its nose-axis should be up. To land the vehicle: while
the vertical attractor is in effect, rotate the existing [[VEHICLE_REFERENCE_FRAME]] by +PI/2 about the
left-axis, then the vehicle will pitch up such that it’s nose points toward the sky. The vehicle could be allowed to
fall to the landing pad under friction, or a decreasing hover effect.

{{LSLC|Vehicle|Tutorial}} {{LSLC|Tutorials|Vehicle}}

Linden Vehicle Tutorial

2007-09-26T21:54:30Z

Ralph Doctorow:

{{LSL_Header}}

== Vehicles ==

Vehicles are a new feature now available for use through LSL. This chapter will cover the basics of how vehicles
work, the terms used when describing vehicles, and a more thorough examination of the api available.

There are several ways to make scripted objects move themselves around. One way is to turn the object into a
"vehicle". This feature is versatile enough to make things that slide, hover, fly, and float. Some of the behaviors
that can be enabled are:

*deflection of linear and angular velocity to preferred axis of motion
*asymmetric linear and angular friction
*hovering over terrain/water or at a global height
*banking on turns
*linear and angular motor for push and turning

== Overview ==

Each scripted object can have one vehicle behavior that is configurable through the[[llSetVehicleType]],
llSetVehicleFloatParam,llSetVehicleVectorParam,llSetVehicleRotationParam,llSetVehicleFlags, and
llRemoveVehicleFlags library calls.

These script calls are described in more detail below, but the important thing to notice here is that the vehicle
behavior has several parameters that can be adjusted to change how the vehicle handles. Depending on the values
chosen the vehicle can veer like a boat in water, or ride like a sled on rails.

Setting the vehicle flags allow you to make exceptions to some default behaviors. Some of these flags only have
an effect when certain behaviors are enabled. For example, the [[VEHICLE_FLAG_HOVER_WATER_ONLY]] will
make the vehicle ignore the height of the terrain, however it only makes a difference if the vehicle is hovering.

== Warnings ==

Vehicles are new in Second Life 1.1 and some of the details of their behavior may be changed as necessary to
ensure stability and user safety. In particular, many of the limits and defaults described in the appendices will
probably change and should not be relied upon in the long term.

It is not recommended that you mix vehicle behavior with some of the other script calls that provide impulse and
forces to the object, especially[[llSetBuoyancy]],[[llSetForce]],[[llSetTorque]], and[[llSetHoverHeight]].

While the following methods probably don’t cause any instabilities, their behavior may conflict with vehicles
and cause undesired and/or inconsistent results, so use[[llLookAt]],[[llRotLookAt]],[[llMoveToTarget]], and
[[llTargetOmega]] at your own risk.

If you think you have found a bug relating to how vehicle’s work, one way to submit the problem is to give a
copy of the vehicle and script to Andrew Linden with comments or a notecard describing the problem. Please
name all submissions "Bugged Vehicle XX" where XX are your Second Life initials. The vehicle and script will
be examined at the earliest convenience.

== Definitions ==

The terms "roll", "pitch", and "yaw" are often used to describe the modes of rotations that can happen to a
airplane or boat. They correspond to rotations about the local x-, y-, and z-axis respectively.
z-axis .

http://en.wikipedia.org/wiki/Tait-Bryan_angles

The right-hand-rule, often introduced in beginning physics courses, is used to define the direction of positive
rotation about any axis. As an example of how to use the right hand rule, consider a positive rotation about the
roll axis. To help visualize how such a rotation would move the airplane, place your right thumb parallel to the
plane’s roll-axis such that the thumb points in the positive x-direction, then curl the four fingers into a fist. Your
fingers will be pointing in the direction that the plane will spin.

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

Many of the parameters that control a vehicle’s behavior are of the form:

VEHICLE_'''BEHAVIOR'''_TIMESCALE

A '''BEHAVIOR''' ’s "timescale" can usually be understood as the time for the
behavior to push, twist, or otherwise affect the vehicle such that the difference between what it is doing, and
what it is supposed to be doing, has been reduced to 1/e of what it was, where "e" is the natural exponent
(approximately 2.718281828). In other words, it is the timescale for exponential decay toward full compliance to
the desired behavior. When you want the vehicle to be very responsive use a short timescale of one second or
less, and if you want to disable a behavior then set the timescale to a very large number like 300 (5 minutes) or
more. Note, for stability reasons, there is usually a limit to how small a timescale is allowed to be, and is usually
on the order of a tenth of a second. Setting a timescale to zero is safe and is always equivalent to setting it to its
minimum. Any feature with a timescale can be effectively disabled by setting the timescale so large that it would
take them all day to have any effect.

== Setting the Vehicle Type ==

Before any vehicle parameters can be set the vehicle behavior must first be enabled. It is enabled by calling
[[llSetVehicleType]] with any '''VEHICLE_TYPE_*''', except [[VEHICLE_TYPE_NONE]] which will disable the
vehicle. See the {{LSLGC|Vehicle|vehicle types}} constants section for currently available types. More types will be available soon.

Setting the vehicle type is necessary for enabling the vehicle behavior and sets all of the parameters to its default
values. For each vehicle type listed we provide the corresponding equivalent code in long format. Is is important
to realize that the defaults are not the optimal settings for any of these vehicle types and that they will definitely
be changed in the future. Do not rely on these values to be constant until specified.

Should you want to make a unique or experimental vehicle you will still have to enable the vehicle behavior with
one of the default types first, after which you will be able to change any of the parameters or flags within the
allowed ranges.

Setting the vehicle type does not automatically take controls or otherwise move the object. However should you
enable the vehicle behavior while the object is free to move and parked on a hill then it may start to slide away.

We’re looking for new and better default vehicle types. If you think you’ve found a set of parameters that make a
better car, boat, or any other default type of vehicle then you may submit your proposed list of settings to
Andrew Linden via a script or notecard.

== Linear and Angular Deflection ==

A common feature of real vehicles is their tendency to move along "preferred axes of motion". That is, due to
their wheels, wings, shape, or method of propulsion they tend to push or redirect themselves along axes that are
static in the vehicle’s local frame. This general feature defines a class of vehicles and included in this category a
common dart is a "vehicle": it has fins in the back such that if it were to tumble in the air it would eventually
align itself to move point-forward -- we’ll call this alignment effect angular deflection.

A wheeled craft exhibits a different effect: when a skateboard is pushed in some direction it will tend to redirect
the resultant motion along that which it is free to roll -- we’ll call this effect linear deflection.

So a typical Second Life vehicle is an object that exhibits linear and/or angular deflection along the "preferential
axes of motion". The default preferential axes of motion are the local x- (at), y- (left), and z- (up) axes of the
local frame of the vehicle’s root primitive. The deflection behaviors relate to the x-axis (at): linear deflection will
tend to rotate its velocity until it points along it’s positive local x-axis while the angular deflection will tend to
reorient the vehicle such that it’s x-axis points in the direction that it is moving. The other axes are relevant to
vehicle behaviors that are described later, such as the vertical attractor which tries to keep a vehicle’s local z-axis
pointed toward the world z-axis (up). The vehicle axes can be rotated relative to the object’s actual local axes by
using the [[VEHICLE_REFERENCE_FRAME]] parameter, however that is an advanced feature and is covered in
detail in a later section of these documents.

Depending on the vehicle it might be desirable to have lots of linear and/or angular delfection or not. The speed
of the deflections are controlled by setting the relevant parameters using the[[llSetVehicleFloatParam]] script call.

Each variety of deflection has a "timescale" parameter that determines how quickly a full deflection happens.

Basically the timescale it the time coefficient for exponential decay toward full deflection. So, a vehicle that
deflects quickly should have a small timescale. For instance, a typical dart might have a angular deflection
timescale of a couple of seconds but a linear deflection of several seconds; it will tend to reorient itself before it
changes direction. To set the deflection timescales of a dart you might use the lines below:
<pre>
llSetVehicleFloatParam(VEHICLE_ANGULAR_DEFLECTION_TIMESCALE, 2.0);
llSetVehicleFloatParam(VEHICLE_LINEAR_DEFLECTION_TIMESCALE, 6.0);
</pre>
Each variety of deflection has an "efficiency" parameter that is a slider between 0.0 and 1.0. Unlike the other
efficiency parameter of other vehicle behaviors, the deflection efficiencies do not slide between "bouncy" and
"damped", but instead slide from "no deflection whatsoever" (0.0) to "maximum deflection" (1.0). That is, they
behave much like the deflection timescales, however they are normalized to the range between 0.0 and 1.0.

== Moving the Vehicle ==

Once enabled, a vehicle can be pushed and rotated by external forces and/or from script calls such as
[[llApplyImpulse]], however linear and angular motors have been built in to make motion easier and smoother.
Their directions can be set using the[[llSetVehicleVectorParam]] call. For example, to make the vehicle try to move
at 5 meters/second along its local x-axis (the default look-at direction) you would put the following line in your
script:
<pre>
llSetVehicleVectorParam(VEHICLE_LINEAR_MOTOR_DIRECTION, <5, 0, 0>);
</pre>
To prevent vehicles from moving too fast the magnitude of the linear motor is clamped to be no larger than about
30 meters/second. Note that this is clamped mostly because of limitations of the physics engine, and may be
raised later when possible.

Setting the motor speed is not enough to enable all interesting vehicles. For example, some will want a car that
immediately gets up to the speed they want, while others will want a boat that slowly climbs up to its maximum
velocity. To control this effect you can use the [[VEHICLE_LINEAR_MOTOR_TIMESCALE]] parameter.

Basically the "timescale" of a motor is the time constant for the vehicle to exponentially accelerate toward its full
speed.

What would happen if you were to accidentally set the vehicle’s linear velocity to maximum possible speed and
then let go? It would run away and never stop, right? Not necessarily: an automatic "motor decay" has been built
in such that all motors will gradually decrease their effectiveness after being set.

Each time the linear motor’s vector is set its "grip" immediately starts to decay exponentially with a timescale
determined by the [[VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE]], such that after enough time the
motor ceases to have any effect. This decay timescale serves two purposes. First, since it cannot be set longer
than 120 seconds, and is always enabled it gaurantees that a vehicle will not push itself about forever in the
absence of active control (from keyboard commands or some logic loop in the script). Second, it can be used to
push some vehicles around using a simple impulse model. That is, rather than setting the motor "on" or "off"
depending on whether a particular key is pressed "down" or "up" the decay timescale can be set short and the
motor can be set "on" whenever the key transitions from "up" to "down" and allowed to automatically decay.

Since the motor’s effectiveness is reset whenever the motor’s vector is set, then setting it to a vector of length
zero is different from allowing it to decay completely. The first case will cause the vehicle to try to reach zero
velocity, while the second will leave the motor impotent.

The two motor timescales have very similar names, but have different effects, so try not to get them confused.

::[[VEHICLE_LINEAR_MOTOR_TIMESCALE]] is the time for motor to "win", and

::[[VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE]] is the time for the motor’s "effectiveness" to decay
toward zero. If you set one when you think you are changing the other you will have frustrating results. Also, if
the motor’s decay timescale is shorter than the regular timescale, then the effective magnitude of the motor
vector will be diminished.

== Steering the Vehicle ==

Much like the linear motor, there is also an angular motor that is always on, and whose direction and magnitude
can be set. For example, to make a vehicle turn at 5 degrees/sec around it’s local z-axis (its up-axis) you might
add the following lines to its script:
<pre>
vector angular_velocity = <0, 0, 5 * PI / 180>;
llSetVehicleVectorParam(VEHICLE_ANGULAR_MOTOR_DIRECTION, angular_velocity);
</pre>
The magnitude of the angular motor is capped to be no more than two rotations per second (4*PI radians/sec).

Also like the linear motor it has an efficiency parameter, [[VEHICLE_ANGULAR_MOTOR_TIMESCALE]], and a
motor decay parameter, [[VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE]], which is set to themaximum possible value of 120 seconds by default.

When steering a vehicle you probably don’t want it to turn very far or for very long. One way to do it using the
angular motor would be to leave the decay timescale long, enable a significant amount of angular friction (to
quickly slow the vehicle down when the motor is turned off) then set the angular motor to a large vector on a key
press, and set it to zero when the key is released. Another way to do it is to set the
[[VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE]] to a short value and push the vehicle about with a
more impulsive method that sets the motor fast on a key press down (and optionally setting the motor to zero on
a key up) relying on the automatic exponential decay of the motor’s effectiveness rather than a constant angular
friction.

Setting the angular motor to zero magnitude is different from allowing it to decay. When the motor completely
decays it no longer affects the motion of the vehicle, however setting it to zero will reset the "grip" of the vehicle
and will make the vehicle try to achieve zero angular velocity.

For some vehicles it will be possible to use the "banking feature" to turn. "Banking" is what airplanes and
motorcycles do when they turn. When a banking vehicle twists about its roll-axis there is a resultant spin around
its yaw-axis. Banking is only available when using the "vertical attractor" which is described below.

== The Vertical Attractor ==

Some vehicles, like boats, should always keep their up-side up. This can be done by enabling the "vertical
attractor" behavior that springs the vehicle’s local z-axis to the world z-axis (a.k.a. "up"). To take advantage of
this feature you would set the [[VEHICLE_VERTICAL_ATTRACTION_TIMESCALE]] to control the period of
the spring frequency, and then set the [[VEHICLE_VERTICAL_ATTRACTION_EFFICIENCY]] to control the
damping. An efficiency of 0.0 will cause the spring to wobble around its equilibrium, while an efficiency of 1.0
will cause the spring to reach it’s equilibrium with exponential decay.
<pre>
llSetVehicleVectorParam(VEHICLE_VERTICAL_ATTRACTION_TIMESCALE, 4.0);
llSetVehicleVectorParam(VEHICLE_VERTICAL_ATTRACTION_EFFICIENCY, 0.5);
</pre>
The vertical attractor is disabled by setting its timescale to anything larger than 300 seconds.

Note that by default the vertical attractor will prevent the vehicle from diving and climbing. So, if you wanted to
make a airplane you would probably want to unlock the attractor around the pitch axis by setting the
[[VEHICLE_FLAG_LIMIT_ROLL_ONLY]] bit:
<pre>
llSetVehicleFlags(VEHICLE_FLAG_LIMIT_ROLL_ONLY);
</pre>

== Banking ==

The vertical attractor feature must be enabled in order for the banking behavior to function. The way banking
works is this: a rotation around the vehicle’s roll-axis will produce a angular velocity around the yaw-axis,
causing the vehicle to turn. The magnitude of the yaw effect will be proportional to the

::[[VEHICLE_BANKING_COEF]], the angle of the roll rotation, and sometimes the vehicle’s velocity along it’s
preferred axis of motion.

::The [[VEHICLE_BANKING_COEF]] can vary between -1 and +1. When it’s positive then any positive rotation (by
the right-hand rule) about the roll-axis will effect a (negative) torque around the yaw-axis, making it turn to the
right -- that is the vehicle will lean into the turn, which is how real airplanes and motorcycle’s work. Negating
the banking coefficient will make it so that the vehicle leans to the outside of the turn (not very "physical" but
might allow interesting vehicles so why not?).

::The [[VEHICLE_BANKING_MIX]] is a fake (i.e. non-physical) parameter that is useful for making banking
vehicles do what you want rather than what the laws of physics allow. For example, consider a real motorcycle...
it must be moving forward in order for it to turn while banking, however video-game motorcycles are often
configured to turn in place when at a dead stop -- because they’re often easier to control that way using the
limited interface of the keyboard or game controller. The [[VEHICLE_BANKING_MIX]] enables combinations of
both realistic and non-realistic banking by fuctioning as a slider between a banking that is correspondingly
totally static (0.0) and totally dynamic (1.0). By "static" we mean that the banking effect depends only on the
vehicle’s rotation about it’s roll-axis compared to "dynamic" where the banking is also proportional to it’s
velocity along it’s roll-axis. Finding the best value of the "mixture" will probably require trial and error.

The time it takes for the banking behavior to defeat a pre-existing angular velocity about the world z-axis is
determined by the [[VEHICLE_BANKING_TIMESCALE]]. So if you want the vehicle to bank quickly then give it
a banking timescale of about a second or less, otherwise you can make a sluggish vehicle by giving it a timescale
of several seconds.

== Friction Timescales ==

[[VEHICLE_LINEAR_FRICTION_TIMESCALE]] is a vector parameter that defines the timescales for the vehicle
to come to a complete stop along the three local axes of the vehicle’s reference frame. The timescale along each
axis is independent of the others. For example, a sliding ground car would probably have very little friction along
its x- and z-axes (so it can easily slide forward and fall down) while there would usually significant friction along
its y-axis:
<pre>
llSetVehicleVectorParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, <1000, 1000, 3>);
</pre>
Remember that a longer timescale corresponds to a weaker friction, hence to effectively disable all linear friction
you would set all of the timescales to large values.

Setting the linear friction as a scalar is allowed, and has the effect of setting all of the timescales to the same
value. Both code snippets below are equivalent, and both make friction negligible:
<pre>
// set all linear friction timescales to 1000
llSetVehicleVectorParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, <1000, 1000, 1000>);
// same as above, but fewer characters
llSetVehicleFloatParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, 1000);
</pre>
/[[VEHICLE_ANGULAR_FRICTION_TIMESCALE]] is also a vector parameter that defines the timescales for the
vehicle to stop rotating about the x-, y-, and z-axes, and are set and disabled in the same way as the linear friction.

== Buoyancy ==

The vehicle has a built-in buoyancy feature that is independent of the[[llSetBuoyancy]] call. It is recommended that
the two buoyancies do not mix! To make a vehicle buoyant, set the [[VEHICLE_BUOYANCY]] parameter to
something between 0.0 (no buoyancy whatsoever) to 1.0 (full anti-gravity).

The buoyancy behavior is independent of hover, however in order for hover to work without a large offset of the
[[VEHICLE_HOVER_HEIGHT]], the [[VEHICLE_BUOYANCY]] should be set to 1.0.

It is not recommended that you mix vehicle buoyancy with the[[llSetBuoyancy]] script call. It would probably
cause the object to fly up into space.

== Hover ==

The hover behavior is enabled by setting the [[VEHICLE_HOVER_TIMESCALE]] to a value less than 300
seconds; larger timescales totally disable it. Most vehicles will work best with short hover timescales of a few
seconds or less. The shorter the timescale, the faster the vehicle will slave to is target height. Note, that if the
values of [[VEHICLE_LINEAR_FRICTION_TIMESCALE]] may affect the speed of the hover.

Hover is independent of buoyancy, however the [[VEHICLE_BUOYANCY]] should be set to 1.0, otherwise the
vehicle will not lift itself off of the ground until the [[VEHICLE_HOVER_HEIGHT]] is made large enough to
counter the acceleration of gravity, and the vehicle will never float all the way to its target height.

The [[VEHICLE_HOVER_EFFICIENCY]] can be thought of as a slider between bouncy (0.0) and smoothed (1.0).

When in the bouncy range the vehicle will tend to hover a little lower than its target height and the
[[VEHICLE_HOVER_TIMESCALE]] will be approximately the oscillation period of the bounce (the real period
will tend to be a little longer than the timescale).

For performance reasons, until improvements are made to the Second Life physics engine the vehicles can only
hover over the terrain and water, so they will not be able to hover above objects made out of primitives, such as
bridges and houses. By default the hover behavior will float over terrain and water, however this can be changed
by setting some flags:

If you wanted to make a boat you should set the [[VEHICLE_HOVER_WATER_ONLY]] flag, or if you wanted to
drive a hover tank under water you would use the [[VEHICLE_HOVER_TERRAIN_ONLY]] flag instead. Finally,
if you wanted to make a submarine or a balloon you would use the [[VEHICLE_HOVER_GLOBAL_HEIGHT]].

Note that the flags are independent of each other and that setting two contradictory flags will have undefined
behavor. The flags are set using the script call[[llSetVehicleFlags()]].

The [[VEHICLE_HOVER_HEIGHT]] determines how high the vehicle will hover over the terrain and/or water, or
the global height, and has a maximum value of 100 meters. Note that for hovering purposes the "center" of the
vehicle is its "center of mass" which is not always obvious to the untrained eye, and it changes when avatar’s sit
on the vehicle.

== Reference Frame ==

The vehicle relies on the x- (at), y- (left), and z- (up) axes in order to figure out which way it preferres to move
and which end is up. By default these axes are identical to the local axes of the root primitive of the object,
however this means that the vehicle’s root primitive must, by default, be oriented to agree with the designed at,
left, and up axes of the vehicle. But, what if the vehicle object was already pre-built with the root primitive in
some non-trivial orientation relative to where the vehicle as a whole should move? This is where the

[[VEHICLE_REFERENCE_FRAME]] parameter becomes useful; the vehicle’s axes can be arbitrarily reoriented
by setting this parameter.

As an example, suppose you had built a rocket out of a big cylinder, a cone for the nose, and some stretched cut
boxes for the fins, then linked them all together with the cylinder as the root primitive. Ideally the rocket would
move nose-first, however the cylinder’s axis of symmetry is its local z-axis while the default "at-axis" of the
vehicle, the axis it will want to deflect to forward under angular deflection, is the local x-axis and points out from
the curved surface of the cylinder. The script code below will rotate the vehicle’s axes such that the local z-axis
becomes the "at-axis" and the local negative x-axis becomes the "up-axis":
<pre>
// rotate the vehicle frame -PI/2 about the local y-axis (left-axis)
rotation rot =llEuler2Rot(0, PI/2, 0);
llSetVehicleRotationParam(VEHICLE_REFERENCE_FRAME, rot);
</pre>
Another example of how the reference frame parameter could be used is to consider flying craft that uses the
vertical attractor for stability during flying but wants to use VTOL (vertical takeoff and landing). During flight
the craft’s dorsal axis should point up, but during landing its nose-axis should be up. To land the vehicle: while
the vertical attractor is in effect, rotate the existing [[VEHICLE_REFERENCE_FRAME]] by +PI/2 about the
left-axis, then the vehicle will pitch up such that it’s nose points toward the sky. The vehicle could be allowed to
fall to the landing pad under friction, or a decreasing hover effect.

Catagories: {{LSLC|Vehicle|Tutorial}} {{LSLC|Tutorials|Vehicle}}

Linden Vehicle Tutorial

2007-09-26T21:53:44Z

Ralph Doctorow:

{{LSL_Header}}

== Vehicles ==

Vehicles are a new feature now available for use through LSL. This chapter will cover the basics of how vehicles
work, the terms used when describing vehicles, and a more thorough examination of the api available.

There are several ways to make scripted objects move themselves around. One way is to turn the object into a
"vehicle". This feature is versatile enough to make things that slide, hover, fly, and float. Some of the behaviors
that can be enabled are:

*deflection of linear and angular velocity to preferred axis of motion
*asymmetric linear and angular friction
*hovering over terrain/water or at a global height
*banking on turns
*linear and angular motor for push and turning

== Overview ==

Each scripted object can have one vehicle behavior that is configurable through the[[llSetVehicleType]],
llSetVehicleFloatParam,llSetVehicleVectorParam,llSetVehicleRotationParam,llSetVehicleFlags, and
llRemoveVehicleFlags library calls.

These script calls are described in more detail below, but the important thing to notice here is that the vehicle
behavior has several parameters that can be adjusted to change how the vehicle handles. Depending on the values
chosen the vehicle can veer like a boat in water, or ride like a sled on rails.

Setting the vehicle flags allow you to make exceptions to some default behaviors. Some of these flags only have
an effect when certain behaviors are enabled. For example, the [[VEHICLE_FLAG_HOVER_WATER_ONLY]] will
make the vehicle ignore the height of the terrain, however it only makes a difference if the vehicle is hovering.

== Warnings ==

Vehicles are new in Second Life 1.1 and some of the details of their behavior may be changed as necessary to
ensure stability and user safety. In particular, many of the limits and defaults described in the appendices will
probably change and should not be relied upon in the long term.

It is not recommended that you mix vehicle behavior with some of the other script calls that provide impulse and
forces to the object, especially[[llSetBuoyancy]],[[llSetForce]],[[llSetTorque]], and[[llSetHoverHeight]].

While the following methods probably don’t cause any instabilities, their behavior may conflict with vehicles
and cause undesired and/or inconsistent results, so use[[llLookAt]],[[llRotLookAt]],[[llMoveToTarget]], and
[[llTargetOmega]] at your own risk.

If you think you have found a bug relating to how vehicle’s work, one way to submit the problem is to give a
copy of the vehicle and script to Andrew Linden with comments or a notecard describing the problem. Please
name all submissions "Bugged Vehicle XX" where XX are your Second Life initials. The vehicle and script will
be examined at the earliest convenience.

== Definitions ==

The terms "roll", "pitch", and "yaw" are often used to describe the modes of rotations that can happen to a
airplane or boat. They correspond to rotations about the local x-, y-, and z-axis respectively.
z-axis .

http://en.wikipedia.org/wiki/Tait-Bryan_angles

The right-hand-rule, often introduced in beginning physics courses, is used to define the direction of positive
rotation about any axis. As an example of how to use the right hand rule, consider a positive rotation about the
roll axis. To help visualize how such a rotation would move the airplane, place your right thumb parallel to the
plane’s roll-axis such that the thumb points in the positive x-direction, then curl the four fingers into a fist. Your
fingers will be pointing in the direction that the plane will spin.

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

Many of the parameters that control a vehicle’s behavior are of the form:

VEHICLE_'''BEHAVIOR'''_TIMESCALE

A '''BEHAVIOR''' ’s "timescale" can usually be understood as the time for the
behavior to push, twist, or otherwise affect the vehicle such that the difference between what it is doing, and
what it is supposed to be doing, has been reduced to 1/e of what it was, where "e" is the natural exponent
(approximately 2.718281828). In other words, it is the timescale for exponential decay toward full compliance to
the desired behavior. When you want the vehicle to be very responsive use a short timescale of one second or
less, and if you want to disable a behavior then set the timescale to a very large number like 300 (5 minutes) or
more. Note, for stability reasons, there is usually a limit to how small a timescale is allowed to be, and is usually
on the order of a tenth of a second. Setting a timescale to zero is safe and is always equivalent to setting it to its
minimum. Any feature with a timescale can be effectively disabled by setting the timescale so large that it would
take them all day to have any effect.

== Setting the Vehicle Type ==

Before any vehicle parameters can be set the vehicle behavior must first be enabled. It is enabled by calling
[[llSetVehicleType]] with any '''VEHICLE_TYPE_*''', except [[VEHICLE_TYPE_NONE]] which will disable the
vehicle. See the {{LSLGC|Vehicle|vehicle types}} constants section for currently available types. More types will be available soon.

Setting the vehicle type is necessary for enabling the vehicle behavior and sets all of the parameters to its default
values. For each vehicle type listed we provide the corresponding equivalent code in long format. Is is important
to realize that the defaults are not the optimal settings for any of these vehicle types and that they will definitely
be changed in the future. Do not rely on these values to be constant until specified.

Should you want to make a unique or experimental vehicle you will still have to enable the vehicle behavior with
one of the default types first, after which you will be able to change any of the parameters or flags within the
allowed ranges.

Setting the vehicle type does not automatically take controls or otherwise move the object. However should you
enable the vehicle behavior while the object is free to move and parked on a hill then it may start to slide away.

We’re looking for new and better default vehicle types. If you think you’ve found a set of parameters that make a
better car, boat, or any other default type of vehicle then you may submit your proposed list of settings to
Andrew Linden via a script or notecard.

== Linear and Angular Deflection ==

A common feature of real vehicles is their tendency to move along "preferred axes of motion". That is, due to
their wheels, wings, shape, or method of propulsion they tend to push or redirect themselves along axes that are
static in the vehicle’s local frame. This general feature defines a class of vehicles and included in this category a
common dart is a "vehicle": it has fins in the back such that if it were to tumble in the air it would eventually
align itself to move point-forward -- we’ll call this alignment effect angular deflection.

A wheeled craft exhibits a different effect: when a skateboard is pushed in some direction it will tend to redirect
the resultant motion along that which it is free to roll -- we’ll call this effect linear deflection.

So a typical Second Life vehicle is an object that exhibits linear and/or angular deflection along the "preferential
axes of motion". The default preferential axes of motion are the local x- (at), y- (left), and z- (up) axes of the
local frame of the vehicle’s root primitive. The deflection behaviors relate to the x-axis (at): linear deflection will
tend to rotate its velocity until it points along it’s positive local x-axis while the angular deflection will tend to
reorient the vehicle such that it’s x-axis points in the direction that it is moving. The other axes are relevant to
vehicle behaviors that are described later, such as the vertical attractor which tries to keep a vehicle’s local z-axis
pointed toward the world z-axis (up). The vehicle axes can be rotated relative to the object’s actual local axes by
using the [[VEHICLE_REFERENCE_FRAME]] parameter, however that is an advanced feature and is covered in
detail in a later section of these documents.

Depending on the vehicle it might be desirable to have lots of linear and/or angular delfection or not. The speed
of the deflections are controlled by setting the relevant parameters using the[[llSetVehicleFloatParam]] script call.

Each variety of deflection has a "timescale" parameter that determines how quickly a full deflection happens.

Basically the timescale it the time coefficient for exponential decay toward full deflection. So, a vehicle that
deflects quickly should have a small timescale. For instance, a typical dart might have a angular deflection
timescale of a couple of seconds but a linear deflection of several seconds; it will tend to reorient itself before it
changes direction. To set the deflection timescales of a dart you might use the lines below:
<pre>
llSetVehicleFloatParam(VEHICLE_ANGULAR_DEFLECTION_TIMESCALE, 2.0);
llSetVehicleFloatParam(VEHICLE_LINEAR_DEFLECTION_TIMESCALE, 6.0);
</pre>
Each variety of deflection has an "efficiency" parameter that is a slider between 0.0 and 1.0. Unlike the other
efficiency parameter of other vehicle behaviors, the deflection efficiencies do not slide between "bouncy" and
"damped", but instead slide from "no deflection whatsoever" (0.0) to "maximum deflection" (1.0). That is, they
behave much like the deflection timescales, however they are normalized to the range between 0.0 and 1.0.

== Moving the Vehicle ==

Once enabled, a vehicle can be pushed and rotated by external forces and/or from script calls such as
[[llApplyImpulse]], however linear and angular motors have been built in to make motion easier and smoother.
Their directions can be set using the[[llSetVehicleVectorParam]] call. For example, to make the vehicle try to move
at 5 meters/second along its local x-axis (the default look-at direction) you would put the following line in your
script:
<pre>
llSetVehicleVectorParam(VEHICLE_LINEAR_MOTOR_DIRECTION, <5, 0, 0>);
</pre>
To prevent vehicles from moving too fast the magnitude of the linear motor is clamped to be no larger than about
30 meters/second. Note that this is clamped mostly because of limitations of the physics engine, and may be
raised later when possible.

Setting the motor speed is not enough to enable all interesting vehicles. For example, some will want a car that
immediately gets up to the speed they want, while others will want a boat that slowly climbs up to its maximum
velocity. To control this effect you can use the [[VEHICLE_LINEAR_MOTOR_TIMESCALE]] parameter.

Basically the "timescale" of a motor is the time constant for the vehicle to exponentially accelerate toward its full
speed.

What would happen if you were to accidentally set the vehicle’s linear velocity to maximum possible speed and
then let go? It would run away and never stop, right? Not necessarily: an automatic "motor decay" has been built
in such that all motors will gradually decrease their effectiveness after being set.

Each time the linear motor’s vector is set its "grip" immediately starts to decay exponentially with a timescale
determined by the [[VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE]], such that after enough time the
motor ceases to have any effect. This decay timescale serves two purposes. First, since it cannot be set longer
than 120 seconds, and is always enabled it gaurantees that a vehicle will not push itself about forever in the
absence of active control (from keyboard commands or some logic loop in the script). Second, it can be used to
push some vehicles around using a simple impulse model. That is, rather than setting the motor "on" or "off"
depending on whether a particular key is pressed "down" or "up" the decay timescale can be set short and the
motor can be set "on" whenever the key transitions from "up" to "down" and allowed to automatically decay.

Since the motor’s effectiveness is reset whenever the motor’s vector is set, then setting it to a vector of length
zero is different from allowing it to decay completely. The first case will cause the vehicle to try to reach zero
velocity, while the second will leave the motor impotent.

The two motor timescales have very similar names, but have different effects, so try not to get them confused.

::[[VEHICLE_LINEAR_MOTOR_TIMESCALE]] is the time for motor to "win", and

::[[VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE]] is the time for the motor’s "effectiveness" to decay
toward zero. If you set one when you think you are changing the other you will have frustrating results. Also, if
the motor’s decay timescale is shorter than the regular timescale, then the effective magnitude of the motor
vector will be diminished.

== Steering the Vehicle ==

Much like the linear motor, there is also an angular motor that is always on, and whose direction and magnitude
can be set. For example, to make a vehicle turn at 5 degrees/sec around it’s local z-axis (its up-axis) you might
add the following lines to its script:
<pre>
vector angular_velocity = <0, 0, 5 * PI / 180>;
llSetVehicleVectorParam(VEHICLE_ANGULAR_MOTOR_DIRECTION, angular_velocity);
</pre>
The magnitude of the angular motor is capped to be no more than two rotations per second (4*PI radians/sec).

Also like the linear motor it has an efficiency parameter, [[VEHICLE_ANGULAR_MOTOR_TIMESCALE]], and a
motor decay parameter, [[VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE]], which is set to themaximum possible value of 120 seconds by default.

When steering a vehicle you probably don’t want it to turn very far or for very long. One way to do it using the
angular motor would be to leave the decay timescale long, enable a significant amount of angular friction (to
quickly slow the vehicle down when the motor is turned off) then set the angular motor to a large vector on a key
press, and set it to zero when the key is released. Another way to do it is to set the
[[VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE]] to a short value and push the vehicle about with a
more impulsive method that sets the motor fast on a key press down (and optionally setting the motor to zero on
a key up) relying on the automatic exponential decay of the motor’s effectiveness rather than a constant angular
friction.

Setting the angular motor to zero magnitude is different from allowing it to decay. When the motor completely
decays it no longer affects the motion of the vehicle, however setting it to zero will reset the "grip" of the vehicle
and will make the vehicle try to achieve zero angular velocity.

For some vehicles it will be possible to use the "banking feature" to turn. "Banking" is what airplanes and
motorcycles do when they turn. When a banking vehicle twists about its roll-axis there is a resultant spin around
its yaw-axis. Banking is only available when using the "vertical attractor" which is described below.

== The Vertical Attractor ==

Some vehicles, like boats, should always keep their up-side up. This can be done by enabling the "vertical
attractor" behavior that springs the vehicle’s local z-axis to the world z-axis (a.k.a. "up"). To take advantage of
this feature you would set the [[VEHICLE_VERTICAL_ATTRACTION_TIMESCALE]] to control the period of
the spring frequency, and then set the [[VEHICLE_VERTICAL_ATTRACTION_EFFICIENCY]] to control the
damping. An efficiency of 0.0 will cause the spring to wobble around its equilibrium, while an efficiency of 1.0
will cause the spring to reach it’s equilibrium with exponential decay.
<pre>
llSetVehicleVectorParam(VEHICLE_VERTICAL_ATTRACTION_TIMESCALE, 4.0);
llSetVehicleVectorParam(VEHICLE_VERTICAL_ATTRACTION_EFFICIENCY, 0.5);
</pre>
The vertical attractor is disabled by setting its timescale to anything larger than 300 seconds.

Note that by default the vertical attractor will prevent the vehicle from diving and climbing. So, if you wanted to
make a airplane you would probably want to unlock the attractor around the pitch axis by setting the
[[VEHICLE_FLAG_LIMIT_ROLL_ONLY]] bit:
<pre>
llSetVehicleFlags(VEHICLE_FLAG_LIMIT_ROLL_ONLY);
</pre>

== Banking ==

The vertical attractor feature must be enabled in order for the banking behavior to function. The way banking
works is this: a rotation around the vehicle’s roll-axis will produce a angular velocity around the yaw-axis,
causing the vehicle to turn. The magnitude of the yaw effect will be proportional to the

::[[VEHICLE_BANKING_COEF]], the angle of the roll rotation, and sometimes the vehicle’s velocity along it’s
preferred axis of motion.

::The [[VEHICLE_BANKING_COEF]] can vary between -1 and +1. When it’s positive then any positive rotation (by
the right-hand rule) about the roll-axis will effect a (negative) torque around the yaw-axis, making it turn to the
right -- that is the vehicle will lean into the turn, which is how real airplanes and motorcycle’s work. Negating
the banking coefficient will make it so that the vehicle leans to the outside of the turn (not very "physical" but
might allow interesting vehicles so why not?).

::The [[VEHICLE_BANKING_MIX]] is a fake (i.e. non-physical) parameter that is useful for making banking
vehicles do what you want rather than what the laws of physics allow. For example, consider a real motorcycle...
it must be moving forward in order for it to turn while banking, however video-game motorcycles are often
configured to turn in place when at a dead stop -- because they’re often easier to control that way using the
limited interface of the keyboard or game controller. The [[VEHICLE_BANKING_MIX]] enables combinations of
both realistic and non-realistic banking by fuctioning as a slider between a banking that is correspondingly
totally static (0.0) and totally dynamic (1.0). By "static" we mean that the banking effect depends only on the
vehicle’s rotation about it’s roll-axis compared to "dynamic" where the banking is also proportional to it’s
velocity along it’s roll-axis. Finding the best value of the "mixture" will probably require trial and error.

The time it takes for the banking behavior to defeat a pre-existing angular velocity about the world z-axis is
determined by the [[VEHICLE_BANKING_TIMESCALE]]. So if you want the vehicle to bank quickly then give it
a banking timescale of about a second or less, otherwise you can make a sluggish vehicle by giving it a timescale
of several seconds.

== Friction Timescales ==

[[VEHICLE_LINEAR_FRICTION_TIMESCALE]] is a vector parameter that defines the timescales for the vehicle
to come to a complete stop along the three local axes of the vehicle’s reference frame. The timescale along each
axis is independent of the others. For example, a sliding ground car would probably have very little friction along
its x- and z-axes (so it can easily slide forward and fall down) while there would usually significant friction along
its y-axis:
<pre>
llSetVehicleVectorParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, <1000, 1000, 3>);
</pre>
Remember that a longer timescale corresponds to a weaker friction, hence to effectively disable all linear friction
you would set all of the timescales to large values.

Setting the linear friction as a scalar is allowed, and has the effect of setting all of the timescales to the same
value. Both code snippets below are equivalent, and both make friction negligible:
<pre>
// set all linear friction timescales to 1000
llSetVehicleVectorParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, <1000, 1000, 1000>);
// same as above, but fewer characters
llSetVehicleFloatParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, 1000);
</pre>
/[[VEHICLE_ANGULAR_FRICTION_TIMESCALE]] is also a vector parameter that defines the timescales for the
vehicle to stop rotating about the x-, y-, and z-axes, and are set and disabled in the same way as the linear friction.

== Buoyancy ==

The vehicle has a built-in buoyancy feature that is independent of the[[llSetBuoyancy]] call. It is recommended that
the two buoyancies do not mix! To make a vehicle buoyant, set the [[VEHICLE_BUOYANCY]] parameter to
something between 0.0 (no buoyancy whatsoever) to 1.0 (full anti-gravity).

The buoyancy behavior is independent of hover, however in order for hover to work without a large offset of the
[[VEHICLE_HOVER_HEIGHT]], the [[VEHICLE_BUOYANCY]] should be set to 1.0.

It is not recommended that you mix vehicle buoyancy with the[[llSetBuoyancy]] script call. It would probably
cause the object to fly up into space.

== Hover ==

The hover behavior is enabled by setting the [[VEHICLE_HOVER_TIMESCALE]] to a value less than 300
seconds; larger timescales totally disable it. Most vehicles will work best with short hover timescales of a few
seconds or less. The shorter the timescale, the faster the vehicle will slave to is target height. Note, that if the
values of [[VEHICLE_LINEAR_FRICTION_TIMESCALE]] may affect the speed of the hover.

Hover is independent of buoyancy, however the [[VEHICLE_BUOYANCY]] should be set to 1.0, otherwise the
vehicle will not lift itself off of the ground until the [[VEHICLE_HOVER_HEIGHT]] is made large enough to
counter the acceleration of gravity, and the vehicle will never float all the way to its target height.

The [[VEHICLE_HOVER_EFFICIENCY]] can be thought of as a slider between bouncy (0.0) and smoothed (1.0).

When in the bouncy range the vehicle will tend to hover a little lower than its target height and the
[[VEHICLE_HOVER_TIMESCALE]] will be approximately the oscillation period of the bounce (the real period
will tend to be a little longer than the timescale).

For performance reasons, until improvements are made to the Second Life physics engine the vehicles can only
hover over the terrain and water, so they will not be able to hover above objects made out of primitives, such as
bridges and houses. By default the hover behavior will float over terrain and water, however this can be changed
by setting some flags:

If you wanted to make a boat you should set the [[VEHICLE_HOVER_WATER_ONLY]] flag, or if you wanted to
drive a hover tank under water you would use the [[VEHICLE_HOVER_TERRAIN_ONLY]] flag instead. Finally,
if you wanted to make a submarine or a balloon you would use the [[VEHICLE_HOVER_GLOBAL_HEIGHT]].

Note that the flags are independent of each other and that setting two contradictory flags will have undefined
behavor. The flags are set using the script call[[llSetVehicleFlags()]].

The [[VEHICLE_HOVER_HEIGHT]] determines how high the vehicle will hover over the terrain and/or water, or
the global height, and has a maximum value of 100 meters. Note that for hovering purposes the "center" of the
vehicle is its "center of mass" which is not always obvious to the untrained eye, and it changes when avatar’s sit
on the vehicle.

== Reference Frame ==

The vehicle relies on the x- (at), y- (left), and z- (up) axes in order to figure out which way it preferres to move
and which end is up. By default these axes are identical to the local axes of the root primitive of the object,
however this means that the vehicle’s root primitive must, by default, be oriented to agree with the designed at,
left, and up axes of the vehicle. But, what if the vehicle object was already pre-built with the root primitive in
some non-trivial orientation relative to where the vehicle as a whole should move? This is where the

[[VEHICLE_REFERENCE_FRAME]] parameter becomes useful; the vehicle’s axes can be arbitrarily reoriented
by setting this parameter.

As an example, suppose you had built a rocket out of a big cylinder, a cone for the nose, and some stretched cut
boxes for the fins, then linked them all together with the cylinder as the root primitive. Ideally the rocket would
move nose-first, however the cylinder’s axis of symmetry is its local z-axis while the default "at-axis" of the
vehicle, the axis it will want to deflect to forward under angular deflection, is the local x-axis and points out from
the curved surface of the cylinder. The script code below will rotate the vehicle’s axes such that the local z-axis
becomes the "at-axis" and the local negative x-axis becomes the "up-axis":
<pre>
// rotate the vehicle frame -PI/2 about the local y-axis (left-axis)
rotation rot =llEuler2Rot(0, PI/2, 0);
llSetVehicleRotationParam(VEHICLE_REFERENCE_FRAME, rot);
</pre>
Another example of how the reference frame parameter could be used is to consider flying craft that uses the
vertical attractor for stability during flying but wants to use VTOL (vertical takeoff and landing). During flight
the craft’s dorsal axis should point up, but during landing its nose-axis should be up. To land the vehicle: while
the vertical attractor is in effect, rotate the existing [[VEHICLE_REFERENCE_FRAME]] by +PI/2 about the
left-axis, then the vehicle will pitch up such that it’s nose points toward the sky. The vehicle could be allowed to
fall to the landing pad under friction, or a decreasing hover effect.

Catagories: {{LSLC|Vehicle|Tutorial}} {{LSLC|Tutorials|Vehicle}}
{{LSLGC|Vehicle}}

LlRemoveVehicleFlags

2007-09-26T21:50:26Z

Ralph Doctorow:

{{LSL_Function
|func_id=237|func_sleep=0.0|func_energy=10.0
|func=llRemoveVehicleFlags
|p1_type=integer|p1_name=flags|p1_desc=mask of VEHICLE_FLAG_* flags
|func_footnote|func_desc=Removes the enabled bits in 'flags'
|return_text
|spec
|caveats
|constants={{LSL Constants/Vehicle Flags}}
|examples
|helpers
|also_functions={{LSL DefineRow||[[llSetVehicleFlags]]|Sets vehicle flags}}
|also_tests
|also_events
|also_articles=[[Linden Vehicle Tutorial]]
|notes
|deprecated
|cat1=Vehicle
|cat2
|cat3
|cat4
}}

LlSetVehicleFlags

2007-09-26T21:48:53Z

Ralph Doctorow:

{{LSL_Function
|func_id=236|func_sleep=0.0|func_energy=10.0
|func=llSetVehicleFlags
|p1_type=integer|p1_name=flags|p1_desc=mask of VEHICLE_FLAG_* flags
|func_footnote
|func_desc=Sets the enabled bits in '''flags'''
|return_text
|spec
|caveats
|constants={{LSL Constants/Vehicle Flags}}
|examples
|helpers
|also_functions={{LSL DefineRow||[[llRemoveVehicleFlags]]|Remove vehicle flags}}
|also_events
|also_tests
|also_articles=[[Linden Vehicle Tutorial]]
|notes
|permission
|negative_index
|sort=SetVehicleFlags
|cat1=Vehicle
|cat2
|cat3
|cat4
}}

LlSetVehicleFloatParam

2007-09-26T21:48:31Z

Ralph Doctorow:

{{LSL_Function
|func_id=233|func_sleep=0.0|func_energy=10.0
|func=llSetVehicleFloatParam
|p1_type=integer|p1_name=param|p1_desc=VEHICLE_* flag
|p2_type=float|p2_name=value
|func_footnote
|func_desc=Sets the vehicle float parameter '''param''' to '''value'''.
|return_text
|spec
|caveats
|constants={{LSL Constants/Vehicle|type=float}}
|examples
|helpers
|also_functions=
{{LSL DefineRow||{{LSLG|llSetVehicleRotationParam}}|Sets a vehicle rotation parameter}}
{{LSL DefineRow||{{LSLG|llSetVehicleVectorParam}}|Sets a vehicle vector parameter}}
|also_events
|also_tests
|also_articles=[[Linden Vehicle Tutorial]]
|notes
|permission
|negative_index
|sort=SetVehicleFloatParam
|cat1=Vehicle
|cat2
|cat3
|cat4
}}

LlSetVehicleRotationParam

2007-09-26T21:44:50Z

Ralph Doctorow:

{{LSL_Function
|func_id=235|func_sleep=0.0|func_energy=10.0
|func=llSetVehicleRotationParam
|p1_type=integer|p1_name=param|p1_desc=VEHICLE_* flag
|p2_type=rotation|p2_name=rot
|func_footnote
|func_desc=Sets the vehicle rotation parameter '''param''' to '''rot'''.
|return_text
|spec
|caveats
|constants={{LSL Constants/Vehicle|type=rotation}}
|examples
|helpers
|also_functions={{LSL DefineRow||{{LSLG|llSetVehicleFloatParam}}|Sets a vehicle float parameter}}
{{LSL DefineRow||{{LSLG|llSetVehicleVectorParam}}|Sets a vehicle vector parmeter}}
|also_events
|also_tests
|also_articles=[[Linden Vehicle Tutorial]]
|notes
|permission
|negative_index
|sort=SetVehicleRotationParam
|cat1=Vehicle
|cat2
|cat3
|cat4
}}

Linden Vehicle Tutorial

2007-09-26T21:44:23Z

Ralph Doctorow:

{{LSL_Header}}

== Vehicles{{LSLC|Vehicle|Tutorial}} ==

Vehicles are a new feature now available for use through LSL. This chapter will cover the basics of how vehicles
work, the terms used when describing vehicles, and a more thorough examination of the api available.

There are several ways to make scripted objects move themselves around. One way is to turn the object into a
"vehicle". This feature is versatile enough to make things that slide, hover, fly, and float. Some of the behaviors
that can be enabled are:

*deflection of linear and angular velocity to preferred axis of motion
*asymmetric linear and angular friction
*hovering over terrain/water or at a global height
*banking on turns
*linear and angular motor for push and turning

== Overview ==

Each scripted object can have one vehicle behavior that is configurable through the[[llSetVehicleType]],
llSetVehicleFloatParam,llSetVehicleVectorParam,llSetVehicleRotationParam,llSetVehicleFlags, and
llRemoveVehicleFlags library calls.

These script calls are described in more detail below, but the important thing to notice here is that the vehicle
behavior has several parameters that can be adjusted to change how the vehicle handles. Depending on the values
chosen the vehicle can veer like a boat in water, or ride like a sled on rails.

Setting the vehicle flags allow you to make exceptions to some default behaviors. Some of these flags only have
an effect when certain behaviors are enabled. For example, the [[VEHICLE_FLAG_HOVER_WATER_ONLY]] will
make the vehicle ignore the height of the terrain, however it only makes a difference if the vehicle is hovering.

== Warnings ==

Vehicles are new in Second Life 1.1 and some of the details of their behavior may be changed as necessary to
ensure stability and user safety. In particular, many of the limits and defaults described in the appendices will
probably change and should not be relied upon in the long term.

It is not recommended that you mix vehicle behavior with some of the other script calls that provide impulse and
forces to the object, especially[[llSetBuoyancy]],[[llSetForce]],[[llSetTorque]], and[[llSetHoverHeight]].

While the following methods probably don’t cause any instabilities, their behavior may conflict with vehicles
and cause undesired and/or inconsistent results, so use[[llLookAt]],[[llRotLookAt]],[[llMoveToTarget]], and
[[llTargetOmega]] at your own risk.

If you think you have found a bug relating to how vehicle’s work, one way to submit the problem is to give a
copy of the vehicle and script to Andrew Linden with comments or a notecard describing the problem. Please
name all submissions "Bugged Vehicle XX" where XX are your Second Life initials. The vehicle and script will
be examined at the earliest convenience.

== Definitions ==

The terms "roll", "pitch", and "yaw" are often used to describe the modes of rotations that can happen to a
airplane or boat. They correspond to rotations about the local x-, y-, and z-axis respectively.
z-axis .

http://en.wikipedia.org/wiki/Tait-Bryan_angles

The right-hand-rule, often introduced in beginning physics courses, is used to define the direction of positive
rotation about any axis. As an example of how to use the right hand rule, consider a positive rotation about the
roll axis. To help visualize how such a rotation would move the airplane, place your right thumb parallel to the
plane’s roll-axis such that the thumb points in the positive x-direction, then curl the four fingers into a fist. Your
fingers will be pointing in the direction that the plane will spin.

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

Many of the parameters that control a vehicle’s behavior are of the form:

VEHICLE_'''BEHAVIOR'''_TIMESCALE

A '''BEHAVIOR''' ’s "timescale" can usually be understood as the time for the
behavior to push, twist, or otherwise affect the vehicle such that the difference between what it is doing, and
what it is supposed to be doing, has been reduced to 1/e of what it was, where "e" is the natural exponent
(approximately 2.718281828). In other words, it is the timescale for exponential decay toward full compliance to
the desired behavior. When you want the vehicle to be very responsive use a short timescale of one second or
less, and if you want to disable a behavior then set the timescale to a very large number like 300 (5 minutes) or
more. Note, for stability reasons, there is usually a limit to how small a timescale is allowed to be, and is usually
on the order of a tenth of a second. Setting a timescale to zero is safe and is always equivalent to setting it to its
minimum. Any feature with a timescale can be effectively disabled by setting the timescale so large that it would
take them all day to have any effect.

== Setting the Vehicle Type ==

Before any vehicle parameters can be set the vehicle behavior must first be enabled. It is enabled by calling
[[llSetVehicleType]] with any '''VEHICLE_TYPE_*''', except [[VEHICLE_TYPE_NONE]] which will disable the
vehicle. See the {{LSLGC|Vehicle|vehicle types}} constants section for currently available types. More types will be available soon.

Setting the vehicle type is necessary for enabling the vehicle behavior and sets all of the parameters to its default
values. For each vehicle type listed we provide the corresponding equivalent code in long format. Is is important
to realize that the defaults are not the optimal settings for any of these vehicle types and that they will definitely
be changed in the future. Do not rely on these values to be constant until specified.

Should you want to make a unique or experimental vehicle you will still have to enable the vehicle behavior with
one of the default types first, after which you will be able to change any of the parameters or flags within the
allowed ranges.

Setting the vehicle type does not automatically take controls or otherwise move the object. However should you
enable the vehicle behavior while the object is free to move and parked on a hill then it may start to slide away.

We’re looking for new and better default vehicle types. If you think you’ve found a set of parameters that make a
better car, boat, or any other default type of vehicle then you may submit your proposed list of settings to
Andrew Linden via a script or notecard.

== Linear and Angular Deflection ==

A common feature of real vehicles is their tendency to move along "preferred axes of motion". That is, due to
their wheels, wings, shape, or method of propulsion they tend to push or redirect themselves along axes that are
static in the vehicle’s local frame. This general feature defines a class of vehicles and included in this category a
common dart is a "vehicle": it has fins in the back such that if it were to tumble in the air it would eventually
align itself to move point-forward -- we’ll call this alignment effect angular deflection.

A wheeled craft exhibits a different effect: when a skateboard is pushed in some direction it will tend to redirect
the resultant motion along that which it is free to roll -- we’ll call this effect linear deflection.

So a typical Second Life vehicle is an object that exhibits linear and/or angular deflection along the "preferential
axes of motion". The default preferential axes of motion are the local x- (at), y- (left), and z- (up) axes of the
local frame of the vehicle’s root primitive. The deflection behaviors relate to the x-axis (at): linear deflection will
tend to rotate its velocity until it points along it’s positive local x-axis while the angular deflection will tend to
reorient the vehicle such that it’s x-axis points in the direction that it is moving. The other axes are relevant to
vehicle behaviors that are described later, such as the vertical attractor which tries to keep a vehicle’s local z-axis
pointed toward the world z-axis (up). The vehicle axes can be rotated relative to the object’s actual local axes by
using the [[VEHICLE_REFERENCE_FRAME]] parameter, however that is an advanced feature and is covered in
detail in a later section of these documents.

Depending on the vehicle it might be desirable to have lots of linear and/or angular delfection or not. The speed
of the deflections are controlled by setting the relevant parameters using the[[llSetVehicleFloatParam]] script call.

Each variety of deflection has a "timescale" parameter that determines how quickly a full deflection happens.

Basically the timescale it the time coefficient for exponential decay toward full deflection. So, a vehicle that
deflects quickly should have a small timescale. For instance, a typical dart might have a angular deflection
timescale of a couple of seconds but a linear deflection of several seconds; it will tend to reorient itself before it
changes direction. To set the deflection timescales of a dart you might use the lines below:
<pre>
llSetVehicleFloatParam(VEHICLE_ANGULAR_DEFLECTION_TIMESCALE, 2.0);
llSetVehicleFloatParam(VEHICLE_LINEAR_DEFLECTION_TIMESCALE, 6.0);
</pre>
Each variety of deflection has an "efficiency" parameter that is a slider between 0.0 and 1.0. Unlike the other
efficiency parameter of other vehicle behaviors, the deflection efficiencies do not slide between "bouncy" and
"damped", but instead slide from "no deflection whatsoever" (0.0) to "maximum deflection" (1.0). That is, they
behave much like the deflection timescales, however they are normalized to the range between 0.0 and 1.0.

== Moving the Vehicle ==

Once enabled, a vehicle can be pushed and rotated by external forces and/or from script calls such as
[[llApplyImpulse]], however linear and angular motors have been built in to make motion easier and smoother.
Their directions can be set using the[[llSetVehicleVectorParam]] call. For example, to make the vehicle try to move
at 5 meters/second along its local x-axis (the default look-at direction) you would put the following line in your
script:
<pre>
llSetVehicleVectorParam(VEHICLE_LINEAR_MOTOR_DIRECTION, <5, 0, 0>);
</pre>
To prevent vehicles from moving too fast the magnitude of the linear motor is clamped to be no larger than about
30 meters/second. Note that this is clamped mostly because of limitations of the physics engine, and may be
raised later when possible.

Setting the motor speed is not enough to enable all interesting vehicles. For example, some will want a car that
immediately gets up to the speed they want, while others will want a boat that slowly climbs up to its maximum
velocity. To control this effect you can use the [[VEHICLE_LINEAR_MOTOR_TIMESCALE]] parameter.

Basically the "timescale" of a motor is the time constant for the vehicle to exponentially accelerate toward its full
speed.

What would happen if you were to accidentally set the vehicle’s linear velocity to maximum possible speed and
then let go? It would run away and never stop, right? Not necessarily: an automatic "motor decay" has been built
in such that all motors will gradually decrease their effectiveness after being set.

Each time the linear motor’s vector is set its "grip" immediately starts to decay exponentially with a timescale
determined by the [[VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE]], such that after enough time the
motor ceases to have any effect. This decay timescale serves two purposes. First, since it cannot be set longer
than 120 seconds, and is always enabled it gaurantees that a vehicle will not push itself about forever in the
absence of active control (from keyboard commands or some logic loop in the script). Second, it can be used to
push some vehicles around using a simple impulse model. That is, rather than setting the motor "on" or "off"
depending on whether a particular key is pressed "down" or "up" the decay timescale can be set short and the
motor can be set "on" whenever the key transitions from "up" to "down" and allowed to automatically decay.

Since the motor’s effectiveness is reset whenever the motor’s vector is set, then setting it to a vector of length
zero is different from allowing it to decay completely. The first case will cause the vehicle to try to reach zero
velocity, while the second will leave the motor impotent.

The two motor timescales have very similar names, but have different effects, so try not to get them confused.

::[[VEHICLE_LINEAR_MOTOR_TIMESCALE]] is the time for motor to "win", and

::[[VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE]] is the time for the motor’s "effectiveness" to decay
toward zero. If you set one when you think you are changing the other you will have frustrating results. Also, if
the motor’s decay timescale is shorter than the regular timescale, then the effective magnitude of the motor
vector will be diminished.

== Steering the Vehicle ==

Much like the linear motor, there is also an angular motor that is always on, and whose direction and magnitude
can be set. For example, to make a vehicle turn at 5 degrees/sec around it’s local z-axis (its up-axis) you might
add the following lines to its script:
<pre>
vector angular_velocity = <0, 0, 5 * PI / 180>;
llSetVehicleVectorParam(VEHICLE_ANGULAR_MOTOR_DIRECTION, angular_velocity);
</pre>
The magnitude of the angular motor is capped to be no more than two rotations per second (4*PI radians/sec).

Also like the linear motor it has an efficiency parameter, [[VEHICLE_ANGULAR_MOTOR_TIMESCALE]], and a
motor decay parameter, [[VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE]], which is set to themaximum possible value of 120 seconds by default.

When steering a vehicle you probably don’t want it to turn very far or for very long. One way to do it using the
angular motor would be to leave the decay timescale long, enable a significant amount of angular friction (to
quickly slow the vehicle down when the motor is turned off) then set the angular motor to a large vector on a key
press, and set it to zero when the key is released. Another way to do it is to set the
[[VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE]] to a short value and push the vehicle about with a
more impulsive method that sets the motor fast on a key press down (and optionally setting the motor to zero on
a key up) relying on the automatic exponential decay of the motor’s effectiveness rather than a constant angular
friction.

Setting the angular motor to zero magnitude is different from allowing it to decay. When the motor completely
decays it no longer affects the motion of the vehicle, however setting it to zero will reset the "grip" of the vehicle
and will make the vehicle try to achieve zero angular velocity.

For some vehicles it will be possible to use the "banking feature" to turn. "Banking" is what airplanes and
motorcycles do when they turn. When a banking vehicle twists about its roll-axis there is a resultant spin around
its yaw-axis. Banking is only available when using the "vertical attractor" which is described below.

== The Vertical Attractor ==

Some vehicles, like boats, should always keep their up-side up. This can be done by enabling the "vertical
attractor" behavior that springs the vehicle’s local z-axis to the world z-axis (a.k.a. "up"). To take advantage of
this feature you would set the [[VEHICLE_VERTICAL_ATTRACTION_TIMESCALE]] to control the period of
the spring frequency, and then set the [[VEHICLE_VERTICAL_ATTRACTION_EFFICIENCY]] to control the
damping. An efficiency of 0.0 will cause the spring to wobble around its equilibrium, while an efficiency of 1.0
will cause the spring to reach it’s equilibrium with exponential decay.
<pre>
llSetVehicleVectorParam(VEHICLE_VERTICAL_ATTRACTION_TIMESCALE, 4.0);
llSetVehicleVectorParam(VEHICLE_VERTICAL_ATTRACTION_EFFICIENCY, 0.5);
</pre>
The vertical attractor is disabled by setting its timescale to anything larger than 300 seconds.

Note that by default the vertical attractor will prevent the vehicle from diving and climbing. So, if you wanted to
make a airplane you would probably want to unlock the attractor around the pitch axis by setting the
[[VEHICLE_FLAG_LIMIT_ROLL_ONLY]] bit:
<pre>
llSetVehicleFlags(VEHICLE_FLAG_LIMIT_ROLL_ONLY);
</pre>

== Banking ==

The vertical attractor feature must be enabled in order for the banking behavior to function. The way banking
works is this: a rotation around the vehicle’s roll-axis will produce a angular velocity around the yaw-axis,
causing the vehicle to turn. The magnitude of the yaw effect will be proportional to the

::[[VEHICLE_BANKING_COEF]], the angle of the roll rotation, and sometimes the vehicle’s velocity along it’s
preferred axis of motion.

::The [[VEHICLE_BANKING_COEF]] can vary between -1 and +1. When it’s positive then any positive rotation (by
the right-hand rule) about the roll-axis will effect a (negative) torque around the yaw-axis, making it turn to the
right -- that is the vehicle will lean into the turn, which is how real airplanes and motorcycle’s work. Negating
the banking coefficient will make it so that the vehicle leans to the outside of the turn (not very "physical" but
might allow interesting vehicles so why not?).

::The [[VEHICLE_BANKING_MIX]] is a fake (i.e. non-physical) parameter that is useful for making banking
vehicles do what you want rather than what the laws of physics allow. For example, consider a real motorcycle...
it must be moving forward in order for it to turn while banking, however video-game motorcycles are often
configured to turn in place when at a dead stop -- because they’re often easier to control that way using the
limited interface of the keyboard or game controller. The [[VEHICLE_BANKING_MIX]] enables combinations of
both realistic and non-realistic banking by fuctioning as a slider between a banking that is correspondingly
totally static (0.0) and totally dynamic (1.0). By "static" we mean that the banking effect depends only on the
vehicle’s rotation about it’s roll-axis compared to "dynamic" where the banking is also proportional to it’s
velocity along it’s roll-axis. Finding the best value of the "mixture" will probably require trial and error.

The time it takes for the banking behavior to defeat a pre-existing angular velocity about the world z-axis is
determined by the [[VEHICLE_BANKING_TIMESCALE]]. So if you want the vehicle to bank quickly then give it
a banking timescale of about a second or less, otherwise you can make a sluggish vehicle by giving it a timescale
of several seconds.

== Friction Timescales ==

[[VEHICLE_LINEAR_FRICTION_TIMESCALE]] is a vector parameter that defines the timescales for the vehicle
to come to a complete stop along the three local axes of the vehicle’s reference frame. The timescale along each
axis is independent of the others. For example, a sliding ground car would probably have very little friction along
its x- and z-axes (so it can easily slide forward and fall down) while there would usually significant friction along
its y-axis:
<pre>
llSetVehicleVectorParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, <1000, 1000, 3>);
</pre>
Remember that a longer timescale corresponds to a weaker friction, hence to effectively disable all linear friction
you would set all of the timescales to large values.

Setting the linear friction as a scalar is allowed, and has the effect of setting all of the timescales to the same
value. Both code snippets below are equivalent, and both make friction negligible:
<pre>
// set all linear friction timescales to 1000
llSetVehicleVectorParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, <1000, 1000, 1000>);
// same as above, but fewer characters
llSetVehicleFloatParam(VEHICLE_LINEAR_FRICTION_TIMESCALE, 1000);
</pre>
/[[VEHICLE_ANGULAR_FRICTION_TIMESCALE]] is also a vector parameter that defines the timescales for the
vehicle to stop rotating about the x-, y-, and z-axes, and are set and disabled in the same way as the linear friction.

== Buoyancy ==

The vehicle has a built-in buoyancy feature that is independent of the[[llSetBuoyancy]] call. It is recommended that
the two buoyancies do not mix! To make a vehicle buoyant, set the [[VEHICLE_BUOYANCY]] parameter to
something between 0.0 (no buoyancy whatsoever) to 1.0 (full anti-gravity).

The buoyancy behavior is independent of hover, however in order for hover to work without a large offset of the
[[VEHICLE_HOVER_HEIGHT]], the [[VEHICLE_BUOYANCY]] should be set to 1.0.

It is not recommended that you mix vehicle buoyancy with the[[llSetBuoyancy]] script call. It would probably
cause the object to fly up into space.

== Hover ==

The hover behavior is enabled by setting the [[VEHICLE_HOVER_TIMESCALE]] to a value less than 300
seconds; larger timescales totally disable it. Most vehicles will work best with short hover timescales of a few
seconds or less. The shorter the timescale, the faster the vehicle will slave to is target height. Note, that if the
values of [[VEHICLE_LINEAR_FRICTION_TIMESCALE]] may affect the speed of the hover.

Hover is independent of buoyancy, however the [[VEHICLE_BUOYANCY]] should be set to 1.0, otherwise the
vehicle will not lift itself off of the ground until the [[VEHICLE_HOVER_HEIGHT]] is made large enough to
counter the acceleration of gravity, and the vehicle will never float all the way to its target height.

The [[VEHICLE_HOVER_EFFICIENCY]] can be thought of as a slider between bouncy (0.0) and smoothed (1.0).

When in the bouncy range the vehicle will tend to hover a little lower than its target height and the
[[VEHICLE_HOVER_TIMESCALE]] will be approximately the oscillation period of the bounce (the real period
will tend to be a little longer than the timescale).

For performance reasons, until improvements are made to the Second Life physics engine the vehicles can only
hover over the terrain and water, so they will not be able to hover above objects made out of primitives, such as
bridges and houses. By default the hover behavior will float over terrain and water, however this can be changed
by setting some flags:

If you wanted to make a boat you should set the [[VEHICLE_HOVER_WATER_ONLY]] flag, or if you wanted to
drive a hover tank under water you would use the [[VEHICLE_HOVER_TERRAIN_ONLY]] flag instead. Finally,
if you wanted to make a submarine or a balloon you would use the [[VEHICLE_HOVER_GLOBAL_HEIGHT]].

Note that the flags are independent of each other and that setting two contradictory flags will have undefined
behavor. The flags are set using the script call[[llSetVehicleFlags()]].

The [[VEHICLE_HOVER_HEIGHT]] determines how high the vehicle will hover over the terrain and/or water, or
the global height, and has a maximum value of 100 meters. Note that for hovering purposes the "center" of the
vehicle is its "center of mass" which is not always obvious to the untrained eye, and it changes when avatar’s sit
on the vehicle.

== Reference Frame ==

The vehicle relies on the x- (at), y- (left), and z- (up) axes in order to figure out which way it preferres to move
and which end is up. By default these axes are identical to the local axes of the root primitive of the object,
however this means that the vehicle’s root primitive must, by default, be oriented to agree with the designed at,
left, and up axes of the vehicle. But, what if the vehicle object was already pre-built with the root primitive in
some non-trivial orientation relative to where the vehicle as a whole should move? This is where the

[[VEHICLE_REFERENCE_FRAME]] parameter becomes useful; the vehicle’s axes can be arbitrarily reoriented
by setting this parameter.

As an example, suppose you had built a rocket out of a big cylinder, a cone for the nose, and some stretched cut
boxes for the fins, then linked them all together with the cylinder as the root primitive. Ideally the rocket would
move nose-first, however the cylinder’s axis of symmetry is its local z-axis while the default "at-axis" of the
vehicle, the axis it will want to deflect to forward under angular deflection, is the local x-axis and points out from
the curved surface of the cylinder. The script code below will rotate the vehicle’s axes such that the local z-axis
becomes the "at-axis" and the local negative x-axis becomes the "up-axis":
<pre>
// rotate the vehicle frame -PI/2 about the local y-axis (left-axis)
rotation rot =llEuler2Rot(0, PI/2, 0);
llSetVehicleRotationParam(VEHICLE_REFERENCE_FRAME, rot);
</pre>
Another example of how the reference frame parameter could be used is to consider flying craft that uses the
vertical attractor for stability during flying but wants to use VTOL (vertical takeoff and landing). During flight
the craft’s dorsal axis should point up, but during landing its nose-axis should be up. To land the vehicle: while
the vertical attractor is in effect, rotate the existing [[VEHICLE_REFERENCE_FRAME]] by +PI/2 about the
left-axis, then the vehicle will pitch up such that it’s nose points toward the sky. The vehicle could be allowed to
fall to the landing pad under friction, or a decreasing hover effect.

{{LSLGC|Vehicle}}