Weapons

The file cfg/weapons.json5 lists the weapons in a game and the code each one uses. A weapon the file does not name is not in the game.

The weapons the games ship with are the pistols, the magnums, the automatic pistols, the desert eagle, the revolver, the uzis, the shotgun, the M16, the MP5, the grenade launcher, the rocket launcher, the harpoon gun, the crossbow, the black skidoo, and the flare, which is not strictly a weapon but is treated as one.

An entry is keyed by the weapon and holds its settings. Values that describe its objects, ammunition, and aim are grouped under their own keys.

"uzis": {
    "kind": "dual_pistols",
    "damage": 1,
    "gun_height": 650,
    "equip_key": "equip_uzis",
    "is_remembered": true,
    "objects": {
        "pickup": "uzis_item",
        "ammo": "uzis_ammo_item",
        "anim": "lara_uzis",
    },
    "ammo": {
        "box_shots": 100,
        "icon": "\\{ammo uzis}",
    },
    "aim": {
        "speed": 10,
        "accuracy": 8,
        "lock": [-60, +60, -60, +60],
    },
    "sound": {
        "fire": "lara_uzi_fire",
        "alternating": true,
    },
    "save": {
        "ammo_key": "uzis",
        "required": true,
    },
}

A script uses the same settings and may add its own weapons; see the Weapon module.

trx.weapons.patch("uzis", { damage = 2, ammo = { box_shots = 80 } })

A spec uses degrees for angles and sectors for distances. A weapon read by a script uses the engine's units instead, so a spec that says aim.speed = 10 reads back as weapon.aim_speed == 1820, and aim.target_dist = 8.0 as weapon.target_dist == 8192. Write degrees and sectors in a spec, and trx.math.Angle and trx.math.Distance everywhere else.

An XYZ value is an array of three numbers, or a group naming all three of x, y and z. A weapon that leaves the key out keeps the offset it has.

What a weapon holds

The keys a weapon states on its own:

Property Type Description
kind String How the weapon is held, drawn and put away. This selects its arm animations and firing routine. One of dual_pistols, single_pistol, rifle, mounted or flare. A kind the engine does not drive, such as mounted, leaves the weapon to the game code that owns it.
base String The weapon this one starts from, named by its key. Everything the base holds is taken except its identity, the names it is saved under, and the key that draws it.
damage Integer The HP damage value to subtract from targets when struck by this weapon type.
gun_height Integer Used to determine the start Y position when firing a weapon, and to determine if Lara is too far submerged in water to be able to use a weapon (other than the harpoon).
equip_key String The key that draws the weapon straight away. One key draws one weapon, so a weapon that claims a key takes it from whichever weapon held it. A weapon that names no key is reached through the inventory only.
fire String What the weapon does when fired: generic, m16, grenade, rocket or harpoon. A script may provide a function instead.
is_available Boolean Determines if a weapon can be given to Lara when using item cheats. Pickups for unavailable weapons/flares will still work normally.
is_default Boolean Whether Lara starts the game with the weapon, and reaches for it when what she holds runs dry.
is_remembered Boolean Whether Lara returns to the weapon after she puts away what she holds now.
is_launcher Boolean Whether the weapon throws an explosive that flies on its own.
is_machine_gun Boolean Whether the weapon keeps firing while the trigger is held, which also lets Lara fire it on the move.
is_usable_underwater Boolean Whether Lara may bring the weapon out under water.
wants_combat_camera Boolean Whether drawing the weapon swings the camera to Lara's back.
unaims_on_release Boolean Whether the weapon comes down as soon as Lara stops firing, rather than staying up until she puts it away.

objects

Property Type Description
weapon String What Lara picks the weapon up as.
ammo String What its ammunition arrives as.
anim String The object holding the animations she carries it with.
shell String What it throws out as it fires, which is an ordinary shell where the weapon names nothing.
projectile String What it sends on its way, for a weapon that throws something rather than sending a round straight at what Lara aims at.

ammo

Property Type Description
initial_shots Integer The amount of ammo given when the weapon itself is collected.
box_shots Integer The amount of ammo given when the equivalent ammo object is picked up.
box_label_qty Integer Multiplier used in the inventory ring for each loose ammo pickup.
rounds_per_shot Integer What one pull of the trigger spends, which is one round unless the weapon fires more at once, as the shotgun does.
infinite Boolean Whether firing spends nothing, so that the weapon never runs out and shows no count in the inventory ring or the overlay. The pistols and the skidoo's guns have it; taking it away from the pistols makes pistol clips worth collecting. The flare answers to it as well, and a bonus game overrides it for everything.
icon String The icon the ammunition counter shows beside the number of shots left.

aim

Property Type Description
speed Integer Determines how quickly Lara's arms rotate into position when aiming at a target.
accuracy Integer Adds a random factor to angles used when firing a weapon. Higher values mean less accuracy.
target_dist Float The maximum distance (in world sectors) that a target can be from Lara in order for her to lock on.
lock Integer array (length 4) These values are used to test if Lara is able to lock on to a target.
left Integer array (length 4) These values determine if Lara has lost target on her left arm.
right Integer array (length 4) These values determine if Lara has lost target on her right arm.

anim

Property Type Description
equip Integer For rifle type weapons, the relative equip animation index of the associated object e.g. O_LARA_SHOTGUN.
draw_frame Integer For rifle type weapons, the relative frame number of the equip animation where the object mesh swap is performed e.g. removing the shotgun from Lara's back and putting it in her hand.
undraw_frame Integer For rifle type weapons, the relative frame number of the unequip animation where the object mesh swap is performed e.g. removing the shotgun from Lara's hand and putting it on her back.
recoil_frame Integer For pistol type weapons, this value determines when Lara should snap back to the aiming frame after the weapon is fired i.e. Uzis have a lower value than Pistols for faster fire rate.
shell_frame Integer The frame a spent shell leaves the weapon at. A weapon that names no frame drops its shells as it fires instead.
ready String The animation the weapon rests in once it is out: grenade or harpoon. A weapon that names none rests in the aim.

flash

Property Type Description
time Integer Determines the number of frames to show the weapon flash object (O_GUN_FLASH / O_M16_FLASH) after firing a weapon.
shade Integer Specifies the shade applied when drawing the weapon flash object (O_GUN_FLASH / O_M16_FLASH / O_FLARE_FIRE).
color Float array (length 3) Specifies the color applied when drawing the weapon flash object (O_GUN_FLASH / O_M16_FLASH / O_FLARE_FIRE), used in TR3 lighting system.
pos XYZ Specifies the offset position where the weapon flash object (O_GUN_FLASH / O_M16_FLASH / O_FLARE_FIRE) will be drawn. flash_pos_alt is used only for discarded flares.
pos_alt XYZ Specifies the offset position where the weapon flash object (O_GUN_FLASH / O_M16_FLASH / O_FLARE_FIRE) will be drawn. flash_pos_alt is used only for discarded flares.
routine String The muzzle flash one shot shows: m16, mp5 or flare. A weapon that names none shows the ordinary flash, upright at the barrel.
lights_room Boolean Whether the flash lights the room around Lara.
is_optional Boolean Whether the player may turn the flash off, which the shotgun flash setting governs.

glow

Property Type Description
color Float array (length 3) Specifies the color applied when drawing the weapon glow object (O_GLOW), used in TR3 lighting system.
pos XYZ Specifies the additional offset to apply to the glow sprite position.
scale Float Multiplies the glow sprite's own size. 0 turns the glow off.
flicker Boolean Whether the brightness is randomized every frame, the way a flare burns.

muzzle

Property Type Description
pos XYZ Specifies the additional offset to apply to the muzzle for smoke effects (right hand).
pos_alt XYZ Specifies the additional offset to apply to the muzzle for smoke effects (left hand for dual pistols).

smoke

Property Type Description
pos XYZ Where smoke leaves the weapon, which is the muzzle where the weapon gives no other place.
pos_alt XYZ The same, for the left hand of a weapon held in both.
tip XYZ The far end of the barrel. A weapon that names one drives its smoke along the barrel and throws sparks with it; one that does not lets the smoke drift.
tip_alt XYZ The same, for the left hand.
count Integer How many smoke effect instances to spawn upon shooting.
size String How big the smoke one shot leaves is: launcher. A weapon that names none smokes as an ordinary round does.

shell

Property Type Description
pos XYZ Specifies the additional offset to apply to the gun for shells (right hand).
pos_alt XYZ Specifies the additional offset to apply to the gun for shells (left hand for dual pistols).
throws_forward Boolean Whether spent shells leave ahead of Lara rather than fall from the hand that fired.
angle Integer The angle they leave at.
min_speed Integer A shell slower than this carries the amount again, so that a weapon that throws them far does not drop one at Lara's feet.

sound

Property Type Description
fire String The sound effect to play when the weapon is fired (see ./SAMPLES.md).
overlay String A second sample played over the first (see ./SAMPLES.md).
overlay_pitch Integer The pitch that second sample plays at.
rapid_fire String The sound a held trigger makes: m16 or mp5. A weapon that names none falls silent between the shots its own sample marks.
alternating Boolean Whether the weapon sounds every shot as it fires, alternating between its sample and the one beside it.

stow

Property Type Description
place String Where the weapon rides when it is put away: none, holster or back.
order Integer Which weapon shows there when Lara carries several: the lowest order wins.

save

Property Type Description
ammo_key String The name a savegame gives the rounds Lara carries now.
resume_has_key String The name a level keeps the weapon under for her return.
resume_ammo_key String The name it keeps her rounds under.
required Boolean Whether a savegame that lacks those names is broken, which is true of the weapons the first savegame format already held.

cheat

Property Type Description
ammo Integer What the item cheat hands out. A weapon that names none is left out of it.
key_ammo Integer What the key cheat hands out, which is generous by a different amount.