Vehicle Scripting: Positions & Views

Discuss how positions & views are set up. Detail the options that go with positions. Detail the view types & configuration parameters for the view types.

Introduction

Positions define how many players can be in a vehicle, and the properties of the positions they sit. There must be one position for every player that can be in a vehicle, and each must have associated views.

A position is added to the vehicleDef by adding a positionDef block:

positionDef {
    ... properties here ...
}

Properties:

• name sets the string used to identify the view
• hudname sets the localized string used to display on the player's HUD.
• The data block contains a series of keys used to configure various properties of the position. These are described in the Position Configuration section below.
• view blocks are used to describe camera views the position can use. These are described in the View Configuration section below.
• ik blocks set up IK systems that are to be influenced by this position. These are described in the IK section (??)
• weapon blocks set up weapons that are to be linked to this position. These are described in the Weapons article.

Position Configuration

Positions are configured in the data block using a series of keys.

Keys:

• "require" - requirements allowing a vehicle position to exclude players from getting in
• "tt_blocked" - tooltip decl to display when a player can't enter a vehicle due to not meeting the requirements
• "view_offset_rate" - rate at which the view angle will be offset when steering - used to allow the view to automatically "look into" a corner. Defaults to 0.
• "max_view_offset" - the maximum angle the view will be offset by when steering. Defaults to 0.
• "joint_attach" - joint at which the player is positioned. Defaults to "origin".
• "joint_icon" - joint to display the player icons at
• "player_anim" - player animation group used. Defaults to "VehicleDefault". Script functions player::Torso_* & player::Legs_* (where * is player_anim) are called to drive the player animations when the player enters the position.
• "show_player" - player in the position is visible. Defaults to 0.
• "min_z_frac" - the minimum value of the vehicle's up vector's up component allowable - beyond this the player is ejected. Used in the Husky to make the driver fall off when the vehicle tips over, for example. Defaults to -2.
• "use_fallback" - player should be ejected safely when the vehicle is destroyed. Defaults to 0.
• "take_damage" - player should be able to take damage. Defaults to 0.
• "player_stance_crouch" - player's hitbox uses the crouch stance height. Defaults to 0.
• "player_height" - custom height for the player's hitbox. If set to zero it uses the default height for the player's stance. Defaults to 0.
• "allow_weapon" - allows the player to use their hand held weapon. Defaults to 0.
• "adjust_body_angles" - allows normal body angle adjustment to occur - the stepped turning of the head, then torso, and finally legs that happens when on foot. Defaults to 0.
• "reset_view_on_enter" - resets the player's view yaw to zero when they get into this position. Defaults to 1.
• "damage_scale" - scaler to damage the player takes. Defaults to 1.
• "ability*" - extra abilities players in this position have.
• "cockpit" - name of the vehicle cockpit to be used by this position.
• "stat_name" - the statistic associated with this position, used for tracking how long the player spends in the position.

View Configuration

Each position can have a number of views that the player can cycle through.

Properties

There are a number of properties each view has, described below.

• type - The view mode. Each mode is detailed in the View Modes section below.
• eyeJoint - Joint used to define the position of the view.
• eyeJointPivot - Joint used by some views to define where the view pivots around when aiming.
• interior - Flags this as an "interior" view, and plays the vehicle's interior sounds. Defaults to false.
• thirdPerson - Flags this as a "third person" view. Defaults to false.
• hideVehicle - Hides the vehicle's model when in this view. Defaults to false.
• showCockpit - Show the cockpit assigned to this position when in this view. Defaults to false.
• playerShadow - Display the player's shadow when in this view. Defaults to false.
• noCockpitShadows - Don't draw the cockpit's shadows in this view. Defaults to false.
• noShowOtherPlayers - Don't draw other passengers' player models in this view. Defaults to false.
• hideHud - Don't display the HUD in this view. Defaults to false.
• hideDecoyInfo - Don't display the decoy charge bar on the HUD in this view. Defaults to false.
• showTargetingInfo - Display the gunner targeting overlay in this view. Defaults to false.
• showCrosshairInThirdPerson - Shows the crosshair in a thirdPerson mode. Defaults to false.
• followPitch - Used by "pivot" view mode. When enabled the view will pivot about the pivot joint when pitching. Defaults to false.
• followYaw - Used by "pivot" view mode. When enabled the view will pivot about the pivot joint when yawing. Defaults to false.
• tophatRequired - Player needs to hold down _tophat to aim with this view. Defaults to false.
• disableDamping - Disables view axis damping for "smooth", "pivot" and "freepivot" views. Defaults to false.
• autoCenter - Autocenters the view aim after 2.5 seconds. Defaults to false.
• foliageDepthHack - Amount of depth hack to prevent foliage being drawn inside the vehicle cockpit. Defaults to 0.
• noMatchPrevious - Prevents the view trying to match the previous view direction when player switches position in a vehicle. Defaults to false.
• cameraDistance - Distance backward from the eye joint position. Defaults to the value of pm_thirdPersonRange.
• cameraHeight - Distance upward from the eye joint position. Defaults to the value of pm_thirdPersonHeight.
• cameraFocus - Distance ahead of the vehicle to focus on. Defaults to 512.
• cameraFocusHeight - Distance above the vehicle to focus on. Defaults to 0.
• dampSpeed - Speed at which camera responds to movement - from 0 to 1. Defaults to 0.25.
• dampCopyFactor - How much of the vehicle movement is damped for each axis - from 0 to 1. Defaults to "0 1 0"
• sensitivityYaw - Name of the cvar used to store the custom yaw sensitivity (eg "m_helicopterYaw").
• sensitivityPitch - Name of the cvar used to store the custom pitch sensitivity (eg "m_helicopterPitch").
• zoomOutSound - Sound played when zooming out.
• zoomInSound - Sound played when zooming in.
• zoomTable - Points to table of zoom values (FOVs) used by this view.

View Modes

There are quite a few different view modes available, each behaving in a subtly different manner. Some aim in vehicle space - meaning that as the vehicle turns the view also turns without the user applying input - and some aim in world space - meaning that as the vehicle turns the view remains stationary. The latter is useful for vehicle gunner positions to make it easier to aim.

Available Modes:

• "standard" - This is the default view mode, which does some simple dampening and aims in vehicle space.
• "pivot" - This mode dampens similarly to "standard", but the view pivots around a base joint
• "freepivot" - Similar to "pivot", but aims in world space
• "player" - this behaves much like the player view, with a fixed height and distance from the vehicle with no dampening
• "smooth" - heavily damped view, taking no influence from the roll. Pitch aim is in world space but yaw aim is in vehicle space, to reduce nauseating view bobbing.
• "smooth_free" - Same as "smooth" but all aiming is in world space.
• "smooth_locked" - Same as "smooth" but with no aiming - view attempts to stay in one position relative to the vehicle. Using the _tophat key the player can aim around. With the ui_drivingCameraFreelook cvar set the behaviour swaps, so the player can aim around normally and using _tophat returns the view to the centered position.

Clamps

Clamps can be applied to prevent the view angles going beyond certain values relative to the vehicle. This is useful for restricting the view (and hence the weapon's arc of fire) to specific areas, or preventing the player being able to see the edges of the cockpit model.

View clamps support the following properties:

• min - Minimum angle (degrees)
• max - Maximum angle (degrees)
• rate - Maximum rate of change of angle (degrees per second)

Clamps can be set on the following angles:

• yaw - Player aiming yaw relative to vehicle
• pitch - Player aiming pitch relative to vehicle
• dampedYaw - Final edge-of-screen yaw relative to vehicle (after dampening). This is internally adjusted for horizontal FOV & screen aspect ratio.
• dampedPitch - Final edge-of-screen pitch relative to vehicle (after dampening). This is internally adjusted for vertical FOV & screen aspect ratio.

View angle dampening (dampening out the bumps and jostles from the road surface) is applied after clamping the player's view angles, so in some cases the pitch & yaw resulting from extreme movements could cause edges of the model to become visible at the corners of the screen on widescreen displays. Clamping the dampedYaw & dampedPitch limits the edges of the screen to an appropriate range of values to avoid this.

Examples

Husky Driver

positionDef {
    name                           "guis/vehicles/husky_driver"
    hudname                        "guis/vehicles/husky_driver"

    data {
        "max_view_offset"          "0"
        "view_offset_rate"         "10"
        "joint_attach"             "base"
        "player_anim"              "VehicleHusky"
        "show_player"              "1"
        "use_fallback"             "1"
        "min_z_frac"               "-0.3"
        "cockpit"                  "main"
        "take_damage"              "1"
        "stat_name"                "husky_driver"
        "joint_icon"               "carrier_driver"
        "player_stance_crouch"     "1"
    }

    ik {
        type                       "sdVehicleIK_Steering"
        parms {
            "joint_left"           "left_hand"
            "joint_right"          "right_hand"
        }
    }

    // first-person + cockpit
    view {
        eyeJoint                   "cam_1"
        autoCenter
        showcockpit

        clamp pitch {
            min                    -70
            max                    20
        }

        clamp yaw {
            min                    -30
            max                    30
        }

        // don't let the final damped pitch & yaw go too far 
        clamp dampedPitch {
            min                    -180
            max                    64
        }

        clamp dampedYaw {
            min                    -75
            max                    75
        }
    }

    view {
        eyeJoint                   "cam_1"
        type                       "smooth_locked"
        cameraDistance             240
        cameraHeight               50
        dampSpeed                  0.15
        thirdPerson
    }
}

This creates a position in which the player is visible, attached at the "base" joint and using the VehicleHusky script functions to control the animation state machine. The player will fall off when the vehicle's up axis z component drops below -0.3 - so when the vehicle is tipped over a reasonable way - and will be ejected safely when the vehicle blows up, rather than being killed. The player can take damage in this position, and will have a hitbox as tall as a crouching player. The cockpit associated with it is the "main" cockpit, and time spent in the position will go towards the "husky_driver" statistic.

The IK is in this case used to keep the driver's hands on the handles. IK is discussed in more detail in the IK section.

The first view for this position is a first person view. It shows the cockpit and auto-centers the player's aim. The eye position is based off the "cam_1" joint. Aim is clamped between a pitch of -70 & 20 (where negative is upwards) and a yaw of -30 & 30. The edges of the screen cannot exceed a pitch of -180 & 64, and a yaw of -75 & 75.

The second view is a third person view using the "smooth_locked" mode. Its position is based off the "cam_1" joint but offset backwards by 240 units and upwards by 50 units. The damping speed is slowed down from the default to provide a less jarring view.