API
All input to the game is via API. There is no interactive UI.
Call signatures such as GetSelf() are illustrative. Routes, fields, and codes are as named.
Principles
- Pull only. The server never pushes, so no agent needs a publicly reachable endpoint.
- Agents run on their own infrastructure. Any model, harness, fine-tune, or human driver is valid.
- The tick is server-side and authoritative. Agents do not need a synchronized clock.
- The game is real time. A world ticks 10 times per second by default, and speed of decision is part of play.
- Intents are validated against world state at resolution time, not against what the agent believed when it decided.
- The server answers questions and holds no client's view of the world. A radius on a query bounds that query's answer.
- Agents never receive full world state. Live state reaches an agent only if its character perceives it. Authored world facts are given to every character alike and are not perception.
- A character is a data object the agent controls. The server never drives one on its behalf.
Two Surfaces
| Surface | Shape |
|---|---|
| Tick loop | Small polled calls. Submit intents, read state. Hard latency budget. |
| History and replay | Occasional, expensive, quota limited. Outside the tick loop. |
History and replay quotas are per account, not per character, so running many characters does not multiply the query budget. Quotas are metered in seconds of game time replayed rather than request count, since span drives cost, and in real time rather than ticks so a quota means the same at any tick rate (B41).
| Limit | Default |
|---|---|
| Seconds of game time replayed per account per minute | 10,000 |
| Seconds of game time per single request | 5,000 |
| Requests per account per minute | Rate limited as a backstop |
All configurable.
Three Read Tiers
| Tier | Contents | Guarantees |
|---|---|---|
| Event queue | Perception of what just happened | Expires, bounded, no delivery guarantee |
| Snapshot | Current state and observation | Always authoritative, perception-scoped |
| History log | Durable per-character record and replay | Never expires, quota limited |
Durable facts live in the snapshot and the history log, which is why events need no delivery guarantee.
Tick Loop
Everything is polled. No server-held connections.
Agents poll at whatever interval they choose, within rate limits, and build their own model from whatever reads they find useful. Events queue up in the meantime.
Viewers poll on a fixed interval, up to once per tick, sending the last tick they saw. The response carries the tiles as of the delayed tick and every spectator event since the tick sent, grouped by tick, so a missed poll loses nothing. It is the same shape as the agent round trip below, with the spectator filter in place of perception.
Reads are area capped and rate limited. The area cap is a square viewport. It does not assume a screen shape. For an agent it is the character's whole perception window, 2 × current perception range + 1 blocks on a side and never less than 51, so one read covers everything the character can perceive. Goggles that raise perception raise the cap with them. The range is the character's current perception range, not its darkness-shortened sight range, from the same tick as the tiles. For a spectator or owner watch it is at least 51 by 51 and may grow to 151 by 151 when the viewer is zoomed out, so the screen stays full of map; zooming back in returns to 51. A larger region is area_cap_exceeded. The cap is separate from perception and from the replay quota. Scoping and filtering are separate concerns: spectators get no perception filtering and see the truth of what is in a tile, agents get the same endpoints with perception rules applied, and watch reads are bounded by the watch cap while agent reads stay on the perception window. Any agent can read the spectator view, so it is delayed by the world's spectator delay (default 60 seconds, worlds.spectator_delay_seconds), shows only ground some character in the world has revealed, and never shows what no character could detect. It is the tiles published for that earlier tick, read from the tile cache, never from live sim state.
Sync Model
There is one authoritative sim. Every character's intent for tick N resolves together at tick N. Nobody waits for anybody: the tick closes on time whether or not a given agent has called.
A client that falls behind skips to now. Its next call returns the current state as truth, plus the events it missed, bounded, with a count of any that were dropped. It does not replay the ticks it missed to catch up.
Round Trip
Request
- Optionally
intents, an ordered list of intent objects. It replaces the character's held queue (Intent Queue below), unlessappend_tonames a queue to extend instead. No intent carries a tick: the first runs on the next tick and each one after it on the tick after the one before. A one-entry list is the single-intent case. - Optionally
append_to, aqueue_id. Withintents, the new entries are added to the end of that queue when it is still held or when it was the last queue set and ran to its end with no rejection (Intent Queue). Without a non-emptyintents, or when it isnull, empty, or blank, the request is refusedmalformed_intentat ingest; it is never read as a replace. - The last snapshot version the agent saw:
snapshot_version.
{
"snapshot_version": "…",
"intents": [
{"verb": "Step", "direction": "right"},
{"verb": "Wait"}, {"verb": "Wait"}, {"verb": "Wait"},
{"verb": "Step", "direction": "right"}
]
}
A request without intents leaves the held queue as it is: it submits nothing and still drains and reads the clock. "intents": [] clears the held queue.
Response
queue_id, present only when the request carriedintents: the id of the queue this request set or appended to,[]included. On replace it is the request'sX-Request-Id, an opaque string unique across requests, so no id is ever reused. On append it is theappend_toid.queue, present only while the character's held queue is not empty:{"queue_id": ..., "next_index": i}, the queue being run and the index of its next intent to run. Absent means the queue is empty.finished_queue, present only whilequeueis absent and the last queue set ran to its end with no rejection:{"queue_id": ..., "length": n}.lengthis that queue's whole logical length, the intents it was set with plus every append (Intent Queue).- Results of every intent resolved since the last call:
intent_results, a list ascending by tick (Intent Queue). Absent when nothing has resolved since the last call. It is the one record of what ran, except an appliedWait(Intent Results): those resolve and advance the queue but carry no entry. Usequeue,finished_queue, and gaps inindexto see progress (Intent Queue). - Pending events, ordered and grouped by tick number:
events_by_tick, a list of{"tick": N, "events": [...]}, ascending by tick, each entry that tick's events in the order they happened. Absent when nothing is pending. - Observation, as a delta against the version supplied, with the entity layer as a per-kind patch (Snapshots).
- After a boss clear, a one-shot
level_clear_ceremonywith the level number and, on a first clear, the maximum health gained. Absent otherwise. The character is teleported outside the level on that same tick; the next observation shows the new position. - Current tick number and time remaining in the window:
tickandwindow_remaining_ms. By design the time remaining is accurate to the sim's tick clock, so a client can time its next poll by it. It is read from the handoff clock the sim advances and is true when the round trip answers (B43). - Count of any events dropped since the last call:
events_dropped, present only when it is above 0. Absence means 0. paused, present only whentrue. Absence meansfalse. A 200 never carries it: a paused world answers 503 instead.
A round trip where nothing happened to the character carries only tick, window_remaining_ms, and an unchanged observation: {"tick":N,"window_remaining_ms":N,"observation":{"version":"…","unchanged":true}}, well under 100 bytes. Every other field is absent. GET /characters/{id}/tick follows the same rule for paused. A response body under 100 bytes, the idle round trip included, is always sent as plain JSON. A body of 100 bytes or more is gzipped when the request's Accept-Encoding allows gzip and compressing makes it smaller, and sent as plain JSON otherwise (B44).
POST /characters/{id}/tick is the round trip and answers 200. It drains the queue. GET /characters/{id}/tick reads the clock alone and drains nothing.
GET /characters/{id}/tick also carries tick_started_at, the GMT time the current tick started, as an RFC 3339 UTC timestamp with fractional seconds (B47). It is absent when the clock has no start time yet. The round trip never carries it, so the idle round trip stays under 100 bytes; a client that wants the time reads GET.
Rules
- One intent per character per tick. The head of the character's held queue runs on the next tick, and the rest follow one per tick (One in flight covers a server that falls behind).
- If the queue is empty, the character does nothing that tick.
- There are no standing orders. The server holds one explicit, bounded, ordered list of intents per character and runs it on consecutive ticks while it keeps up. Nothing in it waits, repeats, or is conditional.
- A slow agent that misses ticks acts on a later one. This is normal.
- An awake character sustains one request per tick. The limiter is a token bucket refilled at the world's tick rate, one token per tick, with a burst of 3, so ordinary network jitter is not a 429. The bucket belongs to the character: it is checked after auth and keyed by character id alone, so every request on the character's routes (
/characters/{id}/…) spends from it, whichever key or address it comes from. Viewing reads, a spectator's and an owner watch of the character, spend the account's viewing bucket instead (Tiles), so watching a character takes no requests from its agent. Polling faster than that sustained rate returns the same state and is rate limited. A sleeping character is held to about one request per second (Wait and Sleep). Polling slower is an option, never a requirement. - There is no session to establish. An agent that stops calling and later resumes just calls again.
Intent Queue
Each character has one held queue: an ordered list of intents the server runs one per tick, back to back. The tick round trip sets it.
- Replace by default. Each request that carries
intentsand noappend_toreplaces the held queue whole. A request withoutintentsleaves it as it is."intents": []clears it. - Append. With
append_toandintents, the new entries are added to the end of that queue when it is the held queue or when it was the last queue set and ran to its end with no rejection. The queue keeps itsqueue_id, and the new intents continue its indexes. Otherwise the request is refused 409queue_changed, and the held queue is left as it is. The cap counts what is still held plus what is added, judged in the same seam write as the append, so two appends racing cannot pass it together.append_towithout a non-emptyintents, ornull, empty, or blank, ismalformed_intentat ingest. - Next tick, no matter what. The head runs on the next tick. Each intent after it runs on the tick after the one before it. The server never holds an intent until it becomes legal, and never skips a tick in the queue except while it is behind (One in flight). An idle tick only ever adds time between two intents, so a queue paced with
Waitstays legal. A move queued sooner than the character's movement speed allows is rejected withmovement_cooldownand clears the rest, so an agent paces a queue withWait. At the base 2.5 blocks per second and 10Hz a move is due every 4 ticks:Step,Wait,Wait,Wait,Step. - Validated when it runs. Each intent resolves against the world as it is on its tick, with its own result, like any intent.
- The first rejection clears the rest. When an intent is
rejected, every intent after it in that queue is discarded: never run, never retried, and reported back on the rejected intent's result.appliedandapplied_no_effectdo not stop the queue. - Bounded. A queue holds at most the world's queue horizon in ticks:
worlds.queue_horizon_seconds×tick_rate_hz, 40 at the defaults (4 seconds, 10Hz). The horizon is longer than a one-second poll, so a once-a-second poller can keep the queue from running dry and act on every tick. - All or nothing at ingest. The request's intents are judged together. An intent carrying
tick, or any other field its verb does not take, ismalformed_intent. If any is refused at ingest (Ingest Refusals), nothing is stored, the held queue stays as it was, and the 400 carriescodeandindex, the zero-based position inintentsof the first refused entry. A list longer than the horizon isqueue_too_long, withindexthe first entry past it. On append the cap counts what is still held plus what is added, and is judged once every entry has passed ingest, so another refused entry outranks it. - Replacing mid-tick. If the old head has already been handed to the sim for the tick that is closing, it still resolves, with its old
queue_id. The new queue starts on the tick after. A rejection clears only the rest of its own queue, so that late result never touches the new one. - Late delivery. An intent the seam delivers to the sim after a tick has closed runs on the next tick. Lateness is never a rejection.
- One in flight. The sim holds at most one intent per character. The seam hands a queue's next intent only once the result of the one before has landed, so a tick that closes before then is idle for the character and the intent goes out on the next one (Late delivery). A rejection therefore always lands before anything after it is handed, and a replace leaves at most the one handed head to resolve under the old
queue_id. - Pause. A paused world does not tick, so the held queue does not advance. It resumes where it stopped.
- Where it lives. The held queue is agent input, not world state. It lives on the world's handoff seam beside the round-trip results and, for append after a clean finish, the id and length of the last queue set while it is no longer held and ran to its end with no rejection (Redis in production, in process when front and sim run as one process), never in Postgres or in the sim's live state (invariant 6). The sim takes the head when the tick closes and removes it in the same seam write that records its result, so an intent leaves the queue only once its result has landed. A store loss drops both; an append after that is
queue_changed. - Sim restart. With Redis, a restarting sim does not clear the seam, and the world is paused while the sim is down, so the queue survives and resumes where it stopped. An in-process seam goes with its process, which is a store loss. A head whose tick the sim committed before it stopped does not run again: its result, and everything else that tick brought the character (its events, its observation, its sleep state, and a level-clear ceremony), is on the next round trip, exactly as if the sim had never stopped. A head whose tick never committed runs on the first tick after restart, against the recovered world.
- Store loss and queue progress. If the handoff store loses its data, every held queue in that world is gone, along with any results not yet drained. Nothing reports it and nothing is lost that progress depends on (invariant 9): the character idles and the agent sends a new queue. For the latest queue
Qthe agent set withnintents, appends included, over every round trip since it setQ: whilequeue.queue_idisQ, every index belowqueue.next_indexhas run, and an index without a result was an appliedWait. Anyrejectedresult whosequeue_idisQendedQon that index; every index up to it is accounted for the same way, nothing after it runs, anddiscardedwhen present lists the indexes after it that will not run (a rejection on the last index has none). Whenqueueis absent andfinished_queueis{Q, n},Qran to its end with no rejection, and every index without a result was an appliedWait. A character's end drops its held queue without results for the intents cut off; the round trip that carries the ending tick reports the end (Tick Rejection Reasons,character_ended), which is not a store loss. Whenqueueis absent and none of the above holds, the store lostQ: the indexes after the highest one known to have run (the highest result index forQ, or the lastnext_indexseen forQminus one) are unaccounted for, and the agent sends a new queue from there if it still fits.Qstops being the latest queue when the agent sets another; from thenqueueandfinished_queuename the new queue, andQ's unrun intents never run. A late result forQ's in-flight head can still arrive and is read as above, not as a sign about the new queue. An append keepsQthe latest queue: it continuesQ's indexes,ngrows by the appended count,queue.queue_idisQagain, andfinished_queueis absent until the appended intents run out. A wakingWaitis an appliedWait: no result, and its index is accounted for byqueue.next_indexorfinished_queue. - Explicit and unconditional. The agent wrote every intent in the queue and the server holds no conditions and no repeats. That is what keeps the queue from being a standing order (invariant 4).
Waitis an ordinary intent: an idle tick inside a queue. - Relative moves. A queued
SetPositionnames a block, so it is only one block from the character if the character is where the agent expected when it wrote the queue. When it is not, after an old head that still resolved, a wake onto another block, or a placement out of a hunting ground, the nextSetPositionisbeyond_movement_rangeand clears the rest.Stepnames a direction instead and moves one block from wherever the character stands on its tick, so a queue of them stays legal. QueueStepto walk; useSetPositionwhen the move must land on one exact block (B101).
{"intents": [
{"verb": "Step", "direction": "right"},
{"verb": "Wait"}, {"verb": "Wait"}, {"verb": "Wait"},
{"verb": "Step", "direction": "right"},
{"verb": "Wait"}, {"verb": "Wait"}, {"verb": "Wait"},
{"verb": "Step", "direction": "down_right"}
]}
{"code": "blocklisted", "index": 2}
Intent Results
| Result | Meaning |
|---|---|
| Applied | Executed and had effect. |
| Applied with no effect | Executed but changed nothing. Broadcast speech with nobody in range. |
| Rejected | No longer possible. Includes a reason, and clears the rest of its queue. |
Rejections cover attacking a character that has moved out of range, taking a supply another character already collected, and speaking directly to a named character who is no longer nearby. All are things that were possible when the intent was submitted and stopped being true by the time it resolved.
Blocklisted speech is not in that set. It never enters a queue at all: the request is refused at ingest, so nothing is applied, stored, or emitted, and the error states why.
Each entry of intent_results is one intent that ran, except an applied Wait: those resolve as applied_no_effect, advance the queue, and carry no entry. A rejected Wait keeps its entry, with rejection, and with discarded when the rejection cleared later intents, as any rejection. Gaps in index are applied waits that ran. An entry carries:
tick: the tick it resolved on.queue_idandindex: the queue it came from and its zero-based position in that queue (the same as its position in the request'sintentswhen the queue was set whole).outcome:applied,applied_no_effect, orrejected.rejection, only when rejected:category,code, andretryability(Tick Rejection Reasons), plusattack_rangeanddistanceon a weapon's or tool'starget_out_of_range(below).discarded, only on a rejection that cleared intents: the indexes, in that same queue, of every intent the rejection cleared, ascending. They were discarded because of this rejection and never ran. Resending from the failure point is the agent'sintents[index:], changed as it sees fit.- Any verb-specific field, such as
textonRead, orwithdrawn_supply_idsandleft_supply_idson aWithdrawFromChestthat named no supplies (Chests). hitand, on a hit,damageon a weaponUsethat rolled against a character or an NPC (B131):damageis what the target took, 0 when armour or the NPC absorbed it all. The outcome isappliedon a miss too, withhitfalse and nodamage: the swing ran and spent the attack credit. A swing at an empty block isapplied_no_effectwith neither, and a block a weapon destroyed carries neither.
"intent_results": [
{"tick": 1300, "queue_id": "5b0e9a1c47d2f3e8a6b4c0d9e7f21a3b", "index": 0, "outcome": "applied"},
{"tick": 1301, "queue_id": "5b0e9a1c47d2f3e8a6b4c0d9e7f21a3b", "index": 1, "outcome": "rejected",
"rejection": {"category": "occupied", "code": "block_occupied", "retryability": "transient"},
"discarded": [2, 3, 4]}
]
An intent a later request replaced before it ran gets no result. The agent replaced it, so it already knows.
Three Refusal Surfaces
A request can be refused in three places, and which one depends on when the answer is knowable. A failure that belongs at ingest but is deferred to the tick has already been accepted into the held queue: it was stored, it replaced whatever valid queue was there, and its rejection clears every intent after it.
| Surface | When | Shape |
|---|---|---|
| Ingest | Answerable from the request alone, before it is accepted into the held queue | HTTP 400 with a code |
| Queue conflict | The named queue is no longer the one to extend | HTTP 409 queue_changed |
| Tick result | Depends on world state at the tick boundary | rejected in the round trip, with category, code, and retryability |
| Transport | About the connection, the key, or the world's availability | HTTP 4xx / 5xx with a code |
The rule: if the request can be judged without looking at the world, judge it at ingest. Everything else waits for resolution.
Ingest Refusals
Refused with 400 before anything is held. Ingest is all or nothing: one refused entry refuses the whole request, nothing in it is stored, and the held queue stays as it was. The body is {"code": ..., "index": i}, index the zero-based position of the first refused entry in intents (Intent Queue). A refusal of the request as a whole, such as intents that is not a list, carries code alone.
| Code | Meaning |
|---|---|
unknown_intent |
Not a verb this API has |
malformed_intent |
Arguments missing, wrong type, or out of bounds |
malformed_target |
Target is not a block, a character, self, a direction, or an npc |
text_too_long |
Over the message length cap |
blocklisted |
Text matches the blocklist |
queue_too_long |
More intents than the world's queue horizon in ticks |
blocklisted is here and not in the tick results because invariant 11 requires blocklisted text to be refused at ingest and never stored. Accepting it into the queue would store it and discard a valid queue to do so, which is two breaks rather than one.
Tick Rejection Reasons
A tick rejection carries a category, a code, and a retryability.
The category set is closed and frozen for the life of a world. Codes are additive and new ones may appear at any time. Retryability is closed too, the same three values for the life of a world. An agent branches on category and retryability forever, and treats a code it has never seen as its category. The retryability is what tells it what to do with a code it does not recognize: category says what went wrong, and two codes in one category do not share a next step. conflict_lost and worn_slot_occupied are both occupied.
| Retryability | What the agent does |
|---|---|
transient |
Submit this same intent again later. The blocker can clear without the agent changing anything. |
precondition |
Do something else first. The same intent keeps failing until the agent changes position, loadout, or target. |
permanent |
Do not submit this intent again. |
| Category | Meaning | Codes |
|---|---|---|
range |
Too far away | beyond_movement_range, target_out_of_range, target_not_nearby, chest_out_of_range |
occupied |
Something is already there | block_occupied, conflict_lost, ground_occupied, worn_slot_occupied, boss_room_occupied |
missing |
Referenced thing is not there | supply_gone, chest_gone, no_trap_here, nothing_armed, not_held, slot_empty, nothing_to_read |
capacity |
Will not fit | carry_capacity_full, chest_full |
invalid |
Legal request, illegal against this thing or place | not_traversable, not_wearable, not_composable, fragments_missing, not_transferable, not_allowed_in_safe_zone, over_strength_ceiling, sleep_not_allowed_in_level, would_strand |
locked |
Needs something you do not have | door_locked, not_enough_gems |
state |
You or the world cannot do this now | character_dead, character_ended, world_not_open, recent_damage, alive_cap_full, movement_cooldown, attack_cooldown, speech_cooldown, store_unavailable |
| Code | Retryability |
|---|---|
beyond_movement_range, target_out_of_range, target_not_nearby, chest_out_of_range |
precondition |
block_occupied, conflict_lost, boss_room_occupied |
transient |
ground_occupied, worn_slot_occupied, would_strand |
precondition |
supply_gone, chest_gone, no_trap_here, slot_empty, nothing_to_read |
permanent |
nothing_armed, not_held |
precondition |
carry_capacity_full, chest_full |
precondition |
not_traversable, not_wearable, not_composable, not_transferable |
permanent |
fragments_missing, not_allowed_in_safe_zone, over_strength_ceiling, sleep_not_allowed_in_level |
precondition |
door_locked, not_enough_gems |
precondition |
character_dead |
transient |
recent_damage, alive_cap_full, movement_cooldown, attack_cooldown, speech_cooldown, store_unavailable |
transient |
character_ended |
permanent |
world_not_open |
transient while the world is in preview (a world that has one), permanent once it is closed |
character_dead is every intent from a character that is downed: dead with lives left, waiting out the world's respawn delay. Wait and Sleep are rejected with it too, so no intent brings a character back early. Retry after respawn_at_tick. store_unavailable is an intent the sim could not resolve because the store did not answer in time: it could not load the character, or could not reserve an id the intent needed, such as for a composed whole or a boss fight. Nothing happened in the world. character_ended is the one terminal state. Transcending and exhausting lives are the same ending, so they share this code. The agent's next round trip after the end still answers once with the ending tick: its intent results, its events (Died on a last death), and the final observation. After that, or once the world's event_retention_seconds passes with no round trip, nothing more is held for the character, and every intent it submits is character_ended (B129). not_traversable is permanent so the rejection does not say whether the block can be destroyed: a block does not reveal that, and bombing it is a different intent. A new code is added to this table with its retryability in the same change. The hint never names a hidden fact.
A weapon's or tool's target_out_of_range, from Use on a character or on a block, also carries attack_range, the reach it was judged by in blocks, Chebyshev (the armed weapon's, the same number GetSelf reports, or 1 for a tool), and distance, the Chebyshev distance from the character to the target's block, when the character sees that block on the tick it resolved and the target is on its map (B100, B104). On a block, both are judged before anything on it, so they are the same whether an NPC stands there or not. The reach is the character's own fact. A target block out of sight, or a character on another map, dead, or asleep, gets no distance, so the refusal never places a character the agent does not perceive. Every other rejection carries neither field.
"rejection": {"category": "range", "code": "target_out_of_range", "retryability": "precondition", "attack_range": 1, "distance": 3}
Reasons never reveal what perception hides. A rejection is a read, and the same scoping applies. door_locked does not say which key fits, because that is a hint the character has not earned. supply_gone does not say who took it. Disarming a trap the character cannot detect returns no_trap_here, the same as bare ground, because "there is a trap you cannot see" is the leak. Any new code is checked against this before it is added: a helpful message that leaks an unperceivable fact is a perception break, not a nicety.
Applied with no effect is not a rejection. It means the intent ran and changed nothing, such as a broadcast with nobody in range. Rejected means it did not run.
Transport-Level Errors
Distinct from both surfaces above, and never mixed with them.
| Status | Meaning | Codes |
|---|---|---|
| 503 | The world is paused. Carries Retry-After. |
maintenance, state_resync, write_buffer_full, event_log_unavailable, tick_schedule_lag |
| 429 | Rate limited or area cap exceeded. Never used for a pause. | rate_limited, area_cap_exceeded, replay_quota_exceeded |
| 401 | The credential is bad. A different key may work. | key_invalid, key_revoked |
| 403 | The credential is valid but not entitled to that character. Retrying the same key will not help. | not_your_character |
401 and 403 are split. A client that gets 401 should try a different key; one that gets 403 should stop. Collapsing them makes a misrouted character look like an auth outage.
An agent must also distinguish a paused world from one moving on without it, which is why pause is 503 and throttling is 429.
A transport refusal outranks an ingest refusal. On the tick POST the key, the character, the world's pause, and the world read are all decided before the body is read, so a malformed body for a character the key cannot reach is 403 not_your_character, not 400 malformed_intent. This holds whether or not the front has a sim wired.
Intents
Queued in order and resolved at the boundary, one per tick (Intent Queue).
Wait()
Sleep()
SetPosition(x, y)
Step(direction)
Use(target)
Arm(supplyId)
Wear(supplyId)
Remove(slot)
Take(supplyId)
Drop(supplyId)
Disarm(x, y)
Compose(supplyIds[])
DepositToChest(chestId, supplyIds[])
WithdrawFromChest(chestId, supplyIds[]?)
Say(characterId, text) or Say(npcId, text)
Broadcast(text)
Read(target)
Every intent above is served, Say(npcId, text) and Read(target) included (B57).
Wait and Sleep
Wait does nothing, on purpose. It resolves as applied_no_effect and carries no intent_results entry when it applies. It counts as activity for auto-sleep. In a queue it is an idle tick. It does not drop anything: "intents": [] clears the held queue.
Sleep takes the character off the map. It takes effect on its tick only when the character has neither dealt nor taken damage for the world's damage window (default 10 seconds). Otherwise it is rejected with recent_damage, transient: submit it again once the fighting stops. GetSelf's last_damage_at plus the damage window is when it will be accepted. Inside a level it is rejected with sleep_not_allowed_in_level, precondition. A rejection fits the result model: every intent resolves on its own tick, and none waits across ticks for a condition to clear.
Any intent from a sleeping character wakes it, unless the alive cap is full. The character reappears on the block it slept on, or on the nearest free walkable block when that one is taken, on the tick that intent resolves, and the intent also acts on that tick. A Wait that wakes a sleeper resolves as applied_no_effect, not applied, so it has no intent_results entry; the round trip shows the wake when asleep is absent once the character is awake. When the cap is full the wake is rejected with alive_cap_full, transient, the character stays asleep, and the server does not hold the intent to retry; that rejected Wait keeps its result entry. When the slept block and every other walkable block on its map are taken, there is nowhere to wake: the wake is rejected with block_occupied, transient, the character stays asleep, and the intent is not held. Sleep from a sleeping character is applied_no_effect.
Use
Use is the only active verb. There is no separate attack, throw, bomb, or drink command.
A character has one armed slot, and Use acts through whatever is armed. Swinging a sword, drinking a potion, and bombing a wall are the same call with different things armed and different targets.
target is a block, a character, self, a direction, or an npc, and is always explicit.
{"kind":"direction","direction":"left"} names the neighbouring block in that direction from wherever the character stands when the Use runs, using the same eight words as Step (B101). It is the swing in front of you. A reach-2 weapon still reaches farther only by naming a block.
{"kind":"npc","npc_id":N} names the block that NPC stands on when the Use runs. An NPC the character does not see on that tick, a dead one, or an id that names none is target_out_of_range with no distance, so the refusal never places an NPC the character does not perceive (invariant 5). Reach, safe-zone refusal, cooldown, and the hit roll are those of a Use on its block.
A missing or unknown direction on a direction target is malformed_intent at ingest, the same rule as Step (B101, B126).
A block targeted with a weapon or a tool armed must be within reach: the weapon's attack range, or one block for a tool, Chebyshev, corners included. Beyond reach it is target_out_of_range, judged before anything on the block, so a far block answers the same whether an NPC stands there or not, and nothing breaks (B104). A trap is armed on its block or a neighbouring one (target_not_nearby farther), and a teleport keeps its own range.
Swapping what is armed costs a tick, via Arm. Drinking mid-fight means a turn not swinging.
An attack is Use with a weapon armed. Nothing armed is rejected. Each weapon subtype has an attack cooldown in real time, default 1 second, on the character's attack accumulator (Movement). An attack while that accumulator is short is rejected with attack_cooldown. The default roll is 1–20. To-hit and damage are two rolls, each seeded from the tick, the actor, the target, and a roll kind of hit or damage. It hits when the roll plus attack power, plus the world's character hit bonus when a character swings, is at least the world's hit target plus defense plus worn armor defense. The default target is 10 and the default bonus 0; a hostile, a boss, or a trap never adds the bonus, and it does not change damage (B150). The lowest face misses. The highest face hits. The weapon does not change the hit roll. A miss deals 0. A hit deals a uniform roll from 1 up to the greater of 1 and attack power plus weapon damage, minus defense, minus armor defense. A hostile or a boss uses its own attack power, and as weapon damage its attack's damage when it has one; no shipped NPC does. A trap uses its grade as attack power and has no weapon damage. Disarm uses the same die and the world's hit target: roll plus detection grade against that target plus the trap grade. Its seed adds the roll kind disarm, with the character as actor and the trap as target. A world may replace the die size, the target of 10, and the minimum of 1, and those values are what gets published. Those settings are worlds.combat_die_size (default 20), worlds.combat_hit_target (default 10), and worlds.combat_damage_minimum (default 1). occupy_damage does not use this roll.
Worn slots are separate and passive. The wearable classes are armor and accessory. Armor uses head, body, legs, and feet. Accessory uses the accessory slot. There are five slots, and each holds one supply. Worn items apply continuously and do not occupy the armed slot. A tool is armed. An always-on light is an accessory. The outfit is a separate cosmetic layer, bought on the website with cash, points, or both, as that outfit is priced: no stats, not in the chest, and not dropped. No worn supply is purely cosmetic. A character's look is its face and its outfit, and worn supplies exist for their effect; a viewer draws the armed supply and the worn head, body, legs, and feet supplies on the character (B88).
Movement
SetPosition moves one block, to a neighboring block, corners included. A farther destination is beyond_movement_range. Nothing hops over a block, a character, or a trap.
Step moves one block in a direction: up, down, left, right, up_left, up_right, down_left, or down_right, with up toward row 0, the words a block art facing uses (Tiles). It is a SetPosition to the neighbour in that direction of the block the character stands on when the Step resolves, after any wake on that tick, and nothing else: the same movement speed, traversability, occupancy, same-destination roll, doors, hunting-ground ceiling, ground-supply pickup, traps, results, rejection codes, and events. A Step off the map's playable area is not_traversable, as a SetPosition there is. A missing or unknown direction is malformed_intent at ingest. A Step is one intent on one tick: it does not repeat, wait, or find a path (B101).
Movement speed is a character value: a permanent base plus modifiers from armed and worn supplies, in blocks per second. Move, attack, and speech each keep their own integer accumulator, three per character, one mechanism. The rate is per second: blocks for movement, attacks for a weapon (one over its cooldown), messages for speech. Every tick adds the whole rate in thousandths, not a per-tick share of it, so 2.5 blocks per second adds 2500 each tick. An action costs 1000 times the world's tick rate, 10,000 at 10Hz. The order within a tick is add, then spend if the intent acts and the accumulator covers the cost, then cap what is left at one cost. A move at 2.5 blocks per second is therefore one every 4 ticks at 10Hz, and a 1 second cooldown is one attack or message every 10 ticks. A rate that does not divide the tick rate carries its remainder, so it still averages out exactly. While the accumulator is short the intent is rejected with movement_cooldown, attack_cooldown, or speech_cooldown, and the tick is spent. The cap means a character never banks a second action. The arithmetic is integer, so an authored rate plays exactly and replay matches. A new character's speed is 2.5 blocks per second. The fastest a character can ever move is one block per tick. Hostiles and bosses use the same move and attack accumulators. A boss clear refills current health to the character's maximum, first raising that maximum by the level's authored gain on the character's first clear of that level. Every other permanent base gain is a supply consumed for that gain.
The observation carries attack_ready_at_tick and move_ready_at_tick for the character itself (B125): the absolute tick on which that accumulator first covers one action since it was last spent, from the same integer credit and per-tick rates the sim spends, remainder included. Queue an attack or move to resolve on that tick or later and it applies; one tick sooner is attack_cooldown or movement_cooldown. A value at or before the next tick means ready now: a ready accumulator reads the tick it filled, so it does not count up while the character waits. Each stays fixed between spends while the rate is unchanged, changes when the character spends that accumulator or its rate changes (arming a weapon, wearing armour, a timed effect starting or ending), and is left out of a delta when unchanged. attack_ready_at_tick is absent with no weapon armed, like attack_range on GetSelf.
There is no teleport command. A teleport supply is armed and Used on a block within its range. A block beyond that range is target_out_of_range.
Position is (mapId, x, y). Movement stays on the current map unless the destination is a door. If several characters target the same empty block in one tick, one is chosen at random to arrive; the others are rejected. The choice is seeded from the tick and destination so replay matches live.
A block holds one character or one NPC. A move, Step, or teleport onto a block an alive NPC holds, a door warp's landing included, is block_occupied. Characters move before NPCs act, so an NPC never steps onto a block a character took that tick, nor onto another NPC or a door's landing block. Wakes, respawns, and every other placement land on a free block (B104).
framed_door and rock_entry are doors and there is no enter command. Terrain reads include the block's occupy_damage. Setting position onto a door warps the character to the linked position on the destination map. A locked door requires a matching key in inventory. Match is by key subtype for a class of locks, or by a specific key identity. A successful unlock consumes the key and warps; a missing or wrong key rejects. A boss door rejects with boss_room_occupied while that fight is in progress and does not consume a resource. A character never occupies a door tile, so blocking a doorway means standing on the approach.
SetPosition into a hunting ground is rejected with over_strength_ceiling when the character's strength is over that zone's ceiling. Strength is permanent attack, permanent defense, armed weapon damage, and worn armor defense. A character already inside and over the ceiling is placed outside at the end of the tick: the nearest walkable block outside the zone with no character or NPC on it, straight-line distance, ascending character id, ties seeded from the tick and the character. That placement is not an intent. The next snapshot shows the new position.
A ground supply is acquired by SetPosition onto its block, or by Take when the character is already on that block or a neighboring block, corners included. Farther away, Take is target_not_nearby.
A gem supply has no price. Either call auto-consumes it into the character's gem counter and leaves nothing in the chest. The snapshot includes that counter. A life supply auto-consumes the same way into the life counter, under the cap of 20 lives ever gained. Gems are not sold for real money.
A supply may show a gem price. Either call spends the gems and takes the supply. Without enough gems the call is rejected with not_enough_gems and the supply stays. Several characters moving onto one priced supply in the same tick use the ordinary seeded same-destination roll. An ordinary supply that will not fit rejects with carry_capacity_full. A rejected SetPosition does not enter the block.
Chests
DepositToChest and WithdrawFromChest name a ground chest by chest_id and act only while it is on the character's block or a neighbouring one, corners included; farther is chest_out_of_range, and a chest that is not on the ground, or no longer exists, is chest_gone. supply_ids names the supplies to move. Every one must be where the intent says, and all of them must fit, or nothing moves: not_held for one that is not, carry_capacity_full or chest_full for one too many, and, on a deposit, not_transferable for a gem, a life, or a non-transferable supply.
WithdrawFromChest may leave supply_ids out (or send it null) to take everything in the chest that fits (B117). It takes the chest's supplies ascending by id until the carried chest is full and leaves the rest. Reach, carry capacity, and chest_gone are judged as for a named withdrawal, and it works on storage chests and dropped chests alike. The result is applied with withdrawn_supply_ids, what it took, ascending, and left_supply_ids, what stayed because the carried chest filled, ascending and left out when nothing stayed. An empty chest is applied_no_effect. A chest with supplies and no room for even one is carry_capacity_full, and nothing moves. Taking everything from a dropped chest empties it, so it leaves the world that same tick (Snapshots). An explicitly empty supply_ids, [], is still malformed_intent, for both verbs, and DepositToChest always names its supplies.
{"tick": 1302, "queue_id": "5b0e9a1c47d2f3e8a6b4c0d9e7f21a3b", "index": 0, "outcome": "applied",
"withdrawn_supply_ids": [1321, 1322], "left_supply_ids": [1340]}
Speech
Say is directed and rejected with target_out_of_range when the speaker is outside the recipient's perception range. The speaker's range does not matter. Say to a dead recipient is also target_out_of_range. Broadcast is never rejected for range the way Say is. A character hears it only when the speaker is inside that hearer's perception range. Distance is Chebyshev, corners included, the same as perception. A dead or ended speaker is rejected with character_dead or character_ended for either verb, like any other action.
The Say body names exactly one of character_id or npc_id. Both, or neither, is malformed_intent. Say to an NPC is target_out_of_range when the speaker is more than 25 blocks from that NPC, Chebyshev, corners included. An NPC id the character cannot perceive is the same rejection, not a hint that the id was wrong.
A helper does not call out on its own. When a Say to that helper is applied, the helper replies on the same tick, after character speech resolves. The reply is one SpokenTo back to each character whose Say to it applied this tick. The text is the helper's authored line, the same line every time, so Say again is how you hear it again. That reply is the helper's one action for the tick. A helper with no line does not reply, and the character's Say still applied. Hostiles and bosses do not reply. The reply does not spend the speaking character's speech accumulator. Read does not target a helper.
Read returns authored text on a sign or a scroll. A sign's cell carries readable: true on terrain reads. target is exactly one of a sign ({"kind":"block","x":10,"y":12}) or a scroll ({"kind":"supply","supply_id":4}). Any other kind, including an NPC, is malformed_target. A sign or a scroll on the ground must be inside the character's sight range; otherwise target_out_of_range. A carried scroll has no range check. A scroll another character carries, and a supply_id that names no supply, are the same target_out_of_range, not a hint whether the id exists. A target with no text is nothing_to_read, permanent. A sign's text, like its art, applies only while the cell shows its authored regular type: a destroyed sign carries no readable and is nothing_to_read until it recovers. Read does not spend the speech accumulator and does not emit speech. On applied, the intent result carries text, and a later Read returns the same text.
Speech a character sends is capped at one message per second, across Say and Broadcast together, on the character's speech accumulator (Movement). A Say or Broadcast while that accumulator is short is rejected with speech_cooldown, transient, and nothing is emitted. Blocklisted text is still refused at ingest before this applies. Authored helper, sign, and scroll text is bundle text: bundle load rejects text that matches the blocklist, and each text is at most 280 characters.
Text only. No images, files, attachments, or encoded payloads.
Reads
Immediate, not tick-bound.
GetSelf()
GetPosition()
GetSupplies()
GetEvents()
LookAround(radius)
GetNearbyCharacters()
GetTerrainTiles(mapId, viewport)
GetEntityTiles(mapId, viewport)
GetChest(chestId)
GetZone(mapId, x, y)
GetTick()
GetWorld()
GetMinimap()
GetSupplies and GetChest are not served: the snapshot's inventory and entities.chests carry their facts (Snapshots).
What a supply subtype does is not a read here. The website serves it once for every agent, with no key: GET /docs/supplies.json is the Manual's Supplies reference as JSON (B132), every subtype that is not a world's secret find with its slot, its capabilities (each with its trigger and its amount, reach, cooldown_ms, and duration_seconds where it takes them), and each shipped world's gem price. It never says which blocks a supply breaks. B138 changed its shape: each row's capabilities list replaced use_effects and the per-stat fields (attack_range, damage, heal, teleport_range, chest_capacity, defense, light_radius, grants).
GetPosition returns (mapId, x, y). Tile and zone reads are scoped to a map. GetZone includes the zone's brightness, safe, true in a safe zone and false elsewhere, and, for a hunting ground, its strength ceiling. A cell in no authored zone reads at brightness 1, not safe, with no ceiling. GetWorld includes level_count, how many levels the world authored (clearing all of them is beating the world), respawn_delay_seconds, how long a dead character stays downed before it respawns (default 5), the current operator notice while one is posted, and the world's music table: each music code with the URL and content hash of its track. A client reads it once and pulls a track when it first needs it; tracks are immutable and cache by hash. A track GET is a keyed read like GetWorld itself and needs the same bearer, so the official viewer fetches the track with its watch key and plays the returned blob, since an audio element cannot send Authorization. It sends the key only to the API's own origin. The table names no zone and no coordinate. GetSupplies reports an authored recipe's finished shape, the total piece count, and which pieces are missing. It does not say where the missing pieces are. Compose requires the full set.
LookAround, GetNearbyCharacters, and GetZone are served as GET /characters/{id}/look-around?radius=, GET /characters/{id}/nearby-characters, and GET /characters/{id}/zone?map_id=&x=&y=. A radius past the current sight range is 409 radius_exceeds_sight_range, and a zone cell the character neither sees nor has revealed is 409 outside_sight_range. GetNearbyCharacters lists the other characters in sight, never the caller, in the observation shape: position, outfit, and visible armed and worn supplies. A character not on a map is 409 not_on_map on all three. The front serves LookAround and GetZone from the tile cache at the newest closed tick, from the character's published pose and reveals and the zone facts the sim writes for each map at startup (B95). LookAround checks the radius against the pose's sight range and returns tick and radius; it reveals nothing new, because every closed tick has already revealed each tile inside the sight range, and the radius cannot pass it. GetNearbyCharacters needs each character's armed and worn supplies and disguise, which the cache does not carry, so the front answers it 501 not_implemented (B16). GetZone is also 501 not_implemented on a map the sim has published no zone facts for, which is a sim that predates them, and all three are 501 on a front with no tile cache wired. Terrain reads differ: a character, owner watch, replay, or spectator terrain read of ground on a map with no zone facts is 500 internal_error, because the sim publishes zone facts before any tile and the read will not serve safe ground as unsafe (B127).
Perception range and trap detection grade are character values, each a permanent base plus supply modifiers. A new character's perception range is 25 blocks in every direction, corners included. Different goggles raise that range by different amounts and reveal traps ordinary observation cannot. Darkness shortens that to a sight range: perception range times the brightness of the zone the character stands in, rounded to the nearest block, never less than 1, plus the radius of a light the character has armed or worn, capped at perception range. LookAround cannot ask past the current sight range. A terrain tile the character's sight range has touched stays readable, and shows the ground as it is now. The server saves that revealed set with the world, so after a restart a character sees the ground it had revealed as of the last save. A tile it has never touched is clouds. Characters, NPCs, supplies, and traps appear only inside the current sight range. The tile read cap and speech reach stay on perception range. Spectators see ground any character in the world has revealed, on a delay, and darkness does not limit them.
GetSelf reports movement speed in thousandths of a block per second: the character's permanent base plus modifiers from armed and worn while-equipped supplies and from timed consumable effects, the same number SetPosition uses for movement admission. The sim computes it whenever the character's gear, timed effects, or base values change; the front tier only reads it, live like lives when the front has live sim state wired. While a weapon is armed it reports attack_range, that weapon's reach in blocks, Chebyshev: the subtype's attack range, or 1, the next block, corners included, when it authors none. It is absent while nothing, or something other than a weapon, is armed. It is the same number the sim judges target_out_of_range by, read like movement speed (B100, B144). It reports whether the character is asleep, and, while it is downed (dead with lives left), respawn_at_tick: the tick it respawns on at the earliest, its death tick plus the world's respawn delay in whole ticks. It is absent while the character is alive or once it has ended. While the character's last death chest still exists in the world, GetSelf reports death_chest: {chest_id, map_id, x, y} where that chest landed. The field is omitted once the chest is emptied or gone, when a death dropped nothing, and after the next death replaces it. It is the character's own fact, not another character's chest. It reads the saved world and, when the front tier has live sim state wired, the same durable picture as lives, so it survives after events expire and across a restart. The round trip's observation carries the same death_chest while it holds; a delta sends null when it clears. It reports the character's own health and max_health while it is awake, and omits both while it sleeps, the same rule as the owner sheet's on-map vitals; a downed character is awake and reads health 0 until its respawn refills it (B94). They read the live snapshot when the front tier has it wired, like lives. Only the character's own credential sees them: no read carries another character's health. It also reports last_damage_at: the world-clock time the character last dealt or took damage, absent if it never has. Only the character's own credential sees it; spectators never do. A client adds the world's damage window to it to show when Sleep will be accepted. A sleeping character's reads are minimal: it perceives nothing, and its round trip answers with its asleep state and the clock, no observation and no events. A sleeping character that keeps polling is held to about one request per second.
POST /worlds/{code}/characters creates a character from name, avatar (an outfit code), model_agent, and an optional face: {"skin", "hair_style", "hair_color", "eyes", "mouth"}. Each part is optional and, when sent, one code from its fixed set: skin is pale, fair, tan, olive, brown, or dark; hair_style is bald, short, spiky, bob, long, ponytail, mohawk, or curly; hair_color is black, brown, auburn, blonde, red, grey, white, or blue; eyes is dot, round, narrow, sleepy, or wink; mouth is smile, grin, flat, open, or smirk. A value outside its set is 400 face_invalid with part naming the first bad part, and nothing is stored; an unknown key inside face is 400 malformed_intent, like any unknown field. Every part left out is picked from the new character's id by a fixed hash, so the same character always gets the same face, and the whole face is stored with the character at creation. The face is fixed for the character's life and cosmetic (B59). The created character and GetSelf carry the whole face. A later character of the same model_agent in that world is 409 identity_reuse when it reuses a prior name or that stored face. The outfit may be reused. Two bald faces match whatever their hair_color, because bald draws no hair. When the agent left parts out and the face would match a prior one, the left-out parts are derived again, so identity_reuse on the face comes only from the parts the agent chose. A character created before the face was stored counts with the face derived from its id.
A new character is created off the map and waits in the town queue. The sim places it on a free town tile at the end of a later tick. Until then GetPosition fails with 409 not_on_map, and GetSelf reports placed: false. GetPosition, and lives, alive, placed, and respawn_at_tick on GetSelf, read live sim state (the tile cache pose and the durable observation the sim last published) when the front tier has them wired, not the Postgres snapshot.
A tile read or GetPosition for a character the sim has not yet loaded into live state, such as one created moments ago whose first handoff has not landed, fails with 409 character_not_live and returns no cells. It is transient: retry the read. It is a read refusal, not a transport error, and says nothing about the world. GetSelf still answers for such a character, with placed: false.
GetMinimap works with or without a map worn. It returns tick, map_worn, and maps. A world map is included only after at least one of its tiles has been revealed; maps never opened are omitted. Each map carries map_id, map_width, map_height, entrances, and cells. entrances lists every level entrance door on that map as {x, y}, found or not, with no level number. level is the authored level the map belongs to, omitted outside every level. While a map supply is worn in the accessory slot, map_worn is true and cells covers the map: revealed cells carry the current block type, the rest are fog and carry no type. With no map worn, map_worn is false and cells is empty: the whole map is fog. Characters, NPCs, and supplies are omitted. The minimap is not a tile read and is not limited by the viewport cap. Spectators have no minimap. On a front tier reading the tile cache, each map's level and entrances come from level facts the sim writes into the cache once at startup, from the world bundle, beside the map sizes. A cache with no level facts at all, written by a sim that predates them, still serves the minimap, with no level and no entrances on any map, and the front logs a warning. A cache whose level facts leave out an opened map disagrees with itself, and the read fails as it does for an opened map with no size.
Snapshots
A snapshot covers everything durable, including lives remaining, levels cleared, and whether the character is alive. While the character is downed the snapshot carries respawn_at_tick, the same tick GetSelf reports; a delta clears it with null when the character respawns or ends. A downed character has no position and perceives nothing, so its snapshot has no position and no entities.
The snapshot carries the character's own health and max_health under the same rule as GetSelf: present while awake, omitted while asleep (B94). A delta carries health on any tick it changed, so a Damaged tick shows the new total and a dropped event loses nothing; a delta clears both with null when the character falls asleep. They are the character's own vitals only: no perceived character in entities, and no character on an entity tile, carries health.
While the character is alive the snapshot also carries attack_ready_at_tick and move_ready_at_tick (Movement above), attack_ready_at_tick only with a weapon armed. Both are absent while downed; a delta clears them with null when the character goes down, and attack_ready_at_tick with null when it disarms its weapon.
It is scoped to what the character can perceive. Without that there is no ambush, stealth, hidden area, or reason to explore.
The snapshot's inventory is the character's own holdings: gems, armed, worn by slot, held, and chest, each supply an id and supply_subtype_code. Each supply is in exactly one of them: the armed supply and the worn ones are not also in held. held is everything else the carried chest holds. chest is empty today, since no intent stows a supply in the character's own carried chest apart from holding it. A fragment supply also carries fragment, the same shape as on entity tiles: the composed whole's subtype code, piece_count, this piece's slot, and missing_slots, the recipe slots of that whole the character does not hold, arm, or wear; a piece's own slot is never missing, including a piece in the carried chest. It never says where a missing piece is.
The snapshot's entities.chests lists the ground chests in sight, storage and dropped alike (B103): each an id, x, and y. A chest dropped at a death leaves the world the moment its last supply is withdrawn, by any character: it is a removed id in the patch, as any entity leaving sight, and a later WithdrawFromChest or DepositToChest naming it is chest_gone. A storage chest stays when empty (B116). A carried chest is never listed; its contents are the holder's inventory.chest. While a chest is within reach, on the character's block or a neighbouring one, corners included, the reach WithdrawFromChest and DepositToChest have, its entry also carries contents: each supply's id and supply_subtype_code (and fragment, as in inventory), [] when the chest is empty. Farther away the entry has no contents, so a chest is found by sight and opened by walking up to it, and stepping in or out of reach is a changed entry. No entry says whose chest it was. This is how a chest's contents are read; GetChest is not served.
Each perceived character carries its position, outfit code, armed item, and worn items by slot, as subtype codes. Stats and a strength number are never included. When that character wears a disguise cloak in the accessory slot, other characters' snapshots show worn.accessory as the cloak and nothing else: no armed and no other worn slot, unless the viewer has attacked that character before or wears or has armed a detection supply that reveals gear, then the cloak no longer hides anything from that viewer, and the viewer sees the character's current gear. Being attacked does not teach the target anything; the target learns the attacker's gear by attacking back. The character's own snapshot always shows the truth.
Every snapshot carries a version id. The agent sends the last version it saw and receives a delta. A complete snapshot is sent only on resync, when the agent's snapshot_version is a version the server no longer holds, or on request, and complete means the character's entire perception-scoped view rather than the world.
The version names the snapshot's content, not when it was read: it is the tick on which the character's view last changed. The sim builds every character's view at the close of every tick and publishes it only when it differs, so the snapshot on any round trip is the current view as of the newest tick the sim has resolved and written, which is the round trip's tick less one: one tick earlier while that tick's write is landing, and never more than the second the sim may run behind the tick grid before the world pauses with tick_schedule_lag. A version far behind tick is not stale: it means nothing in the view has changed since that tick. A resync's complete snapshot is the same current view and carries the same version when nothing changed, so the version does not advance on its own. The freshness of an observation is the response's tick; a complete snapshot also carries resync.current_tick, the same clock. The version is only the base a delta applies to (B100).
A delta carries only the top-level fields that changed: lives, alive, respawn_at_tick, health, max_health, attack_ready_at_tick, move_ready_at_tick, levels_cleared, death_chest, position, inventory, entities. Each is the new value whole, except entities, which is a patch (B92): one object per kind that changed, characters, npcs, supplies, and chests, each with up to three lists keyed by the entity's stable id:
added: whole entries for entities that came into sight.changed: the whole entry, in the snapshot's shape, for each entity still in sight whose fields differ. One entry is a handful of fields, so it is sent whole rather than field by field.removed: the ids of entities that left sight, for any reason: they moved away, the character moved, sight shrank, they were taken or died.
A kind with nothing added, changed, or removed is left out, and so is an empty list, so one NPC moving costs one entry however many entities are in sight. Applying the patch to the previous snapshot's lists gives the new snapshot's. A downed character's patch removes everything it saw. Every entry is drawn from the new perception-scoped snapshot and every removed id is one the character already saw, so a patch reveals nothing a complete snapshot would not (invariants 5 and 8). A complete snapshot's entities is the whole layer and replaces what the client held.
{"version": "42", "delta": {"position": {"map_id": 1, "x": 12, "y": 9},
"entities": {"npcs": {"changed": [{"id": 301, "x": 14, "y": 9, "npc_type_code": "rat"}], "removed": [288]},
"supplies": {"added": [{"id": 77, "x": 13, "y": 11, "supply_subtype_code": "apple"}]}}}}
Tiles
The world is cached as fixed aligned tiles. A client names a square viewport, and the front assembles the response from the tiles covering it.
A cache tile is a 16 by 16 block square aligned to the map origin; tile (i, j) covers blocks x from i×16 through i×16+15 and y from j×16 through j×16+15.
A tile is not a game concept. Zones, maps, and worlds are gameplay groupings (safety, music, spawn role, which grid, which world), and none of them is sized for caching. A zone can be one block or ten thousand; a map can be an entire overworld. A tile solves a different problem: reads at 100,000 requests per second need a cache key that many viewers looking at the same patch of ground share, and an arbitrary viewport rectangle is a unique key every time. Fixing the rectangle is what makes that key reusable: a tile at a given tick is one cache entry, immutable once the tick closes, so many viewers watching the same area cost one computation instead of one per viewer.
Two layers with different change rates, requested separately:
| Layer | Contents | Cache lifetime |
|---|---|---|
| Terrain | Block types and states | Until a block in the tile changes |
| Entities | Characters, NPCs, visible supplies, ground chests. A ground chest, storage or dropped at a death, includes its id, x, and y only: never its contents or whose it was (B103). A dropped chest is gone from entity tiles, the spectator read (under its delay), and the owner watch once it is emptied; a storage chest stays (B116). A character includes its name, its cosmetic outfit code, its face, headgear, armed, worn_body, worn_legs, and worn_feet, never a strength number. An NPC includes its type's display name. A boss NPC also includes its current health and max_health, so a viewer can draw its health bar; no character, hostile, or helper carries health. A supply includes its subtype code, its gem price when it has one, and trap_armed when a trap on the ground is armed. A fragment supply also includes fragment: the composed whole's subtype code, piece_count, this instance's slot, and missing_slots for unfilled recipe slots, never where missing pieces are. |
Per tick |
The sim writes each closed tile into the tile cache, and the front reads it. The cache is Redis once the front and the sim run apart, the same split as the handoff. Without Redis the sim keeps it in process and mirrors it to a snapshot file the front reloads for character, owner-watch, and spectator tile reads, so both must share one machine and one cache directory. The cache holds the shared picture. An agent's sight filter is applied when the front reads, and a picture per character is not stored. Tile reads do not come from Postgres, and the front does not call the sim over HTTP.
Agents and spectators share one read: events since the caller's last seen tick, grouped by tick, plus the picture and the current tick. Only the filter differs. An agent's is its character's sight range, live, except speech, which it hears by perception range. A spectator's is the spectator delay, revealed ground only, and nothing no character could detect. Spectators get every event kind that happened inside the viewport, speech, attacks, damage, deaths, and supplies taken included. The sim writes each closed tick's events beside the tiles in the tile cache, back to the spectator delay, and the front reads them there. Speech a moderation verdict or the speech kill switch withholds is left out when the front reads.
A viewing read carries an API key, like every other call. There is no anonymous read. Viewing reads are spectator reads and owner watch reads (below). They spend from the account's viewing bucket, eight tokens per tick of the world being watched, burst of 8, keyed by account id: one bucket per account, shared by every viewing read of any world or character. An agent's requests spend its character's bucket, never this one, and a viewing read never spends a character's bucket, so watching a character takes no requests from its agent.
The revealed-ground set spectators are limited to is world-wide. Each revealed tile carries the tick it was first revealed, and a spectator read shows a tile only when that tick is at or before the delayed tick. The front's copy is eventually consistent and may lag the sim. A lagging copy shows less ground, never more, and nothing waits on it.
A request returns the tiles covering that capped square viewport, each tile carrying every block in it. Every terrain and entity read, character or spectator, also carries map_width and map_height, the requested map's whole size in blocks, and leaves both out when the tile cache has no size for that map. A terrain read carries music, the music code of the zone under the viewport's centre block, and leaves it out when that block is not revealed to the reader. The centre is clamped onto the map, so a map smaller than the viewport, or a viewport at the map's low edge, still reads the zone at the map's nearest block. Spectator and owner watch terrain reads also carry brightness on each cell's legend entry, the brightness of the zone the block sits in, so the viewer can tint the block art; it is left out at brightness 1 and where no zone is authored. Those reads also carry safe on a legend entry when the block sits in a safe zone, so the viewer can mark refuge ground; it is left out when the block is not safe. An agent's own terrain read carries safe on a legend entry under the same rule and leaves brightness out; an agent reads a zone's brightness with GetZone. The client may scale those pictures locally. It does not ask the server for a coarser, wider map.
A terrain read is a grid, not a list of cells (B102). rows holds one string per row of the viewport, height of them, each width characters long: rows[j] is row y0 + j, and its i-th character is the block at x0 + i. Each character is a key of legend, or ? for a cell the read carries no block for: ground the reader has neither in sight nor revealed (for a spectator, ground no character has revealed by the delayed tick), or no ground at all past the map's edge. A ? is unknown, never empty ground. A legend entry is everything about the cell: block_type, and locked, occupy_damage, readable, brightness, safe, art, and facing under the rules below, each left out when false, zero, empty, or not served (B133). Two cells share a character exactly when their entries are equal, so a door that needs a key and one that does not have different characters, and so do two cells of one block type with different art, or with the same art facing different ways. Legend characters are chosen per response, from the block type's own letters where they are free (g for grass, G for a second grass entry, S for sign once s is taken) and otherwise from the next free printable character; they are not stable across reads, since a symbol fixed by the block catalog would tell the reader about block types it has never perceived (invariant 5). A character is one Unicode code point in the Basic Multilingual Plane, never ?, ", \, a space, <, >, or &; a read with more distinct entries than printable ASCII goes on into Latin Extended and then CJK, so index rows by code point, not byte. A read with more distinct entries than those ranges hold, about 21,000, is refused with 500 internal_error and the server logs it; it never falls back to a different shape.
{
"map_id": 1, "x0": 10, "y0": 20, "width": 5, "height": 3, "map_width": 300, "map_height": 200,
"tick": 1251, "current_tick": 1251, "music": "town",
"legend": {
"g": {"block_type": "grass"}, "l": {"block_type": "lava", "occupy_damage": 8},
"s": {"block_type": "statue", "art": "statue_hadoze", "facing": "left"},
"f": {"block_type": "framed_door", "locked": true},
"S": {"block_type": "sign", "readable": true}
},
"rows": ["gggs?", "glfgS", "???gg"]
}
Here the statue at (13, 20) is Hadoze's and faces left, (14, 20) and the first three cells of row 22 are unknown, and (12, 21) is a locked door. A 51 by 51 town read with about 600 art cells is about 4.4 KB, and about 3 KB without art, against about 100 KB as a list of cell objects.
The spectator picture is served on the front tier as GET /worlds/{code}/terrain-tiles and GET /worlds/{code}/entity-tiles. The query names the map and the viewport: map_id, then either x0, y0, width, and height, or the corners x0, y0, x1, y1, inclusive. A missing or malformed viewport is 400 malformed_intent. The viewport is capped at 151 by 151; a larger one is 429 area_cap_exceeded. The response is the same terrain or entity shape the character routes return, at the delayed tick: the newest closed tick minus the world's spectator delay, named in the payload's tick. It is assembled from the same 16 by 16 tile versions the character reads use, shows revealed ground only, and applies no perception filter. An unknown world code is 404 world_not_found, and a paused world refuses spectators the way it refuses agents. A missing or unknown key is 401 key_invalid and a revoked one 401 key_revoked, as on the character routes; an unverified account is 403 email_not_verified, the same bar as play (Accounts and Access). Terrain and entity reads, of any world, spend the viewing bucket of the key's account; past it the read is 429 rate_limited. That bucket refills eight tokens per sim tick of the watched world, read from the handoff clock the sim advances. Tick credit never carries across worlds: on a switch, only wall time is credited, at the slower of the two worlds' rates, so time that passed under a slower world's rate is never credited at a faster one's (B43). A front tier with no tile cache wired answers 501 not_implemented.
The delayed player list beside those reads is GET /worlds/{code}/players (B130). It names every placed, awake, alive character the spectator entity tiles show at the same delayed tick, across every map of the world, on ground some character has revealed by that tick; sleepers, the downed, and characters on ground not yet revealed are absent. Each row is id, name, map_id, x, and y, the values that character's entity tile cell carries at that tick, and rows are sorted by name, ignoring case, then id. The response carries tick, the delayed tick the picture names, current_tick, the newest closed tick, and players. It takes no viewport. limit is the page size, 1 to 200, default 200. name is a case-insensitive prefix filter, applied before paging. next is the last row's name and id as a JSON object, {"name":"Ada","id":12}, and is left out on the last page; pass it back URL-encoded as after for the following page. A limit outside 1 to 200, or an after that is not such an object, is 400 malformed_intent. Auth and refusals are the spectator tile reads': an API key or an OAuth token with the watch scope, and a token without it is 403 insufficient_scope; a missing or unknown key is 401 key_invalid and a revoked one 401 key_revoked; an unverified account is 403 email_not_verified; an unknown world is 404 world_not_found; a paused world refuses it with 503 and its pause code; a front tier with no tile cache wired answers 501 not_implemented. Each page spends one token from the account's viewing bucket, and past it the read is 429 rate_limited. No /characters/{id}/… route and no MCP tool serves the list.
A spectator reads the world itself with GET /worlds/{code}, the spectator GetWorld (B49). It returns the same payload as a character's GET /characters/{id}/world: code, name, status, is_sandbox, tick_rate_hz, level_count, respawn_delay_seconds, operator_notice while one is posted, and music, plus town, the starting zone's map_id and one walkable block x, y in it, and needs no character. town is an authored fact, the same place characters are placed. Map ids are database identities, so the row numbered 1 is not that town once another world's maps, or a level, were inserted first. The official viewer opens a spectator watch on town when the URL names neither map, x0, nor y0. It is left out when the front cannot name it. Auth, bucket, and refusals are the spectator tile reads': a missing or unknown key is 401 key_invalid and a revoked one 401 key_revoked; an unverified account is 403 email_not_verified; it spends the viewing bucket of the key's account, never a character's, and past it is 429 rate_limited; an unknown world code is 404 world_not_found; a paused world refuses it with 503 and its pause code (Paused World). A spectator viewer reads it once per watch for the music table. A replay watch does not read it.
Every terrain and entity read, character, spectator, or owner watch, carries the same round-trip fields beside the picture: current_tick, the authoritative tick the read was taken against (the newest closed tick for a live agent read, or the newest closed tick of the world while the picture's own tick may be delayed for a spectator), and events_by_tick, events inside the viewport since the caller's last seen tick, grouped ascending by tick as in a round trip, with event tick at or before the payload's tick. The optional events_after query is the last tick the caller has seen; only later ticks are returned, and without it every tick still available to the read is. A spectator read keeps delayed events for the world's event_retention_seconds behind the spectator tick; when a tick after events_after has already been dropped from that window, the read returns every tick it still has and carries events_truncated: true, so a viewer that fell behind knows it missed events. events_truncated is left out otherwise. A negative or non-integer events_after is 400 malformed_intent. events_by_tick is left out when no event matches. Character tile reads peek the character's pending queue and do not drain it. Owner watch tile reads use the same perceived events, and keep them for the queue retention window after the round trip drains the pending queue, so the map still shows what the character heard while its agent is polling. Spectator reads take delayed events from the tile cache. Spectator and owner watch reads are human views, so their events pass display-time speech filtering (B24); an agent's own read does not. A human view may send Speech-Filter: friendly, medium, or mature on spectator, owner watch, and replay watch reads (B52); absent or unknown is medium, which shows exactly the frozen verdict. friendly also withholds borderline speech; mature shows soft speech medium withholds, but never the hard categories or anything the endpoint flagged. Those responses carry Vary: Speech-Filter. An agent's own read ignores the header. The level changes only what that read displays; the ingest blocklist and stream enforcement apply to everyone.
The owner watch is served as GET /watch/characters/{id}/terrain-tiles and GET /watch/characters/{id}/entity-tiles. GET /watch/characters/{id}/sheet is the owner panel for that same key: asleep, face (the same resolved {skin, hair_style, hair_color, eyes, mouth} as GetSelf), and while awake health, max_health, and strength, plus lives, gems, armed (or null), worn for head, body, legs, feet, and accessory (each a {id, code} or null), map (true only when the character is awake and a map supply is worn in the accessory slot), bag for every other carried supply, and the goal: levels_cleared, the level numbers the character has cleared, and level_count, the world's count. The goal is there asleep or awake. Each supply there may carry fragment with the same shape as on entity tiles; held fragments aggregate missing slots across everything the character carries, arms, and wears for that whole. While asleep, on-map vitals are omitted and map is false so the panel does not read like a character standing in the world. strength is permanent attack and defense plus the armed weapon's damage and worn armor's defense, the number the sim checks hunting-ground entry against, written by the sim to the saved row. Supply codes are subtype codes. The sheet is read from the saved world, so it can briefly trail the live tiles; GetSelf's lives, alive, and placed are live when wired, so the sheet's lives can briefly trail them. It spends the viewing bucket and is refused the same way as the other watch reads. GET /watch/characters/{id}/minimap is GetMinimap for that same key: the same maps, entrances, levels, revealed ground, and fog, with or without a map worn. The viewer reads it while the character is awake. It spends the viewing bucket and is refused the same way as the other watch reads. GET /watch/characters/{id}/replay?at_tick= is the owner's replay watch, described under History and Replay. The tile reads take the same query as the character tile reads and return the same payload: the character's live, perception-filtered picture at the same tick, capped at the 151-block watch square while awake. The one addition is each terrain cell's brightness, as above. While the character is awake it shows only what the character perceived, nothing more. A sleeping character is off the map and perceives nothing, so its own tile reads have no picture to show. While the sheet says asleep, the owner watch shows the world's spectator picture instead: the official viewer reads GET /worlds/{code}/terrain-tiles and GET /worlds/{code}/entity-tiles on the same key, for the world GET /characters/{id}/world names, opening on the block where the watch last drew the character, or on town when it never did. A ?world= on the viewer URL stands in only until that read lands, or when it fails, so it cannot point the watch at another world. These are ordinary spectator reads: delayed by the world's spectator delay, capped at the watch square (151 by 151 at most), limited to ground some character has revealed, refused the same way, and spending the account's viewing bucket, never the character's. They square with invariants 5 and 8 because they give the owner nothing new: any key may read that same picture, so it reveals nothing the character's own perception would hide, and a replay of it shows no more than the live read did. The sleeper itself is not drawn, though the delayed picture can still hold it standing where it lay down. The owner watch goes back to the character's own reads when the sheet says it woke, and the two pictures share no tick, events cursor, or cached tiles. Its events can outlast the agent's read: they stay for the queue retention window after the round trip drains them. GET /watch/characters/{id}/position returns the same (map_id, x, y) as GetPosition, taken from that live pose rather than the Postgres snapshot, so a viewer can move its window onto the character. A character with no map position yet is 409 not_on_map. The key must belong to the character's account: a missing or unknown key is 401 key_invalid, a revoked one 401 key_revoked, and another account's character is 403 not_your_character, as on the character routes. It spends the account's viewing bucket, never the character's; past it the read is 429 rate_limited. It is not agent activity: it submits no intent, drains no round trip, and does not hold off auto-sleep. The path sits outside /characters/ so the character's limit never applies to it. A paused world refuses it as it refuses the character's own reads, and a character the sim has not loaded is 409 character_not_live.
Tile payloads name types by catalog code (block_types.code, npc_types.code, supply_subtypes.code, outfits.code), never by numeric id, since ids differ between environments. Character, NPC, and supply instance ids are world state and stay. Each character in characters carries its name, its face (the same five part codes creation takes, always whole), headgear, the subtype code of the supply worn in its head slot (B59), armed, the subtype code of the supply in its armed slot (B78), and worn_body, worn_legs, and worn_feet, the subtype codes worn in those slots (B88). Each is left out when its slot is empty (armed when nothing is armed); all five are also left out when the character wears a disguise cloak: a tile is the shared picture, so it shows no more gear than a disguised character shows other characters (Observation above). The accessory slot is not on the tile. A viewer draws a character as layers, bottom first: the body in the skin tone, the face (eyes, mouth, then hair in the hair colour), the outfit, which is clothing only and leaves the head clear, then the worn legs, feet, and body armor, then the headgear, then the armed supply. Armed and worn supplies are drawn from the gear bucket, never from the supply's ground picture in supplies, and a code with no gear picture draws nothing on the character; each NPC in npcs carries the display name from npc_types. A terrain cell whose block is a door that requires a key has locked: true in its legend entry while that block shows as a warp, and omits it otherwise. The field does not name the key subtype or which key opens the door. A terrain cell's legend entry carries art, the cell's art code, while the cell shows its authored regular type, and omits it otherwise, so a destroyed cell's entry has none (B61, B133). It also carries facing, one of up, down, left, or right, the map direction that art faces with up toward row 0, when the bundle authors one, and omits it otherwise; it is never present without art (B97). A terrain cell with authored sign text has readable: true in its legend entry while the cell shows its authored regular type, and omits it otherwise (B57).
Tiles carry codes, not image bytes. The client decides which picture to draw for a code. The official viewer ships its pictures with itself. A separate request may return the standard image files. Another client may draw the same code with its own picture.
When the front tier is started with VIEWER_GRAPHICS_DIR pointing at the official viewer asset tree, it serves those files at GET /viewer/graphics/{bucket}/{code}.svg. {bucket} is one of blocks, supplies, npcs, or outfits, the catalog namespaces, or faces or gear, the character layers (B59, B88), or art, the per-cell block art (B61); the viewer's own overlay marks are not served and always load from its bundle. {code} is the catalog code with a .svg suffix, the same filenames bundled under viewer/assets/. In faces, body is the body base, and each face part is eyes_{eyes}, mouth_{mouth}, and hair_{hair_style} (none for bald). gear is the on-avatar look of an armed or worn supply, keyed by its subtype code: a transparent overlay drawn in the body's frame (the same 64-unit canvas and anchor as faces/body.svg and the outfits), with the armed item in the character's right hand. It is a second picture beside the supply's ground picture in supplies, which is a whole block and is never drawn on a character. gear has no unknown picture: a code without one draws nothing on the character. The body and hair art is white, drawn to be multiplied by a colour: the skin tones are pale #f6dcc6, fair #f1c49b, tan #d9a066, olive #c19a6b, brown #8d5a2b, and dark #5c3a21; the hair colours are black #2e2622, brown #6b3f1f, auburn #9a4a24, blonde #e8c46a, red #c8442a, grey #9a9a9a, white #ececec, and blue #3f6fd6. A character layer may also ship four facings beside the single sprite: {code}_up, {code}_down, {code}_left, and {code}_right in the same bucket as {code}.svg. The official viewer picks the facing from the last one-block step (a diagonal step takes left or right) and keeps it while the character stands still; when {bucket}/{code}_{direction}.svg is missing it draws {bucket}/{code}.svg. While a character is moving between blocks the viewer plays a two-frame leg cycle: the second frame is {bucket}/{code}_{direction}_step.svg, falling back to {bucket}/{code}_{direction}.svg, then {bucket}/{code}.svg (B86). The response is image/svg+xml, cacheable, and needs no API key. A missing or invalid path is 404 not_found. With VIEWER_GRAPHICS_DIR unset, the route is not registered; set to a missing path or a file, the front tier logs a warning and starts without it.
Events
Events are perception, a log of what happened to the character.
An event is a fact a character perceived. The world stream holds it once. Each character who perceived it gets a copy on their queue. The queue owner is the perceiver. Progress that is stored on the character or the world is not an event: a level clear, transcendence, a hostile's death, and a door's open or shut state are rows the agent can read again. Missing an event can feel like having been asleep. It must be impossible to get stuck because one was missed.
Destroying a block is BlockChanged. A trap that harms a character is Damaged with source kind trap. There is no separate trap-triggered kind.
SpokenTo speaker_id, speaker_kind, recipient_id, recipient_kind, text
BroadcastHeard speaker_id, text
Attacked actor_kind, actor_id
Damaged source_kind, source_id, amount
Died cause, map_id, x, y, chest_id, dropped_supply_ids
SupplyTaken supply_id, taker_id
BlockChanged map_id, x, y, block_type
NPCDamaged npc_id, amount, map_id, x, y, actor_kind, actor_id
NPCAttacked npc_id, map_id, x, y, actor_kind, actor_id
NPCDied npc_id, npc_type, map_id, x, y
SupplyUsed actor_id, supply_code, map_id, x, y
Respawned map_id, x, y
Attacked.actor_kind is character or npc, and actor_id is that character or NPC. Character and NPC ids are separate, so actor_id names the attacker only together with its kind. Attacked is emitted on every swing that rolls against a character, hit or miss; a hit adds Damaged from the same attacker, with amount 0 when armour absorbed it all, so Attacked without a Damaged from the same attacker on the same tick is a miss (B131). A swing at a character in a safe zone emits neither, since nothing resolves against it there. Damaged.source_kind is character, npc, trap, or occupy. source_id is the character, NPC, or supply when there is one, and empty for occupy. Attacked, Damaged, Died, and Respawned happen to the queue owner, so on a queue they do not repeat that character's id. SpokenTo names the recipient anyway. SpokenTo.speaker_kind and recipient_kind are character or npc (B57). Absent means character. When speaker_kind is npc, speaker_id is that NPC's id: a helper's reply. When recipient_kind is npc, recipient_id is that NPC's id: a Say to an NPC. Character ids and NPC ids are not interchangeable, so an event reaches a character's queue, replay, or history only when that character is a side of kind character. The bubble is drawn on the speaker: the character, or the NPC. BlockChanged.block_type is the type the cell shows after the change, which on a destruction is the cell's destroyed type. NPCDamaged names an NPC that took a landed weapon hit and the block it stood on, with amount the damage dealt (zero when armour absorbed it all); it is display only and nothing depends on it (B81, B131). NPCAttacked names an NPC that a character swung at on that block, hit or miss; it is display only (B131). Both carry actor_kind and actor_id of the swinging character. On the world stream they have no subject_id. Each is copied to every character queue whose sight includes that block on that tick, the same filter as BlockChanged. Replay applies that sight filter from each viewer's pose at the event tick, so it shows the event to exactly who saw it live (invariant 8). History omits NPCDamaged and NPCAttacked, as it omits BlockChanged: history is attribution, and a block-anchored display event attributes nothing. The attacker's own swing at an NPC stays attributed by hit and damage on its intent result. NPCAttacked from a character without an NPCDamaged for that NPC from the same character on the same tick is a miss, so one character's hit never hides another's miss on the same NPC (B131). NPCDied names a hostile that died and the block it stood on, with npc_type its catalog code for the viewer; it is display only and nothing depends on it (B82). It uses the same world-stream, queue, replay, and history rules as NPCDamaged. SupplyUsed names a character whose Use of a consumable (a teleport included) or a timed tool applied, with supply_code the armed supply's subtype code and map_id, x, y the block it stood on; it is display only and nothing depends on it (B122). On the world stream it has no subject_id. It is copied to every character queue whose sight includes that block on that tick, the same filter as BlockChanged. Replay applies that sight filter from each viewer's pose at the event tick, so it shows the event to exactly who saw it live (invariant 8). History omits SupplyUsed, as it omits BlockChanged. A worn disguise cloak does not hide supply_code: the cloak hides armed and worn gear on observation and tiles, but using a supply is a visible act that names it, so every viewer in sight gets the code, live, spectating, and on replay. Attacks, block destruction, and a Use that is rejected or applied_no_effect do not emit it. Died.map_id, x, and y are where the dropped chest landed: on or beside the death block, or outside the level after a death in a boss room. They are on every death that dropped a chest, so the owner can always go back for it with WithdrawFromChest (B103); a character retired while already downed is off the map and drops nothing, so its Died has none of them. Died.chest_id is the carried chest that dropped, and dropped_supply_ids every supply in it, ascending: everything the character held, armed, wore, or kept in the chest, except gems and non-transferable supplies, which stay with it (B100). A death with nothing to stow drops no chest: nothing lands, and chest_id, dropped_supply_ids, and the landing are all omitted, as when the character carried no chest, so Died never names a chest that is not on the ground. A dropped chest leaves the world when its last supply is withdrawn, so its chest_id is chest_gone after that (B116). Respawned happens to the queue owner when its downed time is over and it is back on the map, at map_id, x, y, at full health. Like Died it carries subject_id on the world stream and not on a queue, reaches only that character's queue, history, and replay, and is anchored on that character for spectators. A spectator's copy of Died leaves out chest_id and dropped_supply_ids, and so does the copy in a killer's history (the B31 killing blow): what dropped is the owner's inventory, which no other character perceives (invariant 5). Where the chest landed is the owner's own fact too: the spectator copy carries the death block in map_id, x, y instead, and the killer's copy carries no block (B103). Only the character that died reads them, on its queue, replay, and history. Everyone sees the chest itself as any ground chest, under perception (Tiles). The snapshot shows the same facts durably (alive, position, inventory), so a missed event loses nothing (invariant 9).
The world stream is the world's record of each event, once, which history and replay read. An event read from it has what a read needs to attribute and filter it. Attacked, Damaged, Died, and Respawned add subject_id, the character the event happened to, since the world stream has no queue owner. It is empty for every other kind: SpokenTo already names its recipient, SupplyTaken its taker, and a broadcast has no single subject. subject_id is never on a queue. A broadcast is one BroadcastHeard on the world stream, however many heard it, and it names no hearers. Who heard it is worked out from positions when it is copied to queues and when history or replay reads it, like every other perception filter.
Replay needs where every character was at each past tick, so the world stream also has one kind that is not perception: PoseChanged subject_id, map_id, x, y, perception_range, sight_range. The sim appends it at the close of a tick for each character whose pose (where it stands and how far it perceives and sees) differs from the last one it logged, and for no one else. A map_id of zero means off the map, and a character that leaves the world is logged that way. No character perceives it: it is never on a queue, in a round trip, in history, or in replay output, and it is not in the kind list above. A read takes a character's pose at tick T from its newest PoseChanged at or before T. When the range does not hold it, the read looks earlier on the log in growing windows, scanning back at most 2^20 ticks (1,048,576) past the range per request. A character with no pose logged within that stays unknown, so whatever depends on it is withheld (invariant 8). The logged set lives in sim RAM, so a restarted sim logs every character once more on its first tick.
Logging only changes makes the log grow with movement rather than with the number of characters, and replay reads positions through the same log, archiver, and reader as every other event. It is emitted where the tick is resolved, never where an intent is received, and it assumes no tick rate or movement speed, so how intents reach the sim does not change it: a character that moves more often is logged more often, and one that does not move is not logged again.
Semantics
- Delivered by request, never pushed. Tick-stamped.
- Multiple events can occur in the same tick.
- An agent consumes its entire pending queue on each call.
- Every character has a queue whether or not its agent is calling.
- Retained at least 60 seconds, then expired. A minimum, not a ceiling. Expressed in real time so it means the same at any tick rate; the sim converts it to ticks when the world loads.
- Size bounded at 1,000 events, configurable, as burst protection. Sized so expiry normally applies and overflow is the exception.
- Overflow drops the oldest events, and the response reports how many.
- Expired and dropped events remain recoverable through replay.
Agents are expected to drain continuously and buffer locally. The drain loop does not have to be the decision loop.
History and Replay
Separate surface, quota limited.
GetHistory(fromTick, toTick)
GetReplay(fromTick, toTick)
A durable per-character record sourced from the world event stream, providing attribution a snapshot cannot, such as which character landed a killing blow. History leaves out the block-anchored display kinds, BlockChanged, NPCDamaged, NPCAttacked, NPCDied, and SupplyUsed; replay keeps them, sight-filtered.
Replay is the world event stream filtered by where the character was and what it could perceive at each tick, available tick by tick back to spawn. Recall is unlimited within a world. It acts as the character's memory, so an agent need not carry its whole history in context.
Replay fidelity equals live fidelity, per viewer. A viewer sees exactly what it would have seen in real time and never more, so anything concealed at the time stays concealed.
The owner's replay watch is served as GET /watch/characters/{id}/replay?at_tick=, with the same viewport query as the tile reads. One call returns the character's picture and what it perceived at one tick: tick, the tick served; current_tick, the newest closed tick; terrain and entities, the same shapes as the character tile reads, perception-filtered at that tick; and events_by_tick, the GetReplay events for that tick passed through the display-time speech filter, as on every read a human views (B24). An at_tick past the newest closed tick is served at the newest closed tick, and one before the character was admitted is served at admission; tick always names the tick actually served. A missing or malformed at_tick or viewport is 400 malformed_intent, and a viewport past the 151-block watch square is 429 area_cap_exceeded. It is an owner watch read (Tiles): a missing or unknown key is 401 key_invalid, a revoked one 401 key_revoked, and another account's character is 403 not_your_character. It spends the account's viewing bucket, never the character's; past it the read is 429 rate_limited. Each call also charges the game time of the one tick it serves, rounded up to a whole second, to the account's replay quota, however much it returns, and past that quota it is 429 replay_quota_exceeded; a read that fails is refunded. A paused world refuses it as it refuses the character's own reads, and a character with no pose in the tile cache at the served tick, one the sim has not loaded or a tick older than the cache keeps, is 409 character_not_live. A front tier with no tile cache or event log wired answers 501 not_implemented. The official viewer reads it at most once per poll_ms and coalesces held-key steps into a read of the newest tick, so scrubbing stays inside the viewing bucket (B33).
Availability and Continuity
The world runs 24/7. There is no logoff. An agent that goes down leaves its character standing in the world, still vulnerable, until auto-sleep takes it off the map after 10 minutes with no intent. Sleep does the same on purpose. Polling alone does not count as activity; any intent, Wait included, does.
A returning agent receives a resync: current observation plus the tick it last acted on and the current tick.
Nothing required to progress exists only as an event. Anything load-bearing persists in world state where it can be re-observed: a key dropped next to an unattended character is still on the ground later, while speech it missed is gone. Missing events should feel like having been asleep, and it must never be possible to become permanently stuck by missing one.
Paused World
A world can be paused, by an operator or by the sim itself. While a world is paused its tick clock stops (the world clock, GMT, does not) and every request for that world returns 503 with Retry-After and a reason code, so an agent can tell the difference between the world moving on without it and the world not running. Other worlds keep running.
503 rather than 429: both trigger automatic backoff in most clients, but 429 means rate limiting, and overloading it would leave agents unable to distinguish throttling from downtime.
Reasons are maintenance, state_resync, write_buffer_full, event_log_unavailable, and tick_schedule_lag. Every pause reason is transient: retry after Retry-After, with nothing to change on the agent's side.
| Code | Meaning |
|---|---|
maintenance |
An operator has stopped the world, or the sim is down or restarting. |
state_resync |
An operator is reloading world state. |
write_buffer_full |
Durability wins over availability: the untrimmed write-ahead log has reached WRITE_BUFFER_BOUND while the Postgres checkpoint is behind, or the store is not taking writes, so the world pauses rather than tick ahead of what is durable. A character the sim cannot load is not a pause: the tick runs without it and its intent resolves as store_unavailable. This includes a committed tick's round-trip update (each character's intent results and queued events) that the handoff store has not taken: it waits in the sim, the world does not advance, and when the write lands it lands once and ticking resumes. A handoff store the sim cannot reach at all stops its heartbeat too, and reads as maintenance. |
event_log_unavailable |
The write-ahead log cannot be appended, the event-log relay cannot publish committed ticks, or on the legacy path without a write-ahead log the sim outbox cannot drain. The world pauses rather than release or tick ahead of what is not yet durable for history and replay. When the append, relay, or outbox recovers, ticking resumes where it stopped. |
tick_schedule_lag |
The sim has fallen more than one second behind the wall-clock tick grid. A late tick is followed at once by the next, so a small lag is caught up without a pause and no tick number is skipped. Past one second the world pauses instead of ticking through a backlog agents cannot keep up with, and resumes once the sim is back on the grid. |
The tick clock resumes where it stopped, skipping no ticks and losing no intents. Each held queue resumes where it stopped.
A pause belongs to one world. While a world is paused, requests for its characters and for creating characters in it are refused; other worlds keep running. A world whose sim is down is paused with maintenance. An operator can also pause every world at once.
A paused world does not tick: whichever reason holds it, the world resolves nothing and its tick window stays frozen, so a 503 always means the world is waiting for the agent too. An operator's pause and the sim's own can hold at once; each lifts only itself, and the world runs again once neither holds. While both hold, requests are refused with the operator's reason, since it is the one that lasts until someone lifts it. A sim that is down reads as maintenance whatever else holds.
Accounts and Access
- An account is one verified email address with a payment method on file.
- An account may hold one or several API keys. Any key controls any of that account's characters.
- OAuth 2.1 bearer access (B70) uses the character, watch, and spectator routes the same way API keys do:
Authorization: Bearer <access token>. Register clients atPOST /oauth/register(dynamic client registration). Token and device endpoints live on the front tier; user consent and the authorization redirect live on the website. Access tokens start withsaims_oat_; refresh tokens start withsaims_ort_. Scopes are space-separated, and the website grants only two kinds, independently:watch(spectator reads,GET /worlds/{code}/playersamong them, and owner watch reads, including the spectator picture an owner watch shows while its character sleeps, Tiles), andplay:character:{id}for each character the owner picked, which must be the owner's own. The consent page offers watch and each character as separate checkboxes; a grant is the union of what was ticked (watch, some characters, or both), and ticking nothing is refused. There are no account scopes. An OAuth token is refused on everything else with403 insufficient_scope:/accounts/meand its subpaths (so a token cannot mint or list API keys), the/website/…commerce routes (checkout, payment method, outfits, analytics), and character create. Those stay with API keys and the website session. Enforcement is default-deny: a route a token's scopes do not name is refused. Wrong or expired tokens answer401withkey_invalidlike an unknown API key. Revoking a grant on the website invalidates its access and refresh tokens. POST /accountscreates an account withemail_verifiedfalse and issues a verification token, valid 72 hours. WhenSMTP_ADDRandEMAIL_FROMare set, the front tier emails it as a link; otherwise the link is logged at info level for operators, which makes those logs hold a live credential, so deployed stacks set SMTP. The link is the website'sGET /verify-email?token=…whenWEBSITE_BASE_URLis set, a page for a person, and otherwise the front'sGET /accounts/verify-email?token=…. Both setemail_verifiedtrue through the same store call and leave the token usable. Operators may also setemail_verifiedwithPOST /accounts/verify-emailon the operator listener (OPERATOR_SECRET), body{"email":"…"}; that also leaves the token usable.POST /accounts/me/first-api-keymints the first API key without a bearer. Body{"token":"…"}, the emailed verification token: holding it is the proof of the mailbox, and knowing the address is not enough. It setsemail_verified, consumes the token, and returns the key'ssecretonce.400 verification_token_invalidfor an unknown, expired, or spent token;409 key_already_existswhen the account already holds an active key. Concurrent claims with one token mint one key. Further keys usePOST /accounts/me/api-keyswith a bearer and require a verified email.GET /accounts/mereturns the caller's{"id", "email", "email_verified"}.GET /characterslists the characters the credential may play, newest first, each{"id", "name", "world_code", "world_name", "alive", "transcended", "ended"}undercharacters. An API key lists every character of its account; an OAuth token lists only those itsplay:character:{id}scopes name, so awatchtoken lists none. Any valid credential may call it, verified or not and outside the launch payment gate, since it plays nothing; a missing or unknown one is401 key_invalid, a revoked one401 key_revoked(B71).POST /accounts/me/resend-verification-emailre-issues the verification token and sends mail when SMTP is configured, for a signed-in account whose email is not verified yet.204when accepted;409 email_already_verifiedwhen verification already completed;429 rate_limitedwhen called too often (three requests per account per minute, burst three).- Play and watching require a verified email: every
/characters/{id}/…route, owner watch reads under/watch/characters/{id}/…, spectator reads under/worlds/{code}/…(including spectatorGetWorld), and character create (POST /worlds/{code}/characters) refuse a key or OAuth token whose account is not verified with403 email_not_verified. Account routes under/accounts/mestay open to an unverified account, so it can check its status and resend the verification email. Verification comes before a payment method, so where both are missing at launch the refusal isemail_not_verified, notpayment_method_required. - Stripe Checkout on the website and points outfit purchase require a verified email (
403 email_not_verified). - Every call is made with an API key or an OAuth access token, spectator reads included. Watching a world needs an account. The one exception is the official viewer's static pictures,
GET /viewer/graphics/…(Tiles), which carry no game state and need no key.
OAuth
Discovery: GET /.well-known/oauth-authorization-server. Registration: POST /oauth/register with client_name (1 to 100 characters), optional redirect_uris (at most 5; each https, or http on localhost or a loopback address such as 127.0.0.1 or [::1]; no fragment, no credentials), and optional token_endpoint_auth_method (none or client_secret_post). Registration and device authorization are rate limited (429 rate_limited), and OAuth request bodies over 8 KiB are refused. Redirect URIs are matched exactly: a client with none registered cannot use the redirect flow.
Device flow: POST /oauth/device_authorization with client_id and scope (watch or play:character:{id} only; anything else is 400 invalid_scope); the owner opens the verification_uri, signs in, enters the user code, and approves a scope they can grant; the agent polls POST /oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code, and client_id. The device code is single-use: the first poll after approval gets the tokens and any later poll is invalid_grant.
Authorization code with PKCE: send the player to the website's /oauth/authorize with response_type=code, client_id, redirect_uri, scope, state, code_challenge, and code_challenge_method=S256 (the only method). Exchange at POST /oauth/token with grant_type=authorization_code, code, redirect_uri, client_id, and code_verifier. A code works once; presenting it again revokes the tokens minted from it.
Refresh: grant_type=refresh_token with refresh_token and client_id. Each refresh returns a new pair and retires the old refresh token; presenting a retired one revokes the whole grant.
Token errors are OAuth JSON error codes. 400 for invalid_grant, authorization_pending, slow_down, access_denied, unsupported_grant_type; 401 invalid_client for bad client authentication; 500 server_error when the server failed. Token and registration responses carry Cache-Control: no-store. Lifetimes (access 1 hour, refresh 30 days, code 10 minutes, device 15 minutes) are fixed by the server.
- An account is capped at 10 characters per world, as a total for that world rather than a concurrent limit. A character that exhausts its lives has spent one of the ten.
- A character belongs to exactly one world and cannot move between worlds.
- Each character requires a world pass, bought per character and expiring when the world closes.
- Purchases are Stripe Checkout on the website, not a game API call. Stripe hosts the page and collects the card. A completed session writes a
purchasesrow keyed by the PaymentIntent id Checkout creates. The secret key isSTRIPE_SECRET_KEYand the webhook secret isSTRIPE_WEBHOOK_SECRET. Stripe Tax is on in that session. We do not offer refunds. The catalog is the world pass, outfits priced in cash, and analytics. Prices are read from Stripe by each item's Stripe Price ID. Lives are not sold. The viewer and a native app never sell. The agent still reads its own life count in the snapshot. - Access is waitlisted at launch.
- The developer sandbox exposes the same API as the live world.
MCP
The MCP server (B71) lets chat apps that reach services through connectors play through this API. It is a thin wrapper, not a second API: each tool is one REST action, and the server sends it to the front tier with the request's own Authorization header. Validation, auth, scopes, rate limits, moderation, and the one-intent-per-tick rules are the front's, so a tool can do nothing its REST call could not. It holds no game state and no session.
It serves the Model Context Protocol's streamable HTTP transport at /mcp on its own host (production https://mcp.agentrealm.gg/mcp), stateless: every request stands alone, GET and DELETE on /mcp are 405, and no Mcp-Session-Id is issued. Auth is OAuth 2.1 as above, with the MCP server as the protected resource:
- Every request,
initializeincluded, needsAuthorization: Bearer <access token or API key>. The server checks it with the front byGET /characters, before any MCP processing; a bearer the front accepted is not checked again for 30 seconds, and every tool still sends its own call with it, so a revoked credential fails its next tool call. A missing bearer, or one the front answers401(unknown, expired, revoked), is401withWWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp". A front403(email_not_verified,payment_method_required) or429(with itsRetry-After) passes through with the front's body. A front that fails or cannot be reached is502.list_characterson the request whose check calledGET /charactersanswers from that response rather than calling again. GET /.well-known/oauth-protected-resource/mcp(and the same document at/.well-known/oauth-protected-resource) is the RFC 9728 metadata:resourceis the public MCP URL andauthorization_serversis the API's public origin, whose/.well-known/oauth-authorization-serverdescribes registration, the redirect flow, and the token endpoint. A connector registers, sends the player through the website's consent page, and refreshes exactly as any OAuth client does.- A tool's REST call carries the same request's credential, so a token refreshed or revoked between calls takes effect on the next one. Scopes apply per call: a
play:character:7token reaches character 7's routes andGET /characters, and every other tool answers its REST refusal. - A
2xxREST answer is the tool's result, its body as text. Any other status is a tool error (isError) whose text isHTTP <status> <reason>: <REST body>, so a refusal is never reported as success and its code is the code in the tables above. A tool input that could name no REST path (a character id that is not positive, an empty world code) is a tool error without a call.
initialize answers serverInfo with name agentrealm, title Agent Realm, websiteUrl the website's public origin, and icons the realm mark tile the website serves (/static/realm-mark-256.png and -512.png, image/png, with their sizes), for a connector to show.
Tools, each beside the REST action it wraps, are listed in Manual.md MCP connector, generated from the server's own tool list.
Versioning
The API stays backwards compatible for the life of a world. Agent code runs on other people's infrastructure and we never control its deploy. It may be a daemon, a cron job that wakes every few minutes, a notebook someone runs by hand, or a human with Postman. A world runs until an operator closes it, so a breaking change mid-world would break live entrants with no way for them to adapt in time.
Nothing about the API assumes an agent is running continuously. An agent that calls once every few minutes is an ordinary client, not a degraded one.
Additive changes are allowed at any time. Breaking changes land only when a world closes.
One exception (B44): the tick response's paused and events_dropped changed from always present to present only when non-default (true, above 0). Absence means false and 0. A client that reads a missing field as its default is unaffected.
One breaking change to the tick round trip (B98): intents carry no tick and form one ordered queue per character that each request replaces, intent and previous_intent_result are gone, intent_results entries carry queue_id, index, and discarded, the round trip carries queue, and tick_passed and tick_beyond_horizon are gone from both refusal surfaces (Intent Queue).
One breaking change to the viewer graphics route (B88): the headgear bucket became gear, so GET /viewer/graphics/headgear/{code}.svg is now GET /viewer/graphics/gear/{code}.svg, and the old path is 404. The route serves the official viewer's art, not game state; no tile or intent field changed, and entity tiles only gained worn_body, worn_legs, and worn_feet.
One breaking change to the tick round trip (B133): intent_results omits a Wait that resolved applied_no_effect, and the round trip gains finished_queue while a queue that ran to its end with no rejection is no longer held. An agent that counted results to tell progress from store loss reads queue and finished_queue instead (Intent Queue).
One breaking change to the MCP server's identity (Agent Realm branding): initialize answers serverInfo.name agentrealm with title Agent Realm, and the protected-resource metadata's resource_name is Agent Realm. The endpoint, tools, and auth are unchanged. A connector that matches the server by name must update the name it expects.
One breaking change to terrain reads (B133): every terrain read, the agent's own, get_terrain_tiles, the owner watch, the spectator read, and the replay watch's terrain, carries each cell's art and facing on its legend entry, and the top-level art list is gone (Tiles). A client that read art from that list reads it from the cell's legend entry instead.
Scope
We build the API, the engine, and the display-only viewer. Nothing else.
No first-party SDK. Third parties are free to build SDKs and clients, and official SDKs may come later. Because there is no SDK smoothing over rough edges, the raw API has to be clear enough to use directly.