Module for controlling all moveables.
Indexing the module reaches an item, and #trx.items is how many the level has. pairs() walks them in order, keyed by the item number.
trx.items[key] (key: trx.items.Num or string, value: trx.items.Item or nil). An item's unique name reaches it as well.#trx.items (integer). How many there are.Example:
for num, item in pairs(trx.items) do
trx.log.info(item.object_id)
end
trx.items.query (trx.items.ItemQuery). The identity query over every item in the level. Narrow it and read it. (read-only)The values the pickup_mode item property can take. It selects the animation Lara plays when collecting the item.
trx.items.PickupMode.NORMAL = 0trx.items.PickupMode.PLINTH_LOW = 1trx.items.PickupMode.PLINTH_HIGH = 2trx.items.PickupMode.HIDDEN = 3trx.items.PickupMode.CROWBAR = 4trx.items.PickupMode.SARCOPHAGUS = 5trx.items.PickupMode.PLINTH_SCION = 6The values the switch_mode item property can take. It selects the animation Lara plays when interacting with the item.
trx.items.SwitchMode.NORMAL = 0trx.items.SwitchMode.HIDDEN_REACH = 1trx.items.SwitchMode.HIDDEN_PICKUP = 2trx.items.SwitchMode.SHOVE = 3The kind of trigger trx.items.Item:trigger fires, matching the trigger types a level editor offers. Most are forward triggers that differ only in what trips them in a level; from a script they behave alike, and TRIGGER is the one to reach for.
trx.items.TriggerType.TRIGGER = 0trx.items.TriggerType.HEAVY = 1trx.items.TriggerType.SWITCH = 2trx.items.TriggerType.HEAVY_SWITCH = 3trx.items.TriggerType.ANTITRIGGER = 4The animation's number within the object an item is of. Counted from 0.
The frame's number within the animation it belongs to. Counted from 0.
An animation state, as the object's own animations number them. What a state means is the object's business: the numbers of a wolf are not the numbers of a door. Counted from 0.
Item number, matching the numbers level editors show. Counted from 0.
What a trigger carried when it fired.
Properties:
mask: integer. The code bits it set, 1 to 31.one_shot: boolean. Whether it fires only the once.timer: trx.game.Seconds. How long it keeps the item going.type: trx.items.TriggerType. The kind of trigger it was.An item, also known as a moveable.
Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.
Properties:
anim_num: trx.items.AnimNum.anim_state: trx.items.AnimState. The state the item is in.collidable: boolean. Whether Lara can collide with this item.fall_speed: integer. Vertical speed.frame_num: trx.items.FrameNum. Negative values count back from the end.goal_anim_state: trx.items.AnimState. The state the item is transitioning towards.gravity: boolean. Whether gravity applies to this item.hit_points: integer. Current hit points. Raising this above the maximum also raises the max_hit_points entry of properties.is_alive: boolean. Whether the item is a living creature with hit points remaining. (read-only)is_finished: boolean. Whether the item has finished its run - a creature that died, or a one-shot trigger that fired. It stays in the level but no longer acts.is_hostile: boolean. Whether this item is a creature currently hostile to Lara. (read-only)is_in_play: boolean. Whether the item is live: simulated, visible and not finished - the state a targetable enemy is in. A read-only composite of the axes. (read-only)is_killed: boolean. Whether the item has already been killed. (read-only)is_one_shot: boolean. Whether the item's trigger has been spent and will never fire again.is_present: boolean. Whether the item is in the world at all: linked in its room, so drawn and collidable in principle. Managed by the engine. (read-only)is_reversed: boolean. Whether the item's trigger is inverted, so it runs until triggered rather than once triggered. This is how a level ships something already on.is_simulated: boolean. Whether the item's control routine runs each frame. Call activate to start it. (read-only)is_targetable: boolean. Whether Lara's auto-aim can lock onto the item right now. (read-only)is_triggered: boolean. Whether the item's trigger currently says go. This is what a door, a switch or an alarm reads to decide whether to act; a creature ignores it and goes by whether it is running.
It is a verdict on trigger_mask, timer and is_reversed together, not a field of its own. (read-only)is_visible: boolean. Whether the item is drawn. It can be present in the world but not visible, like an ambush enemy waiting to appear.max_hit_points: integer. Maximum hit points. Set the max_hit_points entry of properties to change it. (read-only)mesh_bits: integer. Bitmask of which of the item's meshes are drawn.name: string. Unique item name, or nil. Assigning a name already in use raises an error.num: trx.items.Num. An item handed over by a query can say where it lives. (read-only)object_id: trx.catalog.objects. The item's object type. (read-only)pos: trx.math.Vec3. World position. Updating this also updates room and room_num.room_num: trx.rooms.Num. The room containing this item. Set pos to move the item between rooms. (read-only)rot: trx.math.Rot. Orientation.speed: integer. Forward speed.timer: trx.game.Frames. How long the item's trigger keeps it going. 0 runs it until something takes the trigger back; -1 means it has run out; anything else counts down. trigger takes its own timer as a trx.game.Seconds.touch_bits: integer. Bitmask of which of the item's meshes Lara is touching. (read-only)trigger_mask: integer. The five code bits, counted the way a level editor counts them: 1 to 31. The trigger only says go once every bit is set, which is how a level makes several triggers agree before anything happens. A lone trigger carries all of them.was_hit: boolean. Whether the item was hit during the current frame. (read-only)Computed properties (derived, not stored on the object):
bounds: trx.math.Box. The item's bounding box for the frame it is on. The numbers are in the item's own frame, so they say how far the model reaches around pos before rot turns it, and they change as the item animates.properties: table. Typed, object-specific item properties. Writing here overrides the object's default for this item only; reads fall back to the object. Iterable with pairs(). See Objects.room: trx.rooms.Room. The room containing this item.Methods:
item:activate()
Brings the item to life, exactly as tripping a trigger on it would: its control routine starts running, and a creature also gets its AI, without which it would stand there and ignore Lara.
Objects with no control routine cannot be activated, and an item that is already active is left alone.
item:deactivate()
Stops the item: its control routine no longer runs, and a creature loses its AI and stands down. The item stays where it is and keeps its hit points, so this is not a way of getting rid of it - use destroy for that.
A trigger can still bring it back, and so can activate.
item:destroy()
Removes the item from the game. Any other handle to it becomes stale.
item:die([explode])
Runs the object's creature death handling: the corpse stays, and explode bursts its meshes as a rocket or grenade would. For creatures; destroy simply removes any item from the game.
Parameters:
item:distance_to(pos)
Distance from this item to a world position.
Parameters:
pos (trx.math.Vec3). World position.Returns: trx.math.Distance. Measured between the two positions.
item:get_property(name)
Reads an object property, falling back to the object's default. Prefer item.properties.<name>.
Parameters:
Returns: any or nil. The value, of the type the property is declared with.
item:get_property_names()
Names of every property this item's object declares.
Returns: a list of string.
item:is_valid()
Whether the handle still refers to a live item. Reading or writing a field on a stale handle raises an error rather than silently operating on an unrelated item, so check this for a handle held across time.
Returns: boolean. False once the item it named is gone.
Example:
local wolf = trx.items.query:of_object(trx.catalog.objects.wolf):first()
trx.events.after_control(function()
if wolf:is_valid() and wolf.hit_points <= 0 then
trx.log.info("the wolf is down")
end
end)
item:on_activate(callback)
Happens when this item is activated through the lifecycle front door during play. trx.events.on_activate, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_activate(function(item)
trx.log.info("the item was activated")
end)
item:on_deactivate(callback)
Happens when this item is deactivated through the lifecycle front door during play. trx.events.on_deactivate, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_deactivate(function(item)
trx.log.info("the item was deactivated")
end)
item:on_destroy(callback)
Happens as this item is removed from the game during play. It can still be read from the handler, but not after. trx.events.on_destroy, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_destroy(function(item)
trx.log.info("the item was removed")
end)
item:on_enter_sim(callback)
Happens when this item starts being simulated during play. trx.events.on_enter_sim, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_enter_sim(function(item)
trx.log.info("the item started running")
end)
item:on_enter_world(callback)
Happens when this item enters the world during play, such as a runtime spawn. trx.events.on_enter_world, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_enter_world(function(item)
trx.log.info("the item entered the world")
end)
item:on_finish(callback)
Happens when this item finishes its run during play. trx.events.on_finish, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_finish(function(item)
trx.log.info("the item finished its run")
end)
item:on_hide(callback)
Happens when this item becomes hidden during play. trx.events.on_hide, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_hide(function(item)
trx.log.info("the item vanished")
end)
item:on_hit(callback)
Happens when this item takes damage. trx.events.on_hit, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.damage (integer). Hit points taken, before clamping to zero.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_hit(function(item, damage)
trx.log.info("the item lost " .. damage .. " hit points")
end)
item:on_kill(callback)
Happens when damage takes this item's hit points to zero. trx.events.on_kill, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_kill(function(item)
trx.log.info("the item is down")
end)
item:on_leave_sim(callback)
Happens when this item stops being simulated during play. trx.events.on_leave_sim, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_leave_sim(function(item)
trx.log.info("the item stopped running")
end)
item:on_leave_world(callback)
Happens when this item leaves the world during play. trx.events.on_leave_world, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_leave_world(function(item)
trx.log.info("the item left the world")
end)
item:on_show(callback)
Happens when this item becomes visible during play. trx.events.on_show, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_show(function(item)
trx.log.info("the item appeared")
end)
item:on_trigger(callback)
Happens every time a trigger is aimed at this item, of any kind. trx.events.on_trigger, narrowed to this item.
Parameters:
callback (function). What to run when it happens to this item.
Called with:item (trx.items.Item). This item.trigger (trx.items.Trigger). What the trigger carried.Returns: trx.events.Listener. The attached handler.
Example:
trx.items[12]:on_trigger(function(item, trigger)
trx.log.info("triggered with mask " .. trigger.mask)
end)
item:set_property(name, value)
Overrides an object property for this item. Prefer item.properties.<name> = ....
Parameters:
item:shatter([damage])
Bursts the item's meshes into flying debris, the visual die produces with die.explode, on its own. It does not kill or remove the item.
Parameters:
item:take_damage(damage)
Hurts the item the way a weapon does, and reports through
trx.events.on_hit, and trx.events.on_kill where the blow takes the
last hit point. Writing hit_points reports neither.
The kill counts as the environment's rather than Lara's.
Parameters:
Example:
local lara = trx.lara.item
lara:take_damage(lara.hit_points)
item:trigger([opts])
Fires a trigger at the item, exactly as a floor trigger in the level would: sets the code bits, and once they are all set, starts the item running.
This is the one to reach for on anything a level would trigger - a door, a switch, an alarm - because those read their trigger before they act, and merely activating one leaves it running but doing nothing. Pass type = trx.items.TriggerType.ANTITRIGGER to take the trigger back instead.
Parameters:
opts (table, optional). What the trigger carries.
Keys:
type (trx.items.TriggerType, optional). A plain TRIGGER by default.mask (integer, optional). Which of the five code bits to set, 1 to 31, all of them by default. Pass fewer to act as one of several triggers a puzzle is waiting on.timer (trx.game.Seconds, optional, default 0). How long it should keep the item going. 0 means until something takes the trigger back. A timer of exactly 1 is a single frame, not a second, matching the level format.one_shot (boolean, optional). Never let it fire again.Example:
trx.items[12]:trigger()
Example:
trx.items[12]:trigger({ timer = 3, one_shot = true })
Example:
trx.items[12]:trigger({ type = trx.items.TriggerType.ANTITRIGGER })
A trx.query.Query over the items a level holds, with the narrowings below on top of the ones every query has. Items answer to no names of their own, so of_object is how a name reaches them.
Methods:
itemquery:alive()
The item still has hit points.
Returns: trx.query.Query. The narrowed query.
itemquery:finished()
The item has run its course.
Returns: trx.query.Query. The narrowed query.
itemquery:in_box(min, max)
The item stands inside a world-space box. The corners may come in any order.
An item is tested by its position, the point it stands at, rather than by the box it fills. Position is all this asks after, so the rest of the query says what else the item must be: trx.items.query:in_box(min, max):present() asks for the ones that are in the world as well.
Parameters:
min (trx.math.Vec3). One corner of the box.max (trx.math.Vec3). The opposite corner.Returns: trx.query.Query. The narrowed query.
Example:
local guards = trx.items.query
:in_box({ x = 51200, y = -2048, z = 30720 }, { x = 53248, y = 0, z = 32768 })
:present()
:matches()
itemquery:in_play()
The item is part of the game rather than set aside.
Returns: trx.query.Query. The narrowed query.
itemquery:in_room(room_num)
The item is in the given room.
Parameters:
room_num (trx.rooms.Num).Returns: trx.query.Query. The narrowed query.
itemquery:in_sphere(centre, radius)
The item stands within a radius of a point. As with in_box, the item's position is the whole of the test.
Parameters:
centre (trx.math.Vec3). Middle of the sphere.radius (trx.math.Distance). How far out it reaches.Returns: trx.query.Query. The narrowed query.
itemquery:of_object(key)
The item is of the given object, named the way a player would name it or by its id.
Parameters:
key (any). Object id, or a name trx.objects.query resolves.Returns: trx.query.Query. The narrowed query.
Example:
trx.items.query:of_object("wolf"):simulated():matches()
itemquery:present()
The item is in the world, whether or not anything is simulating it.
Returns: trx.query.Query. The narrowed query.
itemquery:simulated()
The item is being simulated: its control routine runs every frame.
Returns: trx.query.Query. The narrowed query.
itemquery:targetable()
Lara's guns can lock onto the item.
Returns: trx.query.Query. The narrowed query.
itemquery:visible()
The item is drawn.
Returns: trx.query.Query. The narrowed query.
trx.items.get(key)
Retrieves an item by number or by name.
Parameters:
key (trx.items.Num). An item's unique name reaches it as well.Returns: trx.items.Item or nil. The item, or nil where nothing answers to the key.
Example:
local item = trx.items[0]
item.name = "lara"
local lara = trx.items["lara"]
trx.items.spawn(object_id, pos, [angle_y], [opts])
Creates a new item of the given object type at the given position.
Parameters:
object_id (trx.catalog.objects). Object type to spawn.
pos (trx.math.Vec3). World position. Must lie inside the level.
angle_y (trx.math.Angle, optional, default 0). Facing angle.
opts (table, optional). How to spawn it.
Keys:
Returns: trx.items.Item or nil. nil if the item pool is exhausted.
Example:
local wolf = trx.items.spawn(
trx.catalog.objects.wolf, trx.lara.item.pos, 0, { activate = true })
trx.items.count()
Returns the total number of allocated items. Same as #trx.items.
Returns: integer. How many slots the level holds, live or not.