Ped (tm.ped)

Peds on the client and on the server, with different feature sets.

Client

tm.ped.create(props)

Creates a ped on this client. The props table becomes the returned instance, with id, entity, remove and updatePed added. It raises an error when there is no usable model (or appearance.model) or no coords.

local ped = tm.ped.create({
    model = 's_m_y_cop_01',
    coords = vector4(100.0, 200.0, 30.0, 90.0), -- w is the heading
    static = true,         -- frozen, invincible, ignores the world
    distance = 100.0,      -- only exists while the player is closer than this
    nametag = 'Officer Smith',
    animation = { dict = 'amb@world_human_cop_idles@male@base', clip = 'base', flag = 1 },
    onCreated = function(entity) print('spawned', entity) end,
    onDeleted = function(entity) print('removed', entity) end,
})

Prop	Type	Description
model	string or integer	Model name or hash. Taken from appearance.model when missing.
coords	vector4	Position. w is the heading.
heading	number	Heading, used when coords has no w.
appearance	table or JSON string	Appearance data, see below.
animation	table	{ dict, clip, flag?, duration? } plays on spawn.
static	boolean	Freeze, make invincible and ignore the world.
distance	number	Streaming radius in meters.
networked	boolean	Create it as a networked ped.
nametag	string	Floating label over the ped.
robbable	boolean	Sets the local state flag unrobbable to false.
onCreated	fun(entity)	Runs every time the entity is created (again after a distance respawn). An error in it is logged and the ped is kept.
onDeleted	fun(entity)	Runs when the ped is removed or despawned by distance.

Instance

Field or method	Description
id	Unique id.
entity	The entity handle, 0 while a distance ped is despawned or its model could not load.
remove()	Deletes the ped and its tag. Safe to call more than once.
updatePed(key, value)	Changes one prop and recreates the ped (a ped cannot be edited in place).

Appearance and animation hooks

Appearance and emotes are owned by other resources, so this import only announces them. After the ped is created it fires local events that an appearance or emote resource can listen to with AddEventHandler:

Event	Arguments	When
tm_lib:ped:applyAppearance	ped, appearance	The ped has an appearance table.
tm_lib:ped:applyAnimation	ped, animation	The animation table has no dict and clip (for example { emote = 'smoke' }). A dict and clip animation is played directly.

tm.ped.get(input)

Turns an instance, an entity handle, a ped id or { id = id } into an entity handle. Returns nil when it is not a live ped. With no argument it returns the player ped.

tm.ped.getCoords(input)

Returns a vector4 (x, y, z, heading) for the same inputs as get, or nil.

tm.ped.speak(input, line, opts?)

Makes a ped say one of the game's ambient lines. line is a speech name ('GENERIC_HI') or { name, param?, voice? }. The voice follows the ped model, so a line the model has no clip for is silent. voice forces another ambient voice. opts.interrupt cuts off a line the ped is still saying. Without it a ped does not talk over itself and waits 1.5 seconds between lines. Returns false when the ped, the line or the cooldown stopped it.

tm.ped.stopSpeaking(input)

Cuts off whatever the ped is saying.

tm.ped.handsUp(input, seconds, from?, opts?)

Raises a ped's hands (a robbery reaction) for seconds, facing from (a position). The ped stands still and ignores the world, then the animation stops and opts.onDone(ped) runs so you can put it back to its scenario. A ped another client controls is left alone. Asking again restarts the timer. Returns false when the ped is gone, dead, in a vehicle or controlled elsewhere.

tm.ped.handsDown(input)

Ends a handsUp early. The hands come down and onDone runs now. Returns false when the ped was not holding its hands up.

Behavior

• A distance ped is checked every 2 seconds. The checking thread only exists while at least one distance ped does.
• Peds are deleted when the resource stops.
• Local state flags set on every ped: unrobbable (true unless robbable), ignore (true, a tag for interaction layers) and nametag (the tag handle, when there is a nametag). None of them is replicated.
• Server peds made by this same resource (see below) get their client-owned setup here: the owning client makes a static ped invincible, draws its nametag and acknowledges, which clears the initPed state.
• A server ped removed with remove(true) is deleted by whichever client controls it.

Server

tm.ped.create(props)

Creates a networked ped. The props table becomes the returned object, with id, entity, netid, exists and remove added. Returns nil and a reason when the game could not create the entity.

local ped = tm.ped.create({
    model = 's_m_y_cop_01',
    coords = vector4(100.0, 200.0, 30.0, 90.0),
    static = true,
    nametag = 'Officer Smith',
    robbable = false,
    zOffset = -1,
    onCreated = function(entity) print('created', entity) end,
})

Prop	Description
model, coords, static, robbable, nametag	As on the client. The owning client applies invincibility and the nametag.
zOffset	Added to coords.z. Default -1 so the ped stands on the ground. Use 0 for exact coordinates.
routingBucket	Routing bucket for the ped.
orphanMode	SetEntityOrphanMode value.
onCreated	fun(entity).
onDeleted	fun(entity), runs on remove().

Field or method	Description
entity, netid	Entity handle and network id.
exists()	Call with a dot. true while the entity exists.
remove(cleanup?)	Deletes the ped. With cleanup the entity is only flagged (cleanupEntity state) for the client that controls it to delete, and the server deletes it after 10 seconds if that did not happen. onDeleted is skipped in that case.

tm.ped.get(input)

The entity handle for a ped id, a created object or { id = id }. nil when it is not a live ped.

State

Server peds set three replicated state keys: ignore, unrobbable and initPed. initPed is a plain snapshot of the props (resource, model, coords, static, nametag, robbable) with the name of the resource that made the ped. It is guarded by a tm.state rule in the resource that imports tm.ped on the server: only the owning client may clear it, only inside 250 meters, and only by sending the exact snapshot back. For the client part to run, the same resource must import tm.ped on the client too.

Server peds are deleted when the resource stops, and forgotten when the game removes them.