What a weapon is, rather than what Lara has of it.
None of this differs between the inventory she carries and the one a level
keeps for her, so it belongs to neither: what she holds and how many shots she
has are trx.inventory.
A weapon is shared by every copy of it. Changes last for the rest of the session, so levels should restore any values they change when they end.
Indexing the module reaches a weapon definition, so trx.weapons.uzis is the uzis. Keyed by weapon id or catalog name, not by position.
trx.weapons[key] (key: trx.catalog.weapons or string, value: trx.weapons.Weapon or nil). Weapon id, or its catalog name.Example:
trx.weapons.uzis.damage = 5
trx.weapons.shotgun.ammo.box_shots = 12
trx.weapons.flare.glow.color = "33e5ff"
trx.weapons.all (a list of trx.weapons.Weapon). Every weapon the engine knows, in the order it holds them. UNARMED is not one of them. (read-only)How the engine holds and fires a weapon, which decides which arm animations and firing routine it uses.
trx.weapons.Kind.DUAL_PISTOLS = 0trx.weapons.Kind.SINGLE_PISTOL = 1trx.weapons.Kind.RIFLE = 2trx.weapons.Kind.MOUNTED = 3trx.weapons.Kind.FLARE = 4How far off straight ahead an aim may go, as a pair of limits about each axis.
Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.
Properties:
max_pitch: trx.math.Angle. As far down as it reaches.max_yaw: trx.math.Angle. As far to the right as it reaches.min_pitch: trx.math.Angle. As far up as it reaches, which is a negative angle.min_yaw: trx.math.Angle. As far to the left as the aim reaches, which is a negative angle.An offset in the frame of the hand that holds the weapon. A weapon held in one hand only uses the right.
Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.
Properties:
left: trx.math.Vec3. Offset in the left hand.right: trx.math.Vec3. Offset in the right hand.What the weapon is fed. A shot is one pull of the trigger, which for the shotgun spends six rounds; the flare counts a flare where a weapon counts a shot.
Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.
Properties:
box_label_qty: integer. What a box shows on its inventory icon, which follows nothing else.box_shots: integer. What one box of ammunition is worth.infinite: boolean. Whether firing spends nothing, so the weapon never runs out and carries no counter.initial_shots: integer. What the weapon arrives with the first time Lara picks it up.The muzzle flash a shot draws.
Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.
Properties:
color: trx.math.Color. What color it lights with, in TR3 and later.shade: integer. How brightly it lights the model around it, in TR1 and TR2. Later games light it by color instead.time: integer. How many frames the flash stays on screen for.Computed properties (derived, not stored on the object):
pos: trx.weapons.HandPos. Where the flash is drawn, in each hand.The glow sprite drawn where the weapon burns: a gun's muzzle, or a lit flare.
Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.
Properties:
color: trx.math.Color. What color the glow is drawn in.flicker: boolean. Whether the brightness is randomized every frame, the way a flare burns.pos: trx.math.Vec3. Where it sits, in the frame of the mesh it follows.scale: number. Multiplies the sprite's own size. 0 turns the glow off.The animation numbers a rifle is drawn, put away and fired by. They count the animations and frames of the weapon's own object, not Lara's.
Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.
Properties:
A weapon definition, reached as trx.weapons.uzis or by id.
Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.
Properties:
aim_speed: trx.math.Angle. How far the arms swing towards the target each frame, in engine units. A spec says the same thing in degrees, as aim.speed.damage: integer. Hit points one shot takes off what it hits.fire_overlay_pitch: integer. The pitch at which to play the overlay sample.fire_overlay_sample: trx.catalog.samples. The overlay sample a shot plays. One this game has no sound for is silent.fire_sample: trx.catalog.samples. The sample a shot plays. One this game has no sound for is silent.given_in_ngplus: boolean. Whether a bonus game gives Lara the weapon, loaded, at level start.
A weapon added by a script is not given unless this is true.gun_height: trx.math.Distance. How far above Lara's feet the shot leaves the barrel. It also decides how deep she can wade and still fire.id: trx.catalog.weapons. Which weapon this is, for the calls that take one: trx.inventory:set_shots(weapon.id, 100). (read-only)is_available: boolean. Whether the game allows the weapon at all. Turning one off keeps it out of the cheats and off the controls list, and a save that carries it arrives without it.kind: trx.weapons.Kind. How the engine holds and fires it.shot_accuracy: trx.math.Angle. How wide a cone a shot may stray into, in engine units. 0 never misses. A spec says the same thing in degrees, as aim.accuracy.smoke_count: integer. How many puffs of smoke a shot leaves at the muzzle, in TR3. 0 for none.target_dist: trx.math.Distance. How far the weapon reaches, both for auto-aim and for the shot itself, in world units. A spec says the same thing in sectors, as aim.target_dist, and trx.math.from_sectors converts.Computed properties (derived, not stored on the object):
ammo: trx.weapons.Ammo. What the weapon is fed.ammo_icon: string. The markup drawn beside the ammunition count in TR1. Later games count without one, and a weapon that carries no icon answers with nil.ammo_object: trx.catalog.objects. The box of ammunition it takes, or nil where it takes none.anim: trx.weapons.Anim. The animation numbers it is drawn and fired by.flash: trx.weapons.Flash. The muzzle flash a shot draws.glow: trx.weapons.Glow. The glow drawn where it burns.has_infinite_ammo: boolean. Whether the weapon never runs dry. The pistols do in most games, and a level or a script may say so of any weapon. A count of shots left means nothing in this context.left_arm: trx.weapons.AimLimits. How far the left arm may follow a target it has locked onto. A dual-wielded weapon drops the lock on the arm that cannot reach.lock: trx.weapons.AimLimits. Where auto-aim may lock on, measured from where Lara faces.muzzle_pos: trx.weapons.HandPos. Where the barrel ends, which is where smoke and sparks come from.object: trx.catalog.objects. The pickup the weapon is, for handing it to trx.inventory:give. nil where this game has no such weapon.right_arm: trx.weapons.AimLimits. How far the right arm may follow a target.rounds_per_shot: integer. How many rounds one pull of the trigger spends: six for the shotgun, one for everything else. What a box is worth in shots is trx.weapons.Ammo.box_shots.shell_pos: trx.weapons.HandPos. Where a spent shell is thrown from. A weapon that leaves no shells has this at the origin.trx.weapons.declare(weapon, spec)
Adds a weapon of a script's own, under a name the game does not hold yet.
A weapon of a kind the engine implements is held, drawn and put away as the
weapons of that kind are, and only what it does when it fires is a script's
to write. Raises where the spec says neither a kind nor a base, and where
the name is taken, so that two mods claiming one weapon are heard;
trx.weapons.patch changes a weapon that is there already.
Parameters:
weapon (trx.catalog.weapons or string). Which weapon, by id or by name. A name of its own wants a prefix, so that two mods do not claim one weapon.
spec (table). Describes the weapon with the same groups as its weapons file entry:
kind, (objects, meshes, ammo, aim, anim, flash, glow,
muzzle, smoke, shell, sound, stow, save, cheat), and its own
numbers beside them. base starts the weapon from another one, and fire
accepts an engine routine name or a function. An omitted key keeps the
weapon's current value. An unknown key or an invalid value raises an error
and writes nothing.
meshes states where Lara is drawn from while she holds the weapon. It
names an object and the offsets hand_r, hand_l, torso, thigh_r
and thigh_l into it. An offset of -1 draws nothing in that place. A
weapon with no meshes is drawn from the outfit, like every weapon the
game ships.
A spec uses the units of a weapons file: angles in degrees and distances
in sectors. Weapon fields use the engine's units, as other API fields do,
so a spec that says
aim.speed = 10 reads back as weapon.aim_speed == 1820.
Returns: trx.weapons.Weapon. The weapon, to read or write the rest of its numbers.
Example:
trx.weapons.declare("mymod:bigger_gun", {
base = "shotgun",
kind = "rifle",
objects = {
pickup = "shotgun_item",
ammo = "shotgun_ammo_item",
anim = "lara_shotgun",
},
ammo = { initial_shots = 12, box_shots = 12 },
damage = 30,
fire = function(weapon, running)
trx.sound.play(trx.catalog.samples.explosion)
end,
})
trx.weapons.patch(weapon, spec)
Writes a spec into a weapon the game already holds, and raises where it holds no such weapon. This is trx.weapons.declare for a script that would rather hear about a name it got wrong than mint a weapon nothing draws.
Parameters:
weapon (trx.catalog.weapons or string). Which weapon, by id or by name.
spec (table). Describes the weapon with the same groups as its weapons file entry:
kind, (objects, meshes, ammo, aim, anim, flash, glow,
muzzle, smoke, shell, sound, stow, save, cheat), and its own
numbers beside them. base starts the weapon from another one, and fire
accepts an engine routine name or a function. An omitted key keeps the
weapon's current value. An unknown key or an invalid value raises an error
and writes nothing.
meshes states where Lara is drawn from while she holds the weapon. It
names an object and the offsets hand_r, hand_l, torso, thigh_r
and thigh_l into it. An offset of -1 draws nothing in that place. A
weapon with no meshes is drawn from the outfit, like every weapon the
game ships.
A spec uses the units of a weapons file: angles in degrees and distances
in sectors. Weapon fields use the engine's units, as other API fields do,
so a spec that says
aim.speed = 10 reads back as weapon.aim_speed == 1820.
Returns: trx.weapons.Weapon. The weapon, to read or write the rest of its numbers.
Example:
trx.weapons.patch("uzis", {
damage = 2,
ammo = { box_shots = 80 },
})
trx.weapons.set_fire(weapon, handler)
States what a weapon does when it is fired, in place of the routine it fired
with before. One weapon holds one handler, so a second call replaces the
first rather than adding to it. The handler is given the weapon and whether
Lara is running as she fires, and states the same thing as fire in a spec.
Parameters:
weapon (trx.catalog.weapons or string). Which weapon, by id or by name.handler (function). Called as the weapon fires.Example:
trx.weapons.set_fire("mymod:bigger_gun", function(weapon, running)
trx.sound.play(trx.catalog.samples.explosion)
end)
trx.weapons.get(key)
Retrieves a weapon definition by id or by name.
Parameters:
key (trx.catalog.weapons or string). Weapon id, or its catalog name: trx.weapons["uzis"].Returns: trx.weapons.Weapon or nil. nil if this game has no such weapon.
Example:
local uzis = trx.weapons.get(trx.catalog.weapons.UZIS)
uzis.damage = 5
trx.weapons.is_available(weapon)
Deprecated. Read trx.weapons.Weapon.is_available instead.
Whether the game allows this weapon at all. The game flow can keep one out, and a cheat that hands it over anyway leaves Lara with a gun the level was built without.
Parameters:
weapon (trx.catalog.weapons). Which weapon. UNKNOWN, UNARMED, and out-of-range values raise.Returns: boolean. True where this game has the weapon at all.
trx.weapons.object(weapon)
Deprecated. Read trx.weapons.Weapon.object instead.
The pickup the weapon is, for handing it to trx.inventory:give.
Parameters:
weapon (trx.catalog.weapons). Which weapon. UNKNOWN, UNARMED, and out-of-range values raise.Returns: trx.catalog.objects or nil. The object id, or nil if this game has no such weapon.
Example:
trx.inventory:give(trx.weapons.object(trx.catalog.weapons.SHOTGUN))
trx.weapons.ammo_object(weapon)
Deprecated. Read trx.weapons.Weapon.ammo_object instead.
The box of ammunition the weapon takes.
Parameters:
weapon (trx.catalog.weapons). Which weapon. UNKNOWN, UNARMED, and out-of-range values raise.Returns: trx.catalog.objects or nil. The object id, or nil where the weapon takes no ammunition.
trx.weapons.rounds_per_shot(weapon)
Deprecated. Read trx.weapons.Weapon.rounds_per_shot instead.
How many rounds one pull of the trigger spends. Six for the shotgun, one for everything else.
Parameters:
weapon (trx.catalog.weapons). Which weapon. UNKNOWN, UNARMED, and out-of-range values raise.Returns: integer. Rounds, not shots.
trx.weapons.shots_per_box(weapon)
Deprecated. Read trx.weapons.Ammo.box_shots instead, which is the same number.
How many shots one box of ammunition for it is worth.
Parameters:
weapon (trx.catalog.weapons). Which weapon. UNKNOWN, UNARMED, and out-of-range values raise.Returns: integer. Shots, not rounds.