Schema reference#

Every closed set, every constant, every validation rule and every bound this world enforces, in one place. The other documents describe the shapes — a design has parts, a part has a primitive and a material. This one says which primitives, which materials, how long a name may be and what happens at the edge, so that a person, a script or a language model writing into this world can know rather than guess.

Every value here is the one the server actually enforces. Where more than one door checks the same thing, they are held to the same figure and the same words.

How to read this page#

Three refusal styles appear throughout, and they are not interchangeable:

• Refused as a value. A validator returns a list of problems, or a call returns nil, reason. Nothing throws. This is how designs, filesystem calls and script starts fail.
• Refused as an error. The action comes back as action_result with Success: false and an Error string, or a JSON-RPC error.
• Dropped. The value is ignored and the rest proceeds. This is deliberate for AI output: a brain that returns one nonsense action still gets the other seven carried out.

The wire format itself#

One serialiser serves the WebSocket and the world's own storage, so a component stored and the same component sent cannot disagree about their shape.

That rule is the socket's and the database's, and nothing else's. Three other JSON surfaces exist and all of them are camelCase:

GET /designs/{id}/visual.json is the exception to that exception: it is PascalCase, because it is not a description of a design but the design's own geometry exactly as the socket sends it. The browser module that draws the catalogue's patterned preview is the one that draws the world, and giving it a second spelling of the same document to read would have been a second shape to keep in step.

/events shows the double form simulated time takes outside the socket: atTicks is the number, and at is the same moment written for a person, as T+1d 14:24:33. Only the ticks are worth parsing.

Identifiers on the wire#

OwnerId accepts four kinds when parsing — world, player, agent, group — but nothing in a running world issues a group owner today; it exists so the identity can carry one without a storage migration. world: with a GUID is refused: the world's owner id is the bare word world and nothing else.

Closed sets#

Every set in this section is exhaustive. A value outside it is refused, not guessed. The number column is the stored value; it is not what travels.

AccessSubject#

What an access change is about: a thing, or the ground.

AccessSubjectKind#

Whether an access change is about a thing or a piece of ground.

AffordanceAudience#

Which kind of client a verb belongs in front of.

A set of these is one value, written as the names joined with a comma and a space: Authoring, Everything. The numbers add up, and a named combination wins when one matches.

AgentState#

What an agent is doing.

AgentTrigger#

Why an agent is thinking now.

AssetMaterial#

The materials a definition may reference.

BiomeType#

The natural character of a piece of terrain.

ChatScope#

Who hears a line of chat.

ClaimRefusal#

The reason a claim was refused.

DesignSaveOutcome#

What became of a described design.

DesignSeverity#

How much a finding matters.

FileSystemError#

Why a filesystem operation was refused.

InputFieldKind#

The kinds of value the world can ask a person for.

LuaProcessState#

What a Lua process is doing.

NaturalObjectKind#

What kind of thing the generator placed.

OwnerKind#

The category of actor that can own something.

Permission#

What an actor may do with something.

A set of these is one value, written as the names joined with a comma and a space: Inspect, Use. The numbers add up, and a named combination wins when one matches.

PersistenceClass#

How much effort the world owes an entity's continued existence.

PrimitiveShape#

The shapes a procedural model is built from.

ReadoutKind#

How a readout is drawn above the thing carrying it.

ReadoutSource#

Where a readout's number comes from.

RefusalKind#

A refusal the caller is expected to finish in its own vocabulary.

RegionState#

What a region is currently costing.

RegionTransition#

Why a region changed state. Kept for the log, and for asking why.

RouteSeverity#

How much a thing found along a route matters.

ScriptError#

Why a script could not be started or run.

SimulationEventType#

The kinds of scheduled work the simulation knows about.

SimulationSpeed#

How fast simulated time runs relative to real time.

StartingCatalogue#

How much of the shipped catalogue a brand new world is given.

WorldEventKind#

The kinds of thing worth remembering happened.

Notes on particular sets#

The tables above are read off the world itself. What follows is what a table cannot say: where a set is used, and why it is shaped the way it is.

Permission: Handle is not Use#

Operating a thing and emptying it only ever looked like one permission by accident, and the difference is a security boundary. A claim can widen Inspect and Use over anything standing on it — that is what makes a street walkable — but it widens Handle only over things belonging to the claim's own owner. If it widened everything, then since a player's body is property standing on ground like any crate, the flag that made a shop walk-into-able would be the flag that emptied its visitors, in both directions. transfer_items and exchange_items need Handle on both ends.

Seven of the nine can be handed out. The grantable set is Inspect, Use, Build, Modify, Destroy, Program and Handle — Transfer and Control are not grantable, and nothing in that list lets the grantee grant on.

Three spellings exist for the same set, and they are not interchangeable:

PersistenceClass decides how a thing is removed#

It is the only thing that does: Aggregatable is felled with remove_natural, which writes a row saying it is gone; everything else was built and is taken down with demolish_entity, which deletes the rows it had. The affordance the server advertises on an entity is already the right one of the two. Over MCP the same pair is world_clear_natural and world_demolish, reaching the same two methods.

RefusalKind is never on the wire#

It rides beside the reason inside the server. The world decides which of the two removals applies — by PersistenceClass, in one place — but the action it should have been is called remove_natural over the socket and world_clear_natural over MCP, and the world knows neither name. So it states the fact and tags it, and each door appends the pointer in the words its own caller can act on.

DesignSaveOutcome is a word on the wire#

Never a number: MCP answers with the lowercase word in outcome, and the socket's action_result.Design.Outcome carries the same word, plus deleted for the action that removes one. Which applies depends on facts only the server holds — whether the design exists, whose it is, whether anything stored was built from it — so a caller reads the word rather than predicting it.

unchanged is the one that can answer about a design under a different name from the one asked for, because what a design is decides and the name does not. The MCP answer then carries nameAsked alongside name, so a caller can see that the name it asked for was given to nothing.

ReadoutKind and ReadoutSource describe a caption, not a fact#

A readout is what a thing shows above itself, and nothing in the world ever reads one back: the simulation does not consult a caption to decide anything, and taking one down changes nothing but what is drawn.

ReadoutSource is the half worth understanding. Everything but Given names a number the world already keeps and already sends — health, a battery, how grown something is — so a bar bound to one is true for ever with nobody maintaining it, and costs nothing on the wire because those components travel anyway. A source the thing does not carry is refused rather than stored, because a bar that could never move is worse than no bar. Given is a number of the author's own, stored as a value, a rate and a moment, so a bar that empties over the next half minute is one row that nothing ever touches again.

A design may bind a reading only to a number it would itself be allowed to declare, which is why energy may appear in one and health and growth may not — the same two sentences that refuse those components refuse a reading of them.

OwnerKind is part of the identity#

A player and an agent that happen to share a GUID are different owners, and a permission check never conflates them. Nothing in a running world issues a group owner today; the kind exists so the identity can carry one later.

NaturalObjectKind and its variant#

Variant beside it is a kind-specific sub-type — a tree species, or a rock shape — and is an open integer, not a set.

WorldEventKind at the endpoints#

GET /events returns these as the kind field of each entry; it has no filter of its own. The MCP world_history tool's kind argument matches them, and does so case-insensitively. The list is short deliberately: a log that records everything is one nobody reads.

ClaimRefusal is all or nothing#

A request naming any chunk somebody already holds is refused entirely; claims are never partially granted.

AgentState and AgentTrigger as a brain sees them#

agent_list carries the state as a plain string field, not as an enum, but the spellings are the same. The trigger is the value a Lua brain reads as world.trigger: an agent is never woken because a tick passed, and naming the reasons is what makes that rule visible.

SimulationSpeed is the multiplier#

The number is the multiplier, which is why Paused is naturally zero. simulation_control carries the integer, not the name. There is one clock for everybody: a client cannot run its own world faster, only a connection from the machine the world runs on may change it, and when somebody does every connected client is told.

AccessSubject and AccessSubjectKind#

Two names for the same distinction, one on the server and one in the agent action set. Letting somebody build in your town is not letting them into your house: over someone else's property standing on your land, a claim can widen access to Inspect and Use and no further.

InputFieldKind serves two askers#

An affordance the server advertises on an entity may need values before it can be sent; a question something in the world has put to somebody may collect values beside the choice. Each field says what kind of thing it is so a client can draw the right control, and one client control serves both. Permissions is the server's own, written on an affordance it composed itself; a question raised from a script may ask only for Text or a Number.

DesignSeverity and the finding codes#

The finding codes themselves — vanishing, enormous, crack, buried, detached, protrudes, headroom, hovers, limb_missing — are listed with their thresholds under design review thresholds.

FileSystemError and ScriptError in Lua#

Both come back as the second value of a Lua call — nil, reason — and are never thrown. TooLarge is the file or script size limit, TooManyFiles and TooManyProcesses the counts, each listed under numeric bounds.

SimulationEventType is the scheduler's own#

Nothing outside the server can name one and none of them appears on the wire, but it is a closed set worth knowing exists: content that scripts and blueprints invent arrives as ScheduledAction carrying its own payload, so new content never needs a new event type.

Open sets, and the rules that replace enumeration#

Four vocabularies in this world are deliberately not closed. Listing them would be a lie, because the whole point is that a design, a script or an agent can introduce a value nobody wrote down. Each one has a rule instead, and the rule is enforced.

The type is a label for querying and presentation. Behaviour comes from components, so adding a type never means adding a code path — which is exactly why it cannot be an enum.

The semantic tags a character is expected to carry#

The tag is a free string; these are the names the generator writes and the animator looks for, gathered in one place so the two cannot drift apart over a typo.

Required for a character — the seven a figure needs at minimum: root, torso, head, upper_arm_left, upper_arm_right, upper_leg_left, upper_leg_right. A design carrying torso and head and at least one of the eight limb names is treated as a character, and the review reports each of the seven it is missing as a limb_missing note. A four-legged survey robot with a torso and a head but none of the limb names is left alone, because it is exactly as intended.

The limbs an animator swings: the eight upper_/lower_ names above.

Registered component names#

The stable names components are stored and sent under, and what each one carries. The names are part of the storage contract and may not change once a world exists, and a name not in this list is refused on the way in rather than ignored: silently dropping a component would corrupt an entity on the next save. Every field is written exactly as it is named here, inside the component's own JSON, wherever an entity is described; a field marked derived is worked out by the world and sent, and is never read back.

computer#

A virtual computer's capacities.

energy_consumer#

Something that draws power.

energy_producer#

Something that generates power.

energy_storage#

Stored energy, computed analytically rather than ticked.

group#

Marks an entity as part of something bigger.

• MaxTagLength = 32 — Longest a piece's tag may be.

growth#

Growth over simulated time, computed analytically.

health#

Damage state.

interactable#

Says that something can be used, and what to call it.

• MaxVerbLength = 24 — Longest the verb may be.
• MaxHintLength = 96 — Longest the hint may be.

inventory#

What an entity is carrying.

• MaxItemNameLength = 48 — Longest an item's name may be.

movement#

The ability to move, and the current intent to.

• DefaultWalkSpeedMetersPerSecond = 1.4 — A comfortable walking pace, and what a body gets when its design forgot to move.

ownership#

Permissions the owner has granted to others.

part_state#

The parts of a built thing that are not as they were designed.

• MaxParts = 128 — How many parts of one thing may carry state.

physics#

Weight: the thing that makes an unsupported object fall.

• EarthGravity = 9.81 — Earth's, near enough, and the default when a design says nothing.

readouts#

What a thing is showing above itself.

• MaxReadouts = 4 — How many readings one thing may show at once.

script#

The script an entity runs.

• MaxPathLength = 256 — Longest a script's path may be.

sensor#

The ability to detect nearby entities.

transform#

Where an entity is. Every entity has one.

visual#

How an entity should be drawn.

• MaxVisualKeyLength = 64 — Longest a visual key may be.

water#

Held water.

Shapes inside components#

The objects the component fields above are made of.

PartColour#

A colour a design chose for itself.

PartMotion#

A number that goes on changing by itself.

PartState#

What has been done to one part of a design.

Readout#

One reading shown above a thing in the world.

A blueprint may not carry transform: it is set when the entity is spawned, and a blueprint that names one is refused.

Ten of them may be declared by a design somebody wrote — computer, energy_consumer, energy_producer, energy_storage, interactable, inventory, movement, physics, script, sensor — each within bounds. The other eight are refused by name, with a sentence saying why that one is not an author's to write. The rule is applied at the one place a design enters the catalogue, so it holds for every design that arrives from outside the server, whichever door it came through. The table in Blueprints has the figures and the reasoning.

Validated strings#

The values people get wrong. Every one of these is checked by allowing rather than by forbidding — a charset, not a blocklist, because blocklists get bypassed.

BlueprintId is not a validated string: it is a GUID, and a value that is not a GUID fails as JSON before anything sees it. The same goes for EntityId, AgentId, PlayerId, PlanetId and EventId.

Virtual paths#

VirtualPath is a security boundary, not a convenience. Every path reaching it comes from Lua or an AI agent.

/etc/passwd is a perfectly valid virtual path naming a file that does not exist. It has nothing to do with the host.

ScriptComponent.ScriptPath is checked separately and slightly differently at its own edge: ≤ 256 characters, must start with /, and may not contain .. anywhere in the string — belt and braces on untrusted input.

Numeric bounds and defaults#

Simulation limits#

These are the shipped figures. A world's operator may change them, and every answer that hits one names the limit it hit, so a world set up differently still tells you what it is holding you to. A world set up with impossible figures refuses to start rather than misbehaving later: every one must be greater than zero, and LuaInstructionSlice may not exceed MaxLuaInstructionsPerExecution, or the budget would never be checked.

An operator sets these under Limits in the server's configuration, by the same names, except that the two spans — the shortest think interval and the prompt lifetime — are given there in seconds. Every answer that hits one names the limit it hit, by the name above.

The prompt figures bound text that came out of a Lua script, a language model or somebody else's design and is on its way to a person's screen. A question is also cleaned exactly as a chat line is — formatting characters dropped, control characters and whitespace collapsed — and is refused outright if it contains < or >. There is deliberately no token bucket on questions: what makes a dialogue unwelcome is not having asked for it, and the rule that you can only be asked by something you have just used or just answered bounds that where a rate could not.

Chat limits#

A token bucket per account, measured against the wall clock.

Configuring agents to out-talk people is refused at startup rather than discovered when the public channel fills.

There is deliberately no cap on how many people hear a message. Nobody can address a list — public is "everybody the server chose", direct names exactly one participant — so a recipient cap would be a cap on how many people may stand in a town square together.

Account API limits#

Two more token buckets, keyed on the calling address rather than on an account — because the routes they guard are where an account comes from, and a caller there has nothing else to be known by.

Every field must be greater than zero, and the per-minute rates are whole numbers, which is what makes the refusal's "wait a minute" true whatever they are set to.

One more bucket has no setting, because its size is part of why an eight-digit code is safe and an operator lowering it would not see that argument: the whole world together may get 30 device codes wrong a minute, with 60 back to back, after which /api/devices/claim refuses everybody for up to a minute. A per-address limit cannot see a thousand machines guessing slowly; this can. Nothing else is affected — playing, signing in with a token and signing in with a passphrase all carry on — and no code is destroyed by it.

A malformed registration is counted, because otherwise the cheapest way past the limit would be to send rubbish. A refused sign-in is counted whether the token was wrong or absent, because a guesser learns the same thing either way.

An address is not a person: everybody behind one NAT shares a bucket, and anybody with a VPN or a cloud account has as many as they care to pay for. This is a speed bump against casual abuse and not protection against a distributed attacker. X-Forwarded-For is not read — it is a string the caller writes — and IPv6 is keyed on the /64. The WebSocket hello spends the same two buckets: a hello that registers an account is a registration and one that is refused is a failed sign-in, so the socket is not a second, unmetered door.

World settings#

Chosen by the world's operator when the world is made or the server started. These are the shipped defaults, and the ones a player or a client can notice; world_bootstrap and GET /world report the live values of the first five.

The grid sizes are properties of a world in the making: changing them for a world that already exists changes which chunk everything falls in.

MCP options#

Transport and request caps#

What a design may contain#

And the counts and lengths fixed in the design's own shape:

A validator reports every problem, not the first, because the author may be a language model that needs the whole list to correct itself. Nothing throws; refusals are values.

The three extent bounds are deliberately not one number, and they are checked against where a part ends up — parents, turns and ribbon paths applied — rather than against the offset it was written with. Sideways is half a chunk, because every index in this world is a grid in X and Z and widening a design widens every search that runs on every step a walker takes; upwards is a kibibyte of metres, because no index has a Y axis and the only real bound on height is what the client can draw. Something wider than one chunk is built as a composite of designs, each piece an entity filed in its own chunk.

Other rules a design must satisfy: a name; at least one part; unique part ids; a parent that exists and is not the part itself; no cycles; finite position, rotation and scale; a known primitive and material; a Surface naming a material the design itself carries; and Path and Draped only on a Ribbon, whose consecutive path points must be at least 0.01 m apart — two coincident points have no direction, and a client normalising one would divide by zero. An included design needs a blueprint id, a finite offset and rotation, and a tag of at most 32 characters.

Colour#

A part may name a colour of its own instead of taking its material's. Three numbers cannot reference a file, a shader or an asset, so there is nothing to ration here — the closed list bought no safety, and a world where anything can be made should not ration its colours.

Alpha defaults to 1.0. Values are linear, not sRGB, and unpremultiplied, so a design copying a named material's numbers gets that colour exactly.

Written by hand, a colour may be given as hex: #rgb, #rrggbb or #rrggbbaa, with or without the #. Any other length, or any non-hex character, parses as nothing rather than as a guess — red is three characters and would otherwise have been read as shorthand hex.

Surface materials#

A part may be painted with a small SVG drawing carried by its own design. The drawing is multiplied over the part's colour, so a white part shows it exactly and a coloured part shows it tinted.

Two materials with the same Id in one design is is carried twice.

The identity is a digest of the drawing's exact bytes, with no normalisation: the same drawing written by two people is one material, and whitespace that differs makes a different one. Callers do not compute it. A placeholder Id, used consistently by the material and by the parts that name it, is rewritten to the real digest before validation, by the one binding step both the socket and MCP go through.

What a drawing may contain#

SvgMaterial.MaxPerDesign, above, bounds how many of them one design may carry. Each refusal names the element, the attribute and the figure; the byte limit is checked before parsing.

The allowlist#

An allowlist, not a blocklist. A blocklist has to be right about every dangerous construct forever; an allowlist has to be right about the forty that draw a pattern, and everything invented after this was written is refused by default.

Elements. svg, g, defs, title, desc, rect, circle, ellipse, line, polyline, polygon, path, linearGradient, radialGradient, stop, pattern. Anything else: '<name>' is not an allowed element.

Deliberately absent, and why: script and handler execute; foreignObject embeds arbitrary HTML; image and use exist to reference something else, which is a fetch; style carries CSS and with it @import; text needs a font, and naming a font is naming something to load; filter, mask, clipPath and the animation elements are expensive, stateful, or both.

Attributes. id, viewBox, preserveAspectRatio, version, width, height, x, y, x1, y1, x2, y2, cx, cy, r, rx, ry, fx, fy, fr, d, points, transform, fill, fill-opacity, fill-rule, opacity, stroke, stroke-width, stroke-opacity, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-dasharray, stroke-dashoffset, shape-rendering, vector-effect, offset, stop-color, stop-opacity, gradientUnits, gradientTransform, spreadMethod, patternUnits, patternContentUnits, patternTransform. Anything else — every on* handler, style, class, href — is '<element>' carries '<name>', which is not an allowed attribute.

Attribute values. None may contain javascript:, data:, http://, https://, //, &#, < or expression(. url(...) may point only at a fragment of the same drawing: url(#name), where the name is letters, digits, _ and -. Anything else is referencing something outside the drawing.

Namespaces. SVG's, or none at all — a drawing written by hand without an xmlns is accepted, because that is the obvious thing to write and it is handed to the browser as SVG regardless. A prefixed namespace declaration (xmlns:xlink) is refused, which is how the old spelling of an external reference goes.

The document. The root must be svg and must carry a viewBox, so the drawing's own coordinates mean the same thing in every renderer. No DOCTYPE, no entity declaration or reference, no processing instruction (<?xml-stylesheet?> is a stylesheet reference with a different syntax), and no text content. Document type definitions are prohibited outright and nothing outside the drawing is ever resolved — which is the whole of the billion-laughs and external-entity defence, rather than a count of expansions.

A drawing that is not XML at all is the drawing is not readable as xml: ..., with the parser's own sentence, not an exception.

Where a pattern cannot be drawn#

/designs previews, the parts table and the PNG renders are flat shading and cannot show a pattern. They show the drawing's swatch instead: the average of its fills and stops, weighted by area where the shape says its area (rect, circle, ellipse) and counted once where it does not, with strokes at 15% of their weight. Read out of the text, never rasterised — the server does not rasterise anything a caller sent it — and the untrusted SVG is never embedded in a page the server serves.

Character proportions#

The shipped Settler, and every figure the world generates for itself, is built from six proportions rather than from measurements. Nothing you send names them — a character you design is parts like any other design — but they are why a generated person always stands up. Every field is clamped, never refused. A figure that asks for a head four times the body gets the widest head this allows and a character that still stands up; refusing outright would make one bad number lose the whole design. A value that is not a number is replaced with the default rather than clamped, because NaN has no nearest bound.

Clamping is idempotent: clamping a clamped set changes nothing.

Design review thresholds#

The review has no authority and refuses nothing — it is advice, and every check exists because that fault has actually happened here. These are the numbers behind the findings listed in BLUEPRINTS.md.

The 0.05 m² face requirement is why a settler's arm hanging beside its hip is not reported as a crack: two road slabs that fail to meet share half a square metre, an arm beside a hip a fortieth of one, and a page that cries wolf about eleven parts of a character is a page nobody reads.

Agent memory and history#

Writing a key with the value false removes it. Two key names are conventions the shipped brains agree on rather than rules: centre for a work site, and step for where a builder has got to.

Message and action vocabularies#

Client to server#

Discriminator property: "type". An unrecognised value is not ignored — it fails deserialisation, and the server answers error with Malformed message.

ProtocolVersion is 1. It is not a setting: a client either speaks it or is told so.

Omitting LoginName gives an anonymous session, which can watch the world, read designs and inspect things, and owns nothing. Anonymous sessions act as the world itself, which is why they cannot claim, build or design.

Actions inside action_request#

Discriminator property: "action", nested inside the Action object. Also fails deserialisation on an unknown value.

For the three access actions, naming Entity makes it about a thing and omitting it makes it about the claim covering At.

Server to client#

Discriminator property: "type".

PlayerSnapshot.Token is the one field omitted from JSON when null, and it is sent exactly once — at registration.

HTTP endpoints#

POST /designs/preview takes a JSON body of exactly the shape world_create_design takes — name, entityType, parts and materials — read by the same reader and refused in the same words, with the same 256 KiB body limit /mcp has. It saves nothing and never touches the world. With Accept: image/png, or with a view in the query string, the answer is a single PNG at 460 pixels (size=thumb gives 190); otherwise it is JSON carrying the design review and the drawn views, each as a data:image/png;base64,… URI. An unusable design is 400 with {"refused": "…"}; a body over the limit is 413.

It asks who is asking. Send X-World-Player and X-World-Token — the login name and token you were given when you registered, the same two headers the MCP tools take — or the answer is 401. Drawing a design is the most expensive thing this server will do for one request, so it is not done for a stranger, and it is rationed per address: too many and the answer is 429.

One view unless you ask for more. The JSON answer draws the isometric alone; ?views=all gives the set, and ?views=front,top gives exactly those. The answer names what it drew in drawnViews and what else there is in availableViews, so a caller that wanted the rest can ask for it.

MCP tools#

Every tool additionally accepts a session string (≤ 256 characters), and every tool's schema sets additionalProperties: false.

world_preview_design is the only tool that answers with more than text. Its result carries the front and top views as image content blocks — {"type": "image", "data": "<base64>", "mimeType": "image/png"} — after the text block, in both protocol revisions, which spell a content block the same way. They are drawn 256 pixels square rather than the gallery's 460, because an MCP result travels through a model's context: two views of a seven-part house encode to about 4.5 KB of base64. Giving both designId and parts is refused, and so is giving neither. Nothing is saved by a preview.

The acting tools below are offered only when Mcp:ReadOnly is false, and are refused if called anyway.

world_say and world_listen are refused for an anonymous connection: a line has to come from somebody the world can hold to it. Chat is rate limited per identity at the player rate, not the tighter agent one — an MCP caller is a player. An inbox holds at most 100 unread lines and drops the oldest beyond that, reporting the count as missed; reading consumes what it returns.

The three programming tools and world_machine each need Permission.Program on the named entity, judged by PermissionService exactly as program_entity, start_script and stop_script are over the socket. A written file meets VirtualPath parsing and VirtualFileSystem's MaxVirtualFileSize, MaxVirtualFilesPerComputer and capacity limits; a started script meets MaxLuaInstructionsPerExecution and MaxLuaProcessesPerComputer. Every answer reports those five figures back.

MCP callers identify themselves with the X-World-Player and X-World-Token headers, or by calling world_join. The protocol versions offered are 2026-07-28 (the latest), 2025-11-25 and 2025-06-18.

world_create_agent takes a brain in one of two forms and they are not interchangeable. brain is the name of one this server already carries — city, lua, dummy, as world_overview lists them. script is the Lua source of one the caller wrote, so a new kind of agent is a file rather than a feature. Sending a script makes the brain lua whatever brain said; sending neither is refused with a sentence naming both.

A script is measured, compiled and refused before the agent exists: over MaxScriptSizeBytes in UTF-8 bytes, or Lua that will not load, and there is no agent afterwards. What survives goes to /home/agent/brain.lua on the agent's own machine — an ordinary file, saved to the database with the machine, readable and replaceable afterwards with world_machine and world_write_script — and the answer reports that path back as brainScript. It then runs where every other script in this world runs: LuaSandbox, MaxLuaInstructionsPerExecution, and no second door into the scripting host.

A part in world_create_design#

The same shape is taken by world_preview_design and by POST /designs/preview, read by one reader for all three, so a part that previews is a part that saves.

This is the third spelling of the shape and material vocabularies — after the wire's exact enum names and the agent brain's forgiving one — and the one written for a model rather than for a compiler. Underscores are stripped and the rest is matched case-insensitively, so beveled_cube, BeveledCube and beveledcube are the same shape, and forest_grass is ForestGrass.

A field that is not one of these refuses the design, naming the part, the field and the ones it could have been. The same holds for capability and for the entries of materials, scripts, capability.stock and capability.shows: the schema these are published with says no other fields are accepted, and accepting one in silence would mean a design that quietly does less than it was written to do.

world_create_design, world_preview_design and POST /designs/preview also take materials: at most eight { name, svg } objects. The name is what a part's surface refers to; the identity a material really has is a digest of its own bytes, minted by the server, because asking a caller to hash its own SVG would be asking for a way to get it wrong. Two materials under one name refuses the design. The drawings themselves go to the same allowlist described under Surface materials, through the same validator a save runs — so a design that previews is a design that will save.

Refusing outright is the opposite of what the agent-brain reader does with the same two vocabularies, and deliberately so: a tool call can say what was wrong and be called again in the same breath, where an agent's thought cannot.

entityType must satisfy the EntityType rule and is otherwise open — house, lamp, bench and statue are as valid as the seven the world ships with.

Every MCP string argument is trimmed, and a string that is empty after trimming counts as absent rather than as an error — so a required argument given as " " is reported as missing. A control character other than newline or tab is refused outright. Where a tool takes an enum name, it is matched case-insensitively on purpose, so a model does not have to guess the casing.

What an agent brain may write#

A brain returns one table. Everything in it is treated as hostile: an action the reader does not recognise is dropped, a field of the wrong type is ignored, and nothing throws — a brain that returns nonsense gets a decision that does nothing, not a broken server.

Two caps apply in sequence, and they are different numbers. The reader keeps at most 64 actions from the returned table; the runtime then carries out the first MaxAgentActionsPerThought of those, eight by default. Everything past either line is dropped silently — not refused, and not remembered for next time. world.maxActions tells a brain the live value of the second one, so a well-behaved script can size its own list to match.

The fifteen action kinds#

The whole vocabulary an agent has. It is closed on purpose: a brain that may one day be a language model must not be able to name an operation nobody wrote.

The kind string is matched case-sensitively. "Move_Entity" is not move_entity; it matches nothing and the action is dropped.

An action whose required field is missing or unparsable is dropped whole.

Positions may be written either as at = { x, y, z } or as x, y, z on the action table itself. Both x and z are needed for a position to resolve at all; y defaults to 0. For spawn_blueprint, leaving the height out is meaningful: no height named means "stand it on the ground", and naming one means exactly that height.

For the three access actions, the subject is inferred rather than named: entity present makes it about a thing, and its absence makes it about the claim covering the position.

The design a create_blueprint describes#

Per part:

The silent fallbacks are deliberate: a design with one misspelled material is worth building with the wrong colour, and refusing the whole thing would make one bad word lose the design. The validator still has the final say on everything else.

A surface is the one field a part refuses the design over rather than falling back, and deliberately: a fallback would be a wall silently painted with nothing, which looks like a design that worked. The drawing itself is never checked here — it reaches the catalogue exactly as the script wrote it and is held to the allowlist, the size bounds and the element bounds by the same validator a browser's and a model's design meet, in the same words.

What a brain reads#

The world table passed to think(world) is built fresh each thought, from what the world knew at that instant. It is not the world global a computer script sees — a brain has no globals at all.

lastResults is the feedback loop. An agent that keeps being refused the same thing is a stuck agent, and this is where it finds out.

The Lua vocabulary#

What a program running on a machine in the world can call. Failures follow the Lua convention and return nil, "reason" rather than raising, because a missing file should not end a program. Full prose is in LUA_API.md; this is the value reference.

Query-shaped calls take an options table:

schedule.after(seconds, fn) and schedule.every(seconds, fn) refuse a non-function with schedule expects a function, a negative or non-finite delay with a delay must be a non-negative number of seconds, and anything past MaxScheduledEventsPerScript with this script already has 32 scheduled callbacks, which is the limit. every re-arms at no less than 0.001 s, and stops silently when its process dies.

events.on(name, fn) takes any non-blank name; there is no closed set, and 'chat' is a convention the shipped scripts follow rather than a rule. A blank name is an event needs a name. Three names the world itself raises: chat (scope, who, text, id), use (who, what) and answer (who, option, values, promptId).

world.ask(who, question, answers[, values]) is the world asking rather than being asked.

It answers with the question's id as a string, or nil, reason. The commonest reasons are they are not dealing with you… (nobody may be asked out of the blue), … is not standing within 8 m of this, and the bounds above.

world.carry(who) takes somebody who has just answered you wherever this machine is going, and answers with the travel time in seconds or nil, reason. There is no destination argument and there cannot be one: a thing may bring you to itself and nowhere else. It is spent by being used, so a second journey needs a second answer, and … has not agreed to go anywhere with this is what an unspent one says.

String constants a Lua caller must spell exactly#

The two permission vocabularies are genuinely different, and the narrower one is the deliberate half: the grantable set is seven permissions, so the agent action set has seven words. world.hasPermission only asks a question and can therefore afford to name anything.

Chat scope is not a string in Lua at all. It is chosen by which function is called: world.say is Public, world.sayNearby is Local, and world.tell(who, text) is Direct. All three go through the same rate limiter, and a script speaks at the agent rate — six a minute, burst of two — not a person's.

A chat line is cleaned before it is measured: Unicode format characters are removed, every control character and every run of whitespace becomes a single space, and leading and trailing space is dropped. The 240-character limit applies to what is left, so That is N characters; 240 is the most one message may be. counts the cleaned text and not what was typed.

Where the prose is#

This page is the values. What they mean, and why the world is arranged this way, is elsewhere:

• The world — time, people, ownership, land and permissions.
• Protocol — each message in context, and a worked session.
• Blueprints — how a design describes a thing, with examples.
• Lua API — what a program running inside the world can do.
• AI agents — how a brain is written, and what one is for.
• MCP — connecting a model to a running world.