Second Life Wiki - User contributions [en]

Geometry and Physics VAG

2007-11-18T09:46:53Z

Blubb Dixon: /* Purpose */

: (this is an initial draft so scope and focus are still fairly open. Please add comments to the [[Talk:Geometry and Physics VAG]] if you have slightly different viewpoints so we can try to converge on a common view. This discussion could also expose other similar VAG that are needed in this area --[[User:Burhop Piccard|Burhop Piccard]] 18:38, 16 October 2007 (PDT) )

=Purpose=

The Geometry and Physics Viewpoint Advocacy Group exists to provide input for architectural design that is focused on the (virtual) physical modeling of objects.

See the [[Architecture Working Group]] and the [[Viewpoint Advocacy Groups]] for more information.

=List of concerns addressed by this viewpoint=

Areas of concern addressed by the viewpoint include:
* Describing the physical shape of the object.
* Describing the physical and material properties of the object (mass, color, material, surface texture).
* Efficient comunication of Geometric and physical properties.
* Use of open standards that allow for predictable sharing of data with various systems and tools
** Creation of data using various 3D modeling tools (i.e. Maya, Sketchup, 3D CAD, etc.)
** Reading of data by other software (other VW's, design and modeling tools, physics engines).

=Areas not addressed by this viewpoint=

* Display is not addressed by the viewpoint. This is expected to be a fairly complex topic posibly involving differnet viewers and display technologies. Another VAG is needed for this.

* Specific technologies and applications are not specifically part of this viewpoint. That is, this view is one of open archtecture capable of working with multiple applications and tools.

=Source of Viewpoint=

=Use Cases=

See the [[Architecture Working Group Glossary]] and [[usecase templates]] for more information on creating usecases. One liners are fine (and better than nothing) but more detail will result in a better understanding and a better architecture.

* Direct Creation in Second Life
** Direct Creation from Maya
** Direct Creation from Blender
** Direct Creation from Surface based modelers (please split for specific tools)
** Direct Creation from Solid Modelers (3D Mechanical CAD - please split for specific tools)
** Direct Creation from User built External Tools (i.e. such as showed up with Sculpted Prims)
** Direct Creation with User build in-world tools

* Geometry Import - File Format
** Import from Collada
** Import from OBJ
** Import from JT
** Import from 3DM

* Direct Geometry data transfer between Virtual Worlds
** Geometric asset exchange with other AWG based Asset Servers
** Geometric asset exchange with MPK20 (Sun)
** Geometric asset exchange with (who else wants to exchange data with SL? WOW? Metaverse? )

* Viewer scalability use cases
** High Fidelity graphics with High Power Computer
** Low Fidelity graphics with Low Power CPU (i.e. Cell phone)
** Viewer on low bandwidth computer
** Viewer accessing region with large amount of geometric data

* Physics Use Cases
** Mars (or other planet) virtual world/region support
** Underwater virtual world/region support
** Space (no gravity) based virtual world/region support
** non-unidirectional gravity for the whole sim, eg 'floor is the inside of a sphere'

=Related JIRA Issues=

The following JIRA issues are known problems that this VAG would like to see resolved in any future architecture. The purpose of this list it to avoid problems that exist in the curent architecture. The more typical JIRAs that are more short term in nature or can be resolved by simple code or design change should not be listed here.

* {{JIRA|SVC-73}} Request for subtractive prims and holes
* {{JIRA|VWR-858}} Ability to import 3DM files
* {{JIRA|VWR-1110}} Ability to Import .OBJ Files
* {{JIRA|VWR-1387}} Ability to import .JT files
* {{JIRA|VWR-2527}} Ability to Import .DXF Files
* {{JIRA|SVC-814}} New prim type: Geometric prim
* {{JIRA|VWR-2547}} new prim type: ropes

=Organization=

== Joining ==

Anyone with an interest in this Viewpoint is welcome to join. You should join the [[AW_Groupies]] group in Second Life.

== In world meetings ==

We meet once a week in-world and more if people are available.

Also members are active on the wiki and in the SLDEV mailing list.

Meetings are scheduled via the "[http://www.google.com/calendar/embed?src=pdd5mpktklo89bgmfgi076mcc4%40group.calendar.google.com SL AW Groupies" google calendar]"

===Meeting Agendas===

* TBD

===Chat Logs===

* TBD

== Modeling Techniques used to express viewpoint ==

None decided.

=Architecture (Geometry View)=

See here for the [[Geometry Based Architecture View]]

=External Links=
* Geometry
** [http://people.scs.fsu.edu/~burkardt/txt/obj_format.txt Obj format]
** [http://www.khronos.org/collada/ Collada]
** [http://www.jtopen.com/ JT Open]
** Constructive Solid Geometry (CSG) http://gts.sourceforge.net/ http://www.cgal.org/ http://opencsg.org/
** Universal 3D Standard (U3D) http://www.intel.com/technology/systems/u3d/ http://www.ecma-international.org/publications/standards/Ecma-363.htm

* Physics
** [http://www.havok.com/ Havok]
** [http://www.ageia.com/ PhysX Ageia]

=Members (Stakeholders)=

:[[User: Burhop Piccard|Burhop Piccard]] - Founder
:[[User: Morgaine Dinova|Morgaine Dinova]] - Analyst (scalability aspects)
:[[User: Wyn Galbraith|Wyn Galbraith]] - Builder & Prim Torturer
:[[User: Hypatia Callisto|Hypatia Callisto]] - 3d Artist
:[[User: JeanRicard Broek|JeanRicard Broek]] - Licenced Architect, GIS, SL Builder

[[Category: AW Groupies]]

LlEmail

2007-11-14T01:47:47Z

Blubb Dixon: sp

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

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

The real message starts here.
</pre>
{{!}}}
|caveats=* There is a limit to the number of email messages an object can send in a given amount of time.
|constants
|examples=<pre>
string email = "";

default
{
state_entry()
{
if(email == "")
email = (string)llGetKey()+"@lsl.secondlife.com";

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

touch_start( integer num_detected )
{
//Send an email to the person who touched the prim
llEmail( email, "No touching!", "I was defiled by: " + llDetectedName(0)+"\nKey: "+(string)llDetectedKey(0) );
}
}
</pre>
|helpers=
<pre>
email( string time, string address, string subj, string message, integer num_left )
{
if(llGetSubString(address, -19, -1) == "@lsl.secondlife.com")//trim the header
message = llDeleteSubString(message, 0, llSubStringIndex(message, "\n\n") + 1);
}
</pre>
|also_functions=*{{LSLG|llGetNextEmail}}
*{{LSLG|llMessageLinked}}
|also_events=*{{LSLG|email}}
*{{LSLG|link message}}
|also_tests=*[[llEmail]]
|also_articles
|notes=* Because of the long delay on this function, it is often called from a second script triggered by {{LSLG|link message}}.
* If you are sending email within Second Life, remember that the address is ''[key]''@lsl.secondlife.com
** Which means if the key returned by [[llGetKey]] is "a2e76fcd-9360-4f6d-a924-000000000003", then its email address is "a2e76fcd-9360-4f6d-a924-000000000003@lsl.secondlife.com".
|permission
|negative_index
|cat1=Communications
|cat2=Email
|cat3
|cat4
}}{{OSWikiFeatureNav}}
=== Feature Design Document ===
(none)

=== Functional Spec ===
(none)

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

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

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

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

[[Postcards]] - Postcards use email out?

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

Linden Vehicle Tutorial

2007-11-11T12:46:54Z

Blubb Dixon: /* Reference Frame */

{{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 its 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 its
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 its roll-axis compared to "dynamic" where the banking is also proportional to its
velocity along its 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 its 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-11-11T12:44:29Z

Blubb Dixon: /* Steering the Vehicle */

{{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 its 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 its
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 its roll-axis compared to "dynamic" where the banking is also proportional to its
velocity along its 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-11-11T12:34:03Z

Blubb Dixon: /* Banking */

{{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 its
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 its roll-axis compared to "dynamic" where the banking is also proportional to its
velocity along its 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-11-11T12:23:47Z

Blubb Dixon: /* Banking */

{{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 its
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}}

LlGetInventoryKey

2007-11-09T06:18:37Z

Blubb Dixon: added link

{{LSL_Function/inventory|name|uuid=false|type}}
{{LSL_Function
|func_id=175|func_sleep=0.0|func_energy=10.0
|func=llGetInventoryKey|return_type=key|p1_type=string|p1_name=name
|func_footnote=If '''item''' is not [[llGetInventoryPermMask|copy, mod, trans]] then the return is [[NULL_KEY]]
|func_desc
|sort=GetInventoryKey
|return_text=that is the [[UUID]] of the inventory '''name'''
|spec
|caveats
|constants
|examples
|helpers
|also_functions=
{{LSL DefineRow||[[llGetInventoryName]]|}}
{{LSL DefineRow||[[llGetInventoryCreator]]|}}
{{LSL DefineRow||[[llGetInventoryType]]|}}
{{LSL DefineRow||[[llGetInventoryPermMask]]|}}
|also_events
|also_tests
|also_articles
|notes
|cat1=Inventory
|cat2
|cat3
|cat4
}}

LlGetInventoryName

2007-11-09T06:15:59Z

Blubb Dixon: sp

{{LSL Function/negative_index|false|number}}
{{LSL_Function
|func_id=147|func_sleep=0.0|func_energy=10.0
|func=llGetInventoryName|return_type=string
|p1_type=integer|p1_name=type|p1_desc=INVENTORY_* flag
|p2_type=integer|p2_name=number
|func_footnote
|func_desc
|return_text=that is the name of the inventory item '''number''' of '''type'''. Returns an empty string if no item of the specified type is found in the prim's inventory.
|spec
|caveats
|constants={{LSL Constants Inventory}}
|examples======Will Unpack all items of a box=====
<pre>
// script created by SpiritWolf Chikuwa
// minor changes by Strife Onizuka to speed things up
//
// /!\ PUBLIC DOMAIN /!\
// You can Copy/Mod/Trans
// Please, do not resell this script and give it full perm
// Just please leave this header intact
//
// Minor changes: (insert your name here and delete this comment if you do any mod of this script, thank you)
//
// Script start here:

list gInventoryList;

list getInventoryList()
{
list result = [];
integer n = llGetInventoryNumber(INVENTORY_ALL);
integer i = 0;

while(i < n)
{
result += llGetInventoryName(INVENTORY_ALL, i);
++i;
}
return result;
}

default
{
state_entry()
{
gInventoryList = getInventoryList();
}

touch_start( integer n )
{
integer i = 0;
string folder = llGetObjectName();

while(i < n)
{
llGiveInventoryList(llDetectedKey(i), folder, gInventoryList );
++i;
}
}

changed( integer change )
{
if ( change == CHANGED_INVENTORY )
gInventoryList = getInventoryList();
}
}

// llGetInventory number and name will scan all objects on the box.
// llGiveInventory will give you the content.
// See also llGetInventory and llGiveInventory on LSL Wiki for further informations.
</pre>
|helpers
|also_functions=
{{LSL DefineRow||[[llGetInventoryNumber]]|Returns the number of items of a specific type in inventory}}
{{LSL DefineRow||[[llGetInventoryType]]|Tests to see if an inventory item exists and returns its type.}}
{{LSL DefineRow||[[llGetInventoryCreator]]|Returns the inventory item's creator}}
{{LSL DefineRow||[[llGetInventoryPermMask]]|Returns the inventory item's permissions}}
{{LSL DefineRow||[[llGetInventoryKey]]|Returns the inventory item's [[UUID]] (if full perm)}}
|also_events
|also_tests
|also_articles
|notes
|permission
|sort=GetInventoryName
|cat1=Inventory
|cat2
|cat3
|cat4
}}

Sculpted Prims: 3d Software Guide

2007-10-09T13:30:12Z

Blubb Dixon: sp

{| align="right"
| __TOC__
|}

''(Want to help out with this page? Check out the [[Talk:Sculpted_Prims:_3d_Software_Guide#ToDo | To-do list]].)''
= About 3D Modeling Software =

This page offers a list of 3D modeling software for use with Sculpt Maps for [[Sculpted Prims]], along with a short explanation of popular 3D file formats. Each entry lists the software package's web site, operating system support, cost and trial versions if applicable, and the license.

Note: Resident-made sculpt map tools and offline previewers [[Sculpted Prims: Resident-made Tools|now have their own page]].

;What Features are important for making Sculpted Prims?

Each software entry includes a rundown of features that are particularly useful for creating sculpt maps. Although support for these features isn't necessary in order to create sculpt maps, it can make the process a whole lot easier.

*'''User Scripting:''' A script interface is one of the easiest and fastest ways to add functionality to a program or to automate tasks the program is already capable of. Plugins and SDKs can do the same thing but may not be available.
*'''Built-in texture baking/generation:''' This term describes the ability to create/"render" textures and export them to image files. If this functionality is built into the software, it is available to user-generated scripts. For example, it allows manual export of sculpt maps with [[#Blender|Blender]] and [[#Lightwave_.28Newtek.29|Lightwave]]. It can also make it easier to create regular textures for your model; you can apply colors, patterns or just a template guide to your model and bake it out for upload or further detailing in a paint program.
*'''Modeling Methods:''' Over the years a variety of different 3d modeling techniques have emerged, each having various strengths and weaknesses. They include:
** Polygon modeling: The most mature method and the choice output for most games and realtime rendering in which you directly manipulate the faces, edges and vertices of an object.
** NURBS: NURBS modeling uses series of curved splines to define the shape of an object and are excellent for smooth organic shapes. The methodology behind sculpted prims are very largely based on them.
** Subdivision Surface: Subdivision modeling shares some of the advantages of both NURBS and polygon modeling: the shape is manipulated using sets of control points that allow for both smooth surfaces and precise details.
** Brush Sculpting: With this method, you use your mouse or pen tablet and a series of adjustable brushes to literally sculpt on the 3d surface like clay. Many programs such as Blender and 3ds Max offer this function in a limited sense to help with precision detailing but not to the extent of programs built with this method as their focus, such as zBrush.

Which you use will ultimately come down to personal preference and what your exporter will handle best.

;Do I need a really powerful computer to run this stuff?

For most Second Life users, this shouldn't be a major issue. If your computer is capable of running the Second Life client, you should have no trouble running most of these programs. Some programs will run fine on something as old as a Pentium III. A few professional programs (like Maya) say they'll only support high-end workstation graphics cards but it will still run ok on a regular setup. Check the system requirements on the software vendor's webpage for specific details.

;What program(s) are the best for making sculpties?

There's no easy answer to that question. It will depend on a number of factors:
* '''How much money are you willing to spend?''' The cost of 3d software ranges from "free" to thousands of dollars. Programs like Maya and 3ds Max are powerful but if you're not already seriously into 3d modeling, they're probably overkill. Lightwave, zBrush and programs in their price range are powerful professional tools while still being within reach of a reasonably well-to-do person who's dedicated to their SL design work, but these are probably still overkill as most of the features you pay for gone beyond the general tools to create sculpt maps for Second Life. Programs like Amorphium, trueSpace and Milkshape are aimed at professionals and casual hobbyists but not all of them are going to have the full 3D studio capabilities of some more expensive programs. Free programs run the gamut between the pro and hobby levels and you'll have to consider other factors when choosing between them.

* '''How much time are you willing to invest?''' If you want to just make a few sculpted objects, a simple standalone utility like Rokuro might suit you best. If you're a serious content creator though, you'll want to put the time and effort into learning a more complex program.

* '''How much prior experience do you have?''' If you've been working with 3d software for a while already, you probably already know what you like or will have an easier time picking up a new and/or more complicated program. If you're a brand newbie to modeling, it's probably a mistake to jump right into a program like Blender or Maya with their steep learning curves. The availability of general modeling tutorials and other resources (not just SL-related ones) will probably affect your choice as well.
 

;I'm a newbie to all this. What should I start with?
Probably not with anything expensive...''unless'' you're a university student at a school with a good computer art program where you can take advantage of their resources. If you're very serious about learning the tools the pros use you might also seek out such a program, either online or in a classroom.

If you just want to dive in to making sculpties then there are a couple front runners for your attention. (Please note that these are opinions and may not reflect everyone's.) If you have to go the free route, Wings 3d is probably your best bet: the exporter has some hard limitations and the interface isn't necessarily friendly but it's loads easier than the other main free option, Blender. Once you get the hang of it you can make sculpties fairly quickly.

If you want free and simple, try out the Rokuro and Tokoroten sculpt making tools. You'll be limited in the shapes you can produce but they require no 3d experience and you can turn out some good sculpties in a little as ten minutes. The Wings plugin can also import these sculpt maps where you can tweak them further.

If you're willing to spend some money (under $100), AC3D is a good place to start. The interface is nicer than that of Wings and Zora Spoonhamer's exporter allows you to take good advantage of program features that the Wings exporter doesn't; full subdivision capabilities, cutting and extrusion of faces, etc.

That said, the best way to decide what program you should use is to start downloading their demos and trying them to find what you like.

= Adding Programs to This List =
The hobby market for 3d software is currently growing rapidly: as a result there are dozens of software packages in the wild, many undiscovered or not well known. If a new program is discovered and proven by means of it being listed here, great, but it's not within the scope of this list to name them all, else the most usefull ones would get burried and the page would become a confusing mess.

A couple things to consider:
* Popularity: This may seem contrary to the "discovering new programs" bit above, but it's impossible to ignore the impact popularity has on a program: it means there's a community of users that can offer support to newbies and it increases the liklyhood that someone will develop sculpt map support for it.
* Features: If it doesn't allready have sculpt map support, does it have the features that will make it likely able to support sculpt maps? Certian well known programs like Sketchup and Milkshape have been put in the "Other" category because people will ask about them but the chance of sculpt map support being developed for them seems slim because of their feature sets. If that turns out to be an incorrect assumption then they'll certianly be moved up. A file converter like 3dm2sculpt or one of various object to sculpty programs is better than nothing but as such programs are in varrying stages of being beta and/or experimental (and often may not work), being able to save to a convertable file format shouldn't be the only thing to consider. Other things to keep in mind: is the interface useable? Does the program run without frequently crashing?

With those in mind, if you're adding a program, follow the format used in the rest of the entries (they differ slightly between the free and commercial packages) and be sure to fill in as much information as you can; this will usualy take a little research. If you've used the program, you're encouraged to include your insights and experiences in the short decription blurb (you don't need more than a short paragraph). Tutorials, documentation and the like should be linked seperately under the Resources section.

= Special Purpose Sculpted Prim Tools =

The resident-made sculpt tools such as Rokuro, SnurbO'Matic and the preview tools now have their own page: [[Sculpted Prims: Resident-made Tools]].

= Free 3D Modeling Software =

=== Art of Illusion ===

*'''Website:''' [http://www.artofillusion.org artofillusion.org]
*'''License:''' [http://www.gnu.org/licenses/gpl.html GPL]
*'''Operating Systems:''' Any OS that will run Java (requires Java Runtime Environment 1.4 or later)
*'''User Scripting?''' Yes, Java via [http://www.beanshell.org/ Beanshell]
*'''Modeling Methods:''' Polygon, NURBS
*'''Built-in Texture Baking?''' ???
*'''Current Sculpt Map Support?:''' No, although it is possible to save as a .obj file and then convert it to a sculpt image.

A number of Residents have recommended this program. If you're familiar with it, please give the rest of us a summary!

*'''Warning:''' I have a reported '''Malware/Virus''' that came from Art Of Illusion. It infected a few of my files! ''-Caboose Enfield''
[NOTE: chances are it was either downloaded from a shady site or was a false positive. More details are needed!]

'''Resources'''

*[http://www.artofillusion.org/documentation AoI Documentation]
 

=== Blender ===

*'''Website:''' [http://www.blender.org blender.org]
*'''License:''' [http://www.gnu.org/licenses/gpl.html GPL]
*'''Operating Systems''': Cross-platform (Windows, Mac, Linux, Irix, Solaris, FreeBSD and others)
*'''User Scripting?''' Yes, Python
*'''Modeling Methods:''' Polygon, NURBS, Subdivision, Basic Brush Sculpting
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' Yes. Documented [http://amandalevitsky.googlepages.com/sculptedprims here], and [http://www.bentha.net/sculpted2/Blender-to-sculpted.html here]

Formerly a company's in-house tool, Blender is the current king of the open source modeling programs. With all the features of the expensive programs, an active development community and even some existing SL-based tools made by Residents, this is going to be the default choice for many people. Downsides: Blender's interface is not newbie-friendly. That combined with spotty documentation can make for a slow learning curve.

'''Resources'''

* [http://forums.secondlife.com/showthread.php?t=203571 Blender Sculptie Import & Export scripts]
* [http://www.blender.org/tutorials-help/ Blender.org Documentation and Tutorials]
* [http://en.wikibooks.org/wiki/Blender_3D:_Noob_to_Pro Blender 3D: Noob to Pro] - on [http://en.wikibooks.org/wiki/Main_Page Wikibooks], It's a great step-by-step tutorial that contains substantial content, is well-formatted, and has screen shots.
* [http://amandalevitsky.googlepages.com/sculptedprims How to Make Sculpted Prims with Blender]
*[http://www.bentha.net/sculpted-tuto/Blender-export-template-tut.html A template file to start with and export easy]
*[http://blendernewbies.blogspot.com/2007/04/video-oven-baked-pretzels-in-blender-3d.html Oven Baked Pretzels @ BlenderNewbies.com] - A video tutorial that covers the basics of Blender's new sculpt mode, useful if you're creating sculpties using the above manual method.
*[http://www.bentha.net/sculpted2/Blender-to-sculpted.html An almost complete method] to export almost anything from blender
*[http://iramblesorry.blogspot.com/2007/05/how-i-learned-to-stop-worrying-and-love_28.html Another great tutorial] on using blender for sculpts
*[http://forums.secondlife.com/showthread.php?t=110607 Offline Prim Builder] for standard prims (restricted access)
 

=== Moment of Inspiration ===

*'''Website:''' [http://moi3d.com/ Moment of Inspiration]
*'''License:''' Open beta testing/freeware
*'''Operating Systems:''' Windows 2000/XP/Vista
*'''User Scripting?''' ?
*'''Modeling Methods:''' NURBS, Polygon (Import/Export Only)
*'''Built-in Texture Baking?''' ?
*'''Current Sculpt Map Support?:''' Yes, try [[3dm2sculpt]]

This program has some cool things going for it. It's the work of a former [[#Rhino_3D | Rhino]] developer and has an interface that pretty much lets you draw shapes with the mouse or a pen tablet. Documentation on the website is sparse however and being in beta means there will be kinks.

It should be noted that MoI will become a commercial product when it leaves beta testing (expected later this summer), but it will still be comparatively inexpensive; the estimated cost is between US$200-$100.

'''Resources'''

* [http://moi3d.com/forum/ Moment of Inspiration Forums]
* [http://mefeedia.com/tags/momentofinspiration/ Video Tutorials]
 

===Plopp===
[[Image:Plopp example.jpg|thumb|250 px| A SLork sculpted in Plopp]]

*'''Website:''' [http://www.secondplopp.com/ Plopp Second Life]
*'''License:''' Donationware/Commercial
*'''Operating Systems:'''Windows, Mac, Linux
*'''User Scripting?''' No (N/A)
*'''Modeling Methods:''' 2d painting
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' Yes

''Plopp'' is a cute 3D modeling tool designed for little kids. The makers of Plopp have now put out a free version for SL users (the full program can be bought for US$19.50).

Imagine one of those new mylar balloons. You paint the one side with an image, and then paint the other side with an image represetning the other side. Plopp then blows up the balloon and shades it. You can also import graphics from other tools (Photoshop, a scanned drawing, etc.), make a "cutout" with the eraser and inflate that. You can play a little with the lighting and with rotations. The Plopp drawing tools are very basic but keep in mind, this is for little children. Then it bakes the texture and exports the texture and the sculpt map (128x128).

Even if you don't use this for Second Life, you might like to get it for your kids...or inner child. It just looks like a lot of fun.

'''Resources'''
*[http://www.planet-plopp.com/biggerkids/tips.html Plopp Tips] - Video tutorials and neat tricks from the Plopp website

=== Wings 3D ===

*'''Website:''' [http://www.wings3d.com Wings 3D]
*'''License:'''[http://www.opensource.org/licenses/bsd-license.html BSD license]
*'''Get Started:'''[[Wings 3D|Second Life Wings 3D guide]]
*'''Operating Systems:''' Windows, Mac OS X, Linux (binaries), other Unixes (source only)
*'''User Scripting?''' Plugin interface using a language called Erlang
*'''Modeling Methods:''' Polygon, Subdivision
*'''Built-in Texture Baking?''' Not sure
*'''Current Sculpt Map Support?:''' Yes.

Wings3D is a [http://en.wikipedia.org/wiki/Subdivision_surface subdivision modeler] that is easy to learn and is well suited to making sculpted prims. The sculpt import and export for Wings is easy to use. Detailed documentation is sparse, but there are several Second Life tutorials in this Wiki and on the Web.

'''Resources'''
* See the [[Wings 3D|Second Life Wings 3D guide]].
* Get the [[Omei Turnbull]] [http://forums.secondlife.com/showthread.php?t=183764 import/export plugin here.]
* Get the [[user:Strife Onizuka|Strife Onizuka]] [http://forums.secondlife.com/attachment.php?attachmentid=25721 import/export plugin here].
*Get the [http://sourceforge.net/project/downloading.php?groupname=wings&filename=wings3d_manual1.6.1.pdf&use_mirror=internap Wings 3D User Manual] here. (Sourceforge, pdf)

 

=== POV-Ray ===

*'''Website:''' http://povray.org
*'''Cost:''' FREE
*'''Operating Systems:''' Windows/Linux/Mac
*'''Trial version available?'''
*'''User Scripting?'''
*'''Modeling Methods:''' N/A
*'''Built-in Texture Baking/generation?''' Yes
*'''Current Sculpt Map Support:''' Yes. Instructions are here: http://johannahyacinth.blogspot.com/2007/05/sculpted-prims-with-pov-ray.html

POV-Ray is a renderer - you have to do all your modeling in another application, or by describing in plain text the mathematical shapes which make up the model. It may seem an odd inclusion in this part of the list but merits mentioning up here instead of burried at the bottom with the "Other" section because it actualy can produce sculpt maps. Some other programs like AC3D (below) can also call on POV-Ray for texture baking.
 

= Commercial 3D Suites =

It has to be said: most professional 3D software is (understandably) expensive, anywhere from hundreds to many thousands of dollars for a single copy. They're marketed at big professional studios with thousands or millions of dollars to budget for this stuff. There are ways to [[3D software cost savings|reduce this expense]] so that it's within the reach of an average person: some legal, some not.

== Under $200 ==

=== Amorphium (Electric Image)===

*'''Website:''' [http://www.eitechnologygroup.com/products/amorphium Electric Image Amorphium]
*'''Cost:''' US$79 ("Standard")
*'''Operating Systems:''' Windows, Mac (UB) - trial is Mac OS X 10.0 - 10.3 only
*'''Trial version available?:''' Yes
*'''User Scripting?''' Yes
*'''Modeling Methods:''' Brush Sculpting, NURBS, Polygon
*'''Built-in Texture Baking?''' Yes (paint on, further controllable with sensitive pen-tablet)
*'''Current Sculpt Map Support?:''' No (export to a format Blender knows, or to OBJ, and use a converter, can start with the 64x63 sphere made by Wings3D)

Sculpting is what Amorphium is all about. If you have a pen tablet (even a tablet PC), the pressure sensitivity will control the pressure applied to the current brush to morph the sculpture. It gives a very natural feel to being able to sculpt 3d models easily and intuitively. Amorphium has won 14 awards including "Best Graphics Software" from magazines like Computer Graphics World, PC World, and Macworld for its breakthrough real-time approach to creating 3D graphics.

'''Resources'''

* [http://forums.secondlife.com/showthread.php?t=186218 Sculpted Prim Modeler: Amorphium] on sl forums (restricted access)
 

=== AC3D (invis) ===

*'''Website:''' [http://www.inivis.com/ www.invis.com - AC3D]
*'''Cost:''' US$75
*'''Operating Systems:''' Windows, Mac OSX 10.4 or later, Linux (x86 only)
*'''Trial version available?:''' Yes - 14 day trial
*'''User Scripting?''' Plugin Interface available, plus TCL-based scripting
*'''Modeling Methods:''' Polygon, Subdivision
*'''Built-in Texture Baking?''' No (But can be accomplished via 3rd party plug-ins or POV-Ray)
*'''Current Sculpt Map Support?:''' Yes: [http://www.inivis.com/secondlife.html Export plug-in for Windows, Mac and Linux], [http://www.ccccybernetics.com/ developed by Zora Spoonhammer]

AC3D is an inexpensive polygon modeler with SubD support designed to be easy for novice users. The sculpt map plug-in will export any model that has a perfect uv space. Several pre-mapped starter shapes are included with the plug-in, including a cube that can be used as basis for complex objects by artists familiar with the popular box modeling method using sub-division surfaces. Invis recently gave their official blessing (as well as hosting) to the plugin, making them the first vendor of this kind of software to put their backing into sculpy development.

''' Resources '''

*[http://www.youtube.com/watch?v=Y8RC5aJuWks 5-minute video tutorial on creating a pear]
*[http://www.independentdeveloper.com/archive/2007/09/27/sculpted_prims_from_existing_3 Sculpted Prims from Existing 3D Models] in AC3D. A step-by-step guide using an existing 3-D model of a fish.
*[http://www.supercoldmilk.com/ac3dplug/index.html AC3D Plugins @ Super Cold Milk] - several invaluable free plugins can be found here, including the knife tool used in the pear tutorial
 

=== Silo (Nevercenter) ===

*'''Website:''' [http://www.nevercenter.com/ Nevercenter - Silo]
*'''Cost:''' US$159, US$59 (upgrade), edu licensing on request
*'''Operating Systems:''' Windows 2000 or later, Mac OSX 10.3 or later
*'''Trial version available?:''' Yes - 30 day trial
*'''User Scripting?''' -?-
*'''Modeling Methods:''' Polygon, Subdivision
*'''Built-in Texture Baking?''' -?-
*'''Current Sculpt Map Support?:''' -?-

'''Resources'''
* [http://www.nevercenter.com/about/features/ Silo Features] and [http://www.nevercenter.com/about/videos/ how-to videos]

 

== $200 - $999 ==

=== Zbrush (Pixologic) ===

*'''Website:''' [http://www.pixologic.com/zbrush/products/products.php Pixologic :: Zbrush]
*'''Cost:''' US$489
*'''Operating Systems:''' Windows 98/2000/ZP, Mac OS X
*'''Trial version available?:''' No
*'''User Scripting?''' Yes, Zscripting
*'''Modeling Methods:''' Brush Sculpting, "ZSphere" modeling, Polygon (Import/Export)
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' No, future support is planned by Linden Lab (but note to resident developers: this one is in high demand).

Zbrush pretty new and a bit unique. It's a 3d painting and sculpting tool; instead of manipulating polys or curves, you select a brush and literally ''paint'' and chisel and mold...the best way to grasp it is to download the demo and play with it. It's pretty sweet: a ton of studios such as [http://www.epicgames.com/ Epic Games] use it to create the details for their normal maps and some SL designers are already using it for the 3d painting capabilities.

'''Resources'''

* [http://www.pixologic.com/zbrush/education/documentation/guides.php Zbrush Documentation]
* [http://www.zbrushcentral.com/zbc/index.php ZbrushCentral - Official Forums and Online Community]
 

=== Lightwave (Newtek)===

*'''Website:''' [http://www.newtek.com/lightwave/ Lightwave]
*'''Cost:''' US$895, US$495 as a companion upgrade for Photoshop
*'''Operating Systems:''' Windows XP, Mac OS X 10.3.9 or higher
*'''Trial version available?:''' Yes, 30 day time limit, currently only available with a couple books
*'''User Scripting?''' Yes, LScript
*'''Modeling Methods:''' Polygon, NURBS with LWCAD 2.1 add-on (costs extra)
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' Yes, manual method instructions here: [[User:Patchouli_Woollahra/Lightwave_Sculptie_Rendering]] (works with any version of Lightwave of at least version 6) or use the DStorm plugin provided [[http://www.dstorm.co.jp/english/plugin/secondlife.htm]] at DStorm (LW9+ only)

Some high-profile Second Life designers have been using Lightwave for quite a while to burn realistic highlights and shadows onto their skins and clothing textures. Therefore it's not a big surprise that after Blender, this was the second program that community members figured out a sculpt export method for.

'''Resources'''
*[http://www.robinwood.com/Catalog/Technical/LightwaveTuts/LWTutSet.html Lightwave Tutorials] by Robin Wood, a.k.a. SL's [https://wiki.secondlife.com/wiki/User:Robin_Sojourner Robin Sojourner].

 

=== Rhinoceros (McNeel) ===

*'''Website:''' [http://www.rhino3d.com Rhino 3D]
*'''Cost:''' US$995
*'''Operating Systems:''' Windows 2000/XP/Vista (Vista not recommended due to OpenGL issues)
*'''Trial version available?:''' Yes, save count limited
*'''User Scripting?''' Yes, VBScript
*'''Modeling Methods:''' NURBS, Polygon (limited)
*'''Built-in Texture Baking?''' No
*'''Current Sculpt Map Support?:''' please try [[3dm2sculpt]] (not tested with Rhino yet)

Rhino is built from the ground up for NURBS modeling; thus if you intend to use NURBS, this isn't such a bad option. From this author's brief trial with it, it handles certain operations (like joining 2 or more objects) somewhat more intelligently than 3ds Max. A couple UI tricks make it easier to learn than the sea of buttons you're initially presented with: a help window to one side explains each operation as you select it and the command line at the top effectively lets you search for a function by typing in its name, without having to know where the button or menu option is.

'''Resources'''
 

=== trueSpace (Caligari) ===

*'''Website:''' [http://www.caligari.com Caligari]
*'''Cost:''' US$595 for latest version (7), but legacy versions are sold for lower prices ($199 for TrueSpace 5)
*'''Operating Systems:''' Windows XP/Vista
*'''Trial version available?:''' Yes, prior version of the program
*'''User Scripting?''' Yes
*'''Modeling Methods:''' Polygon, NURBS, Subdivision
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' No

trueSpace and its companion products appear to be aimed more at the independent developer and hobby market, resulting in a fully featured program at a much more affordable price. Of interest to Second Life users: trueSpace 7 and up offers a collaborative work environment; the benefit of working together like in SL but without the guy shooting off guns at you in the sandbox.

'''Resources'''

* [http://forms.caligari.com/forms/ts3all_free.html trueSpace3.2 Full Version (very old) for Free]
 

=== Softimage XSI (Avid) ===

*'''Website:''' [http://www.softimage.com/products/xsi/ Softimage XSI]
*'''Cost:''' US$495 ("Foundation") - US$6995 ("Advanced")
*'''Operating Systems:''' Windows XP SP2/64 bit
*'''Trial version available?:''' Yes, 30 day trial with full features, free "Mod Tool" supported by [http://www.valvesoftware.com/ Valve] with limited features (watermarks images).
*'''User Scripting?''' Yes, Python, COLLADA and C#
*'''Modeling Methods:''' Polygon, NURBS, Subdivision
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' No

Billing itself as "the most advanced 3D animation and character creation software for next generation games & film", it does that, modeling, baking, film compositing, ''and'' it makes toast! All kidding aside, they seem to be going after the largest slice of the market they can and their client list includes everything from [http://en.wikipedia.org/wiki/Half-Life_2 Half-Life] to [http://en.wikipedia.org/wiki/Howl's_Moving_Castle_(film) Howl's Moving Castle]. Pluses? It's one of the few commercial programs that uses non-proprietary languages for their scripting...yes, I said languages, because apparently you have a choice between several. However it's unlikely that it has a significant user base within the SL community at the moment.

'''Resources'''
 

=== Modo 301 (Luxology)===

*'''Website:''' [http://www.luxology.com/ Luxology Home]
*'''Cost:''' US$895 professional, $149 Educational, $99 "Good Student" price. Download a trial version then wait 1-2 weeks and you'll receive a voucher dropping professional price to US$695.
*'''Operating Systems:''' Windows, Mac
*'''Trial version available?:''' Yes
*'''User Scripting?''' Yes
*'''Modeling Methods:''' Polygon, Subdivsion, Brush Sculpting
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' Yes, via texture baking

Luxology Modo is a premier modeling and UV system built to maximize the workflow of professional modelers. It has both a rich modeling and painting toolset, ideal for creating models for Second Life.

'''Resources'''

* Lovecraft Forest Testbed [http://www.rabbitroo.com/SL/SLtest7.lxo SLtest7.lxo]
* Lovecraft Forest Usage Instructions: [http://www.lovecraftforest.com/blog/2007/05/17/sculpted-prims-in-modo-part-ii/ Blog Post]
 

=== Mudbox (Skymatter) ===

*'''Website:''' [http://www.mudbox3d.com/ Mudbox]
*'''Cost:''' US$299 ("Basic") - US$649 ("Professional")
*'''Operating Systems:''' Windows XP SP2, Atm untested on x64 or Vista
*'''Trial version available?:''' Yes, 15 days trial fully functional.
*'''User Scripting?''' No
*'''Modeling Methods:''' Brush Sculpting, Subdivision
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' No

With ZBrush one of the most powerful organic modelers out there, really easy to use and artist friendly. Its modeling is based on brushes like ZBrush but aims more to 3D like Maya or 3D Studio Max. It contains a high quality texture renderer for baking normal maps and is used be many 3D professionals and studios like WETA Digital and some artists at Raven Software and id Software.

'''Resources'''
 

=== Carrara (Daz) ===

*'''Website:''' [http://www.daz3d.com/ Daz]
*'''Cost:''' US$249 ("Standard") - US$549 ("Professional")
*'''Operating Systems:''' Windows, Mac (UB)
*'''Trial version available?:''' Yes
*'''User Scripting?''' Yes (plugin development, no scripting)
*'''Modeling Methods:''' Polygon
*'''Built-in Texture Baking?''' No (Yes with third party plug from [http://www.inagoni.com/content.php?content.3/ Inagoni]
*'''Current Sculpt Map Support?:''' Yes - via texture baking with third party plugins - tutorial [[User:Hypatia_Callisto/Carrara_Sculpt_Baking]]

Like Hexagon, Carrara was an Eovia product that is now owned by Daz. Carrara is full-featured 3D application, supporting polygon modeling, spline modeling, "metaballs", and terrain modeling (it is sometimes compared to Vue). This app seems fly under the radar consistently, but Daz does seem to be serious about maintaining it as they have recently released a Mac Universal Binary version, free to registered users. Carrara also provides animation and particles.

'''Resources'''
 

=== Cinema 4D ===

*'''Website:''' [http://www.maxon.net Maxon]
*'''Cost:''' CINEMA 4D R10 Win PC £586.33, additional modules available.
*'''Operating Systems:''' Windows XP/Vista, Mac
*'''Trial version available?:''' Yes, Demo
*'''User Scripting?''' Yes, COFFEE
*'''Modeling Methods:''' Polygon, NURBS, Subdivision
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' Yes, via Shader.

One of the more affordable 3D applications, excellent learning curve. Uses COFFEE script for plugins.

'''Resources'''
 
Nice [http://www.ks-3d.de/KS-3D_SCULPTIES_(SCULPTED_PRIMS).htm tutorial] to create a Shader and modeling (by KS-3D Klaus Strifler - german only)

 

== $1000 and Up ==

=== Maya (Autodesk/Wavefront) ===

*'''Website:''' [http://www.autodesk.com/maya Autodesk Maya]
*'''Cost:''' US$3000 ("Complete") - US$7000 ("Unlimited"). ("Complete" version sufficient for creating sculpted prims.) Educational license: US$300
*'''Operating Systems:''' Windows XP SP2, Mac OS X 10.4, Linux (SUSE, RedHat and Fedora supported)
*'''Trial version available?:''' "Personal Learning Edition", no time limit but not usable for creating sculpted prims (sculpt textures ruined by watermark)
*'''User Scripting?''' Yes, MEL Script
*'''Modeling Methods:''' Polygon, NURBS, Subdivision
*'''Built-in Texture Baking?''' Yes
*'''Current Sculpt Map Support?:''' Yes, script by Qarl Linden available on their wiki [[LlSculpt mel|here]], instructions [[Sculpted_Prims:_FAQ#MayaExporter|here]].
** Qarl has released a new export script that can handle assemblies of prims and can also bake the surface textures for you. [[Advanced_Sculptie_Exporter_From_Maya | Available Here]]

*'''Plugins:''' [http://www.sim-image.co.jp/sltk/en/index.php SIM Image SLTK (Second Life Toolkit)] (￥94,000/126,000, $800/1,100, €600/800) is a plugin for Maya that allows users to create and export objects for Second Life. See [http://www.sim-image.co.jp/sltk/en/function.php this page] for the complete feature set.

Why was Maya the first to receive sculpted prim support from Linden Lab? Because it was what [http://www.qarl.com/ Qarl Linden], the main developer on the project, learned to use while creating kick-ass movie SFX like [http://www.qarl.com/menu/resume/matrix-demo.mov these] and the tech for sculpted prims was adapted from tricks he learned in the process. Maya has been a growing force in the movie industry for some years and a strong presence in the video game industry as well.

'''Resources'''

* [http://webpages.charter.net/talilal/Balloon%20Tutorial/ Maya Sculpt Tutorial] by Talila Liu
* [http://www.sim-image.co.jp/sltk/en/index.php SIM Tools - Second Life ToolKit plugin]
 

=== 3d Studio Max (Autodesk) ===

*'''Website:''' [http://www.autodesk.com/3dsmax Autodesk 3ds Max]
*'''Cost:''' US$3495. Educational License: ~US$200. Subscription: ~US$500/year.
*'''Operating Systems:''' Windows 2000/XP, Windows Vista (with version 9.1)
*'''Trial version available?:''' Yes, 30-day demo, full features
*'''User Scripting?''' Yes, MAX Script/plugins
*'''Modeling Methods:''' Polygons, NURBS, Subdivsion, Basic Brush Sculpting
*'''Built-in Texture Baking?''' Yes (some functions only in version 8 and higher)
*'''Current Sculpt Map Support?:''' 3 methods in development:
** [http://www.joe-brown.net/SecondLife/SculptTut/SculptTut.html Method 1] by Gearsawe Stonecutter, uses a premade template file.
** [http://forums.secondlife.com/showthread.php?t=182461 Method 2] by Abu Nasu, uses a shader. [http://forums.secondlife.com/showpost.php?p=1505984&postcount=46 Download the Materials file here]. [http://tech-slop.serveit.org/wiki/index.php?title=Sculptie_Egg Read the tutorial here].
*** A varient of Abu's methood by Chip Midnight uses a projection modifier and can handle arbitrary shapes but requires Max version 8 or higher. [http://home.comcast.net/~pixelforgeltd/Tutorial.htm The tutorial is here.]
** Method 3 ([http://forums.secondlife.com/showthread.php?t=185426 thread]) ([http://wiki.secondlife.com/wiki/SculptGenMax wiki]) by Shack Dougall, is a vertex-based method using MAXScript and preset geometry as a starting point. Tested on 3dsMax 9.

Formerly Maya's main competitor, especially in the game industry. Then Autodesk (the makers of Max) bought out Alias (the makers of Maya) a couple years ago. So far the company is developing both products separately, marketing Maya at the movie industry and Max at the game developers, but they have long had comparable feature sets, and in the future it's likely that there will be tighter integration between the two. A choice between Maya and Max generally comes down to user preference and (particularly in our case) plugin support. Some users have said that Max is easier for a newbie to learn than Maya and certain basic controls share similarities with SL's build tools (such as shift-drag to copy).

'''Resources'''

 

=== AutoCAD (Autodesk) ===

*'''Website:''' [http://www.autodesk.com/autocad Autodesk AutoCAD]
*'''Cost:''' US$4,000 Educational License: US$400 AutoCAD LT: US$900
*'''Operating Systems:''' -
*'''Trial version available?:''' -
*'''User Scripting?''' -
*'''Modeling Methods:''' -
*'''Built-in Texture Baking?''' -
*'''Current Sculpt Map Support?:'''
** '''[http://ai-designstudio.net/ Henshin III]''' by AI Design Studio is a tool that allows the export of AutoCAD files into Second Life.

'''Resources'''

* [http://ai-designstudio.net/ AI Design Studio]

 

= Other 3d Programs =

These programs may be free or cheap, but they won't have nearly as expansive feature sets as those above.

=== MilkShape 3D ===

*'''Website:''' [http://www.milkshape3d.com/ www.milkshape3d.com]
*'''Cost:''' US$25 / €25
*'''Operating Systems:''' Windows
*'''Trial version available?''' 30-day unrestricted trial, save disabled thereafter until registered
*'''User Scripting?''' Plug-in SDK available (Does that count?)
*'''Modeling Methods:''' Polygons
*'''Built-in Texture Baking/generation?''' No
*'''Current Sculpt Map Support:''' Import/Export plugin under development

'''Resources''' 

* See the '''Tutorials''' and '''Links''' sections on the [http://www.milkshape3d.com/ MilkShape website]
 

=== Hexagon 2 (DAZ Productions) ===

*'''Website:''' [http://www.daz3d.com/i.x/software/hexagon/-/? Hexagon product page]
*'''Cost:''' Full version: $149, "Crossgrade" from other DAZ software: $79, Upgrade: $49
*'''Operating Systems:''' Windows 2000/XP, Mac OS X 10.2 or higher
*'''Trial version available?''' Yes, it's buried: go [http://www.daz3d.com/i.x/support/downloads/-/ here] and select Hexagon from the list.
*'''User Scripting?''' No
*'''Modeling Methods:''' Polygon
*'''Built-in Texture Baking/generation?''' No
*'''Current Sculpt Map Support:''' No

SL animators may have heard about (and perhaps been disappointed with) [http://www.daz3d.com/i.x/software/studio/-/? DAZ Studio], a competitor to Poser. Others may be familiar with [http://www.daz3d.com/i.x/software/bryce/-/? Bryce], a landscape creation tool with a much better reputation. Hexagon was originally developed by eovia until purchased by DAZ and while it appears to be a perfectly capable 3d program by itself with polygon modeling subdivision modeling, sculpting tools, and is that 3d painting I see?, the absence in their feature list of either texture baking or any sort of user scripting or plugin interface could be a deal-breaker until something like a reliable .OBJ converter comes along.
 

=== Google SketchUp ===

*'''Website:''' [http://sketchup.google.com/ Google SketchUp]
*'''Cost:''' Free (Google SketchUp 6); $495 (Google SketchUp 6 Pro)/$45 (full-feature academic license for Google SketchUp 6 Pro)
*'''Operating Systems:''' Windows XP/2000, Windows Vista (with OpenGL 1.5 or higher), Mac OS X (10.3.9 or higher)
*'''Trial version available?:''' 8 hour trial available for Sketchup Pro
*'''User Scripting?''' Yes, Ruby
*'''Modeling Methods:''' Polygon
*'''Built-in Texture Baking?''' No
*'''Current Sculpt Map Support?:''' Indirectly (through OBJ export; Pro version only)

SketchUp is a 3D drafting program popular among architects for its conceptual similarity to manual drafting and physical model-building. It has a very low learning curve, but is rather foreign to most established suites other than AutoCAD.

Hypothetically, SketchUp could be used to reduce the number of prims used in structures already possible with Second Life's built-in tools, as its use of edges and faces allows the creation of efficient compound geometric forms.

On the other hand, SketchUp's "bring your own geometry" approach makes it not particularly suited to the creation of mesh-based organic shapes.

Sketchup's surface modeling paradigm currently makes it difficult to translate SketchUp models into Sculpted Prims. The paid "Pro" version of SketchUp does, however, allow export to OBJ which, via [[Sculpted_Prims:_3d_Software_Guide#obj2sculpt|obj2sculpt]] (or, of course, Maya), may allow sculpt-map export. It also exports to 3DS, Collada, XSI and VRML, ''et cetera'', but these formats may well require software more expensive than SketchUp.

SketchUp uses image textures about as basic as those found in the Second Life build tools. Its texture capabilities would therefore likely not be useful to Second Life designers other than for previewing existing textures.

 
=== Ayam ===

*'''Website:''' [http://ayam.sourceforge.net/ Ayam]
*'''License:''' [http://www.opensource.org/licenses/bsd-license.html BSD license]
*'''Operating Systems:''' Unix/Linux (native), Windows 98, 2000 and XP, Mac OS X (with X11)
*'''User Scripting?''' Yes, tcl
*'''Modeling Methods:''' NURBS, Polygon (Import/Export Only)
*'''Built-in Texture Baking?''' No
*'''Current Sculpt Map Support?:''' No

'''Resources'''

* [http://ayam.sourceforge.net/docs.html Ayam Documentation page]
 

= 3D File Formats =

If you're using software that cannot export to sculpt directly, you might still be able to succeed. You can always give the file to someone with access to the appropriate software, or you could export your model into another 3D modeler. To do that, you'll need to export the model into a format the other program can handle. Here's a brief rundown of the file formats that SL developers will generally find the most useful.

:*'''.OBJ''': Probably the most common cross-platform export format for polygon models; it's fairly open and any 3D program worth its bits supports it. It's also well-documented and easily hackable.

:*'''.3DS''': The default polygon export format supported by [[#3d_Studio_Max_.28Autodesk.29|3D Studio Max]]. Because of this, it is widely supported. However, it doesn't have as many export options as OBJ.

:*'''.FBX''': Another Autodesk format that is good if you need to export whole scenes: objects, animation, lights, cameras, etc. More importantly for our purposes, it preserves [http://en.wikipedia.org/wiki/NURBS NURBS] objects in some programs. Especially useful if you're trading files between 3DS Max and [[#Maya_.28Autodesk.2FWavefront.29|Maya]]; it's also supported in some other programs but [[#Blender|Blender]] isn't among them ...yet.

:*'''.3DM''': a.k.a [http://www.opennurbs.com OpenNURBS]. This is the native format of [[#Rhinoceros_Rhino_3D|Rhino3D]] and [[#Moment_of_Inspiration|MoI]] and, as the name suggests, is a [[Sculpted_Prims:_3d_Modeling_Glossary#NURBS_Modeling | NURBS]] export format. It's gaining some popularity; unfortunately, it's not currently supported by the big three (Maya, Max and Blender). However the format documentation and code libraries are open-source, tempting those brave enough to try and write tools for it, such as [[#3dm2sculpt | 3dm2sculpt]].
 

= Other Resources =

Useful places for anyone interested in 3d modeling:

* [http://www.3dbuzz.com 3d Buzz] — Forums, video tutorials and even classes covering everything from 3d programs to 3d programing and even Photoshop.
* [http://ibiblio.org/e-notes/Splines/Intro.htm An Interactive Introduction to Splines] — a technical introduction to NURBs.
 

== See also ==

* [[Sculpted Prims|Sculpted Prims]]
* [[Sculpted Prims: FAQ|Sculpted Prims: FAQ]]
* [[Sculpt Textures in Paint Programs]]
* [[Sculpted Prims: Technical Explanation|Sculpted Prims: Under the Hood]]
* [[Sharing_sculpt_maps_and_textures|Sculpted Prims: Sharing Sculpt Maps and Textures]]
* [[Sculpted Prims Beta Discussion|Sculpted Prims Beta Discussion]]

 

[[Category:Sculpted Prims]]

Sculpted Prims

2007-10-09T11:12:47Z

Blubb Dixon: spelling

[[Image:Sculpted_fruit_small.png|frame|right|Sculpted Prims]]
[[Image:Sculpted_couch_Xenius_Revere.png|frame|right|Seven prim couch by Xenius Revere, using baked ambient occlusion.]]
[[Image:Sculpted_head_Chip_Midnight.png|frame|right|One prim head by Chip Midnight, using baked diffuse lighting.]]
[[Image:Sculpted_vases_Damanios_Thetan.jpg|frame|right|Vase sculpture by Damanios Thetan]]

{|cellspacing="5px"
|valign="top"|
__TOC__
|valign="top" width="48%"|
{{Sculpted Prims/Links}}
|}

A '''Sculpted Prim''', or ''sculptie'', is a [[prim]] whose shape is determined by an array of <math><x, y, z></math> coordinates stored as RGB values in an image file
(a '''[[Sculpted Prims: FAQ#SculptTextures|Sculpt Texture]]''' or '''[[Sculpted Prims: FAQ#SculptTextures|Sculpt Map]]''').
Sculpted prims can be used to create more complex, organic shapes that were not previously possible with Second Life's prim system. Each piece of fruit to the right is one prim (and so is the plate). For technical details, see [[Sculpted Prims: Technical Explanation]].

== How do I make Sculpted Prims ==

Presently, there only a few limited tools '''inside''' Second Life for creating sculpties. They are usually created externally using a 3D modeling tool such as Blender, Maya, or Wings 3D, and then uploaded to Second Life, where they are applied to a prim with the build tools. See [[Sculpted Prims: Creator's Guide]] for more guidance, or jump straight to [[Sculpted Prims: 3d Software Guide]].

== News ==

=== 20 June 2007 ===

In-world group '''Sculptie Dev''': group primarily for the communication/announcement of sculpted prim development.

=== 24 May 2007 ===

Linden Lab is running a contest: show off your sculpties for fun, fame and schwag! [http://blog.secondlife.com/2007/05/24/second-life-sculpted-prim-contest-show-us-your-sculpties/ Read the blog for details.] Deadline for submissions is June 1st.

=== 23 May 2007 ===

Sculpted prims are now available on the [http://blog.secondlife.com/2007/05/23/the-grid-is-down-for-scheduled-maintenance/ Main Grid] as of version 1.16.0(5).

=== 16 May 2007 ===

An update to sculpted prims, included in the [http://blog.secondlife.com/2007/05/15/beta-grid-updated-to-second-life-11601/ latest build] of the beta viewer ([http://secondlife.com/community/preview.php 1.16.0(1)]), has two changes that are not backwards-compatible:

1) The orientation of the '''sculpt map''' (sculpt texture) is reversed. This means all previously created sculpt maps/textures need to be horizontally flipped (otherwise they'll appear inside out.) This change fixes the orientation discrepancy between sculpt maps/textures and surface textures (which have required a 90 degree rotate and flip.) ([http://blog.secondlife.com/2007/05/15/beta-grid-updated-to-second-life-11601/ source])

2) The LSL call to set sculpted prims is changing to require two parameters: the texture and the topology type. (source: [[Talk:Sculpted_Prims#HEADS_UP.21|Talk page]])

=== 27 April 2007 ===

Sculpted Prims made available on the [http://www.secondlife.com/community/preview.php preview grid].

== Where can I find out more about Sculpted Prims? ==

Sculpted Prims have now a comprehensive [[Sculpted Prims: FAQ|FAQ]] wiki page.

== See also ==

*[[Sculpted Prims: Technical Explanation]]
*[[Sculpted Prims: FAQ| Sculpted Prims FAQ]]
*[[Sculpted_Prims:_Sculpt_Maps_and_Textures|Sculpt Maps and Textures]]
*[[Sculpted_Prims:_3d_Software_Guide|3D Software Guide]]
*[[Sculpted_Prims:_3d_Modeling_Glossary|3D Modeling Glossary]]
*[[Sculpt_Textures_in_Paint_Programs|Sculpt Maps and 2D Graphics Software]]
*[[Sculpted_Prims:_Resident-made_Tools|Sculpted Prims: Resident-made Tools]]

[[Category:Sculpted Prims]]

[[Category:Features]]

[[Category:Creation]]