MCP tools

68 tools, listed by the server itself (tools/list). Read-only tools take no game time and change nothing; debug tools set up tests and do what no player could. Start the server with --no-debug-tools to leave those out.

What the server tells your agent

When an app connects, the server sends these instructions, which most apps pass on to the model:

Zombye is a zombie survival game: a generated town in a forest on a tile map (1 tile = 1 m, x east, y south).
- You are player 1 (P on the map), who wakes up in a bedroom. Tools take `player`, default 1.
- Time is paused between calls and only moves when a tool steps it: step_ticks (20 ticks = 1 s), move_player, attack / shove / stomp, the item tools (search, take, use, treat, craft, ...) and sleep. Each says what happened meanwhile.
- Look first: call observe (an ASCII map with players, zombies by what they're doing, doors, windows, items and containers) before acting and again after. The read-only tools (observe, stats, inventory, health, zombie, edge, ...) take no game time and change nothing. screenshot is a rendered picture, for checking how things look.
- Zombies notice you by sight (a cone; shorter at night, when you sneak or stand still) and by sound (running, doors, breaking glass, fighting), then chase and attack; they can't open doors but batter them and windows down. Fight (pick_up a weapon; attack, shove, stomp) or get away; you have 100 HP.
- To last: search containers for food, drink and bandages, use what you find, treat wounds (health says how), sleep.
- Debug tools (make_noise, set_goal, spawn_zombies, spawn_item, set_needs, wound, add_player, pvp, grid, dev, restrain_now, skip_time, load; marked "Debug" in their titles and descriptions) do what no player can. They are for setting up tests: don't use them while playing unless asked to.
- save keeps the whole world and load puts one back; saves lists them.

Looking (read-only)

observe

Look around (ASCII map)

Look at the world around a point (default: player 1). ASCII map at double resolution: tiles sit between wall lines. Walls - |, shut windows = !, open windows o, broken windows x, shut doors D (d when damaged), open doors /, broken doors #, fences ~, floors: . grass , road : sidewalk/path _ indoors; T tree, u stump, * bush, f furniture, ^ a street prop (mailbox, hydrant, bin), c a container not searched yet, o (on a tile) a searched container, w a weapon on the floor, i any other item on the floor, P player (X dead), h a player heard but not seen, G debug goal, @ spawn. With PvP on it is player’s view (default 1), by the rule a multiplayer server tells clients by: other players only while that survivor sees them (view cone, daylight, their stance, a line of sight) or did a second ago, those it only hears as sounds at a position, and items on the floor only with a line of sight; all: true shows everyone and everything (the default with PvP off). Active zombies by state: Z wandering, I investigating a sound, C chasing a player, L lunging, A attacking, B battering a door or window, S staggered, v down on the ground, % corpse; zombies on the cheaper tiers far from players: n near (updated a few times a second), ? virtual (moved in bulk every few seconds). Lists players (HP, weapon, load, whether they’re climbing through a window or dead, dev toggles [GOD] [IGNORED]), items on the floor, damaged doors and windows in view with their hit points, and the nearest zombies with HP (use zombie {id} for one zombie’s details).

Argument	Type	What it is
all	boolean	Show every player and item, seen or not (default: only with PvP off)
player	integer	Whose senses (and the centre, unless x and y say) Default 1.
radius	integer	Default 10.
x	number	Centre x in metres
y	number	Centre y in metres

zombie

Inspect a zombie

One zombie’s hit points, simulation tier (active, near or virtual) and AI: state (including staggered, down and dead), target player or point, memory/interest timer, cooldowns, and for each player the distance, line of sight and how far this zombie could see them right now.

Argument	Type	What it is
id	integer, required

fires

Campfires and stoves nearby

Read-only: the campfires within radius (default 30 m) of a player, nearest first: id, where, lit or not, fuel left, distance and whether it is in reach; the stoves near it and whether they have power; and whether the player has heat to cook with where it stands (recipes marked heat need a lit fire or a working stove in reach). Build a campfire with craft {recipe: build_campfire}.

Argument	Type	What it is
player	integer	Default 1.
radius	number	Default 30.

builds

The build menu’s catalog

The build menu (assets/data/build.ron): every build’s id, name, what it goes on, what one piece uses up and the tools it needs (kept), seconds a piece, hit points a piece, how many pieces it stacks to, and how it comes down again. Barricades for now: planks nailed across a window or door. Read-only; build builds one.

No arguments.

inventory

Show inventory

What a player has: hands, back, shoulder, worn clothing and carried stacks (pockets and bags) with indices, weights and room; its load (kg of the carry limit, the burden stage and what it does); the container it has open and what’s in it; the floor within reach (ground item ids); containers within reach; its queue of item jobs.

Argument	Type	What it is
player	integer	Default 1.

items

Item table

The item table (assets/data/items/items.ron): id, name, category, kg, litres, stack size, and its food/drink/medical/bag/clothing/light/weapon data. Optional category filter (Food, Drink, Medical, Tool, Material, Clothing, Bag, Weapon, Light, Junk).

Argument	Type	What it is
category	string

containers_near

Containers nearby

Furniture that holds things near a player (default within 8 m): container id, kind, the furniture and room, distance, whether it has been searched (and what it holds, or else the loot table it will fill from), and whether the player can reach it now (same room, within 1.6 m of the nearest edge of the furniture; once open it stays open to 2.2 m).

Argument	Type	What it is
player	integer	Default 1.
radius	number	Default 8.

loot

Loot tables

The loot tables (assets/data/loot.ron), for tuning without walking. With no arguments: every table’s (room, container) key and the scale. With room (a room type: kitchen, shed, …) and container (a container kind from containers.ron, or a furniture kind such as counter or sink, mapped as in that room): which table that container fills from (exact or which fallback), its empty chance, rolls, entries with weights, chance per pick and counts, and groups; then n sample fills (default 200, at most 5000; seeded from the world seed but only rolled, never placed) with how often each item turned up and how many on average. Read-only.

Argument	Type	What it is
container	string
n	integer	Default 200.
room	string

weapons

Weapon table

The weapon table (from assets/data/items/weapons.ron): damage, reach, arc, swing time, targets, knockback, stagger/knockdown/crit chances, endurance cost and noise.

No arguments.

health

Show health and wounds

A player’s health: HP, every wound by body part (bruise, scratch, gash, bite, glass cut) with whether it bleeds and how fast, how far healed and hours to go, dressing, festering, and what it needs next; pain, HP lost per game hour, food poisoning, the zombie infection once it shows (Feverish, then Turning; before that it is hidden and this says ‘unknown’), and what the wounds do (swing power and time, walk and run speed, running, endurance recovery). Then the needs: hunger, thirst and tiredness (0-100%, with their level), asleep or not, and the status icons the HUD shows (Hurt/Wounded/Badly wounded/Near death, Bleeding a little/Bleeding/Bleeding badly/Bleeding out, Sore/Hurting/In real pain/Agony, Sick/Feverish/Turning, Queasy, Peckish/Hungry/Famished/Starving, Dry/Thirsty/Very thirsty/Parched, Drowsy/Tired/Worn out/Exhausted, Short of breath/Winded, Burdened/Heavy/Overloaded/Crushed, Asleep; Well fed and Rested are good states) with their severity (1-4, 0 good) and what each means. A game hour is 150 s of game time by default.

Argument	Type	What it is
player	integer	Default 1.

skills

Show skills

A player’s skills: Fitness, Strength, Bludgeon, Edged, Brawl, Stealth, First Aid, Scavenging, Handiwork. For each: its level (0-10 by default; the world’s thresholds and any XP multipliers are in the reply), XP so far and to the next level, what its level gives now and what the next level gives, and how XP is earned (practice only: running, heavy swings and moving overloaded, hits and kills with blunt or edged weapons or fists, shoves, stomp kills, sneaking near zombies that aren’t after you, treatments, first searches, crafting). Read-only.

Argument	Type	What it is
player	integer	Default 1.

recipes

Crafting recipes

The crafting recipes (assets/data/items/recipes.ron): each one’s id, name, inputs (used up), tools (kept: an item, or any item with a tag), outputs and seconds. Read-only; craft makes one.

No arguments.

heard

What a player heard said

What a player heard said lately (proximity chat), oldest first: how long ago, how loud (whispered, said, shouted), whether muffled by a wall, which way and how far off the voice was, the words, and the speaker’s player id when known (with PvP on only if the player saw the speaker as they spoke; else “a voice”). Its own lines are listed as “you”. The server keeps the last few hundred lines. Read-only.

Argument	Type	What it is
player	integer	Default 1.
secs	number	Only lines from the last this many seconds (default: all kept)

edge

Inspect a tile’s walls, doors and windows

The four edges of tile (x, y): what each is (wall, window shut/open/broken, door shut/open/broken, arch, fence) and, for shut or open doors and windows, hit points left of full.

Argument	Type	What it is
x	integer, required
y	integer, required

buildings

List buildings

List buildings: index, template, bounds, storeys and ground-floor rooms. Marks the one the player wakes up in.

No arguments.

regions

Zombie population by region

Population by 64 m region: ASCII heat maps of living zombies per region (all tiers) and of each region’s target (from the density in population.ron), the pull of attractors (loud events drawing the far horde in) on each region with players marked, and the zone with the most open ground; then the attractors (where, reach, how far the pull has spread, strength, time left) and the regions furthest below and above their targets.

No arguments.

saves

List saves

List the saves in the saves folder: size, age, tick, time of day, seed, map size, zombies and players; and where and how often this session autosaves.

No arguments.

screenshot

Screenshot (rendered picture)

A rendered picture (PNG) of the world around a player, as the game client draws it: 3D isometric view, buildings with the walls and roofs between the camera and the player cut away, zombies, items, day/night lighting, and fog of war from that player’s view (what they can’t see is darkened, and zombies there aren’t drawn). No HUD. Takes a second or two (the server runs the game client offscreen on a copy of the world; no window opens) and changes nothing: no time passes. Use observe for exact positions and states; use this to check how things look.

Argument	Type	What it is
angle	integer	Camera angle, one of the four fixed ones: 0 (default, looking north-west), 1, 2, 3 (each a quarter turn)
height	integer	Pixels, 64 to 1080. Default 540 (a 960x540 PNG is about half a megabyte of base64: ask for more only when the detail matters)
player	integer	Whose view (fog of war, cutaways), and the centre unless x/y are given. Default 1
width	integer	Pixels, 64 to 1920. Default 960
x	number	Centre on this point instead (metres; give y too). Fog is still the player’s: zombies far from players aren’t drawn
y	number
zoom	number	Metres of world visible top to bottom, 8 to 90. Default 26 (the game’s default)

stats

World and player stats

Map size, tick, time of day and daylight, players (HP, weapon, dead, dev toggles god / ignored, wounds, bleeding, HP lost per game hour, pain, sick, the infection once it shows, hunger / thirst / tiredness, asleep, status tags, skill levels; this life’s run: time alive in game hours and seconds played, kills, metres walked, things taken, containers searched, wounds taken, HP lost; and once dead the cause of death in plain words), the time scale (30 while everyone sleeps), zombie counts by state (corpses too) and by simulation tier (active / near / virtual, with the ranges and last tick’s promotions and demotions), weapons on the floor, last tick timing (tier pass, senses, flow fields, active AI, near and virtual updates), sounds heard and the state hash (same seed + same calls = same hash).

No arguments.

Also returns its answer as structured JSON (structuredContent, with an outputSchema).

Playing

step_ticks

Let time pass

Advance the simulation. 20 ticks = 1 second of game time. Reports zombie attacks on players (and how many landed, for how much), player hits on zombies, kills, deaths, thumps on doors and windows, and anything that broke.

Argument	Type	What it is
n	integer	Default 20.

move_player

Move

Drive a player: hold a movement input for some ticks (the world advances), then stop. Walk 3 m/s, run 5.5 m/s (drains endurance; needs some left), sneak 1.4 m/s. Faces the way it moves unless facing is given. aim: aiming (as the right mouse held): walks at 2.2 m/s, can’t run, faces facing; only an aiming player attacks (attack, shove and stomp aim by themselves).

Argument	Type	What it is
aim	boolean	Default false.
direction	string	Compass direction; north is up (-y). Or give dx/dy. One of: n, ne, e, se, s, sw, w, nw, stop.
dx	number	Ground-plane direction x (east), used when direction is omitted
dy	number	Ground-plane direction y (south)
facing	number	Facing in radians (0 = east, pi/2 = south)
player	integer	Default 1.
run	boolean	Default false.
sneak	boolean	Default false.
ticks	integer	Default 20.

interact

Open or close a door or window

A player opens or closes the door or window it faces, if one is within 1.6 m of it (face it with move_player’s facing first if needed). Doors are noisy (10 m), windows quiet (2.5 m). Broken ones can’t be shut.

Argument	Type	What it is
player	integer	Default 1.

climb

Climb a fence or an open window

A player climbs over the fence or through the open or broken window it faces (as E does): within 1.1 m of it, faced within 70 degrees of square on, with room on the far side. Walking into a fence or an open window doesn’t cross it; this does. The world steps until the player is over (about a second and a half), and the reply says where it is. Too heavy a load (overloaded) can’t climb. Give facing (radians) to turn first.

Argument	Type	What it is
facing	number
player	integer	Default 1.

fire

Tend a campfire: fuel, light, put out

A player tends a campfire within 1.6 m (fire: its id from the fires tool; default the nearest). action: add_fuel (one carried item tagged fuel, e.g. firewood, plank or newspaper: item id or index of a carried stack; default the first fuel carried), light (needs fuel on it and something tagged fire carried: matches or a lighter, kept) or put_out (the fuel left stays). A lit fire lights the ground round it at night (and shows you to zombies), crackles now and then, and burns whoever stands in it. Time doesn’t move.

Argument	Type	What it is
action	string, required	One of: add_fuel, light, put_out.
fire	integer
index	integer
item	string
player	integer	Default 1.

blind

Fit, roll or take down a blind

A player works the roller blind of the window or glass door it faces, from inside, within 1.6 m (face it with move_player’s facing first, or give facing in radians). action: use (default: roll it up or down, or fit one if there is none), toggle (roll up or down, at once, a quiet noise), fit (one carried item tagged blind, e.g. roller_blind; takes a few seconds, fitted down) or take_down (back into the bags; a few seconds). A blind that is down stops zombies outside seeing in through that glass; sounds still carry. The world steps until a fit or take-down is done. The edge tool says which edges have blinds and glass.

Argument	Type	What it is
action	string	One of: use, toggle, fit, take_down. Default "use".
facing	number
player	integer	Default 1.

build

Board up a window or door

A player builds one piece of a build (see builds; e.g. board_window, board_door) on the window or door it faces, within 1.6 m, from the side it stands on: one plank nailed across, using the build’s materials (a plank and nails) with a hammer to hand. An open door is shut first. The edge is then boarded up: nobody walks, climbs or sees through it, and zombies batter it, a plank’s hit points at a time, before what’s underneath. Call again for more planks, up to the build’s max. Give facing (radians) to turn first; the world steps until the piece is up, and the reply says the planks and hit points.

Argument	Type	What it is
build	string, required
facing	number
player	integer	Default 1.

unbuild

Prise a plank off

A player prises one plank off the boarded-up window or door it faces, within 1.6 m, with a tool that pries (a crowbar or claw hammer): the plank comes back, the nails are lost. The last plank leaves the window or door as it was. Give facing (radians) to turn first; steps until it’s done.

Argument	Type	What it is
facing	number
player	integer	Default 1.

smash_window

Smash a window

A player smashes the window it faces (shut or open), within 1.6 m. Loud (22 m); it stays broken and can be climbed through.

Argument	Type	What it is
player	integer	Default 1.

attack

Attack

A player swings its weapon (bare hands: a punch) the way it faces, then the world steps until the swing has landed and the player can act again. Hits zombies within the weapon’s reach and arc, nearest first up to its target count, with a clear line (not through glass or fences); damage, knockback and a chance to stagger or knock down. Downed zombies are below the swing: stomp them. Costs endurance; makes noise. Give facing (radians), target (a zombie id) or target_player (a player id) to turn first. With PvP on (the pvp tool, or –pvp on) other players are hit by the same rules, in the same list: a wound on a body part, HP, a chance to stagger or floor them; the reply’s PLAYER HITS says so. Holding a gun (see weapons) it fires one round instead: along the facing and the pitch, through shut glass (which breaks), stopped by walls, shut doors, trees and the first body (the rifle’s goes through two); a hit 1.5 m or more up a standing body is the head. Given a target it aims at aim_height on it (default the chest; 1.65 for the head, more spread than a still target allows at long range); otherwise give pitch. Very loud: every zombie within the gun’s noise radius comes, and the far horde over the next minutes. An empty gun doesn’t fire: reload it with use {from: “hand”}.

Argument	Type	What it is
aim_height	number	A gun, with a target: metres up its body to aim at (default 1.15; 0.2 for one on the ground)
facing	number	Turn to this angle first (0 = east, pi/2 = south)
pitch	number	A gun: radians up (+) or down (-) of level (the muzzle is 1.4 m up); default level, or at the target
player	integer	Default 1.
target	integer	Turn to face this zombie first
target_player	integer	Turn to face this player first

shove

Shove

A player shoves the zombies in front (short reach, wide arc, up to 3): no damage, pushes them back about 1.2 m (further with a weapon in hand) and always staggers them, with a chance to knock down that grows with each shove on the same zombie in the last few seconds (better still against a staggered zombie or from behind, and with Strength and Brawl). Cheap, quick, quiet. Steps until it lands and the player can act again. facing / target / target_player as for attack. With PvP on it pushes other players back and staggers them too (no moving or acting for a moment), or floors them.

Argument	Type	What it is
facing	number
player	integer	Default 1.
target	integer
target_player	integer

stomp

Stomp

A player stamps on a downed zombie in front: anywhere along its body within about 1 m, solid damage (two or three finish one), or on its head (it lies on its back, the head about 1.45 m behind its feet; stand within 0.9 m of it) for four times that, which kills. It keeps the zombie down a while longer. A miss if none is down there when it lands. Steps until it lands and the player can act again. facing / target / target_player as for attack. With PvP on, a player knocked down is stamped on the same way (a bruise).

Argument	Type	What it is
facing	number
player	integer	Default 1.
target	integer
target_player	integer

pick_up

Pick up

A player picks up the item on the floor nearest to where it faces, within 1.3 m, at once: a weapon goes into its hand (what it held goes into its pockets and bags if there’s room, else stays on the floor), anything else into its pockets and bags, as many as fit (room and weight permitting).

Argument	Type	What it is
player	integer	Default 1.

search

Search a container

A player searches (opens) a container within reach: container by id (see containers_near), or the one it faces. The first search takes the container’s search time (x1.5 sneaking, half the noise) and fills it; reopening is quick. Steps the world until it’s done and lists what’s inside. It stays open until the player walks off.

Argument	Type	What it is
container	integer
player	integer	Default 1.

take

Take an item

A player takes count (default all) of a stack into its pockets and bags: from the open container (from: “container”, index as listed by inventory) or the floor (from: “ground”, index = the ground item id). 0.3 s a stack (0.6 s over 3 kg); steps the world until done. Refused if there’s no room or it would be too heavy.

Argument	Type	What it is
count	integer	Default 0.
from	string	Default "container".
index	integer, required
player	integer	Default 1.

move_item

Move an item

Move count (default all) of the stack at from/index to to. Places: carried (pockets and bags), hand, off_hand, back, shoulder, worn, container (the open one), ground (index = ground item id). Slots take one item; whatever was in the way goes into pockets and bags. Each bag has its own room: as to, pockets, bag_back, bag_shoulder, bag_hand or bag_off_hand puts a carried stack in that one (inventory says where each is). Steps the world until done.

Argument	Type	What it is
count	integer	Default 0.
from	string, required
index	integer	Default 0.
player	integer	Default 1.
to	string, required

drop

Drop an item

A player drops count (default all) of the stack at from (default carried) / index at its feet.

Argument	Type	What it is
count	integer	Default 0.
from	string	Default "carried".
index	integer	Default 0.
player	integer	Default 1.

equip

Equip an item

A player puts the carried stack index where it belongs: a bag on its back, shoulder or in a hand, clothing on, anything else (a weapon) in its hand. A two-handed weapon frees the other hand.

Argument	Type	What it is
index	integer, required
player	integer	Default 1.

wear

Wear an item

A player puts on the carried clothing index (what it wore on the same body part and layer comes off into its bags).

Argument	Type	What it is
index	integer, required
player	integer	Default 1.

unequip

Take off or put away an item

A player takes off or lets go of what’s at from (hand, off_hand, back, shoulder, or worn with index) into its pockets and bags, or onto the floor if there’s no room. A bag that’s holding things can’t come off until they fit in what’s left.

Argument	Type	What it is
from	string, required
index	integer	Default 0.
player	integer	Default 1.

use

Eat or drink

A player eats or drinks one go of the stack at from (default carried) / index (2-5 s by the item; an item with several goes, like a loaf or a bottle, lasts that many). It lowers hunger and thirst by the item’s amounts (see items; negative raises it). Stale food gives 70% and may poison you, mouldy 40% and usually does; food eaten with hunger under 10% does nothing for hunger; food poisoning means no eating. The reply says beforehand what it will do (freshness, waste), then what it did, with the needs before and after. Using the gun in your hand (from: “hand”) reloads it: the fullest magazine carried swapped in, else loose rounds pushed in one at a time until it is full; using a carried magazine fills it with loose rounds.

Argument	Type	What it is
from	string	Default "carried".
index	integer	Default 0.
player	integer	Default 1.

sleep

Sleep

A player lies down and sleeps (tiredness 30% or more, not in agony): on a bed (rests fastest) or a sofa within 1 m in its room, else the floor (slow, and you wake up sore). Steps the world until it wakes, and says why (rested below 5% tiredness, hit, a noise within 20 m that reaches it, a zombie seeing it, agony, an hour starving or parched; or max_hours of game time), how long it slept and its needs and HP before and after. While every player sleeps, game time runs 30x as fast (clock, needs, wounds, and the far horde beyond 150 m: its wandering, migration and respawn; zombies nearer keep real time), and agony only stops sleep with no painkiller working, so a night is a minute or two of simulation.

Argument	Type	What it is
max_hours	number	Default 12.
player	integer	Default 1.

sit

Sit down or get up

A player sits down (on the sofa, bed, toilet, bench or deckchair within 0.9 m, else the ground) or gets up. Seated it doesn’t move, gets its breath back twice as fast and slowly loses tiredness; moving, swinging, climbing or sleeping gets it up. Eating, crafting and cooking work seated. Time doesn’t move.

Argument	Type	What it is
player	integer	Default 1.
sit	boolean	true sit, false get up; left out: the other

treat

Treat a wound

First aid: a player treats one of its wounds, or takes a pill, with what it carries or holds. action: dress (a plaster, gauze, a clean rag or a rag; on a dressed wound it changes the dressing), clean (antiseptic, on an undressed wound), stitch (a sewing kit, a gash), remove (take a dressing off: a dirty rag back), painkillers, antibiotics. Say which wound by wound (its # in health) or part (the most urgent wound there it fits); with neither, the most urgent wound it fits. item: an item id (see items); left out, the best the player has (a plaster where one will do, then a clean dressing, then a rag). Left out, action follows from the item. Takes a few seconds standing still (dress 4 s, a plaster 2 s, a hand x1.5, clean 3 s, stitch 8 s, a pill or removing 1 s); a strike landing interrupts it. Steps the world until it’s done and replies with what changed and the health.

Argument	Type	What it is
action	string
item	string
part	string
player	integer	Default 1.
wound	integer

craft

Craft

Crafting: a player makes a recipe (see recipes) from what it carries and holds in its hands (not what it wears; only whole items count as inputs: a part-drunk bottle won’t do). With no recipe: what it can make now, and for the rest what’s missing. With recipe (an id): queues it, steps the world until it’s done (the recipe’s seconds; you can walk meanwhile, but a strike landing or a swing interrupts it) and replies with what was made, what changed in its inventory and on the floor (outputs with no room in pockets and bags go at its feet) and the inventory. E.g. rip clothing into rags, wash rags into clean rags (a clean dressing for treat).

Argument	Type	What it is
player	integer	Default 1.
recipe	string

respawn

Get up again after dying

A dead player gets up again in the bedroom with full health and empty hands.

Argument	Type	What it is
player	integer	Default 1.

say

Say something to whoever is near

A player says a line of text to whoever is near (proximity chat): heard by every other living, waking survivor within the volume’s reach of it (whisper 3 m, talk 12 m, shout 40 m), only 0.4 of that through a wall or shut door, and then muffled. Each listener gets the words and where the voice came from, and who spoke only if it sees the speaker (read them with heard). Speaking is a noise: zombies within 1.5 m (whisper), 7 m (talk) or 30 m (shout) hear it on the next tick and come to look, and a shout draws the far horde over the following minutes. At most one line a tick; 120 characters. Time doesn’t move: step_ticks afterwards.

Argument	Type	What it is
player	integer	Default 1.
text	string, required
volume	string	One of: whisper, talk, shout. Default "talk".

gesture

Wave, put your hands up or point

A player makes a gesture others can see: wave (hello, over here), hands_up (no threat; held until lowered: hands_up again, or none), point (the way it faces; turn with move_player’s facing first), or none to stop. A wave and a point last 2.5 s. Starting a swing, shove or stomp ends any gesture. observe and stats show it.

Argument	Type	What it is
gesture	string, required	One of: wave, hands_up, point, none.
player	integer	Default 1.

restrain

Tie another survivor’s hands

A player ties another survivor’s hands (a hold-up) with a restraint it carries or holds: a cable tie or rope (an item tagged restrains). Who can be tied: a survivor within 1.6 m with its hands up (gesture hands_up), or, with PvP on, one knocked down or asleep; with PvP off only hands held up will do. It takes 3 s and is called off if they lower their hands, get up or step away. Steps the world until done and says whether they were tied. Tied, a survivor walks slowly and can’t run, climb, fight, gesture or use its things; it can struggle out (struggle), be searched (search_player) and be freed (free). A cable tie is used up and has to be cut off, rope is untied and can be used again. observe and stats show who is tied.

Argument	Type	What it is
player	integer	Default 1.
target	integer	The player to tie (default: the survivor this one faces within reach)

free

Free a survivor’s tied hands

A player frees another survivor’s tied hands (within 1.6 m; 2.5 s). Rope is untied and falls at their feet. A cable tie has to be cut off: the player needs something tagged cuts (scissors, a kitchen knife) in its pockets or hands, and the tie is gone after. Steps the world until done and says whether they are free.

Argument	Type	What it is
player	integer	Default 1.
target	integer	The tied player (default: the survivor this one faces within reach)

search_player

Search a tied survivor

A player searches a survivor whose hands are tied (see restrain; within 1.6 m, 2 s), then lists what they have as the searcher sees it: what they hold (hand, off_hand, back, shoulder), wear (worn[N]) and carry (carried[N]), with item ids and names. The search stays open while they stay tied and within 2.2 m: take_from takes a stack. Already searching them, it just lists. Steps the world until the search is open.

Argument	Type	What it is
player	integer	Default 1.
target	integer	The tied player (default: the survivor this one faces within reach)

take_from

Take something from a searched survivor

A player takes a stack from the tied survivor it is searching (search_player first): into its pockets and bags, or to the floor at its feet when there is no room. 0.6 s for something carried, 1.5 s for something worn or held; a bag only comes off once what is in it would fit without it. Steps the world until done and says what was taken.

Argument	Type	What it is
count	integer	How many of the stack; 0 = all Default 0.
from	string	One of: carried, worn, hand, off_hand, back, shoulder. Default "carried".
index	integer	Which stack of carried or worn, as search_player lists them Default 0.
player	integer	Default 1.

struggle

Struggle out of tied hands

A player whose hands are tied works at getting out: standing still for 60 s of struggling in all for rope, 90 s for a cable tie (what it struggled before counts), making a little noise (4 m, every 2 s) zombies can hear. Steps the world until it is free, dead, or max_secs have passed, then stops struggling and says whether it got out and how far along it is. An error if the player isn’t tied.

Argument	Type	What it is
max_secs	number	Give up after this many seconds (at most 600) Default 120.
player	integer	Default 1.

group

Your group: invite, accept, leave, markers

A player’s optional group: members are told each other’s names and share map markers, nothing else. Groups never switch damage off: with PvP on, blows land on members as on anyone. action: show (default: the members with names and ids, the markers, invitations waiting), invite (target: a survivor within 12 m and in sight; default the nearest; the invitation stands 60 s), accept (target: who invited; default the newest invitation), leave (one member left alone is no group), mark (a shared marker at x, y; at most 8, the oldest goes), unmark (marker: its id, or x, y: the nearest within 3 m). Replies with what happened and the group as it is now. Time doesn’t move.

Argument	Type	What it is
action	string	One of: show, invite, accept, leave, mark, unmark. Default "show".
marker	integer	unmark: the marker’s id
player	integer	Default 1.
target	integer	invite: the player to invite; accept: the player who invited
x	number
y	number

light

Switch the light of the room you’re in

A player flips the light switch of the room it stands in (as E at the switch does): the switch is on a wall beside a doorway, and the player must be within 1.3 m of it (out of reach, the reply says where it is: move there first). On gives the room a light while its building has power (the town’s grid; later generators and solar panels), off puts it out. With no power the switch clicks and does nothing. At night zombies (and other survivors) see you in a lit room as if by day, through its windows: switch it off to hide. Give on (true/false) to set it; without, it flips. The reply says the room, whether it is lit and whether it has power.

Argument	Type	What it is
on	boolean
player	integer	Default 1.

Saves

save

Save the world

Save the whole world (map edits, players, every zombie on every tier, the clock, the RNGs) to a named save in the saves folder, or with no name to this session’s –save file. Loading it gives back exactly this state: the same state hash, and the same future for the same calls.

Argument	Type	What it is
name	string	Save name: letters, digits, - _ . (no folders)

Debug

make_noise

Debug: Make a noise

Debug tool, for setting up tests (no player could do this): a noise at (x, y). Zombies within radius metres (40% of that through walls) come to investigate; heard on the next tick. For scale: walking 6 m, running 14 m, a door 10 m, a groan 9 m, a zombie thumping a door 15 m, breaking glass 22 m, breaking a door 26 m. A loud one (25 m or more, see population.ron) also leaves an attractor: over the next minutes far (virtual) zombies from up to 4x the radius away (less from indoors) drift in toward it. lasting: true makes that pull last 30 minutes instead of 10, like an alarm left ringing. See regions.

Argument	Type	What it is
lasting	boolean	Leave a long-lived attractor Default false.
radius	number, required
x	number, required
y	number, required

set_goal

Debug: Send zombies to a point

Debug tool, for setting up tests (no player could do this): every zombie within 120 m (path distance) heads for this point, ignoring sight and sound. Omit x/y to go back to normal senses.

Argument	Type	What it is
x	number
y	number

spawn_zombies

Debug: Spawn zombies

Debug tool, for setting up tests (no player could do this): Spawn zombies on open tiles in a circle.

Argument	Type	What it is
count	integer, required
radius	number	Default 10.
x	number, required
y	number, required

set_needs

Debug: Set hunger, thirst and tiredness

Debug tool, for setting up tests (no player could do this): set a player’s hunger, thirst and tiredness (0 fine to 1 worst; leave one out to keep it). Replies with the needs and status tags.

Argument	Type	What it is
hunger	number
player	integer	Default 1.
thirst	number
tiredness	number

spawn_item

Debug: Spawn an item

Debug tool, for setting up tests (no player could do this): put count (default 1) of an item on the ground at (x, y), by id (see items; weapons are items too).

Argument	Type	What it is
count	integer	Default 1.
item	string, required
x	number, required
y	number, required

wound

Debug: Wound a player

Debug tool, for setting up tests (no player could do this): give a player a wound now, taking its damage (god mode keeps the HP). part: head, torso, left_arm, right_arm, left_hand, right_hand, left_leg, right_leg, left_foot, right_foot. kind: bruise, scratch, gash, bite, glass_cut. infected: true or false forces the zombie infection on or off; left out, a scratch, gash or bite rolls for it as a zombie’s would. Replies with the player’s health.

Argument	Type	What it is
infected	boolean
kind	string, required
part	string, required
player	integer	Default 1.

restrain_now

Debug: Tie a player’s hands at once

Debug tool, for setting up tests (no player could do this): tie a player’s hands at once with an item (default cable_tie; rope is the other one shipped), as if player by (default 0: nobody) had, whatever it was doing and with nobody near. For testing struggle, free and search_player.

Argument	Type	What it is
by	integer	Default 0.
item	string	Default "cable_tie".
player	integer	Default 1.

add_player

Debug: Add a player

Debug tool, for setting up tests (no player could do this): Another player joins (as a second client would), standing at (x, y) (default: beside player 1), facing east. Replies with its id: give it as player to the other tools. For testing what several players look like together (screenshot) and how the world copes with them.

Argument	Type	What it is
x	number
y	number

grid

Debug: The town’s power grid on or off

Debug tool, for setting up tests (no player could do this): Turn the town’s power grid on or off (every building it reaches: rooms with their switch on light or go dark). With no argument: says whether it is on, and how many rooms are lit.

Argument	Type	What it is
on	boolean

pvp

Debug: Player against player on or off

Debug tool, for setting up tests (no player could do this): Player against player on or off for this world (docs/PLAN.md 4.8; off by default, on with –pvp on; saved with the world’s settings). On, swings, shoves and stomps hit other players as they hit zombies. With no argument: says which it is.

Argument	Type	What it is
on	boolean

dev

Debug: God mode and ignored by zombies

Debug tool, for setting up tests (no player could do this): Dev toggles for a player, for testing without dying (allowed here: the MCP server is a dev tool). god: takes no damage and can’t die (zombie strikes still land and are reported, HP doesn’t drop). ignored: zombies can’t see or hear the player, and those chasing, lunging at, attacking or battering their way to it lose it (they look where they last saw it, then wander). Leave one out to keep it as it is. Not saved: a loaded world has both off. stats and observe show them.

Argument	Type	What it is
god	boolean
ignored	boolean
player	integer	Default 1.

skip_time

Debug: Skip time

Debug tool, for setting up tests (no player could do this): Move the clock forward (0-24 hours).

Argument	Type	What it is
hours	number, required

load

Debug: Load a save (replaces the world)

Debug tool, for setting up tests (no player could do this): Replace the world with a save from the saves folder (see saves), or with no name the session’s –save file. Fails, leaving the world as it is, if the file is damaged, holds impossible values, or is from another save format. Game data changed since the save was made: compatible changes (weapon numbers, weapons added, population.ron) load with a note; a building template that changes the map, or a removed weapon the save uses, fails unless force is true, which loads it anyway, dropping what no longer fits, and says what it changed.

Argument	Type	What it is
force	boolean	Load anyway when the game data changed in a way the save can’t simply take. Default false
name	string