API Entity Access and Movement

Entity access and movement

Lua API / Entities / Entity access and movement

Entity handles provide scoped access to a live player, native entity, or BetaMoon entity. The available methods depend on the target and its declared capabilities.

Motion and direct control

Every kind accepts physics.mode = "static" or "dynamic". Props default to static; projectiles, living entities, and pickups default to dynamic. Static mode stops automatic movement while preserving that kind's health, lifetime, pickup, and callback behavior. For example, a stationary living creature can have health and interactions while Lua changes its position and facing. Static pickups remain collectible.

Dynamic props use collision-aware movement, gravity, drag, and optional bouncing. Prop-only gravity defaults to 0.04, drag to 0.98, groundFriction to 0.6, and bounce to 0; each accepts 0–1. Prop-only pushable defaults to false. Other kinds retain their native or declared movement rules in dynamic mode.

physics = { mode = "dynamic", gravity = 0.04, bounce = 0.3, pushable = true }

Every kind exposes getPosition, setPosition, getRotation, setFacing, getVelocity, and setVelocity through the entity-handle methods on this page. A static entity can still be moved and rotated by Lua; dynamic mode adds automatic motion between callbacks.

The following methods apply to ctx.player, ctx.entity and ctx.target.entity when present.

Handles are live only for the current callback. State queries return detached snapshots where noted; storing a handle for a later tick is invalid. AI routines receive the same methods as other entity callbacks.

entity:isPlayer()

Returns whether the entity is a player.

local player = ctx.entity:isPlayer()

entity:isSneaking()

Returns whether the entity is sneaking.

local sneaking = ctx.player:isSneaking()

entity:heal(amount)

Mutable. Amount is integer 0–32767. Heals a living entity or a nonliving BetaMoon entity with health = { max = ... }. Returns false if the target has no supported health or is dead; true does not report the exact health gained.

ctx.player:heal(2)

entity:damage(amount)

Mutable. Amount is integer 0–32767; applies attack damage attributed to the context player when available. On a BetaMoon entity this runs its damage callbacks with cause = "script". Returns whether the damage handler accepted the hit; this does not necessarily mean health was lost.

local accepted = ctx.target.entity:damage(2)

entity:kill(attacker)

Mutable. Enters a BetaMoon entity's death lifecycle immediately. The optional attacker must be a loaded entity in the same world. Returns false for native entities, multipart proxies, missing definitions, dead entities, or an entity already in its death lifecycle. Declared death drops and enabled inventory/equipment drops run once before onDeath. Healthless props can use this method to distinguish destruction from plain removal.

ctx.entity:kill(ctx.attacker)

entity:dropLoot()

Mutable. Samples the BetaMoon entity's declared drops and drops and clears current inventory or equipment contents whose capability has dropOnDeath = true. Every call runs independently, including repeated calls on the same entity. A rolled count is a total and is split into legal native stacks for the selected item. It does not enter the death lifecycle or call onDeath. Returns false for native entities, multipart proxies, missing definitions, or when server-side item emission is unavailable.

ctx.entity:dropLoot()
ctx.entity:remove()

entity:dropItem(item)

Mutable. Drops one validated item stack at the entity. Accepts an item reference, numeric item ID, or { id, count, damage } stack table. The count defaults to 1 and cannot exceed the item's stack limit. Returns whether the item was emitted on the server.

ctx.entity:dropItem({ id = 331, count = 3 })

entity:getVelocity()

Returns a detached numeric { x, y, z } velocity snapshot.

local velocity = ctx.entity:getVelocity()

entity:setVelocity(x, y, z)

Mutable. Replaces all three motion components with finite numbers.

local velocity = ctx.entity:getVelocity()
ctx.entity:setVelocity(velocity.x, 0.8, velocity.z)

entity:getPosition()

Returns a detached numeric { x, y, z } position snapshot.

entity:getType()

Available for BetaMoon typed entities. Returns the current type reference.

Additional entity queries

Method	Result
isAlive()	Whether the entity remains alive.
getNativeType()	Registered native save type, or nil.
getName()	Player name, BetaMoon display name, or native type.
getIdentity()	Stable saved ID on BetaMoon typed entities.
getAge()	Ticks since this instance began updating.
getRotation()	Detached { yaw, pitch } in degrees.
getEnvironment()	Detached { onGround, inWater, burning, collidedHorizontally, collidedVertically }.
getHealth()	Current integer health for living entities and nonliving BetaMoon entities with health; otherwise nil.
getMaxHealth()	Declared maximum for BetaMoon living entities and nonliving BetaMoon entities with health; otherwise nil.
getTarget()	Current target of a creature, otherwise nil.
getOwner()	Launch owner on a BetaMoon projectile, or loaded saved owner for an ownership-capable entity.
getOwnerIdentity()	Saved player:<name> or entity:<identity> projectile/relationship owner token, or nil.
getTeam()	Current namespaced team key, or nil.
isAlliedWith(other)	Whether ownership or team relationships mark another entity as allied.
getInventorySize()	Container slot count on a capable entity, or nil; slot methods use one-based indices.
getInventoryStack(slot)	Detached { id, count, damage }, or nil.
getEquipmentStack(slot)	Detached logical equipment stack, or nil.
getPassenger()	Current native passenger, or nil.
getVehicle()	Current native vehicle, or nil.
getBehaviorState()	Saved named behavior state, or nil.
getTimer(name)	Remaining simulation ticks for a named timer, or nil.
getPickupStack()	Detached { id, count, damage } on a BetaMoon pickup, or nil if empty.
getPartName()	Name on a multipart shape handle.
getPartRole()	"hit" or "interaction" on a multipart shape handle.
getParent()	Parent handle on a multipart shape.
getNearbyEntities(radius)	Up to 256 live handles within a true radius at most 32 around this entity.
canSee(target)	Living entity's block line-of-sight to another live handle.
getDistanceTo(target)	Distance in blocks, or nil if the target is unavailable.

Additional entity actions

Method	Effect
attack(target, damage)	Attribute integer damage to this entity; BetaMoon targets receive cause = "script". Returns whether the target accepted the hit.
setFacing(yaw, pitch)	Set finite facing angles in degrees.
facePosition(x, y, z, maxYaw, maxPitch)	Turn toward world coordinates, with optional per-call angular limits (0–180 degrees); returns false when already at that point.
setPosition(x, y, z)	Move an entity to a loaded position; returns false for unloaded or out-of-bounds destinations and multipart hitbox proxies.
faceToward(target, maxYaw, maxPitch)	Turn a living entity toward a target by at most the supplied degrees (defaults 30 and 30); returns false if unavailable.
setMovement(forward, strafe, jump)	Supply movement inputs in -1–1 and a boolean jump for whole-manual AI or a composed manual movement stage; otherwise returns false.
navigateTo(x, y, z, range)	Request a ground path for a path-following creature; returns whether one was found. Integer Y 0–127, range at most 32 (default 16). Composed AI tracks the route's status.
getNavigationStatus()	Current composed ground route status: idle, moving, reached, blocked, unavailable, or cancelled; otherwise nil.
getNavigationWaypoint()	Detached { x, y, z } for the current composed ground waypoint, or nil.
cancelNavigation()	Stop a composed ground route; returns false when composed AI is unavailable.
getPathTo(x, y, z, range)	Get detached native path waypoints, or nil if no path or required chunks are unloaded. Integer Y 0–127, range at most 32 (default 16). Manual AI may follow or replace this route.
setTarget(target)	Set a creature's target; pass nil to clear target and path. Returns false if unavailable.
setOwner(owner)	Save a player or BetaMoon entity owner; pass nil to clear.
setTeam(team)	Set a namespaced per-instance team override; pass nil to restore the default.
setInventoryStack(slot, stack)	Set a one-based container slot; nil clears it. Returns false without the capability.
removeInventoryStack(slot, count)	Remove up to 64 items and return a detached stack, or nil.
openInventory(player)	Open the capable entity's native container for a nearby player.
setEquipmentStack(slot, stack)	Set or clear an enabled logical hand/head/chest/legs/feet slot.
addPassenger(passenger)	Mount one allowed passenger on a single-seat capable entity.
removePassenger()	Dismount the current passenger from a capable entity.
dismount()	Dismount this entity from its current vehicle.
setBehaviorState(state)	Change saved state, running exit then enter callbacks.
startTimer(name, ticks, repeatTicks)	Start or replace a saved simulation-time timer.
cancelTimer(name)	Cancel an active named timer.
collect(player)	On a BetaMoon pickup, try native inventory collection and return whether items transferred.
setPartOffset(name, x, y, z)	Move a multipart damage shape center, components -16–16 blocks; returns false if absent.
setInteractionOffset(name, x, y, z)	Move a multipart interaction shape center, components -16–16 blocks; returns false if absent.
setSensorOffset(name, x, y, z)	Move a named sensor center on a BetaMoon entity, components -16–16 blocks; returns false if absent.
playAnimation(clip, options)	Select a clip for this BetaMoon instance; returns false without an appearance animation asset. Options: speed, startTime, and restart.
stopAnimation()	Clear this instance's animation selection and return whether one was active.
getAnimation()	Get a detached { clip, speed, time } snapshot of the transient selection, or nil.
setVisible(visible)	Override this BetaMoon instance's visibility.
setVisualOffset(x, y, z)	Set a local visual-only offset, components -16–16 blocks.
setVisualRotation(yaw, pitch, roll)	Add visual-only rotation in degrees after entity facing.
setVisualScale(x, y, z)	Set visual-only scale, components 0–64.
resetVisuals()	Restore declared visibility and the identity visual transform.
playSound(event, options)	Emit a registered sound event at this entity; works for BetaMoon and native entities. Options: volume, pitch, and range.
remove()	Remove this entity without death callbacks or death drops.

getPosition(), getVelocity(), and setVelocity(x, y, z) provide position and motion access for every entity kind. Each velocity component must be within -16-16 blocks per tick. setFacing controls yaw and pitch for props as well as living entities. Entity inventories and relationships documents inventory, ownership, and riding. Entity lifecycle and data documents states and timers. Entity presentation and sounds documents animation and render controls. Living entities and AI explains how predefined and Lua-controlled behavior use movement methods.

entity.data:get(name) / set(name, value)

Available for BetaMoon typed entities with declared persistent fields. get returns a field's current value. set is mutable and validates the field type. Both require an active callback.

entity.memory:get(name) / set(name, value)

Available for BetaMoon typed entities. Holds unsaved, per-instance AI state. Values are copied on read and write; nil clears a field. See entity memory for limits and supported values.