addEntity attaches an interaction stack to a live entity - a spawned vehicle, ped, or object you already hold a handle to. The anchor rides the entity as it moves: on a bone when you name one, at an offset otherwise, at the entity’s center as the last resort.
nil with a console error explaining what’s wrong. Remove it any time with exports.lation_interact:remove(id).
This page covers what
addEntity adds on top of the shared vocabulary. The anchor fields (label, options, icon, stages, expand, reveal, debug), the option table, condition gates, and handlers are documented in Options.Parameters
number
required
A client entity handle. The entity must exist at call time - a missing entity rejects the registration with a console error and returns
nil.If the server hands you a network id, convert it first: NetworkGetEntityFromNetworkId(netId) (or NetToVeh / NetToPed / NetToObj).table
required
The anchor spec - all the shared anchor fields plus the two placement fields below.
Placement
string
Entity bone name the anchor rides (e.g.
'boot' for a vehicle’s trunk, 'bonnet' for the hood). The bone index is resolved lazily, once per anchor; a bone the entity doesn’t have falls through to offset, then to the entity center.vector3
Entity-local offset from the entity center, rotating with the entity. Used when no
bone is given, or as the fallback when the named bone is missing.One Call, One Anchor
EachaddEntity call creates exactly one anchor with one position and one option stack. To give an entity several interaction spots - trunk, hood, doors - register it several times, one call per spot. Each call returns its own id and is removed independently.
If an
addModel or addGlobal* rule matches the same entity at the same bone or offset, its options merge into the same stack - explicit addEntity options first, then the model rule’s, then the global’s. One stack, never two overlapping anchors.Lifecycle
Entity anchors clean up after themselves:- The entity stops existing - deleted, or streamed out of the client’s world - and the anchor is removed automatically, through the same path as an explicit
remove(id). It does not come back if a networked entity streams back in; re-register on stream-in, or useaddModelfor interactions that should exist wherever the model does. - Your resource stops and every anchor it registered is dropped.
- You call
remove(id)whenever the interaction’s moment has passed.
Death does not remove an anchor - a dead ped still exists, and searching a body is a legitimate interaction. If an option shouldn’t apply to the dead, gate it with
canInteract and IsEntityDead.Handler Payload
Handlers on entity anchors receive the entity in their payload:event receives the same table. serverEvent receives it minus entity - handles are client-local, so hand the server data.netId and let it call NetworkGetEntityFromNetworkId. A purely local entity (a client-spawned prop) has no netId at all. See Handlers for the full dispatch order.
canInteract predicates also get data.entity, evaluated off the frame path - never per render frame.
Behavior Notes
Quiet until looked at
Quiet until looked at
Entity anchors default to
reveal = 'focus' (Config.Reveal.entity): nothing renders until attention lands on the entity, so a street full of registered cars stays perfectly quiet. Pass reveal = 'ambient' to mark one with a grain of light from a distance - right for a mission-critical vehicle the player is meant to find.Moving entities
Moving entities
An entity moving faster than
3.0 m/s holds at the grain stage and can’t be focused - a passing car earns a point of light, not a prompt. It becomes interactable the moment it slows down.Statebag conditions
Statebag conditions
The
state option gate reads Entity(entity).state, so it works on entity anchors (points and zones have no statebag). state = 'trunkLocked' shows a row while the statebag is truthy; state = { key = 'trunkLocked', value = false } while it equals the value. See Condition Gates.Example
A trunk stack riding theboot bone, and the hood as its own second anchor - one call per spot:
remove calls at the end simply do nothing.