Lost Artefacts

Object module

Module for the object definitions a level is built from.

An object is the pattern every item of that type is cut from: a wolf's radius, not this wolf's. Per-item state lives on the item - see trx.items.

Indexing

Indexing the module reaches an object definition, so trx.objects.wolf is the wolf. Keyed by object id or catalog name, not by position.

trx.objects[key] (key: trx.catalog.objects or string, value: trx.objects.Object or nil). Object id, or its catalog name.

Example:

trx.objects.wolf.properties.max_hit_points = 30

Properties

trx.objects.query (trx.objects.ObjectQuery). The identity query over every object definition. Narrow it and read it. (read-only)

Structures

trx.objects.MeshNum

The mesh's number within the object it belongs to. Counted from 0.
trx.objects.Object

An object definition.

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_count: integer. How many animations it has. (read-only)
- is_intelligent: boolean. Whether the object thinks - a creature rather than a door. (read-only)
- loaded: boolean. Whether the current level has this object at all. An object it never loaded still has a definition; this is how a script tells. (read-only)
- mesh_count: integer. How many meshes the object is built from. (read-only)
- pivot_length: integer. How far in front of itself the object turns about.
- radius: integer. Collision radius.
- semi_transparent: boolean. Whether the object is drawn see-through.
- shadow_size: integer. Size of the blob shadow drawn under it, and 0 for none.
- smartness: integer. How readily a creature of this type finds its way to Lara.
Computed properties (derived, not stored on the object):
- default_names: table. The compile-time English names. A lookup tries these when the player's language has no matching name, so an English name still reaches the object in a translated install.
- name: string. The name the game shows for the object. It is the first value in names, or nil where the object has no name.
- names: table. Every name the object answers to, in the player's language. An object has more than one: a large medipack is also a medipack and a big medi.
- properties: table. The object's own typed properties, which every item of the type inherits. Writing here changes the default for all of them; write to trx.items.Item.properties to change one item only. Iterable with pairs(). See Objects.
Methods:
- object:add_family(family)
  Puts the object in a family, so a query narrowed to that family finds it. A family a script mints is reached the same way as one the game ships.
  
  Parameters:
  - family (string). Which family, by the name it answers to.
  Example:
```
local family = trx.catalog.mint(trx.catalog.Context.FAMILIES, "mymod:explosive")
trx.objects.barrel:add_family("mymod:explosive")
for _, id in ipairs(trx.objects.query:family("mymod:explosive"):ids()) do ... end
```
- object:get_default_names()
  The compile-time English names. A lookup tries these when the player's language has no matching name. Prefer default_names.
  
  Returns: a list of string.
- object:get_names()
  Every name the object answers to, in the player's language. Prefer names.
  
  Returns: a list of string.
- object:get_property(name)
  Reads one of the object's properties. Prefer object.properties.<name>.
  
  Parameters:
  - name (string). Which property, as the object declares it.
  Returns: any or nil. The value, of the type the property is declared with.
- object:get_property_names()
  Names of every property this object declares.
  
  Returns: a list of string.
- object:link(link, other)
  Links this object to another object. Use the relation name that the game uses, such as gun_to_ammo. This lets the game use relations between objects created by a script.
  
  Parameters:
  - link (string). The relation to add, such as gun_to_ammo.
  - other (trx.catalog.objects). The object to link.
  Example:
```
trx.objects[gun]:link("gun_to_ammo", ammo)
```
- object:remove_family(family)
  Takes the object out of a family.
  
  Parameters:
  - family (string). Which family, by the name it answers to.
- object:set_property(name, value)
  Writes one of the object's properties. Prefer object.properties.<name> = ....
  
  Parameters:
  - name (string). Which property, as the object declares it.
  - value (any). What to write, of the type the property is declared with.
trx.objects.ObjectQuery

A trx.query.Query over every object the engine knows, with the narrowings below on top of the ones every query has. Objects answer to names, so it carries the name layer too - see trx.query.NamedQuery.

The families do not cover pickup between them: a second state of something Lara already carries, such as a part-full waterskin, is in none of them.

Methods:
- objectquery:ammo()
  Clips for a weapon.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:animation()
  An animation an object borrows rather than a thing of its own.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:boss()
  A creature the game treats as a boss, which the enemy health bar can be held to.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:collectible()
  A collectible, by the slot it fills.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:creature()
  The object is a creature.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:door()
  A door.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:enemy()
  A creature that fights Lara rather than for her.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:examine()
  An examine item, by the slot it fills.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:family(family)
  Narrows to a family by name, which is how a query reaches a family a script mints. The families the game ships have a narrowing of their own.
  
  Parameters:
  - family (string). Which family, by the name it answers to.
  Returns: trx.query.Query. The narrowed query.
  
  Example:
```
trx.objects.query:family("mymod:explosive"):ids()
```
- objectquery:gun()
  A weapon.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:inventory_item()
  An icon in the inventory rather than a thing in the world.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:key()
  A key, by the slot it fills.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:loaded()
  The level loaded the object, so items of it exist.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:loyal()
  One of Lara's own: the butler, and Lara herself.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:null_object()
  A placeholder that is never drawn.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:pickup()
  Something Lara can pick up.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:pushable()
  A block Lara pushes and pulls.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:puzzle()
  A puzzle item, by the slot it fills.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:quest()
  A quest item, by the slot it fills. This is what carries the scion.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:receptacle()
  A slot a puzzle item goes into.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:secret()
  The trinket a secret trigger sits under.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:spawnable()
  The object is a thing in the world at all, rather than an inventory icon, an animation, or a null placeholder.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:supply()
  A pickup Lara spends rather than keeps.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:switch()
  A switch Lara throws.
  
  Returns: trx.query.Query. The narrowed query.
- objectquery:tool()
  A pickup named for itself rather than filling a numbered slot: the crowbar, the lasersight, the binoculars, the waterskins, the leadbar.
  
  Returns: trx.query.Query. The narrowed query.

Functions

trx.objects.get(key)
Retrieves an object definition by id or by name.

Parameters:
- key (trx.catalog.objects). Object id, or its catalog name: trx.objects["wolf"].
Returns: trx.objects.Object or nil. nil if no such object exists.

Example:
```
local wolf = trx.objects.wolf
wolf.properties.max_hit_points = 30
```
trx.objects.declare(object_id, spec)
Defines setup for an object created by a script. The setup is applied at each level load because object records are rebuilt for each level.

control runs once each frame for each active item. initialise runs when an item is created. Both functions receive the item.

Parameters:
- object_id (trx.catalog.objects). The object created with trx.catalog.mint.
- spec (table). The object setup: control, initialise, radius, shadow_size and save_position.
Example:
```
local blast = trx.catalog.mint(trx.catalog.Context.OBJECTS, "mymod:blast")
trx.objects.declare(blast, {
  radius = 128,
  save_position = true,
  initialise = function(item) item.hit_points = 60 end,
  control = function(item) item.pos.y = item.pos.y - 8 end,
})
```
trx.objects.borrow_content(object_id, source_id)
Copies meshes and animations from another object. Use this when the new object has no models in the level, such as a custom projectile that uses the rocket model.

Parameters:
- object_id (trx.catalog.objects). The object that receives the meshes and animations.
- source_id (trx.catalog.objects). The object that gives the meshes and animations.
Returns: boolean. false if the level has no content for the source object.

Example:
```
trx.objects.borrow_content(my_blast, trx.catalog.objects.rocket)
```
trx.objects.swap_mesh(object_id1, object_id2, [mesh_num1], [mesh_num2])
Swaps meshes between two objects. With no mesh numbers, swaps all of them; with both, swaps just those two. One without the other raises.

Parameters:
- object_id1 (trx.catalog.objects).
- object_id2 (trx.catalog.objects).
- mesh_num1 (trx.objects.MeshNum, optional). Mesh of the first.
- mesh_num2 (trx.objects.MeshNum, optional). Mesh of the second.
trx.objects.swap_sprite(object_id1, object_id2)
Swaps the sprites of two objects, which is how a pickup looks when 3D pickups are turned off. Raises if either object is drawn from meshes rather than a sprite.

Parameters:
- object_id1 (trx.catalog.objects).
- object_id2 (trx.catalog.objects).