Vehicle Scripting: Weapons

Describe how weapons are hooked up, how you let people control them, etc.

Introduction

Weapons are added to a vehicle by adding a weapon block to a positionDef. These point to a stringMap configuring the weapon and the code class to use. The weapon block also includes the angle clamps to limit the firing arc of the weapon.

Properties:

• type - The code class of the weapon. Detailed in Weapon Types.
• weapon - Points to a string map containing key/value pairs used by the code class and the script object to configure the behaviour of the weapon.

The pitch & yaw of the weapon can be clamped similarly to the views, however it supports a couple of extra parameters:

• sound - The sound shader to play when the angle is changing (when the weapon is pitching or yawing)
• filter - This acts as a delta-dependant rate scaler. If the angular movement required is large it will have more effect. A filter value of zero will make it have no affect, but with a value of one it will prevent the weapon rotating at all. A small value for this will soften out the small changes in angles often made by computer mice and make them less jerky feeling.

Weapon Types

There are two different types of weapon, "sdVehicleWeaponLocked" and "sdVehicleWeaponFixedMinigun". Both are useful in different situations. They use keys from the weapon's string map to configure their behaviour.

Common keys:

• "weapon_name" - A name identifying the weapon to the code & scripts.
• "gunName" - The localized string name of the weapon used on the HUD.
• "scriptObject" - The name of the script object used to govern the weapon's behaviour. Information about the way scripts interact with & control the weapon is given in Weapon Scripts.
• "no_tophat_crosshair" - Player doesn't get a crosshair when tophat is held down.
• "muzzle" or "joint_muzzle" or "muzzle_right" - Any of these names can be used for the firing joint of the weapon TODO: FIXME! THIS IS UGLY!.
• "lock_clamp_yaw_*", "lock_clamp_pitch_* - Where * is min, max, or rate. These allow the range of valid directions for target locking to be defined, to prevent things like locking onto targets behind the vehicle when in third person and using tophat.
• "lock_enabled" - Enables target locking.
• "lock_duration" - Amount of time it takes to lock onto a target (in seconds). Defaults to 1.
• "lock_distance" - Maximum distance a lock can be acquired at (in units). Defaults to 2048.
• "lock_friendly" - Can lock onto friendly targets.
• "lock_sticky" - Lock stays even when crosshair leaves the target.
• "lock_filter" - Points to a targetInfo definition used to filter suitable targets to lock onto
• "snd_target_locking" - Sound shader played when a target is being locked onto
• "snd_target_locked" - Sound shader played when a target is locked

sdVehicleWeaponLocked

This weapon type constantly aims in the same direction - out from its muzzle joint. This is used for fixed direction weapons such as the Anansi rocket launchers, but with the addition of IK governed by the position it can be used for weapons that aim, such as the nose galing gun of the Anansi.

Specific Keys:

• "not_really_locked" - This is used to allow some projectile direction variance beyond the forward direction of the muzzle joint to increase aiming precision a little.
• "nrl_yawClamp_enabled" - Enables yaw clamping for the extra aim in "not_really_locked" mode.
• "nrl_yawClamp_min" - Minimum yaw allowed in "not_really_locked" mode.
• "nrl_yawClamp_max" - Maximum yaw allowed in "not_really_locked" mode.
• "nrl_pitchClamp_enabled" - Enables pitch clamping for the extra aim in "not_really_locked" mode.
• "nrl_pitchClamp_min" - Minimum pitch allowed in "not_really_locked" mode.
• "nrl_pitchClamp_max" - Maximum pitch allowed in "not_really_locked" mode.
• "canaim_joint_*" - Where * is greater than or equal to 1. When the player is aiming around the joints in this list are used to check whether the target under the player's crosshair is hittable. If it is not, the player's crosshair disappears to signal that he cannot shoot there. If these are not present then the muzzle joint is used.

sdVehicleWeaponFixedMinigun

This weapon type includes an aimer IK. It needs several joints specified to define how it moves and rotates to aim at the target. This is the most common weapon type.

Specific Keys:

• "gunJointShoulder" - The base joint for weapon movements
• "gunJointYaw" - The joint that is yawed to aim
• "gunJointPitch" - The joint that is pitched to aim
• "weapon1_muzzle" - The muzzle joint
• "fix_barrel" - Used in some cases to re-orient a wayward muzzle joint TODO: SEE IF WE STILL NEED THIS
• "invert_pitch" - Used to flip the pitching behaviour of the IK for some unorthodox weapons (eg the Tormentor's belly Hyperblaster)

Weapon Scripts

The weapon script controls much of the behaviour of the weapon, for example firing the projectiles, recharge and refire rates, and effects.

There is a base vehicle weapon script defining much of the generic behaviour for ETQW vehicle weapons, vehicle_weapon_base in base/script/vehicles/weapons. A simple example of a derived weapon script is vehicle_weapon_law, which is used for the Anansi and Tormentor locking missiles. The script implements the Fire function, calling functions from the base class to update the charge, refiring delays, and actually firing the missile itself and its effects.

TODO: DETAIL FEATURES OF THE BASE SCRIPT