Server Entity API

Methods available on the entity object passed to server-side Lua hooks — movement, health, animation, mounts, and player utilities.

Most server-side hooks hand your script an entity object: the mob in a mob update hook, the player in an item-use or chat-command hook, the rider and mount in mount hooks, and so on. This page lists everything you can do with one.

An entity can be a player, a mob, a mount, or a projectile. Methods that only make sense for one kind are safe to call on any entity — on the wrong kind they quietly do nothing and return nil, 0, false, or an empty table as noted below. Your script never errors just because it got a player where it expected a mob.

You receive entity objects from:

• Mob hooks (scripts.server-update, scripts.server-on-create) — the mob itself
• Item hooks (server-on-primary-use) — the player using the item
• Chat commands — the player who typed the command (see lua-chat-commands.md)
• Interactable interaction hooks — the interacting player
• Mount hooks (server-on-mounted / server-on-dismounted) — the rider and the mount
• NPC dialogue hooks — the player and the NPC (see lua-npc-dialogue.md)
• entity:get_closest_player(), entity:get_entity_by_id(...), and the globals spawn_mob_at(...) / spawn_mount(...)

Persistent Script State: lua_data

Every entity carries a lua_data table your scripts can freely read and write. It persists for the lifetime of the entity, across every hook call, so it is the standard place to keep per-entity state (timers, AI mode, counters):

-- /mobs/my_mob/scripts/server_update.lua
return function(entity, delta_ns)
    local data = entity.lua_data
    data.time_alive = (data.time_alive or 0) + delta_ns * 1e-9
end

entity.lua_data returns the live table — changes to its fields stick immediately. Assigning a whole new table (entity.lua_data = {}) replaces everything.

Identity

Position and Movement

Positions are world coordinates in block units (1.0 = one block).

Forced movement vs. setting velocity. set_x_velocity / set_y_velocity replace the entity’s velocity and only work on server-driven entities (mobs, mounts, projectiles) — on a player they do nothing, because the player’s own client is authoritative over its position. apply_impulse / pull_toward are the way to move a player from a script: the push is sent to the player’s client and folded into its movement for the duration. They also work on mobs (added straight to velocity). The push is capped at the target’s own maximum velocity, so it accelerates hard but never launches faster than the entity could normally move; use a longer duration_ms or a repeated pull_toward for a sustained drag. Typical use: local p = entity:get_closest_player(); if p then p:apply_impulse(dir_x * 40, dir_y * 40) end.

Pathfinding (Mobs Only)

Collision

Appearance and Actions

Health

Inventory

Capabilities

Persistent per-player unlocks — the Metroidvania ability set checked by sealed barriers. Capabilities are free-form string ids you choose; grant them from progression scripts (a boss death, a consumed item, a mount, an interactable). They are saved with the player and carry across world transfers. Players only.

-- A shrine that permanently grants an ability. Block interact handlers receive
-- (world, x, y, layer, actor_entity_id, actor); `actor` is the interacting player.
return function(world, x, y, layer, actor_entity_id, actor)
    if actor and actor:grant_capability("storm_ward") then
        actor:send_message("You feel the storm's blessing.")
    end
end

Players

Mounts, Riders, and Taming

These work on mounts and on mobs configured as rideable. On anything else they return the neutral value listed.

Area-of-Effect Zones

Example — A Mob That Chases the Nearest Player

-- a mob's scripts.server-update
return function(entity, delta_ns)
    local player = entity:get_closest_player()
    if player == nil then
        entity:stop_pathing()
        return
    end

    local target = player:get_location()
    -- Safe to call every tick: re-path requests are rate-limited by delay_ms.
    entity:mob_path_to(target.x, target.y, 2.0, 200, 500)
end

Notes

• Timing: update hooks receive delta_ns in nanoseconds. Convert with delta_ns * 1e-9 for seconds.
• Replication: animate, primary_use, mount_entity, dismount, create_aoe_zone, and send_message notify clients immediately. set_location re-indexes the entity on the server at once and reaches clients through the regular entity sync. Plain state setters (velocity, state, display name, collision) take effect on the server and reach clients through the regular entity sync.
• Long-running scripts: each hook call has a server-side time budget (a few seconds). Keep per-tick work small; spread heavy work across ticks using lua_data.
• Numeric inputs are validated: methods that take coordinates, velocities, or amounts (set_x_velocity, set_y_velocity, set_max_x_velocity, set_location, heal, damage, set_taming_progress, set_custom_spawn, create_aoe_zone, primary_use, and the x/y/time_seconds of mob_path_to) raise a Lua error if passed a non-finite number (NaN or infinity — e.g. from 0/0 or math.huge), so a bad value fails loudly instead of corrupting entity state. set_inventory_size clamps each dimension to a sane maximum (256), and mob_path_to’s max_checks is clamped to 100000, so oversized values are bounded rather than allocating or searching without limit.