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:

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

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

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

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.

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.

11.4. 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 vehicle type 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.

11.5. 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:

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.

 11.6. 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:

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

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.