Advanced Vehicle Tutorial

From InWorldz Wiki
Jump to: navigation, search

This advanced tutorial describes in detail how the LSL vehicles support works. It is intended reading for people proficient in LSL scripting and in physics and movement dynamics. If you are not familiar with the mathematics behind movement simulation, please read the Beginners Vehicle Tutorial, which teaches you the basic concepts.

Note: This document was written by the designer of the InWorldz vehicle system. It reflects the code base and design architecture as of February 28, 2015.

Contents

Building a Vehicle

editing the physical shape

A vehicle is a physical object and all physical objects have limits to their complexity else the simulator will not permit them to be physical. The limit is 256 convex hulls and the intricacies of that is explained in the Vehicles and Physical Objects blog article. The salient limits and characteristics are:

  • Maximum 256 convex hulls for physical objects. Above that, the object will not become physical;
  • Prims have varying number of convex hulls depending on their shape, examples: cube is 1CH, cube with hole is 4CH, torus is 25CH, twisted torus is 79CH!
  • Mesh parts derive their convex hulls based on the physics mesh supplied in the mesh model or inferred by the visual model. If the mesh part is complex it is best to make a simplified physics shape to reduce the number of generated convex hulls, or, if the part is decorative, give it no physics shape to generate no convex hulls;
  • A seated avatar does not have a physics shape. This is different than in the SL grid where the avatar is given one of several predefined shapes depending on which built-in animation it plays. Consequently, seated avatars on vehicles will pass through obstructions. Only the vehicle object is subject to collisions. If you need the avatar to be part of the collision domain, you will need to create an invisible mesh part or a prim to simulate the avatar as an obstruction.

You can build some nice vehicles within 256 convex hulls as often a prim build can be up to 90+ prims before the 256 convex hull limit is reached. If the physics cost becomes too high, it can be reduced by simplifying the overall physics shapes of the object's prims or mesh parts. When feasible, change the physics shape of prims or mesh parts to convex hull. Any parts not needed for collisions should be changed to physics shape none.

All of the v2 based viewers are able to directly set the physics shape type. In this photo, you can see how a prim torus, which is 70 convex hulls, is converted into a single convex hull (click on the photo to enlarge it).

aligning the root prim

When building your vehicle, the most important part is to ensure that the root prim is aligned correctly. By default the vehicle support uses the local axes of the root prim to determine the front, side, and up orientation. Using the boat example, this is what the root prim alignment should look like. Note that the local x-axis should point along the vehicle's intended forward direction, and that the z-axis should point in the intended up direction. The simplest approach to getting this orientation correct is to build your vehicle (prims, sculpts, or mesh parts), link it all together then edit it to orient it as you wish. Rez a small cube, edit it, view the local axes of that cube then place it in your build, aligning the axes as described. Finally link your build to the cube so that the cube is the root prim. Now when the vehicle support orients that cube, the entire vehicle will also be oriented correctly.

Alternatively, you may orient the reference frame via the VEHICLE_REFERENCE_FRAME parameter.

Basic Physics

Any physical object will move on its own if placed on an incline or if placed in space with no other object supporting it. The simulated physics forces created by the PhysX engine in InWorldz (or the Havok physics engine in the SL grid or the Bullet physics engine in many OpenSim grids) will move it. The trajectory a physical object takes when moving on its own is determined by the natural virtual forces present. Gravity is the primary force which causes physical objects to fall. When an object collides with other objects or terrain, the object will experience counter-forces that will alter its trajectory. This is what causes an object to bounce, careen, or even spin when it collides with other objects or avatars. The degree of accuracy in the physics simulation differs between the physics engines, and so when objects are colliding as they move, the manner in which they are affected will differ. Objects in free space (airplanes and boats) rarely collide with other objects and so the differences between physics engines are minimal, though some physics engines do not implement true exponential movement, and that can cause some trajectory deviations between them. Other objects, notably cars, are in a state of constant collisions; remember that when a car 'rolls' along the ground or roadway, it is actually sliding. Every imperfection in the ground mesh or roadway mesh will cause a myriad of small collisions. It is here where trajectories can depart significantly because all of the nuances of slip or strike asymmetry, and linear force to torque collision conversions will be simulated differently, if at all, between the different physics engines. In short, under certain circumstances, physical objects may react differently in InWorldz than in other grids. PhysX is a high accuracy physics engine, so it looks better but will be different than other physics engines.

Basic Forces

A physical object can be scripted to move using the basic forces LSL functions as its motors. Those force functions do work well, but they are incomplete. A script can apply impulses or constant forces, but there are no graduated velocity functions (accelerate to a fixed velocity). When using basic forces to move a vehicle to a terminal velocity, the script has to simulate all the nuances in timer events, comparing actual velocities to expected velocities, reducing or increasing the forces to achieve the targets. This leads to rather complex scripts.

There are no straightforward orientation functions. llLookAt or llRotLookAt do work but they fixate on a static position or a static rotation. To make them work in a moving vehicle they too require being called in a timer loop to adjust for the movements. Also these functions can be swamped by the strong counter-forces imparted by collisions. Though friction and restitution (bounce) can be set manually or via scripted functions, complex scripting is required to get a vehicle that looks believable and, more important, usable and deterministic.

Vehicle Model

The LSL Vehicle model was developed to simplify the complexities of using basic forces functions. The model provides many higher level movement behaviors that then are used to shape an object's acceleration profile, its terminal speed, its orientation as it moves, and how quickly it comes to rest in the absence of motor and orientation forces. The vehicle model uses these behavior parameters to shape and change the default actions the physics engine applies to an object. In many cases these vehicle behavior parameters need only be input but once in a script. The model also supports dynamic changes to the parameters to permit advanced behaviors to be scripted.

Broad classes of behaviors are determined by setting the vehicle's type. When coding a vehicle script this is the first thing that needs to be done to notify the vehicle support that an object is to be treated as a vehicle. The vehicle type is set in a script by calling the function llSetVehicleType(type). Once called, the default behavior parameters for that vehicle type are set. Then any adjustments to the default parameters may be performed.

Parameters are set using the following scripted functions:

  • llSetVehicleFloatParam(parameter_name, float_value);
  • llSetVehicleVectorParam(parameter_name, vector_value);
  • llSetVehicleRotationParam(parameter_name, rotation_value);

Behaviors can be modified by setting or clearing flags using the following functions:

  • llSetVehicleFlag(flags);
  • llRemoveVehicleFlags(flags);


The InWorldz vehicle model is designed to be compatible with the SL vehicle model. Compatible does not mean identical behaviors in all cases; it means vehicles should experience similar behaviors in most cases. There are extreme edge cases in which trajectories may depart significantly because of differences between physics engines. There are cases where extremely low timescales may cause a departure because of differences in the simulation rate. PhysX simulates at higher accuracy 64 physics steps per second compared to 45 steps per second used by other physics engines. There are also a few cases where some institutionalized bugs were not implemented. Implementing those bugs would have caused massive loss of realism and increased overhead to coerce the physics engine to conform to the bugs. Nonetheless, a large number of scripts brought from the SL grid do work unchanged in InWorldz. Other scripts require minor parameter adjustments, and some might need rework. The following videos demonstrate the script compatibility and differences:

Vehicle Compatibility Roundup
Motorcycle Differences


Definitions

The principal axes of an aircraft

Movement and rotation takes place in three axes. In InWorldz, the axes are labeled X, Y, and Z, corresponding to the forward, left, and up directions of the root prim. When editing an object or a prim, the axes are colored red, green and blue respectively. The axes are also often labeled as roll, pitch, and yaw respectively (see photos).

The LSL vehicle support provides programmable behaviors to:

  • make a vehicle turn toward the direction of its forward movement (angular deflection);
  • make a vehicle move in the direction it is pointing at (linear deflection);
  • introduce arbitrary friction along any of the local axes;
  • make a vehicle hover above ground, above or below water level, hover ground or water, or hover to a global height;
  • introduce positive, neutral, or negative buoyancy;
  • control a vehicle using linear motors to move it in a direction along the three local axes;
  • control a vehicle using angular motors to rotate it in a direction around the three local axes;
  • make a vehicle orient itself vertically (vertical attraction);
  • induce world yaw turns based on the amount of off-vertical X-axis banking;
  • react to system wind and water currents imparting linear and angular force effects to the vehicle.

With these capabilities, many kinds of vehicles can be created with a rich set of behaviors.

Timescale and Efficiency

Some behaviors have related efficiency and timescale parameters. The efficiency defines how much damping is applied to the behavior (0.0 means no damping, 1.0 means critical damping). The timescale defines how long it takes to get the movement to traverse in exponential time; that is, the timescale determines how long a velocity change takes to shift to 1/e (1/2.71828) of its target value. For timescale, a rough estimate is that when a behavior causes a shift from one velocity or rotation to another, it takes approximately three times longer than the timescale for the shift to complete. For efficiency, a rough estimate is that values below 0.5 tend to cause the shift to be springy.

The mathematical basis for exponential behavior is based on a damped harmonic oscillator. In physics this is modeled as a ball on a spring with a damper. The timescale represents the frequency of the spring loaded ball, the efficiency or damping value represents the countering force of the damper. When the ball is set in motion it oscillates at a frequency of 1/timescale if the damper is not present (efficiency = 0.0). When the damper is fully engaged (efficiency = 1.0), when the ball is displaced then let go, it will come to rest with no oscillations.

Angular and Linear Deflection

Many objects or vehicles have a preferred orientation when they move without internal forces (thrown or falling). The orientation is usually governed by aerodynamic influences as the object traverses through the air. For example, a missile or arrow will orient itself to point in the direction of its travel. A baseball will not orient itself when thrown but a football will orient itself. This preferred orientation behavior is simulated with the Angular deflection behavior. The related parameters that determine how quickly the object rotates to point its forward x-axis toward the direction of travel are:

  • VEHICLE_ANGULAR_DEFLECTION_TIMESCALE
  • VEHICLE_ANGULAR_DEFLECTION_EFFICIENCY

Other objects will, when rotated, also eventually rotate their movement toward the direction they are pointing. This conversion of velocity direction is simulated with the linear deflection behavior. Parameters determine how quickly the object changes direction when it is rotated. One example is a boat or sled, in which turning it quickly causes it to move in the direction it is currently pointing. The parameters to control this deflection are:

  • VEHICLE_LINEAR_DEFLECTION_TIMESCALE
  • VEHICLE_LINEAR_DEFLECTION_EFICIENCY

Unlike other motion behaviors, the deflection efficiency parameters are not used to simulate damping. Instead they act as a normalized factor to the timescale. Note that this behavior is likely an old Havok1 vehicle bug that became institutionalized, as the efficiency parameter should have been a damping factor.

Friction

Hover and Buoyancy

Motors

Once a vehicle's type and behaviors have been set up, external forces can move it around, and that in turn triggers the various friction, deflection, attraction behaviors to shape its movement. A script can then apply movement directly to a vehicle through various means. It can use the basic force functions llApplyImpulse or llSetForce to do the movement. These functions have properties that require considerable feedback to make them do predictable movement across various friction surfaces. To simplify vehicle movement, four vehicle motor behaviors (two angular and two linear parameters) are available to specify how long the ramp-up and decay of the motors should take place. The motor timescale is a time constant that specifies the exponential time a motor is to achieve its stated velocity. As an example, if you want a car to move forward at 10m/sec in a couple of seconds, the script code segment would be as follows:

default
{
   state_entry()
   {
      llSetStatus(STATUS_PHYSICS, TRUE);
      llSetVehicleType(VEHICLE_TYPE_CAR);
      llSetVehicleFloatParam(VEHICLE_LINEAR_MOTOR_TIMESCALE, 2.0);

      // Move the vehicle
      llSetVehicleVectorParam(VEHICLE_LINEAR_MOTOR_DIRECTION, <10.0, 0,0>);
   }
}

Whenever a motor is engaged, by setting its direction, two behaviors are applied immediately. One is the ramping to the designated velocity (MOTOR_TIMESCALE), and the other is the motor decay timescale (MOTOR_DECAY_TIMESCALE). It too is a time constant and it represents how long in exponential time the motor effectiveness diminished to zero. Note that this does not necessarily mean the time for the vehicle to come to a stop. It means how long should the motor forces stop acting on the vehicle. A vehicle hovering in the air or in water would continue to move because it has mass and it comes to rest solely based on the friction behavior timescale. A vehicle on a surface would be subject to the natural friction between it and that surface.

As an example, if you want a car to move, when it is touched, forward at 10m/sec in a couple of seconds but have it come to a stop in five seconds, the script code segment would be as follows:

default
{
   state_entry()
   {
      llSEtStatus(STATUS_PHYSICS, TRUE);
      llSetVehicleType(VEHICLE_TYPE_CAR);
      llSetVehicleFloatParam(VEHICLE_LINEAR_MOTOR_TIMESCALE, 2.0);
      llSetVehicleFloatParam(VEHICLE_LINEAR_MOTOR_DECAY_TIMECALE, 5.0);
   }

   touch_start(integer num)
   {
      // Move the vehicle
      llSetVehicleVectorParam(VEHICLE_LINEAR_MOTOR_DIRECTION, <10.0, 0,0>);
   }
}

The four motor timescales are now vector parameters, an InWorldz enhancement from its LSL float origin. This enhancement permits the vehicle script to control the timescales of each axis independently to gain refined control of movement vectors. One example of different timescale per axis are in large ships where the side thrusters can achieve the same velocity but being smaller they take longer to ramp up. Another example is a spaceship where the forward motor is a long burn engine but the side thrusters are short burst gas jets.

The timescale can still be changed as a float parameter, which compatibly sets all the axes to the same value.


Angular Motor

Linear Motor

Vertical Attraction

Banking

Wind and Currents

InWorldz uses the Zephyr Winds System to create interesting diurnal regional wind patterns that are influenced by terrain features. Hills and valleys shift the wind patterns. Zephyr winds supports three bands of wind that apply depending on the height of the object or vehicle:

  • below water, the winds are ocean currents that swish back and forth to create the effects of tidal ebb and flow;
  • surface winds that react to terrain variations
  • winds aloft that are not affected by the terrain below

Vehicles can be programmed to react to the region winds automatically. There are two parameters and a flag that govern how the winds affect a vehicle:

  • VEHICLE_LINEAR_WIND_EFFICIENCY
  • VEHICLE_ANGULAR_WIND_EFFICIENCY
  • VEHICLE_FLAG_REACT_TO_WIND

The linear wind efficiency (-10.0 to +10.0) is specified as a vector, and it specifies how strongly the wind pushes against each local axis of the vehicle. <0,0,0> means no wind effects occur.

The angular wind efficiency (-10.0 to +10.0) is also a vector which specifies how strongly the wind will twist or impart rotation to each local axis of the vehicle.

To enable wind reaction, use llSetVehicleFlags(VEHICLE_FLAG_REACT_TO_WIND)

The following video shows a boat reacting to the wind:

Vehicle Reacting to the Region Winds


Vehicle Types

There are eight vehicle types with two InWorldz extensions:

  • VEHICLE_TYPE_NONE
  • VEHICLE_TYPE_SLED
  • VEHICLE_TYPE_CAR
  • VEHICLE_TYPE_MOTORCYCLE (InWorldz extension)
  • VEHICLE_TYPE_BOAT
  • VEHICLE_TYPE_SAILBOAT (InWorldz extension)
  • VEHICLE_TYPE_AIRPLANE
  • VEHICLE_TYPE_BALLOON

When a vehicle type is set, by called llSetVehicleType(...), the vehicle model changes the vehicle behaviors to a set of default parameters. Most behaviors have modifiable parameters, but some behaviors do not have accessible parameters. All previous vehicle parameters and flags are changed, hence, any changes to parameters or flags must be executed after the call to llSetVehicleType.

VEHICLE_TYPE_NONE

The 'none' type turns off the vehicle model. All the parameters are reset to turn off their respective behaviors, and the object reverts to basic forces physics.

VEHICLE_TYPE_SLED

The sled type is an unpowered vehicle. By default, the motors are disabled, it has a behavioral preference to slide on its own when facing downhill, has very low friction in the forward direction, much higher side to side friction. Motors can be enabled by setting the motor ramp-up and decay parameters and then coding calls to engage the motors as needed.

VEHICLE_TYPE_CAR

The car type is a powered vehicle. By default the motors are enabled and they operate on the three local axes. Forward x-axis friction is lower, side y-axis friction is high. Angular and linear deflection are set to assist with cornering on high speed turns, and no-deflection-up is enabled to prevent it from motoring skyward.

Additionally, the motors are disabled when the vehicle is a meter above the ground. This InWorldz behavior extension can be adjusted or disabled altogether with the VEHICLE_DISABLE_MOTORS_HEIGHT parameter.

VEHICLE_TYPE_MOTORCYCLE (InWorldz extension)

The motorcycle type is similar to the car type, but designed to radically simplify true motorcycle vehicles. No support slab is needed. The motors operate with local x-axis and y-axis forces but the z-axis motor uses world forces. This permits flat turns when the motorcycle is heavily banked. The vertical attractor is made strong to keep the motorcycle upright when not actively banked. Banking is enabled and the parameters set to permit strong sideways banking. The motors are set to disable when the motorcycle is in the air. All of these new behaviors can be modified using new accessible parameters.

VEHICLE_TYPE_BOAT

The boat type is a powered watercraft. By default the motors operate with local x-axis and y-axis forces but the z-axis motor uses world forces. This permits flat turns when the boat is banked. The boat is set to hover over water with a small hover height. Banking based turning is enabled. The boat will experience extreme drag when above water on terrain. It also is stopped when it strikes a steep shoreline. The drag and shoreline stop behaviors are disabled when any terrain hover is set.

VEHICLE_TYPE_SAILBOAT (InWorldz extension)

The sailboat type is similar to the boat type. The banking range is increased, the sailboat will react to the Zephyr ocean currents and winds, gently pushed and rocking actions. Under extreme weather it can capsize and remain inverted for a short while. All of these new behaviors can be modified using new accessible parameters.

VEHICLE_TYPE_AIRPLANE

The airplane type is a powered vehicle designed to be piloted using banking (roll causes turning). To make that happen, banking is enabled with a short timescale so that the turning commences within a second of a roll. The z-axis turns are based on world forces to retain a flat turn. This simulates cancelling of the down dip that would have taken place had not aerodynamic lift forces pulled upward to counteract the dip. The motor decay timescales are very long, a minute, to simulate either the locked throttles in powered planes or the long aloft time in gliders.

VEHICLE_TYPE_BALLOON

The balloon type is a buoyant, mostly unpowered vehicle designed to be piloted either directly or by using banking (roll causes turning). The buoyancy is set to remove all gravity interactions, a hover height is set (and this needs to be adjusted by the script). All of the timescales are long to simulate the slow reaction times of such a massive object. linear friction is a few seconds to simulate strong interaction with static (virtual) air. A small amount of wind reaction has been added so that the balloon, when afloat, will slowly be dragged by the winds. This too may be adjusted within the script.

Vehicle Flags

There are fifteen vehicle flags, five are InWorldz extensions, and one flag is not implemented:

  • VEHICLE_FLAG_NO_DEFLECTION_UP
  • VEHICLE_FLAG_LIMIT_ROLL_ONLY
  • VEHICLE_FLAG_HOVER_WATER_ONLY
  • VEHICLE_FLAG_HOVER_TERRAIN_ONLY
  • VEHICLE_FLAG_HOVER_GLOBAL_HEIGHT
  • VEHICLE_FLAG_HOVER_UP_ONLY
  • VEHICLE_FLAG_LIMIT_MOTOR_UP
  • VEHICLE_FLAG_MOUSELOOK_STEER
  • VEHICLE_FLAG_MOUSELOOK_BANK
  • VEHICLE_FLAG_CAMERA_DECOUPLED (not implemented)
  • VEHICLE_FLAG_REACT_TO_CURRENTS (InWorldz extension)
  • VEHICLE_FLAG_REACT_TO_WIND (InWorldz extension)
  • VEHICLE_FLAG_LIMIT_MOTOR_DOWN (InWorldz extension)
  • VEHICLE_FLAG_TORQUE_WORLD_Z (InWorldz extension)
  • VEHICLE_FLAG_MOUSEPOINT_STEER (InWorldz extension)
  • VEHICLE_FLAG_MOUSEPOINT_BANK (InWorldz extension)

The vehicle flags are set and cleared with two LSL functions: llSetVehicleFlags and llRemoveVehicleFlags. llSetVehicleFlags does not set the flags to the specified values, as the function name implies, it ORs in the specified flags. llRemoveVehicleFlags ANDs out the specified flags. This permits individual flags to be set or cleared by the script without knowledge of current value of the flags.

The flags modify, limit and/or disable certain vehicle behaviors. Partly this is done to permit the vehicle system to disable or simplify entire sets of behaviors to reduce the simulation overhead.

NOTE: It is good programming practice to only change the flags you want changed. These functions are designed so that new flags can be added later without affecting older scripts. It is not good programming practice to clear all the flags unconditionally. Unused flags might be used later or hidden flags with important behaviors might exist but are not documented. Code, such as llRemoveVehicleFlags(-1) or llRemoveVehicleFlags(0xffffffff), should not be used in scripts as it ensures a script will break when new vehicle flags are added.

VEHICLE_FLAG_NO_DEFLECTION_UP

Linear deflection will add forces to move the vehicle in the direction its local forward axis is currently pointing. Though this is useful for missiles and airplanes, land vehicles should not deflect into the sky. This flag removes any positive vertical forces from a vehicle's deflection.

VEHICLE_FLAG_LIMIT_ROLL_ONLY

Vehicles with the vertical attractor set will be oriented so that its local z-axis points up. Some vehicles, notably airplanes, need to be able to set an off vertical pitch. This flag limits the vertical attractor to apply only to the roll axis (x-axis).

VEHICLE_FLAG_HOVER_WATER_ONLY

Causes the vehicle to hover over water. The amount and springiness of the hover is determined by the VEHICLE_HOVER_HEIGHT, VEHICLE_HOVER_TIMESCALE, and VEHICLE_HOVER_EFFICIENCY parameters.

VEHICLE_FLAG_HOVER_TERRAIN_ONLY

Causes the vehicle to hover only over terrain. Note, when both HOVER_WATER and HOVER_TERRAIN are set, the vehicle hovers over both water and terrain.

VEHICLE_FLAG_HOVER_GLOBAL_HEIGHT

Changes the hover height from being based on the surface of the water, terrain or both to based on an absolute height. This flag overrides HOVER_WATER and HOVER_TERRAIN.

VEHICLE_FLAG_HOVER_UP_ONLY

When hover is enabled, the vehicle actively tries to move its vertical position toward the specified hover height. This flag overrides that behavior to actively hover up. If the vehicle is above its hover point, no active height adjustment is performed. Only gravity or other explicit forces will move it downward.

VEHICLE_FLAG_LIMIT_MOTOR_UP

This flag prevents the vehicle motor forces from generating upward velocity. It is useful for land vehicles to keep them from motoring upward.

VEHICLE_FLAG_MOUSELOOK_STEER

By default, a vehicle's angular motors are engaged via scripted calls that set the VEHICLE_ANGULAR_MOTOR_DIRECTION and parameter, usually in a control or timer event. When this flag is set and when the avatar is in mouse-look view, the vehicle is steered by engaging the angular motor to attempt to point the vehicle's forward axis in the same direction as the camera's viewpoint.

VEHICLE_FLAG_MOUSELOOK_BANK

When banking is enabled, and the avatar is in mouse-look view, the vehicle will bank (rotate about the x-axis) based on the left-right movements of the mouse pointer.

VEHICLE_FLAG_CAMERA_DECOUPLED

NOTE: This flag is not implemented. In mouse-look view, the camera rotates along with the vehicle's angular movements. This flag decouples the camera from being influenced by the vehicle rotations.

VEHICLE_FLAG_REACT_TO_CURRENTS (InWorldz extension)

The winds of InWorldz are based on the Zephyr winds model, which in addition to creating shifting and programmable wind patterns, also creates subsurface winds or ocean currents. This flag causes the vehicle to react to those currents. The amount of linear and angular influences are determined by the VEHICLE_ANGULAR_WIND_EFFICIENCY and VEHICLE_LINEAR_WIND_EFFICIENCY parameters.

VEHICLE_FLAG_REACT_TO_WIND (InWorldz extension)

The winds of InWorldz are based on the Zephyr winds model, which creates shifting and programmable wind patterns affected by land masses. This flag causes the vehicle to react to those winds. The amount of linear and angular influences are determined by the VEHICLE_ANGULAR_WIND_EFFICIENCY and VEHICLE_LINEAR_WIND_EFFICIENCY parameters.

VEHICLE_FLAG_LIMIT_MOTOR_DOWN (InWorldz extension)

This flag prevents the vehicle motor forces from generating downward velocity. It is useful for sea vehicles to keep them from motoring downward

VEHICLE_FLAG_TORQUE_WORLD_Z (InWorldz extension)

Vehicle motors usually apply their forces to the vehicle's local axes. When this flag is set, the z-axis motor operates on the world z-axis.

This flag is set internally when the vehicle's type is set to motorcycle, boat, sailboat or airplane. Clearing it will cause these vehicles to dip or behave unexpectedly on banked turns.

VEHICLE_FLAG_MOUSEPOINT_STEER (InWorldz extension)

This flag enables mouse pointer based steering. It behaves like MOUSELOOK_STEER except that it enables mouse steering while the avatar is in 3rd person view (out of mouse-look view).

VEHICLE_FLAG_MOUSEPOINT_BANK (InWorldz extension)

This flag enables mouse pointer based banking. It behaves like MOUSELOOK_BANK except that it enables mouse banking while the avatar is in 3rd person view (out of mouse-look view).

Vehicle Parameters

  • VEHICLE_LINEAR_FRICTION_TIMESCALE
  • VEHICLE_ANGULAR_FRICTION_TIMESCALE
  • VEHICLE_LINEAR_MOTOR_DIRECTION
  • VEHICLE_LINEAR_MOTOR_OFFSET
  • VEHICLE_ANGULAR_MOTOR_DIRECTION
  • VEHICLE_HOVER_HEIGHT
  • VEHICLE_HOVER_EFFICIENCY
  • VEHICLE_HOVER_TIMESCALE
  • VEHICLE_BUOYANCY
  • VEHICLE_LINEAR_DEFLECTION_EFFICIENCY
  • VEHICLE_LINEAR_DEFLECTION_TIMESCALE
  • VEHICLE_LINEAR_MOTOR_TIMESCALE
  • VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE
  • VEHICLE_ANGULAR_DEFLECTION_EFFICIENCY
  • VEHICLE_ANGULAR_DEFLECTION_TIMESCALE
  • VEHICLE_ANGULAR_MOTOR_TIMESCALE
  • VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE
  • VEHICLE_VERTICAL_ATTRACTION_EFFICIENCY
  • VEHICLE_VERTICAL_ATTRACTION_TIMESCALE
  • VEHICLE_BANKING_EFFICIENCY
  • VEHICLE_BANKING_MIX
  • VEHICLE_BANKING_TIMESCALE
  • VEHICLE_REFERENCE_FRAME
  • VEHICLE_MOUSELOOK_AZIMUTH (InWorldz extension)
  • VEHICLE_MOUSELOOK_ALTITUDE (InWorldz extension)
  • VEHICLE_BANKING_AZIMUTH (InWorldz extension)
  • VEHICLE_DISABLE_MOTORS_HEIGHT (InWorldz extension)
  • VEHICLE_DISABLE_MOTORS_DELAY (InWorldz extension)
  • VEHICLE_INVERTED_BANKING_MODIFIER (InWorldz extension)
  • VEHICLE_LINEAR_WIND_EFFICIENCY (InWorldz extension)
  • VEHICLE_ANGULAR_WIND_EFFICIENCY (InWorldz extension)


VEHICLE_LINEAR_MOTOR_TIMESCALE

The linear motor timescale is a vector parameter, an InWorldz enhancement from its LSL float origin. This enhancement permits the vehicle script to control the timescale of each axis independently. The timescale can be changed as a float parameter, which compatibly sets all the axes to the same value.

VEHICLE_LINEAR_MOTOR_DECAY_TIMESCALE

The linear motor decay timescale is a vector parameter, an InWorldz enhancement from its LSL float origin. This enhancement permits the vehicle script to control the timescale of each axis independently. The timescale can be changed as a float parameter, which compatibly sets all the axes to the same value.

VEHICLE_ANGULAR_MOTOR_TIMESCALE

The angular motor timescale is a vector parameter, an InWorldz enhancement from its LSL float origin. This enhancement permits the vehicle script to control the timescale of each axis independently. The timescale can be changed as a float parameter, which compatibly sets all the axes to the same value.

VEHICLE_ANGULAR_MOTOR_DECAY_TIMESCALE

The angularmotor decay timescale is a vector parameter, an InWorldz enhancement from its LSL float origin. This enhancement permits the vehicle script to control the timescale of each axis independently. The timescale can be changed as a float parameter, which compatibly sets all the axes to the same value.

VEHICLE_MOUSELOOK_AZIMUTH (InWorldz extension)

The mouse-look azimuth is a float parameter, ranging from 0 to PI. The default value is PI/2 (90 degrees). It modifies the sensitivity of mouse pointer movements when steering a vehicle with the mouse-look steering behavior. The lower the value the faster the left/right steering.

VEHICLE_MOUSELOOK_ALTITUDE (InWorldz extension)

The mouse-look altitude is a float parameter, ranging from 0 to PI. The default value is PI/2 (90 degrees).It modifies the sensitivity of mouse pointer movements when steering a vehicle with the mouse-look steering behavior. The lower the value the faster the up/down steering.


VEHICLE_BANKING_AZIMUTH (InWorldz extension)

The banking azimuth is a float parameter, ranging from 0 to PI. The default value is PI/4 (45 degrees). It modifies the sensitivity of mouse pointer movements when banking a vehicle with the mouse-look banking behavior. The lower the value the faster the left/right banking.


VEHICLE_DISABLE_MOTORS_HEIGHT (InWorldz extension)

The disable motors height is a float parameter, ranging from 0.0 to 10,000.0. Specifying 0.0 turns off the behavior. When a positive value is set, the vehicle motors become inoperative, after a delay, when the vehicle's bottom surface is higher than the specified height above terrain or any object or created surface. This can be used to simulate the effect of vehicles that require contact with a surface to move.

VEHICLE_DISABLE_MOTORS_DELAY (InWorldz extension)

The disable motors delay is a float parameter, ranging from 0.0 to 1,000.0. When the bottom of a vehicle and a surface below it is higher than the disable motors height, the motors are made inoperative after the specified disable motor delay. he delay is expressed in seconds. A delay of 0.0 causes the motors to become inoperative immediately when the height is exceeded. In practice, there should be a small delay set (1.0-2.0 seconds) in virtual vehicles because of simulator to viewer latencies. A vehicle may have bounced upward before the viewer renders it to the person.

VEHICLE_INVERTED_BANKING_MODIFIER (InWorldz extension)

The inverted banking modifier is a float parameter. It is an extension to the banking efficiency parameter to correct an institutionalized bug in the banking feature. The modifier ranges from -10.0 to 10.0, for most vehicle types it defaults to 1.0. The modifier applies when the vehicle's z-axis points below the horizon (the vehicle is upside down), and when so, any banking induced velocity is the product of the banking efficiency and the inverted banking modifier.

VEHICLE_LINEAR_WIND_EFFICIENCY (InWorldz extension)

Linear wind efficiency is a vector parameter with values ranging from -10.0 to 10.0. The efficiency is a multiplier which determines how the current wind speed at the location of the vehicle pushes the vehicle along each of its local axes. The strength of the forces exerted diminishes as the vehicle approaches the wind speed. Coding 0.0 for an axis reduces the effectiveness to zero, or no effect.

To simulate winds affecting balloons code small positive values. Coding negative values induces movement along the respective axis against the wind. Coding negative values can be used to simulate the forward forces caused by sails.

VEHICLE_ANGULAR_WIND_EFFICIENCY (InWorldz extension)

Angular wind efficiency is a vector parameter with values ranging from -10.0 to 10.0. The efficiency is a multiplier which determines how the current wind speed at the location of the vehicle rotates the vehicle along its local x-axis (roll) and local y-axis (pitch). The strength of the forces exerted diminishes as the vehicle approaches the wind speed. Coding 0.0 for an axis reduces the effectiveness to zero, or no effect.

Tuning Tips

Default Parameters

The following table lists the default behavior parameters for each vehicle type. These values were chosen to create a working default vehicle for each type if only llSetVehicleType() is called in the script. These defaults are also subject to change, so do not rely on them. They are listed here to help the script writer start from a known set of behaviors and then make customizations as desired. Hover your mouse pointer over the vehicle flag abbreviations to see the full flag name.

Vehicle Type:

Vehicle Parameter

None Sled Car Motorcycle Boat Sailboat Airplane Balloon
Vehicle Flags none lmu lro ndu huo lmu lro ndu huo lmd lmu lro ndu twz hwo lmd lmu ndu twz hwo lmd lmu ndu rtc rtw twz lro twz rtw
Linear Friction Timescale <0,0,0> <1000,1,1000> <100,0.1,10> <100,0.1,10> <200,0.5,3> <200,0.5,3> <200,10,5> <1,1,5>
Angular Friction Timescale <0,0,0> <1000,1000,1000> <100,100,0.3> <3,0.2,10> <10,1,0.1> <10,1,0.2> <1,0.1,0.5> <2,0.5,1>
Linear Motor Direction <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0>
Angular Motor Direction <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0>
Linear Motor Offset <0,0,0> <0,0,-0.1> <0,0,0> <0,0,-0.1> <0,0,0> <0,0,0> <0,0,0> <0,0,0>
Linear Motor Timescale <1000,1000,1000> <1000,1000,1000> <0.5,1,1> <0.5,1,1> <1,5,5> <1,5,5> <2,2,2> <1,5,5>
Angular Motor Timescale <1000,1000,1000> <1000,1000,1000> <0.2,0.2,0.05> <0.1,0.1,0.05> <0.2,2,0.1> <2,2,0.1> <1,2,1> <2,2,0.3>
Linear Motor Decay Timescale <0,0,0> <120,120,120> <10,2,2> <10,1,1> <1,10,10> <1,10,10> <60,60,60> <60,60,60>
Angular Motor Decay Timescale <0,0,0> <120,120,120> <0.3,0.3,0.1> <0.2,0.8,0.1> <0.3,0.3,0.1> <0.3,0.3,0.1> <8,8,8> <0.3,0.3,1>
Linear Wind Efficiency <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0.02,0.001,0> <0.1,0,0> <0.1,0.1,0.1>
Angular Wind Efficiency <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0,0,0> <0.1,0.01,0> <0.05,0,0> <0.01,0.01,0>
Hover Height 0 0 0 0 0.5 0.0001 0 5.0
Hover Efficiency 0 0 0 0 0.8 0.8 0.5 0.8
Hover Timescale 1000 1000 1000 1000 0.2 0.5 1000 10.0
Buoyancy 0 0 0 0 0 0 0 1.0
Linear Deflection Efficiency 0 1.0 1.0 1.0 0.5 0.5 0.5 0
Linear Deflection Timescale 1000 0.3 2.0 2.0 3.0 3.0 0.5 5.0
Angular Deflection Efficiency 0 1.0 0.5 0.8 0.5 0.5 1.0 0
Angular Deflection Timescale 1000 1.0 2.0 2.0 5.0 5.0 2.0 5.0
Vertical Attraction Efficiency 0 0.1 0.6 1.0 0.5 0.5 0.9 0.5
Vertical Attraction Timescale 1000 10.0 2.0 1.0 0.2 0.3 2.0 4.0
Banking Efficiency 0 0 -0.2 0.95 1.0 0.8 1.0 0.05
Inverted Banking Modifier 1.0 1.0 1.0 -0.5 1.0 -0.2 1.0 1.0
Banking Mix 0.0 1.0 1.0 0.5 0.5 0.5 0.7 0.5
Banking Timescale 1000 10.0 1.0 0.1 0.2 0.5 1.0
Mouselook Altitude PI/4 PI/4 PI/4 PI/4 PI/4 PI/4 PI/4 PI/4
Mouselook Azimuth PI/4 PI/4 PI/4 PI/4 PI/4 PI/4 PI/4 PI/4
Banking Azimuth PI/2 PI/2 PI/2 PI/2 PI/2 PI/2 PI/2 PI/2
Disable Motors Above 0 0 0.75 1.5 0 0 0 0
Disable Motors After 0 0 2.5 2.5 0 0 0 0
Reference Frame ZERO_ROTATION ZERO_ROTATION ZERO_ROTATION ZERO_ROTATION ZERO_ROTATION ZERO_ROTATION ZERO_ROTATION ZERO_ROTATION