Vehicle Scripting: Components

From Mod Wiki
Revision as of 16:50, 15 October 2007 by 192.168.0.142 (talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Detail each of the vehicle components and their configuration parameters. Eg "part", "mass", "wheel", "pseudoHover", etc etc etc.

The physical behaviour of a vehicle is defined in its vehicle definition using a series of components. This page lists the parts available, their function, and the options for defining each.

Common Keys & Functionality

Some behaviour and the keys describing the behaviour are common to nearly all components. The exceptions to this are marked.

Keys:

  • "name" - a string to describe the components. Sometimes used to reference specific parts to be manipulated (eg the thrusters on the Platypus)
  • "health" - can be used to allow component to be destroyed (eg wheels)
  • "def_brokenPart" - specifies the entityDef for the entity to be spawned when the component is blown off
  • "damageScale" - scales the amount of damage done to the vehicle when this component is damaged. Defaults to 1.
  • "collisionScale" - scales the amount of damage done to the vehicle when this component is damaged due to collisions. Defaults to 1.
  • "collisionMinSpeed" - minimum speed of collision that will cause collision damage. Defaults to 256.
  • "collisionMaxSpeed" - speed of collision at which damage will reach full strength. Defaults to 1024.
  • "noAutoHide" - setting this will prevent the visible surfaces of the component automatically being hidden when it is detached (ie destroyed)
  • "flipMaster" - selects this part as the "master" part for flipping behaviour on destruction. Other parts of the vehicle will be blown off with velocities relative to the master. The main part of the body is generally used for this.
  • "flipPower" - scales the amount of "flipping" force the component will take when it is blown off. Defaults to 5.
  • "surface*" - the surface/s associated with the part (eg visual & shadow surface)

Basic Parts

part

A "part" is the simplest kind of vehicle component. A part is a rigid body that is part of the physics representation of the vehicle.

TODO: REWRITE THIS IN A BETTER FORMAT

The shape of this rigid body can be defined in two ways:

  • A bounding box
    The "mins" vector key defines the minimum extents of the rigid body.
    The "maxs" vector key defines the maximum extents of the rigid body.
    The "type" string key allows you to select between 3 different shapes:
    • Box
    This is the default. This is a simple box shape filling the bounds.
    • Cylinder
    This creates a prism with a number of sides.
    The "sides" key allows you to specify the number of sides.
    The "angleOffset" key allows you to change the angle that the first side will start at, effectively rotating it about the axis of the cylinder whilst keeping it within the bounds specified.
    The "option" key allows you to select which axis the cylinder is about. 0 = z-axis, 1 = x-axis, 2 = y-axis.
    • Frustum
    This is a box that has had the top rectangle enlarged or shrunk.
    The "topOffset" key offsets the top of the box outwards in the x & y axes. Using a negative value here will shrink the top rectangle.
  • A custom collision model
    The "cm_model" key specifies a model (eg an LWO) to use. This must be convex.


Other Keys:

  • "mass". This defines the weight of the part. Note that this will affect the center of mass and the inertia tensor of the vehicle, which impacts how it will handle & behave in the game. This must be greater than 0, and defaults to 1.
  • "offset". This is a vector key that defines the offset from the origin of the vehicle that the collision model will be at.
  • "contactFriction". This is a vector key, defining the friction in each axis from contacts. This must be between 0 & 1, and defaults to "0 0 0".
  • "buoyancy". This value represents the buoyancy of the part when submerged in water. Recommended values for this are between 0 & 1, and defaults to 0.01.
  • "waterDrag". This value represents the drag on the vehicle when submerged in water. Recommended values for this are between 0 & 1, and defaults to 0.
  • "noCollision". This can be used to make the part be non-solid for collision detection, meaning that objects can pass through it and it can pass through other objects.
  • "joint". This is used to calculate the bounds of the part. TODO: Check this.


Examples:

part {
    "cm_model"               "models/vehicles/edf_badger/parts/collision.lwo"
    "mass"                   "1000"
    "contactFriction"        "0.4 0.4 0.4"
    "health"                 "-1"
    "collisionScale"         "0.5"
    "buoyancy"               "0.14"
}

This is the definition for the main body of the Badger, which uses a custom collision model.

part {
    "mins"               "-48 -30 24"
    "maxs"               "58 30 64"
    "type"               "frustum"
    "topOffset"          "-5"
    "mass"               "100"
    "contactFriction"    "0.4 0.4 0.4"
    "health"             "-1"
    "collisionScale"     "0.5"
    "buoyancy"           "0.025"
}

This is the definition for the main body of the Husky, which uses a slightly frustum shaped model.

mass

This component is effectively a point mass. This has no collision, but modifies the vehicle's center of mass and inertia, so this is useful for altering a vehicle's handling. For example boats benefit from having a point mass added below the actual collision object to make them more stable (much like the keel of a yacht).

Keys:

  • "mass" - the mass of the component
  • "origin" - the position relative to the origin of the vehicle


Example:

mass {
    "origin"        "16 0 30"
    "mass"          "4000"
}

This is the mass used to balance the Badger.

simplePart

This component is, as the name suggests, very simple. It has no physics representation or impact to the handling of a vehicle. It is merely a set of surfaces on the model that are associated with a joint. This part is used to allow for parts of the vehicle to be blown off (eg the mirrors on the Armadillo).

Example:

simplePart {
    "name"              "body"
    "joint"             "origin"
    "def_brokenPart"    "part_vehicle_husky_body"
    "health"            "0"
    "flip_power"        "20"
    "flip_master"       "1"
}

This is the component for the broken version of the main body. As it is the flip master the other parts of the vehicle will get velocities relative to this part. The entityDef for the broken part uses a handy template to define most of the parameters used:

entityDef part_vehicle_husky_body {
    useTemplate templates/vehicles/destroyedParts <
            "models/vehicles/edf_husky/parts/body.lwo",
            "20 1900 0",
            "100 0 0",
            "vehicles/misc/debris/metal_med"
        >

    "climate_skin_key"     "husky"
    "priority"             "3"
}

The "priority" parameter of the part is used to throttle the amount of debris that can be present at once. The priority value can be from 0 to 3, with 0 being the least important (controlled by g_maxTransportDebrisLow) and 3 being the most important (controlled by g_maxTransportDebrisExtraHigh).

scriptedPart

This component is the same as simplePart, however it can have a script associated with it. This script can have several callbacks from code implemented to do custom things.

Keys:

  • "scriptObject" - the name of the script object to be used


The following callbacks are used:

void OnPostDamage( entity attacker, float oldHealth, float health )

This is called when the component is damaged.

void OnKilled()

This is called when the component is destroyed.

Complex Parts

airBrake

This component acts, as the name suggests, to slow the vehicle. It reacts to the speed of the vehicle in the forward direction, applying a force to slow the vehicle down. This does NOT share the common keys.

This component needs to be activated and deactivated in code using the "Enable" & "Disable" functions.

Keys:

  • "factor" - the amount of the velocity that is opposed. This effectively scales the strength of the brake. This value should be between 0 and 1.
  • "max_speed" - the maximum speed that will be opposed by the airbrake.
  • "name" - the name of the component.

Example:

airBrake {
    "name"          "air_brake"
    "factor"        "0.75"
    "max_speed"     "100"
}

This is the air brake from the Anansi.

antigrav

This component is specific to the Icarus. It is purely for appearances and does not affect the handling at all. It governs the rotating "fans", tail "vanes" and effects of the Icarus.

Keys:

  • "fanJoint" - the joint for fan rotation
  • "tailJoint" - the joint for tail rotation
  • "fan_speed_multiplier" - vehicle speed multiplied by this in fan speed calculation. Defaults to 0.9.
  • "fan_speed_offset" - added to the calculated fan speed (ie - minimum fan speed). Defaults to 500.
  • "fan_pitch_max" - maximum fan speed. Defaults to 800.
  • "fan_ramp_rate" - acceleration with which fan speed ramps up & down. 1 is instant. Defaults to 0.1.
  • "rotAxis" - this selects the axis of the joint to be rotated with forward & backward movement.
  • "tailUpAxis" - this selects the axis of the tail joint to be influenced by up & down movement. Defaults to 0.
  • "tailSideAxis" - this selects the axis of the tail joint to be influenced by side to side movement. Defaults to 2.
  • "effect" - the effect key of the parent to use for the engine effect. Defaults to "fx_engine".
  • "effect_boost" - the effect key of the parent to use for the boosting effect. Defaults to "fx_engine_boost".


Vehicle entityDef Keys:

  • "fx_groundeffect" - the effect played when near the ground


Example:

antigrav {
    "joint"           "r_engine"
    "fanJoint"        "r_fan"
    "tailJoint"       "r_tail"
    "effect"          "fx_engine"
    "effect_boost"    "fx_engine_boost"
    "frontAxis"       "0"
    "rotAxis"         "1"
    "tailUpAxis"      "0"
    "tailSideAxis"    "1"
}

This is the antigrav pod for right engine of the Icarus.

antiPitch

This adds a physical constraint to the vehicle which tries to prevent it from pitching about its side axis. This is a soft constraint, so it will not "explode" when the constraint is violated but it cannot guarantee that the pitch will not exceed the limits.

Keys:

  • "angle_start" - the angle in degrees from the vertical at which the constraint will start to apply
  • "angle_end" - the angle in degrees from the vertical at which the constraint will reach its maximum strength
  • "strength" - the strength of the constraint at the end angle. 0 -> 2 is the recommended range for this key.
  • "needs_ground" - if this constraint requires the vehicle to be on the ground to be active. Defaults to 1.

The constraint will be active when any of these conditions is true:

  • "needs_ground" is 0
  • The vehicle is touching the ground
  • The vehicle is in the water
  • The angle of pitch exceeds "angle_start"

The strength of the constraint (the tendency for the vehicle not to pitch) linearly increases from zero after "angle_start" is exceeded, reaching a maximum of "strength" at "angle_end".

The constraint will not attempt to correct pitch at a rate greater than 5 degrees per frame, to prevent crazy movements being generated. TODO: Make this configurable.


Example:

antipitch {
    "angle_start"      "5"
    "angle_end"        "25"
    "strength"         "1"
    "needs_ground"     "0"
}

This is the antipitch constraint from the Desecrator.

antiRoll

This is identical to the "antiPitch" component but opposes the vehicle's roll instead of pitch.

dragPlane

This part acts like a plane in the water that causes drag on the body. This is used by the Platypus to make it react as though the bow is being pushed up by the water in front of it when at speed.

Keys:

  • "origin" - the origin of the plane
  • "normal" - the normal of the plane. Only velocity against the normal causes drag.
  • "double_sided" - if this is set then velocity in both directions causes drag
  • "coefficient" - the drag force is equal to the normal velocity squared multiplied by the coefficient
  • "max_force" - the maximum drag force magnitude
  • "min_force" - the minimum drag force magnitude - below this the drag plane does not apply any force at all
  • "use_angle_scale" - if enabled, the plane's force will be scaled based on the pitch of the vehicle. This roughly emulates the surface area in contact with the water being reduced.


Example:

dragPlane {
    "name"                "hull_front"
    "origin"              "0 0 0"
    "normal"              "0.3 0 -1"
    "coefficient"         "120"
    "max_force"           "1150000"
    "use_angle_scale"     "1"
}

This is the drag plane from the Platypus.

hover

This part is a very specific part for the Desecrator hover pads. They are purely for appearances and do not affect handling in any way. Refer to desecrator.vscript for examples.

Keys:

  • "direction" - the direction relative to the vehicle that it searches in to find things to latch lightning to
  • "distance" - distance to search
  • "min_angles" - the minimum angles of rotation for the pad
  • "max_angles" - the maximum angles of rotation for the pad
  • "adaption_speed" - the speed at which angles of rotation will change
  • "shaderParmIndex" - shader parm index used to indicate engine enabled/disabled

Vehicle entityDef Keys:

  • "fx_hoverpad" - the lightning effect
  • "ti_lightning" - target info to filter invalid entities for lightning to attach to

hurtZone

This is similar to the "part" component in many respects (and keys), however it is not a true part of the vehicle's physics representation. It cannot have buoyancy, friction, drag or mass. It only collides with players, and only players collide against it. This is used to block off the area underneath a vehicle so that it squashes players that the vehicle hits and players can't crawl under it, without affecting the collision of the vehicle against the ground surface.

Example:

hurtZone {
    "mins"       "-92 -50 0"
    "maxs"       "104 50 36"
}

This is the hurtzone beneath the body of the Badger.

pseudoHover

This component controls the motion of the Desecrator. This creates constraints to move the vehicle into positions and orientations calculated using information about the height of the vehicle off the ground and traces in several directions. Refer to desecrator.vscript for an example.

Keys:

  • "height" - ideal hover height. Defaults to 60.
  • "height_park" - ideal height when in park (siege) mode. Defaults to 30.
  • "repulsion_speed_height" - when the height above the ground becomes lower than this it will repulse the ground more strongly
  • "repulsion_speed_coeff" - acceleration away from the surface when under "repulsion_speed_height" is equal to velocity multiplied by this
  • "repulsion_speed_max" - acceleration away from the surface when under "repulsion_speed_height" will not exceed this
  • "yaw_coeff" - yawing force
  • "fwd_coeff" - forward/backward movement force
  • "fwd_speed_damping_coeff" - coefficient used to scale "friction"
  • "fwd_speed_damping_pow" - power factor used to ramp "friction"
  • "fwd_speed_damping_max" - the limit of the "friction"
  • "front_cast" - the position in the x axis of the starting point for the two casts from the front of the vehicle
  • "back_cast" - the position in the x axis of the starting point for the two casts from the rear of the vehicle
  • "cast_offset" - the position in the z axis of the starting point of the casts
  • "max_slope" - when the slope of the surface (in degrees) exceeds this the allowed acceleration up the slope will be ramped down, and dropped to zero when the slope exceeds max_slope * 2
  • "slope_dropoff" - the rate at which the allowed acceleration up the slope is reduced
  • "park_time" - the amount of the time it takes to transition in/out of park/siege mode


Vehicle entityDef Keys:

  • "joint_park_fx" - joint the parking effect plays from. Defaults to "origin".
  • "fx_park_engage" - effect played when vehicle goes into park mode.
  • "fx_park_disengage" - effect played when vehicle comes out of park mode.
  • "snd_park_engage" - sound played when vehicle goes into park mode.
  • "snd_park_disengage" - sound played when vehicle comes out of park mode.

rotor

This component acts as a rotor for helicopter style vehicles. It provides forces that vary with user input to allow a flying vehicle to be controlled.

Keys:

  • "rotortype" - this can either be "main" or "tail". The two types of rotor behave differently - "main" represents the main lift rotor of the vehicle, which does the pitch & roll steering, whereas "tail" provides no upwards force but acts to yaw the vehicle left and right.
  • "lift" - the magnitude of force of the rotor
  • "maxPitchDeflect" - the maximum pitch deflection of the vehicle before the rotor will treat it as being deflected. This works like a deadzone.
  • "maxYawDeflect" - similar to "maxPitchDeflect" but for roll. WARNING Deceptively named! This affects roll, not yaw!
  • "cyclicBankRate" - rate at which the bank control affects the bank of the rotor
  • "cyclicPitchRate" - rate at which the pitch control affects pitch of the rotor
  • "force_side_scale" - scales the side & forward axes - effectively increases the velocity picked up due to tilting the vehicle
  • "z_offset" - offsets the position that the force is applied
  • "num_blades" - the number of blade joints - joints that are rotated to give the appearance of rotor blades


Blade Keys (where [num] is from 1 to the number of blades specified with "num_blades"):

  • "blade[num]_joint" - the joint for blade [num]
  • "blade[num]_speedScale" - the speed of the rotor is scaled by this to get the speed of rotation of the joint
  • "blade[num]_isYaw" - For tail rotors this makes the rotor get rotated in the yaw instead of pitch (eg for the Bumblebee where the tail rotor faces vertically)


Examples:

rotor {
    "health"             "-1"
    "joint"              "center_rotor"
    "rotortype"          "main"
    "num_blades"         "1"
    "blade1_joint"       "center_rotor"
    "blade1_speedScale"  "1"
    "lift"               "1"
    "cyclicPitchRate"    "500000"
    "cyclicBankRate"     "150000"
    "force_side_scale"   "2"
    "maxPitchDeflect"    "5"
    "maxYawDeflect"      "5"
}

This is the main rotor definition for the Anansi.

rotor {
    "health"                "-1"
    "joint"                 "tail_rotor"
    "num_blades"            "1"
    "blade1_joint"          "tail_rotor"
    "blade1_speedScale"     "1"
    "rotortype"             "tail"
    "lift"                  "-4000000"
    "z_offset"              "-7"
    "noCollision"           "1"
}

This is the tail rotor definition for the Anansi.

rudder

This is a specialization of the "dragPlane" component. The origin & coefficient of this part are modified based on the input values to cause steering.


Example:

rudder {
    "name"             "rudder"
    "origin"           "0 0 0"
    "normal"           "0 1 0"
    "coefficient"      "150"
    "max_force"        "500000"
    "double_sided"     "1"
}

This is the rudder definition from the Platypus.

suspension

This part represents a shock absorber with a start point and an end point. It can have friction on the end. This is useful for "sprung" landing gear that does not have wheels, for example on the Tormentor.

Keys:

  • "joint" - The "foot"
  • "startJoint" - The start point
  • "contactFriction" - Friction coefficients for each axis of the "foot". Defaults to "0 0 0".
  • "aggressiveDampening" - Makes it more aggressively try to dampen out any velocity
  • "suspensionVelocityScale" - Only used when "aggressiveDampening" is set - scales how aggressively the dampening is. Defaults to 1.
  • "suspensionKCompress" - Compression coefficient
  • "suspensionDamping" - Damping coefficient
  • "radius" - The "radius" of the foot
  • "suspension" - Points to the string map used for the suspension IK setup. Described in detail here.

thruster

This component imparts a force on the vehicle. This does NOT share the common keys listed. The amount of the thrust that is applied needs to be set in code or script using the SetThrust function or setThrust script event.

Keys:

  • "name" - the name of the part
  • "direction" - the direction in the local space of the vehicle that the thrust will be in. Eg '1 0 0' will push the vehicle forwards.
  • "fixed_direction" - the direction in world space that the force will be in. Eg '0 0 1' will give a thrust upwards, no matter the vehicle's orientation. This is combined with the thrust given by the "direction" key.
  • "origin" - the position in the local space of the vehicle that the thrust will be applied.
  • "force" - the magnitude of the thrust force applied
  • "reverse_scale" - the thrust is scaled by this value when the thrust is reversed (eg when boosting in reverse in the Tormentor)
  • "need_water" - if this is enabled then the thruster will only function when under water.

Example:

thruster {
    "direction"      "1 0 0"
    "origin"         "-28 64 44.95"
    "force"          "400000"
    "name"           "left_thruster"
}

This is the left thruster for the Anansi.

track

This part creates a series of wheels. These wheels all rotate in the same direction. A start & end wheel (separate components) are also linked to the track. The keys are the same as those of wheel (all of the suspension parameters etc are shared between all the wheels of the track), with the following additional keys.

Keys:

  • "direction" - the local direction vector used to calculate the speed to pass to the shader
  • "shaderParmIndex" - the shader parm index to take the speed of the wheel (used to scroll the track texture)
  • "num_true_wheels" - the number of wheels that have physics
  • "start_wheel" - the name of the component representing the start wheel of the track
  • "end_wheel" - the name of the component representing the end wheel of the track


Wheel Keys (where [num] is between from 1 to "num_true_wheels" + 1):

  • "wheel_joint_[num]" - the wheel joint for this wheel number
  • "wheel_suspension_[num]" - the suspension joint for this wheel number
  • "wheel_trace_index_[num]" - the index in the trace order for this wheel (used for trace rate throttling)


Example:

track {
    "direction"               "1 0 0"
    "joint"                   "right_wheel_rotation_04"
    "shaderParmIndex"         "10"

    "num_true_wheels"         "5"

    "start_wheel"             "right_wheel_rotation_01"
    "end_wheel"               "right_wheel_rotation_08"

    "wheel_joint_2"           "right_wheel_rotation_02"
    "wheel_suspension_2"      "right_wheel_dynamix_02"

    "wheel_joint_3"           "right_wheel_rotation_03"
    "wheel_suspension_3"      "right_wheel_dynamix_03"

    "wheel_joint_4"           "right_wheel_rotation_04"
    "wheel_suspension_4"      "right_wheel_dynamix_04"

    "wheel_joint_5"           "right_wheel_rotation_05"
    "wheel_suspension_5"      "right_wheel_dynamix_05"

    "wheel_joint_6"           "right_wheel_rotation_07"
    "wheel_suspension_6"      "right_wheel_dynamix_07"

    "wheel_trace_index_2"     "5"
    "wheel_trace_index_3"     "2"
    "wheel_trace_index_4"     "4"
    "wheel_trace_index_5"     "8"
    "wheel_trace_index_6"     "1"

    useTemplate templates/vehicles/titan/wheel_behavior<>
    "base_org_offset"         "0 7 0"
}

This is the right track from the Titan. A template is used to define the physical characteristics of the wheels:

template templates/vehicles/titan/wheel_behavior {
    parameters< >
    text {
        "slowonLeftRightParm"           "1"

        "drive"                         "1"
        "noRotation"                    "1"
        "contactFriction"               "0.3 0.7 0"

        "health"                        "-1"

        "radius"                        "20"
        "footprint"                     "30"

        "suspensionUpTrace"             "12"
        "suspensionDownTrace"           "28"
        "suspensionKCompress"           "35000"
        "suspensionDamping"             "0.1"
        "suspensionVelocityScale"       "200"
        "suspensionBase"                "250000"
        "suspensionRange"               "32"
        "suspensionMaxRestVelocity"     "2.5"

        "traction_sand"                 "0.85"
        "traction_mud"                  "0.85"
        "traction_grass"                "1.00"
        "traction_stone"                "0.85"
    }
}

vtol

This part is used to animate the "engines" and effects of the Tormentor. It uses a "shoulder" joint and an "elbow" joint. The shoulder joint is rotated based on the pitch of the vehicle, and the elbow joint is rotated based on the roll of the vehicle.

Keys:

  • "joint" - The shoulder joint
  • "shoulderAngleScale" - Scales the pitch of the vehicle to get the angle of the shoulder joint
  • "shoulderBounds" - The minimum & maximum angle for the shoulder joint to be rotated by
  • "shoulderAxis" - The axis of the shoulder joint to rotate
  • "elbowJoint" - The elbow joint
  • "elbowAngleScale" - Scales the roll of the vehicle to get the angle of the elbow joint
  • "elbowBounds" - The minimum & maximum angle for the elbow joint to be rotated by
  • "elbowAxis" - The axis of the elbow joint to rotate
  • "effectJoint" - Joint that the the effect is played on

Keys used from the vehicle's entityDef:

  • "fx_vtol" - The effect played at "effectJoint"

wheel

This component represents a wheel & the wheel's suspension. Wheels can be powered and steered, and can have brakes. Kinetic friction of the wheel is assumed to be 80% of the static friction. TODO: Make this adjustable in vscript.

Keys:

  • "turn" - can be steered
  • "inverseturn" - can be steered, but steers in reverse (eg for rear wheel steering)
  • "noPhysics" - has no physical effect - only visual
  • "drive" - powered by the engine
  • "noRotation" - does not visibly rotate
  • "slowsOnLeft" - causes this wheel to cut its speed by half when steering left (to make up for the lack of a differential)
  • "slowsOnRight" - causes this wheel to cut its speed by half when steering right (to make up for the lack of a differential)
  • "hasHandBrake" - this wheel is locked when handbrake is applied
  • "radius" - the wheel's radius
  • "contactFriction" - the friction of the wheel against the ground (forward, side & up). Effectively the static friction of the wheel.
  • "steerScale" - the steering angle is scaled by this. Defaults to 1.
  • "brakingForce" - the amount of stopping force able to be applied when braking. Defaults to 500000.
  • "handBrakeSlipScale" - scales the lateral slip velocity when under handbraking to adjust the ease of sliding (used to emulate change from static friction to kinetic friction when rear wheels lock under handbraking). Defaults to 1.
  • "maxSlip" - the amount of lateral slip velocity required for full sliding friction (kinetic friction) to be applied. Defaults to 100000.
  • "setSteering" - this wheel sets the steering angle used for visual stuff eg steering wheel in the cockpit
  • "wheelSpinForceThreshhold" - if the motor force divided by the traction available on the surface exceeds this the wheel is considered to be spinning (produces spinning effects)
  • "wheelSkidVelocityThreshold" - if the lateral velocity of the wheel exceeds this speed the wheel is considered to be skidding (produces skidding effects). Defaults to 150.
  • "base_org_offset" - wheel suspension traces & reaction forces are offset from the joint origin of the wheel by this value (to allow non-ideal vehicle geometries to provide good handling)
  • "localRotation" - changes the wheel rotation axis to be the local axis of the wheel joint
  • "footprint" - the size of the wheel
  • "stroggTread" - causes the skidmarks to use a special Strogg image - ie for the Hog
  • "traction_*" - traction scale values for each of the surface types. All default to 1.
  • "suspension" - points to the stringMap configuring the suspension's IK. Described in detail here.


Suspension tuning keys:

  • "suspensionUpTrace" - Suspension trace starts at this distance above the joint
  • "suspensionDownTrace" - Suspension trace ends at this distance below the joint
  • "suspensionRange" - The distance range over which the supsension can move
  • "suspensionKCompress" - Compression coefficient - multiplied by the square of the amount of value to find the spring force
  • "suspensionBase" - Base spring force - added to the spring force resultant from the above
  • "suspensionVelocityScale" - Used to scale amount of effect the suspension's velocity has on the force resultant from the constraint
  • "suspensionDamping" - Damping coefficient - adjusts the opposition to suspension velocity
  • "suspensionMaxRestVelocity" - If the suspension's velocity is less than this it is considered to be "at rest"
  • "aggressiveDampening" - Changes the velocity dampening method. With it on it will much more aggressively oppose suspension velocity.
  • "slowScaleSpeed" - Speed below which the parameters are scaled to assist settling
  • "slowScale" - Various parameters are scaled by this value to assist the vehicle to settle
  • "hardStopFrames" - When the vehicle "bottoms out" (the suspension reaches the top of its allowed travel) the constraint changes to "hard-stop" mode, doing whatever is necessary to stop the suspension compressing further. This adjusts the number of frames it allows the constraint to act over - effectively "softening out" the bottoming behaviour, making it a less jarring ride over bumpy surfaces.


Keys used from the vehicle's entityDef:

  • "fx_wheeldust_*" - wheel dust effects for various surface types
  • "fx_wheelspin_*" - wheel spin effects for various surface types
  • "fx_skid_*" - wheel skid effects for various surface types


Example: We tend to use templates for wheels to prevent having to repeat the same parameters for each wheel, as that is prone to human error. In the case of the Badger we use one base template to define all of the common parameters, and use template parameters to construct many specific parameters eg the surface & joint names. This template then uses another template based on the front/back template parameter to add the specific properties for the front/back wheels. Most of the other vehicles follow the same model.

Templates:

template templates/vehicles/badger/wheel_behavior {
    parameters< FrontBackParm, LeftRightParm >
    text {
        "name"                          "FrontBackParm LeftRightParm Wheel"
        "surface1"                      "m_FrontBackParm_LeftRightParm_wheel"
        "surface2"                      "s_FrontBackParm_LeftRightParm_wheel"
        "def_brokenPart"                "part_vehicle_badger_FrontBackParm_LeftRightParm_wheel"
        "joint"                         "FrontBackParm_LeftRightParm_wheel"
        "suspension"                    "vehicle_badger_FrontBackParm_LeftRightParm_suspension"

        "drive"                         "1"
        "health"                        "100"
        "slowonLeftRightParm"           "1"

        "footprint"                     "10"

        "wheelSpinForceThreshhold"      "400000"

        "slowScale"                     "1"
        "slowScaleSpeed"                "400"

        "radius"                        "20"

        "suspensionUpTrace"             "18"
        "suspensionDownTrace"           "29"
        "suspensionKCompress"           "20000"
        "suspensionDamping"             "0.1"
        "suspensionVelocityScale"       "150"
        "suspensionBase"                "250000"
        "suspensionRange"               "15"

        "brakingForce"                  "500000"
        "maxSlip"                       "400"

        useTemplate templates/vehicles/badger/wheel_FrontBackParm< "LeftRightParm" >
    }
}

template templates/vehicles/badger/wheel_front {
    parameters< LeftRightParm >
    text {
        "turn"                          "1"

        "contactFriction"               "0 0.7 0"
    }
}

template templates/vehicles/badger/wheel_rear {
    parameters< LeftRightParm >
    text {
        "contactFriction"               "0 0.6 0"

        "hasHandbrake"                  "1"
        "handBrakeSlipScale"            "10"
    }
}

The wheel component definition then becomes as simple as:

// front left wheel
wheel {
    useTemplate templates/vehicles/badger/wheel_behavior< "front", "left" >
    "control_steering"				"1"
    "base_org_offset"				"8 7 0"
}

// front right wheel
wheel {
    useTemplate templates/vehicles/badger/wheel_behavior< "front", "right" >
    "base_org_offset"				"8 -7 0"
}

// back left wheel
wheel {
    useTemplate templates/vehicles/badger/wheel_behavior< "rear", "left" >
    "base_org_offset"				"0 7 0"
}

// back right wheel
wheel {
    useTemplate templates/vehicles/badger/wheel_behavior< "rear", "right" >
    "base_org_offset"				"0 -7 0"
}