Message reference#

Every message a client can send this server and every message the server can send back, field by field, with every shape those fields are made of. It is read off the server's own message definitions when the server starts, so what is written here is what the running server accepts and sends — a message kind or a field added to the server is on this page without anybody editing it.

The protocol page says how the messages are used together: how a session starts, what a client subscribes to, what an action's reply promises. The schema reference has every closed set a field can name, how identifiers and positions are written, and every bound the world enforces.

Field names are written exactly as they appear on the wire. Required is about the client writing the message: yes means the server refuses the message without it, no means it may be left out, and a default is what leaving it out means. A field marked derived is one the server computes and sends, and never reads.

Client to server#

Anything a client sends.

Each one carries "type": "…" naming which it is, spelled exactly as the headings below.

`hello`#

Opens a session, states which protocol the client speaks, and says who is playing.

Field	Type	Required	Meaning
`ProtocolVersion`	integer	yes	The protocol this client speaks. Must be 1; anything else is answered with an error and the rest of the message is ignored.
`Token`	string	no	The secret proving this account is yours. Given when the account was registered; omitted on a first connection, which registers.
`ClientName`	string	no, default `"unknown"`	Free text for logs, such as "Unity Editor".
`LoginName`	string	no	Stable account name. Null for an anonymous session.
`DisplayName`	string	no	Name other players see. Defaults to the login name.
`ResumeKey`	string	no	Which browsing context this connection belongs to, so a reload is recognised as the same one coming back rather than a second arrival. Opaque to the server, which never reads it as anything but a label.

`chunk_subscribe`#

Asks for chunks to be streamed. This is the client's area of interest: the server sends nothing about a chunk nobody is subscribed to.

Field	Type	Required	Meaning
`Chunks`	array of `ChunkId`	yes	The chunks to start watching. Each one newly watched is answered with its snapshot, and from then on with deltas.

`chunk_unsubscribe`#

Stops the streaming of chunks the client no longer wants; nothing more is sent about them until they are asked for again.

Field	Type	Required	Meaning
`Chunks`	array of `ChunkId`	yes	The chunks to stop watching.

`action_request`#

Asks the server to do something. It may refuse.

Field	Type	Required	Meaning
`RequestId`	string (a UUID)	yes	Correlates the reply, so a client can await one action among many.
`Action`	one of the actions, by `action`	yes	What to do: one of the actions, named by its `action` field.

`simulation_control`#

Changes the server's simulation speed. Deliberately a server concern: a client changing its own time scale would only desynchronise itself.

Field	Type	Required	Meaning
`Speed`	integer	yes	The multiplier: 0, 1, 2, 5, 10 or 50. Anything else is refused, and so is anybody not connected from the machine the world runs on.

`metrics_request`#

Asks for the server's counters. Answered with server_metrics; the same figures are served at /metrics.

No fields beyond type.

`blueprint_request`#

Asks for a design the client has been told about but does not hold.

Field	Type	Required	Meaning
`Blueprint`	`BlueprintId`	yes	Which design, as a snapshot's `visual` component or a list names it.

`blueprint_list_request`#

Asks what designs exist.

No fields beyond type.

`player_list_request`#

Asks who else is connected.

No fields beyond type.

`agent_list_request`#

Asks what the world's agents are doing.

No fields beyond type.

`chat_send`#

Says something. A request like any other: the server decides who hears it, and may refuse.

Field	Type	Required	Meaning
`Scope`	`ChatScope`	no, default `Public`	Who should hear it. Public when omitted.
`Text`	string	yes	What to say. Length-capped and stripped of control characters server-side.
`To`	string	no	Who to say it to, for `Direct`: a player's login name or an agent's name. Ignored otherwise, and resolved to an `OwnerId` by the server — a name is how somebody addresses another, an id is who they reached.

`prompt_list_request`#

Asks what the world is currently waiting on an answer to.

No fields beyond type.

Actions#

The actions a client may request.

Each one carries "action": "…" naming which it is, spelled exactly as the headings below.

`move_entity`#

Starts a journey for something with a movement component. It takes simulated time, and the destination's height is the server's: the point is snapped to the ground, or to a floor the walker can reach from where it is. Needs Control.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes	What to move.
`Destination`	`WorldPosition`	yes	Where to. The height you send is ignored.

`teleport_entity`#

Puts an entity somewhere now, with no journey. Judged exactly as MoveEntityAction is, plus a refusal for open water; the height names the storey wanted and the server lands it on the surface there. Needs Control.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes
`Destination`	`WorldPosition`	yes

`remove_natural`#

Fells a tree or clears a rock, recording a world delta.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes	The tree or rock. Needs Destroy.

`demolish_entity`#

Unbuilds something that was built, deleting what was stored for it.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes	What to take down. Needs Destroy, which a claim over the ground never gives over somebody else's property standing on it.
`WithContents`	boolean	no, default `false`	Whether what it holds is destroyed with it.

`inspect_entity`#

Asks for one entity in full: every component, what can be asked of it, and what you may do to it. Needs Inspect, which anybody has.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes	What to look at.

`claim_land`#

Claims unheld ground.

Field	Type	Required	Meaning
`Chunks`	array of `ChunkId`	yes	The chunks to claim. Refused entirely if any one of them is already held, and refused outright for an anonymous session.

`release_land`#

Gives claimed ground back, in whole or in part.

Field	Type	Required	Meaning
`Chunks`	array of `ChunkId`	yes	The chunks to give back. All of them must be yours.

`program_entity`#

Puts a script on something, which needs Program permission.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes	The machine.
`ScriptPath`	string	yes	A path on the machine's own filesystem, such as `/main.lua`.

`spawn_blueprint`#

Builds a machine from a stored design. Needs Build permission on the ground it will stand on.

Field	Type	Required	Meaning
`Blueprint`	`BlueprintId`	yes	The design to build from.
`Position`	`WorldPosition`	yes	Exactly where to put it. Nothing is snapped: the caller decides the height, and a design with a physics component falls from there.

`save_blueprint`#

Saves a design, so a person can make a thing rather than only place one somebody else made.

Field	Type	Required	Meaning
`Name`	string	yes	What to call it.
`EntityType`	`EntityType`	yes	What kind of thing it is — a validated string, not a closed set.
`Visual`	`ProceduralAssetDefinition`	yes	The shapes it is made of.
`Components`	object of string by string	no	Components a spawned one should carry, by registered name and JSON.
`Scripts`	object of string by string	no	Scripts to put on a spawned one's filesystem, by path.
`Includes`	array of `BlueprintPart`	no	Other designs this one is built from.
`Revises`	`BlueprintId`	no	A design of the sender's this is a new description of.

`delete_blueprint`#

Removes a design of the sender's from the catalogue.

Field	Type	Required	Meaning
`Blueprint`	`BlueprintId`	yes

`set_access`#

Says who else may do what with something of yours.

Field	Type	Required	Meaning
`To`	`OwnerId`	yes	Who is being let in, or shown out.
`Permissions`	`Permission`	yes	What they may do.
`Granting`	boolean	no, default `true`	False to take it back.
`Entity`	`EntityId`	no	The thing this is about, if it is about a thing.
`At`	`WorldPosition`	no	Where the ground is, if it is about ground.

`set_public_access`#

Says what anybody at all may do with something of yours.

Field	Type	Required	Meaning
`Permissions`	`Permission`	yes	What anybody may do. Replaces the previous policy rather than adding to it.
`Entity`	`EntityId`	no	The thing this is about, if it is about a thing.
`At`	`WorldPosition`	no	Where the ground is, if it is about ground.

`request_access`#

Asks somebody to let you in.

Field	Type	Required	Meaning
`Permissions`	`Permission`	yes	What you are asking to be allowed.
`Note`	string	no	A line for the owner, saying why.
`Entity`	`EntityId`	no	The thing this is about, if it is about a thing.
`At`	`WorldPosition`	no	Where the ground is, if it is about ground.

`create_agent`#

Asks for an agent to be created and set to work.

Field	Type	Required	Meaning
`Name`	string	yes	What to call it.
`Brain`	string	yes	Which brain should decide for it, such as `city` or `dummy`.
`Goals`	array of string	yes	What it is for. At least one and at most sixteen, each at most 120 characters; the world refuses more, and names the bound when it does.
`At`	`WorldPosition`	no	Where to put it to work. Omitted means wherever the server finds room.
`Script`	string	no	A brain written in Lua, for an agent nobody has written a brain for. Given one, `Brain` is ignored and the agent runs this.

`dismiss_agent`#

Dismisses an agent.

Field	Type	Required	Meaning
`Agent`	`AgentId`	yes	Which agent. Only the account that employed it may dismiss it.

`use_entity`#

Uses something. The general verb: the server checks permission and delivers a use event to the thing's scripts, which decide what it means. A door and a market stall are the same action with different Lua.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes	What to use. Needs Use, and to be within reach of it unless it is your own.

`transfer_items`#

Moves items between two inventories. Needs Handle on both ends, because taking is as much an imposition as giving, and the two ends have to be within reach of each other unless both are the asker's own. Everything moves, or nothing does.

Field	Type	Required	Meaning
`From`	`EntityId`	yes	The inventory to take from.
`To`	`EntityId`	yes	The inventory to put into.
`Item`	string	yes	The item's name, as the inventory lists it.
`Quantity`	integer	yes	How many.

`exchange_items`#

Swaps goods both ways at once, or moves nothing.

Field	Type	Required	Meaning
`A`	`EntityId`	yes	One side of the trade: the one that gives `Give` and receives `Take`.
`B`	`EntityId`	yes	The other side.
`Give`	string	yes	What `A` hands over.
`GiveQuantity`	integer	yes	How many of `Give`.
`Take`	string	yes	What `B` hands back.
`TakeQuantity`	integer	yes	How many of `Take`.

`start_script`#

Runs a script already on a computer's filesystem.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes	The machine.
`ScriptPath`	string	yes	The script's path on that machine.

`stop_script`#

Stops one running process on a machine. Needs Program.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes	The machine.
`Pid`	integer	yes	The process, by the id the machine's computer component lists.

`answer_prompt`#

Answers a question the world put to you.

Field	Type	Required	Meaning
`Prompt`	`PromptId`	yes	Which question. Assigned by the server when it was raised.
`Option`	string	yes	Which of the answers it offered.
`Values`	object of string by string	no	What was typed into the fields it asked for, by their names.

`set_readout`#

Puts a reading above something, or takes one away.

Field	Type	Required	Meaning
`Entity`	`EntityId`	yes	What to show it on. Needs Modify.
`Key`	string	yes	Which reading: lowercase letters, digits and underscores. Writing the same one twice replaces it.
`Readout`	`ReadoutChange`	yes	What to change about it. A reading left with neither words nor a number is taken down.

Server to client#

Anything the server sends.

Each one carries "type": "…" naming which it is, spelled exactly as the headings below.

`world_bootstrap`#

Everything a client needs before it can render anything.

Field	Type	Required	Meaning
`ProtocolVersion`	integer	yes	What this server speaks.
`PlanetId`	`PlanetId`	yes	Which world this is.
`PlanetName`	string	yes	What the world is called.
`Seed`	integer	yes	What the terrain is generated from. A client holding the seed can generate matching natural visuals itself.
`GeneratorVersion`	integer	yes	Which generator made the terrain from that seed; a different version is a different planet from the same number.
`RegionSizeMeters`	number	yes	The unit of region activity, in metres.
`ChunkSizeMeters`	number	yes	The unit of streaming, claiming and searching, in metres.
`SeaLevelMeters`	number	yes	The height water stands at, in metres.
`Simulation`	`SimulationStateSnapshot`	yes	The clock, its speed and what it has scheduled, as of this message.
`SpawnPosition`	`WorldPosition`	yes	Where a client should place a newly arrived player. Deterministic for a given seed, and chosen to be dry land rather than whatever the origin happens to be.
`Player`	`PlayerSnapshot`	no	Who this connection is. Null for an anonymous session, which can watch the world but owns nothing.
`MayControlSimulation`	boolean	yes	Whether this connection may change how fast the world runs.
`Brains`	array of string	yes	The names of the brains this server can run, for a `create_agent`'s `Brain`. Empty means this world runs no agents at all.

`chunk_snapshot`#

A chunk's terrain and everything currently standing in it.

Field	Type	Required	Meaning
`Chunk`	`ChunkId`	yes	Which chunk.
`DominantBiome`	`BiomeType`	yes	The biome most of it is.
`Heightmap`	`HeightmapSnapshot`	yes	Its terrain, sampled on a grid that shares its edges with the neighbouring chunks.
`Entities`	array of `EntitySnapshot`	yes	Everything standing in it, described in full.

`entity_delta`#

What changed in a chunk since the last message about it.

Field	Type	Required	Meaning
`Chunk`	`ChunkId`	yes	Which chunk this is about.
`Updated`	array of `EntitySnapshot`	yes	The entities that changed, described in full.
`Removed`	array of `EntityId`	yes	The entities gone from this chunk: destroyed, or walked into another one.

`action_result`#

The answer to an action_request, refusals included. It is always sent, and it reaches the asker before any delta describing what the action changed.

Field	Type	Required	Meaning
`RequestId`	string (a UUID)	yes	The request this answers.
`Success`	boolean	yes	Whether it happened.
`Error`	string	no	Why the server refused. Null when it did not.
`Entity`	`EntitySnapshot`	no	The entity the action concerned, when the client asked to inspect one.
`Affordances`	array of `EntityAffordance`	no	What can be asked of that entity, whenever one is described.
`Permissions`	`Permission`	no	What the server currently thinks the asker may do to that entity.
`Removed`	boolean	no	Whether the entity the action concerned is gone because of it.
`Prompt`	`PromptSnapshot`	no	A question the world put to the asker while carrying this out.
`Design`	`DesignResult`	no	What became of the design a `save_blueprint` or `delete_blueprint` concerned. Absent for every other action.

`simulation_state`#

The clock changed speed. Sent to every client, because everybody shares one clock.

Field	Type	Required	Meaning
`Simulation`	`SimulationStateSnapshot`	yes	The clock as it now stands.

`server_metrics`#

The server's counters, answering a metrics_request.

Field	Type	Required	Meaning
`Metrics`	`ServerMetricsSnapshot`	yes	The counters.

`blueprint`#

A design, so the client can build its model at runtime.

Field	Type	Required	Meaning
`Blueprint`	`BlueprintDefinition`	yes	The whole design.

`blueprint_list`#

What designs exist, without their full definitions.

Field	Type	Required	Meaning
`Blueprints`	array of `BlueprintSummary`	yes	One summary per design in the catalogue.

`player_list`#

Who is connected, and roughly where.

Field	Type	Required	Meaning
`Players`	array of `ConnectedPlayer`	yes	Everybody the world counts as here, whether over a socket or over MCP.

`agent_list`#

What the world's agents are doing.

Field	Type	Required	Meaning
`Agents`	array of `AgentSummary`	yes	Every agent, as somebody watching it needs to see it.

`chat`#

One line of chat, as delivered.

Field	Type	Required	Meaning
`Scope`	`ChatScope`	yes	Who this line reached.
`From`	`OwnerId`	yes	Who said it: a player or an agent, kind included.
`FromName`	string	yes	Their name, as the server holds it — never as a sender asserted it.
`Text`	string	yes	What was said, after cleaning.
`At`	string (a timestamp)	yes	When it was said, by the wall clock.
`To`	`OwnerId`	no	The recipient, for a direct message. Null for everything else.
`ToName`	string	no	The recipient's name, for a direct message.

`prompt`#

Something in the world is asking you a question.

Field	Type	Required	Meaning
`Prompt`	`PromptSnapshot`	yes	The question.

`prompt_list`#

Everything currently waiting on this connection's answer.

Field	Type	Required	Meaning
`Prompts`	array of `PromptSnapshot`	yes	Every question still waiting on this connection.

`error`#

A request the server would not carry out. Never a reason to drop the connection: invalid input is expected, not exceptional.

Field	Type	Required	Meaning
`Message`	string	yes	What was wrong.
`Detail`	string	no	More, when there is more to say.

Shapes the messages carry#

The objects the fields above are made of, by the name the tables use for them.

`AgentGoalSummary`#

One goal, and whether the agent considers it done.

Field	Type	Required	Meaning
`Name`	string	yes	The goal, in the words it was given.
`Completed`	boolean	yes	Whether the agent considers it done.

`AgentSummary`#

One agent, as somebody watching it needs to see it.

Field	Type	Required	Meaning
`Id`	`AgentId`	yes	Which agent.
`Name`	string	yes	What it is called.
`Brain`	string	yes	Which brain decides for it, such as `city` or `dummy`.
`Employer`	string	no, default `""`	Who employed it, written as an owner — `player:<uuid>` — or empty where nobody is on record.
`State`	string	yes	Idle, Waiting, Thinking, Finished or Failed.
`ThoughtCount`	integer	yes	How many times its brain has run.
`NextThinkTimeTicks`	integer	no	When it is next due to think, in simulation ticks. Null means dormant.
`Body`	`EntityId`	yes	Its character, or the empty identity while it has none.
`Home`	`EntityId`	yes	The machine it thinks on.
`Position`	`WorldPosition`	no	Where its character stands, or where its machine is if it has none.
`Destination`	`WorldPosition`	no	Where it is walking to, if it is.
`Goals`	array of `AgentGoalSummary`	yes	What it is for, and how far it has got.
`Memory`	object of string by string	yes	What it has written down about its own work, such as which step it is on.
`Reasoning`	string	no	The line its brain last gave for what it did.
`LastActions`	array of string	yes	What its last thought asked for, and whether the world agreed.

`AssetPart`#

One piece of a procedural model.

Field	Type	Required	Meaning
`Id`	`PartId`	yes	The part's name within the design: lowercase letters, digits and underscores, starting with a letter.
`Primitive`	`PrimitiveShape`	yes	Which shape.
`Parent`	`PartId`	no, default `""` (none)	The part this hangs from, or none for a root part.
`Position`	`WorldPosition`	no	Offset from the parent's pivot, in metres, in the parent's own frame — so a turned parent swings this round with it, while its scale leaves it alone.
`Rotation`	`WorldRotation`	no, default `(0, 0, 0, 1)`	How it is turned relative to its parent.
`Scale`	`WorldPosition`	no, default `(1, 1, 1)`	Size in metres along each axis.
`Material`	`AssetMaterial`	no, default `White`	What it is made of, from the named materials.
`Colour`	`PartColour`	no	A colour of the design's own choosing, overriding `Material`.
`Surface`	`MaterialId`	no	A surface pattern from the design's own `Materials`, drawn over this part.
`SurfaceTiling`	number	no, default `1`	How many times the surface pattern repeats across a metre.
`SemanticTag`	string	no	What this part is for, such as `head` or `lower_arm_left`.
`Solid`	boolean	no, default `false`	Whether this part blocks movement.
`Path`	array of `PathPoint`	no	The line a `Ribbon` runs along, in this part's own frame, in metres. Null for every other shape, and for a ribbon that simply runs straight.
`Draped`	boolean	no, default `false`	Whether this part lies on the ground it crosses rather than holding the shape the design gave it.
`IsRoot`	boolean	derived — sent, never read	Whether it hangs from nothing.

`BlueprintDefinition`#

A design something can be built from.

Field	Type	Required	Meaning
`Id`	`BlueprintId`	yes	The design's identity.
`Name`	string	yes	What it is called.
`Creator`	`OwnerId`	yes	Who designed it. A player, an agent, or the world itself.
`Version`	integer	yes	Which version of its line this is. The first is 1.
`Supersedes`	`BlueprintId`	no	The design this one replaced, or none if it is the first of its line.
`CreatedAt`	string (a timestamp)	yes	When it was saved, by the wall clock.
`Visual`	`ProceduralAssetDefinition`	yes	What it looks like.
`EntityType`	`EntityType`	yes	What entity type a spawned instance has.
`Components`	object of string by string	no, default `{}`	Components by registered name and serialised value.
`Scripts`	object of string by string	no, default `{}`	Scripts to place on the spawned machine's filesystem, by virtual path.
`Includes`	array of `BlueprintPart`	no, default `[]`	Other designs this one is built from. Each becomes its own entity in the group, so a door in a house is something you can open.
`IsComposite`	boolean	derived — sent, never read	Whether this design is made of other designs.
`Metadata`	object of string by string	no, default `{}`	Free-form notes: who made it, why, what it is for.

`BlueprintPart`#

Another design, included in this one.

Field	Type	Required	Meaning
`Blueprint`	`BlueprintId`	yes	The design to include.
`Offset`	`WorldPosition`	no	Where it sits relative to the design that includes it, in metres.
`Rotation`	`WorldRotation`	no, default `(0, 0, 0, 1)`	How it is turned relative to the design including it.
`Tag`	string	no	What this piece is to the whole — `front_door`, `left_wheel`. The same idea as a part's semantic tag, one level up.

`BlueprintSummary`#

Enough of a design to choose it from a list.

Field	Type	Required	Meaning
`Id`	`BlueprintId`	yes	The design's identity.
`Name`	string	yes	What it is called.
`Version`	integer	yes	Which version of its line this is; a revision is a new design with the next number.
`Creator`	string	yes	Who designed it: a player, an agent, or the world.
`PartCount`	integer	yes	How many shapes it is made of.
`EntityType`	string	no	What kind of thing it is, so a client can put a design back into a form to change it.
`Versions`	integer	no, default `1`	How many versions the line has, this one included. One for most designs.

`ConnectedPlayer`#

One other person in the world.

Field	Type	Required	Meaning
`ClientId`	string	yes	This connection's identity, which is not the account's: one person with two windows open is two of these.
`LoginName`	string	no	Their account name, or null for an anonymous spectator.
`ClientName`	string	yes	What their client called itself when it said hello.
`Position`	`WorldPosition`	no	Where they are: their body, or the middle of what they are watching if they have none, and null if they have neither.
`Body`	`EntityId`	no	The body they are standing in, or none if they have not taken one.
`SubscribedChunks`	integer	yes	How many chunks they are watching. Zero for somebody acting over MCP, who is in the world with nothing streamed to them.
`IsYou`	boolean	yes	Whether this row is the asker.

`DesignResult`#

A design as an action left it.

Field	Type	Required	Meaning
`Id`	`BlueprintId`	yes
`Name`	string	yes
`Version`	integer	yes
`Outcome`	string	yes	`created`, `unchanged`, `updated`, `superseded` or `deleted`.
`Supersedes`	`BlueprintId`	no	For `superseded`: the design that was revised and is still there.
`BuiltFromPrevious`	integer	no	For `superseded`: how many stored things were built from it, and keep it.

`EntityAffordance`#

One thing the server says can be asked of an entity.

Field	Type	Required	Meaning
`Id`	string	yes	A stable identifier for this affordance on this kind of thing, so a client can keep a button in the same place between two descriptions. Distinct from `Action`, because one action can be offered twice with different settled arguments — sharing and revoking are both `set_access`.
`Action`	string	yes	The `WorldAction` discriminator this asks for.
`Label`	string	yes	The button, in the words of whoever designed the thing where it says.
`Hint`	string	yes	A line explaining what pressing it does.
`Audience`	`AffordanceAudience`	no, default `Visiting`	Which kind of client this verb belongs in front of.
`Needs`	array of `InputField`	no, default `[]`	What the person has to supply. Empty when the verb needs nothing.
`Settled`	object of any JSON by string	no, default `{}`	Arguments the server has already settled for this affordance, merged into the action as they are. It is how one action kind can be two buttons: `Granting` is true on Share and false on Revoke.

`EntitySnapshot`#

One entity as the server describes it to a client.

Field	Type	Required	Meaning
`Id`	`EntityId`	yes	Its identity.
`Type`	`EntityType`	yes	What kind of thing it is: a validated name, not a closed set.
`Owner`	`OwnerId`	yes	Whose it is: the world, a player or an agent.
`PersistenceClass`	`PersistenceClass`	yes	What the world owes it, which is also what decides how it is removed.
`Version`	integer	yes	The version this snapshot describes, so a client can discard stale deltas.
`Components`	object of any JSON by string	yes	Components keyed by their registered name, each as raw JSON. The inspector shows these directly, so a new component becomes visible to the client without a protocol change.

`HeightmapSnapshot`#

The terrain of one chunk, as sampled by the generator.

Field	Type	Required	Meaning
`Resolution`	integer	yes	Points along each edge of the chunk. The grid is this squared.
`Heights`	array of number	yes	Row-major heights, sharing edges with neighbouring chunks.
`Biomes`	array of `BiomeType`	yes	The biome at each of those points, so the client can colour terrain by what is underfoot rather than by one value for the whole chunk.

`InputField`#

One value the world needs before it can act.

Field	Type	Required	Meaning
`Name`	string	yes	The name the client collects it under. Stable: a client builds the message it sends from these, so renaming one is a wire change.
`Label`	string	yes	What to call the field where a person will read it.
`Kind`	`InputFieldKind`	yes	What kind of value: a line of text, a whole number, or a set of permissions.
`Placeholder`	string	no	Greyed-out example text, when there is something useful to say.
`Value`	string	no	What to fill in already, where the server knows a good answer — the script path the thing actually runs, the first item it actually holds.

`PartColour`#

A colour a design chose for itself.

Field	Type	Required	Meaning
`Red`	number	no	Red, from 0 to 1.
`Green`	number	no	Green, from 0 to 1.
`Blue`	number	no	Blue, from 0 to 1.
`Alpha`	number	no	Opacity. Below one makes glass, water and anything else you can see through.
`IsValid`	boolean	derived — sent, never read	Whether every channel is finite and within range.

`PathPoint`#

One point on a part's path, in the part's own frame, in metres.

Field	Type	Required	Meaning
`X`	number	no	Metres east of the part's own origin.
`Z`	number	no	Metres north of the part's own origin.
`IsFinite`	boolean	derived — sent, never read	Whether both numbers are real: a point at infinity has no direction to lay a strip along.

`PlayerSnapshot`#

Who the server thinks this client is, and what it already owns.

Field	Type	Required	Meaning
`Id`	`PlayerId`	yes	The account's durable identity.
`LoginName`	string	yes	The account's name.
`DisplayName`	string	yes	The name other players see.
`WasRegistered`	boolean	yes	True when this connection registered the account just now.
`Token`	string	no (omitted when null)	The account's token, sent exactly once — when it is registered, or when an account older than tokens adopts one. Keep it: the server stores only its hash and cannot send it again.
`OwnedEntities`	array of `EntityId`	yes	Entities this player owns on this planet, restored into the world.

`ProceduralAssetDefinition`#

A model described as parts rather than geometry.

Field	Type	Required	Meaning
`Name`	string	yes	What the model is called.
`Parts`	array of `AssetPart`	yes	The shapes, each with its place, its size and what it is made of.
`Materials`	array of `SvgMaterial`	no, default `[]`	The surface patterns this design's parts may name.
`PartCount`	integer	derived — sent, never read	How many parts.
`Roots`	array of `AssetPart`	derived — sent, never read	Parts with no parent. A well-formed model has at least one.
`FollowsGround`	boolean	derived — sent, never read	Whether this design lies along the ground rather than standing on it: any part of it is `Draped`.

`PromptChoice`#

One answer a prompt offers, as the client draws it.

Field	Type	Required	Meaning
`Name`	string	yes	What comes back when it is chosen. An identifier, not a sentence.
`Label`	string	yes	The wording on the button, in whoever's words asked.

`PromptSnapshot`#

A question the world is waiting on, as it crosses the wire.

Field	Type	Required	Meaning
`Id`	`PromptId`	yes	The question's identity. Sent back with the answer.
`From`	`EntityId`	yes	The thing that is asking, so the client can point at it.
`FromName`	string	yes	What that thing is called, which is all the client has to show.
`Question`	string	yes	What it wants to know.
`Options`	array of `PromptChoice`	yes	The answers it will take. At least one.
`Needs`	array of `InputField`	no, default `[]`	What to collect beside the choice. Usually empty.
`SecondsLeft`	number	yes	How long the question has left, in seconds of simulated time.

`ReadoutChange`#

A change to one of the readings a thing shows above itself.

Field	Type	Required	Meaning
`Kind`	string	no	How to draw it: `bar` or `text`. Text, if never said.
`Source`	string	no	Where the number comes from: `given`, `health`, `energy` or `growth`. Given, if never said.
`Label`	string	no	A word or two naming what is shown. Empty takes it away.
`Text`	string	no	Words to show instead of a number. Empty takes them away.
`Colour`	string	no	A colour as `#rgb`, `#rrggbb` or `#rrggbbaa`. Empty takes it away.
`Value`	number	no	The number to show now.
`RatePerSecond`	number	no	How fast it changes from here, per second. Nothing more is written after this.
`Limit`	number	no	Where it stops changing.
`Maximum`	number	no	What counts as full, for a bar showing a number of your own.
`Order`	integer	no	Where it sits in the stack, smallest first.
`Clear`	boolean	no, default `false`	Start from nothing rather than from what is already there.
`SaysNothing`	boolean	derived — sent, never read	Whether this asks for anything at all.

`ServerMetricsSnapshot`#

Debug counters.

Field	Type	Required	Meaning
`EntitiesTotal`	integer	yes	Entities the world holds.
`EntitiesActive`	integer	yes	Entities in a region that is costing something: active, or operational. The rest are there, but nothing is attending to them.
`LoadedChunks`	integer	yes	Chunks in memory.
`ScheduledEvents`	integer	yes	Events waiting to happen.
`EventsProcessed`	integer	yes	Events carried out since the server started.
`EventsFailed`	integer	yes	Events whose handler failed.
`ConnectedClients`	integer	yes	Sockets open right now.
`SubscribedChunks`	integer	yes	Chunks being watched, counted over every client.
`DatabaseWrites`	integer	yes	Writes to storage since the server started.
`LuaProcesses`	integer	yes	Lua processes alive.
`LuaExecutions`	integer	yes	Times a script has run since the server started.
`LuaErrors`	integer	yes	Times a script has failed since the server started.
`Blueprints`	integer	yes	Designs in the catalogue.
`RegionsActive`	integer	yes	Regions with a player in them.
`RegionsDormant`	integer	yes	Regions costing nothing — dormant or summarised.
`ChunksAggregated`	integer	yes	Chunks of wood collapsed to a summary.
`AgentCount`	integer	yes	Agents this world is running.
`AgentThinkCount`	integer	yes	Thoughts had since the server started.
`Claims`	integer	yes	Claims held.
`ClaimedChunks`	integer	yes	Chunks under those claims.
`BatteriesEmptied`	integer	yes	Batteries that have run flat since the server started.
`GrownToMaturity`	integer	yes	Things that have finished growing since the server started.
`SimulationTimeTicks`	integer	yes	The clock, in ticks.
`PlanetName`	string	no (omitted when null)	What the world is called. Left out where the answer is not about a particular world.

`SimulationStateSnapshot`#

What the server knows about the simulation right now.

Field	Type	Required	Meaning
`SimulationTimeTicks`	integer	yes	The clock, in ticks: ten million to the simulated second.
`Speed`	integer	yes	The multiplier real time is run at. Zero is paused.
`ScheduledEvents`	integer	yes	How many things the world has arranged to do later.

`SvgMaterial`#

A surface pattern, written as SVG.

Field	Type	Required	Meaning
`Id`	`MaterialId`	yes	The digest of `Svg`, and nothing else.
`Name`	string	yes	What a person calls it: `brick`, `tartan`, `rosette`.
`Svg`	string	yes	The drawing itself, as SVG source.
`ByteSize`	integer	derived — sent, never read	How large the drawing is on the wire and in storage.
`IsSelfConsistent`	boolean	derived — sent, never read	Whether `Id` is the digest of `Svg`.

Message reference#

Client to server#

hello#

chunk_subscribe#

chunk_unsubscribe#

action_request#

simulation_control#

metrics_request#

blueprint_request#

blueprint_list_request#

player_list_request#

agent_list_request#

chat_send#

prompt_list_request#

Actions#

move_entity#

teleport_entity#

remove_natural#

demolish_entity#

inspect_entity#

claim_land#

release_land#

program_entity#

spawn_blueprint#

save_blueprint#

delete_blueprint#

set_access#

set_public_access#

request_access#

create_agent#

dismiss_agent#

use_entity#

transfer_items#

exchange_items#

start_script#

stop_script#

answer_prompt#

set_readout#

Server to client#

world_bootstrap#

chunk_snapshot#

entity_delta#

action_result#

simulation_state#

server_metrics#

blueprint#

blueprint_list#

player_list#

agent_list#

chat#

prompt#

prompt_list#

error#

Shapes the messages carry#

AgentGoalSummary#

AgentSummary#

AssetPart#

BlueprintDefinition#

BlueprintPart#

BlueprintSummary#

ConnectedPlayer#

DesignResult#

EntityAffordance#

EntitySnapshot#

HeightmapSnapshot#

InputField#

PartColour#

PathPoint#

PlayerSnapshot#

ProceduralAssetDefinition#

PromptChoice#

PromptSnapshot#

ReadoutChange#

ServerMetricsSnapshot#

SimulationStateSnapshot#

SvgMaterial#

`hello`#

`chunk_subscribe`#

`chunk_unsubscribe`#

`action_request`#

`simulation_control`#

`metrics_request`#

`blueprint_request`#

`blueprint_list_request`#

`player_list_request`#

`agent_list_request`#

`chat_send`#

`prompt_list_request`#

`move_entity`#

`teleport_entity`#

`remove_natural`#

`demolish_entity`#

`inspect_entity`#

`claim_land`#

`release_land`#

`program_entity`#

`spawn_blueprint`#

`save_blueprint`#

`delete_blueprint`#

`set_access`#

`set_public_access`#

`request_access`#

`create_agent`#

`dismiss_agent`#

`use_entity`#

`transfer_items`#

`exchange_items`#

`start_script`#

`stop_script`#

`answer_prompt`#

`set_readout`#

`world_bootstrap`#

`chunk_snapshot`#

`entity_delta`#

`action_result`#

`simulation_state`#

`server_metrics`#

`blueprint`#

`blueprint_list`#

`player_list`#

`agent_list`#

`chat`#

`prompt`#

`prompt_list`#

`error`#

`AgentGoalSummary`#

`AgentSummary`#

`AssetPart`#

`BlueprintDefinition`#

`BlueprintPart`#

`BlueprintSummary`#

`ConnectedPlayer`#

`DesignResult`#

`EntityAffordance`#

`EntitySnapshot`#

`HeightmapSnapshot`#

`InputField`#

`PartColour`#

`PathPoint`#

`PlayerSnapshot`#

`ProceduralAssetDefinition`#

`PromptChoice`#

`PromptSnapshot`#

`ReadoutChange`#

`ServerMetricsSnapshot`#

`SimulationStateSnapshot`#

`SvgMaterial`#