Engine.object¶

Objects in the world: bipeds, vehicles, weapons, equipment, projectiles, scenery, devices and the rest.

Object types are written as strings: "biped", "vehicle", "weapon", "equipment", "garbage", "projectile", "scenery", "deviceMachine", "deviceControl", "deviceLightFixture", "placeholder" and "soundScenery".

Functions¶

Engine.object.getObject¶

local object = Engine.object.getObject(handle, type)

Returns an object, or nil when the handle does not point to a live object. With type, the object is only returned when it is of that type.

The object comes back with the fields of its type, such as BipedObject for a biped. Scenery, placeholders and sound scenery come back with the fields common to every object.

Engine.object.getObjectType¶

local type = Engine.object.getObjectType(handle)

Returns the type of an object, or nil when the handle does not point to a live object.

Engine.object.getObjectCount¶

local count, maxCount = Engine.object.getObjectCount()

Returns how many objects exist and how many can exist.

Engine.object.filterObjects¶

local vehicles = Engine.object.filterObjects("vehicle")

Returns a list with the handles of every live object of the given type. The list is empty when no map is loaded.

Engine.object.createObject¶

local handle = Engine.object.createObject(tagHandle, parentHandle, position)

Creates an object from an object tag and returns its handle. Pass nil as parentHandle for an object without a parent; the argument cannot be left out. position is a Point3d or a table with x, y and z.

Engine.object.deleteObject¶

Engine.object.deleteObject(handle)

Deletes an object. Raises an error when the handle does not point to a live object.

Engine.object.getObjectPosition¶

local position = Engine.object.getObjectPosition(handle)

Returns the position of an object as a Point3d, or nil when the handle does not point to a live object.

Engine.object.setObjectPosition¶

Engine.object.setObjectPosition(handle, position, forward, up)

Moves an object. Unlike writing the object's position fields, it also updates the object's place in the map, so it is drawn and collides correctly at its new position.

Parameter	Type	Description
`handle`	`ObjectHandle`	The object.
`position`	`Point3d`	New position, or a table with `x`, `y` and `z`.
`forward`	`Vector3d`, optional	New facing direction, or a table with `i`, `j` and `k`. Keeps the current rotation when missing.
`up`	`Vector3d`, optional	New up direction. Derived from `forward` when missing. Needs `forward`.

Engine.object.objectAttachToMarker¶

Engine.object.objectAttachToMarker(handle, marker, attachmentHandle, attachmentMarker)

Attaches two objects together, joining the marker marker of handle to the marker attachmentMarker of attachmentHandle. All four arguments must be given; markers can be nil.

Engine.object.unitEnterVehicle¶

local entered = Engine.object.unitEnterVehicle(unitHandle, vehicleHandle, seat)

Puts a unit (biped or vehicle) in a seat of vehicleHandle. seat is a seat index (from 1) or a seat label, matched case insensitively. Returns true if the unit got in; it stays out when the seat is taken or the unit cannot use it.

On a network host, a unit controlled by a player enters through the same player action as pressing the action button, so every client sees it. Anywhere else the change is local only.

Node matrices and orientations¶

Objects returned by getObject have methods to read the pose of their model nodes. Both return live views into the object: writing to them changes what the next frame draws until the engine recomputes them.

Method	Returns	Description
`getNodeMatrixCount()`	`integer`	Number of baked node matrices, 0 when there are none.
`getNodeMatrix(index)`	`Matrix4x3` or `nil`	Node matrix `index` (from 1), in world space. `nil` when out of range.
`getNodeOrientationCount(buffer)`	`integer`	Number of node orientations in `buffer`.
`getNodeOrientation(index, buffer)`	`NodeOrientation` or `nil`	Node orientation `index` (from 1), relative to its parent node. `nil` when out of range.

buffer is optional: "pose" (default) is the pose the node matrices are baked from, and "blendSource" is the pose the engine blends away from when an animation starts. Only bipeds, vehicles, weapons, equipment and garbage have orientations; other objects report 0.

Example¶

-- Spawn a warthog above the local player.
local player = Engine.player.getPlayer()
local position = Engine.object.getObjectPosition(player.unitHandle)
local tag = Engine.tag.lookupTag("vehicles\\warthog\\mp_warthog", "vehicle")
local warthog = Engine.object.createObject(tag, nil, {x = position.x, y = position.y, z = position.z + 2})