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

Tints and the damage flash

A tint is additive and applied after lighting, so it brightens the sprite rather than recolouring it — a dark colour is a subtle wash, 1.0 on a channel is as strong as it gets.

The pulse, the hold and the client’s own red damage flash are three separate slots that add together, so:

• a player landing hits on the entity still sees a wind-up pulse — their own damage flash cannot hide it;
• a held tint is still there when a damage flash fades, instead of being wiped by it.

A tint lives on the client’s copy of the entity, so an entity that leaves view and streams back in arrives untinted, and a player who joins mid-hold does not see it. That suits a tell that lasts a moment; it is not state to rely on.

A mob’s archetype attacks can pulse the same way without a script — see wind-up-tint in mob-config.md.

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

Milestones

Grant a one-shot event Almanac milestone to a player from a progression script — a boss death, a world arrival, a story beat. An event milestone is a milestone whose config declares metric: event (no threshold); the id you pass is that milestone’s own id (namespaced, e.g. Creation:felled_torvastus). Like every milestone its reward is cosmetic / title / lore / waypoint only — never power — and the player sees the “milestone reached” banner. Players only.

Because the milestone is granted to the entity you call it on, a mob’s death hook — which is handed only the dying entity — reaches the players who should earn it via entity:get_players_in_radius:

-- A boss's server-on-death hook: credit every player who was present at the kill.
return function(entity)
    for _, player in ipairs(entity:get_players_in_radius(600)) do
        player:grant_milestone_event("Creation:felled_torvastus")
    end
end

Recording a cleared run

Unlike a milestone this is not stored in the world save: it is written to the player’s own cross-save profile, so it still counts on the next seed. That is what the record is for — the post-clear content that unlocks on “you have cleared the game” has to see a clear that happened in a different save.

The tier recorded is the run’s difficulty floor — the lowest tier it ever ran at, not the tier it ended on — and the server reads it itself, so there is no argument to pass and no way for a script to claim a harder clear than the run earned. Calling it again is harmless: the profile keeps the harshest clear and ignores anything softer, so a re-kill neither adds nor downgrades.

Like the milestone grant, a death hook reaches its players through entity:get_players_in_radius:

-- The finale's server-on-death hook: everyone present cleared the game.
return function(entity)
    for _, player in ipairs(entity:get_players_in_radius(600)) do
        player:grant_run_cleared()
    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.

Companion behaviour

The engine stores the companion mode, and moving to follow, holding a spot, and choosing what to fight are all your mob’s server-update script. The one exception is catching up: a companion on "follow" that falls far behind is teleported beside its owner by the engine (see Mob Configuration → Taming), so your script only needs to handle the ordinary walk. These two methods work on any entity and answer the targeting half:

A hit counts only if it did damage: one stopped by friendly fire or absorbed by invulnerability frames is not recorded. Hits are not saved, so a reload forgets every fight. For the usual companion behaviour, check entity:get_last_attacker(n) first, then owner:get_last_attacker(n) and owner:get_last_target(n), and skip the owner and the companion itself. The base game’s glorbo does this in scripts/mobs/glorbo_ai.lua.

Survivors

npc:recruit_survivor(player)

Recruits this NPC on behalf of player: they leave the world and travel to that player’s home, arriving after their configured delay. The scripted counterpart of the recruit dialogue choice — for an NPC whose conversation is Lua rather than a declarative tree, or for a rescue beat that ends in recruitment with no conversation at all.

Requires this mob to have a survivor: block (see mob-config.md). Returns whether the request was queued, not whether it succeeded: the engine enacts it on the next tick and refuses it there if that survivor is already recruited, settled or lost.

The NPC is removed from the world as part of recruiting, so treat the call as the end of anything the script was doing with it.

-- server-on-dialogue-choice: the player agreed to lead them out
if choice_id == "come_with_me" then
    npc:recruit_survivor(player)
    return { type = "close" }
end

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 stages the move for the next movement broadcast — before 2026-09-18 it did only the first half, and the “regular entity sync” it was documented to rely on could not carry it: a position is broadcast by the entity’s own update noticing that it changed during that update, which a write from a script outside it never satisfies. 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.

Last updated Sep 29, 2026