Vehicle Scripting: Vehicle Definition

Structure of vehicle scripts, bits that go in it and bits that dont.

Introduction

The vehicle definition (or vscript) configures much of the behaviour & properties of the vehicle. These are stored in the base/vehicles directory.

The framework of the vehicle definition is created as follows:

vehicleDef "anansi" {
    ... lots of stuff goes here ...
}

In this case the definition is named "anansi". Configuration information goes between the braces, defining a many aspects of the vehicle.

Components

Things that affect the physical behaviour of the vehicle are called components, and are described in detail in the Components section. There can be a maximum of 32 of these.

Seating Positions

These define how many players can sit in the vehicle, the properties of the seating position and the camera views associated with each position. These are described in detail in the Positions & Views section. There can be a maximum of 8 positions in a vehicle.

Exit Positions

These define positions at which players can exit the vehicle. When a player exits the vehicle it will exit at the nearest exit point that is not blocked, so providing a number of these is important - otherwise a player may not be able to exit the vehicle when it is near an obstacle.

Exits are defined using joints in the MD5 of the vehicle.

Example:

exitDef {
    joint   "exit_left_1"
}

This adds the joint "exit_left_1" as an exit point.

Cockpits

These define select the entity definition and script object used for the vehicle's cockpit/s. Vehicle positions are linked to cockpits.

Example:

cockpit main {
    "def_cockpit"		"vehicle_anansi_cockpit"
    "scriptobject"		"vehicle_anansi_cockpit"
}

This defines a cockpit named "main". The "def_cockpit" key makes the cockpit spawn using the "vehicle_anansi_cockpit" entityDef. The "scriptobject" key specifies the script object name to use - this allows things like the steering wheel and other pieces of the cockpit to be animated in custom ways.

Configuring the entityDef used is detailed in the Cockpits section.

Lights

Lights can be added to a vehicle, for example the Cyclops has a glowing red light on it. These are created by adding a "lightDef" entry to the vehicle definition.

Keys:

• "group" - using this allows lights to be grouped and enabled and disabled as a group by script & code. The group must be a number (eg 0, 1, 2, 3)
• "joint" - selects the joint of the vehicle that the light is to be placed at
• "lightType" - this can be "standard" or "brake".
  • In standard mode the light will be on if the atmosphere is tagged as being nighttime. This also sets shader parm 5 of the vehicle.
  • In brake mode the light will be on if the vehicle is braking. This also modifies shader parm 6 of the vehicle.
• "shader" - selects the material to use for the light
• "color" - the color of the light
• "radius" - the radius of the light
• "pointLight" - sets this as a point light
• "maxVisDist" - cutoff distance for the visibility of this light
• "noSelfShadow" - causes the light to not self shadow
• "offset" - offsets the light's position from the joint

TODO: Verify these, clarify the operation!

• "target" - used for building the frustum of the light: the point it is targeting when using a spotlight
• "up" - used for building the frustum of the light: the up vector of the frustum
• "right" - used for building the frustum of the light: the right vector of the frustum
• "start" - used for building the frustum of the light: the start vector of the frustum
• "end" - used for building the frustum of the light: the end vector of the frustum

Example:

lightDef {
    joint           "driver_cam"
    lightType       "standard"
    color           ( 3 0 0 )
    group           0
    noSelfShadow
    shader          "lights/headlights1"
    right           ( 0 960 0 )
    up              ( 0 0 640 )
    offset          ( 50 0 0 )
}

Engine Sounds

Sounds can be added to the vehicle that are based on the vehicle's velocity. These are faded in & out and pitch shifted based on the speed of the vehicle.

Keys:

• "sound" - the name of the key on the entityDef that points to the sound shader to use
• "low" - the low speed (units per second)
• "high" - the high speed (units per second)
• "volumeMin" - the volume at the low speed (DB)
• "volumeMax" - the volume at the high speed (DB)
• "lowFrequency" - the pitch shift at the speed low + frequencyChangeStart
• "highFrequency" - the pitch shift at the high low + frequencyChangeStop
• "fadeIn" - fades in the sample at the speed low + fadeIn (units per second)
• "fadeOut" - fades out the sample at the speed high - fadeOut (units per second)
• "joint" - the joint the sound plays on

Using multiple of these definitions you can create complex sound cross-fades to achieve interesting effects.

Example:

engineSoundDef {
    sound "snd_treads"
    low 5
    high 1000
    volumeMin -60
    volumeMax -15
    fadeIn 200
    fadeOut 0
    lowFrequency 0.8
    highFrequency 1.4
    frequencyChangeStart 0
    frequencyChangeStop 1500
}

This example is taken from the Titan, and controls the squeaky tread sound.