EntityHandle type

A body the world moves: a pack's own entity, a mob, a stack on the ground. Every read is a fresh look at the world, so a handle to something that has died reads nil. Inside a hook the same handle reads the entity as it was at the top of the tick, and its writes land at that hook's own slot.

Functions 7

entityHandle:play(animation: string, opts: { speed: number? }?)

Model size: reads vec3; write a positive number or equal-axis vec3. Nil without a model. Plays a model entity's animation from the start; on the one already playing, speed only changes its speed.

entityHandle:stop(animation: string)

Stops a model entity's animation; the parts stay where they are.

entityHandle:move(at: Vec3, rotation: BodyRotation?)

Gone on the next tick. Sets position and optional rotation together.

entityHandle:destroy() → boolean

entityHandle:push(v: Vec3) → boolean

A shove, in blocks a tick, added to what it is already doing.

entityHandle:settle() → boolean

It stops being an entity and is a block again where it stands. No argument: the entity remembers what it was.

entityHandle:nearby(radius: number) → { EntityHandle }

What else is around it, by horizontal distance.

Fields 18

entityHandle.id: number

Its entity id, the one players.on_click reports in hit.entity_id.

entityHandle.name: string?

The kind's name: "cow", "rave:rocket". Nil once it is gone.

entityHandle.alive: boolean

Whether it is still in the world. A hook only runs for one that is.

entityHandle.age: number?

Ticks lived.

entityHandle.velocity: Vec3?

Where it is, live; writing it is a teleport. Nil once it is gone. Partial writes preserve other angles; nil after removal. Bodies have no roll. How it is moving, live; writing it is steering by hand. Nil once it is gone. writing it is steering by hand

entityHandle.on_ground: boolean?

Whether it stands on something. Nil once it is gone.

entityHandle.health: number?

Its health now. Nil once it is gone.

entityHandle.max_health: number?

The most health its kind gives it. Nil for an entity that is not a mob and once it is gone. Read-only.

entityHandle.hostile: boolean?

Whether its kind is hostile. Nil once it is gone.

entityHandle.physics: Physics?

Which order of operations moves it: "vehicle", "living", "falling", "item" or "none".

entityHandle.origin: string?

The block it used to be, for anything that arrived through a transition; nil for anything that was never a block.

entityHandle.data: DataView

A pack-defined entity's attached record. Nested edits write through. Saved with persist = "save". Built-in entities raise an error on access. on_steer/on_tick views expire after the callback batch; copy to keep a snapshot.

entityHandle.forward: number

The intent fields: what a body *wants* to do, which is what steering is. Writing one outside on_steer lasts until the next decision.

entityHandle.strafe: number

Intent: 1 left, -1 right. A vehicle's seat 1 writes it from the keys every tick.

entityHandle.jumping: boolean

Intent: whether it wants to jump. A vehicle's seat 1 writes it from the keys every tick.

entityHandle.flying: boolean

Intent, a living body with can_fly only: true flies (no gravity; forward moves it along its look, pitch included), false falls and walks. Setting it true on another body is an error.

entityHandle.driver: Player?

Whether it is in water now. False for an entity that is not alive. The player supplying driving input from seat 1; nil for an NPC or empty seat.

entityHandle.paint: { [string]: Ink }

Every occupant by seat number, including NPCs; nil means empty. Material name to colour; write-only.