MCP tools#

Every tool this server offers a model over MCP, with every argument, its type, its bounds and what it means. This is the same list tools/list answers with, read from the same place the endpoint reads it, so a tool or an argument added to the server is on this page the next time the server starts.

Connecting a model says how to connect, how to join as a player and what to do first; this page is the reference to keep beside it. Every tool also takes session, the handle world_join returns, and acts as whoever it names. Coordinates are metres — x east, z north, y height — and chunk addresses are written "x,z".

A world configured read-only offers only the reading tools, and this page is generated from what this server offers, so on such a world the acting tools are absent here as well.

Reading#

These never change anything, and a read-only world offers these and the catch-up.

world_whoami#

Who this connection is. Says which account this connection acts as and what it may therefore do, and lists the entities that account owns. A connection with no credentials configured is anonymous: it can read everything here but cannot claim ground, build or create agents. Call this first if an acting tool refuses you.

Reads only; calling it twice does what calling it once does.

world_overview#

The world at a glance. The planet's identity, the shape of its grid, what the simulation clock says, and the live counts: entities, active entities, loaded chunks, scheduled events, agents, running Lua processes, claims and designs. Start here; almost every other tool wants a position or an id that this leads you to.

Reads only; calling it twice does what calling it once does.

world_look#

Look around a place. Everything standing within a radius of a point, nearest first, with the ground height, biome and chunk address of the point itself and who has claimed it. Coordinates are metres: x runs east, z runs north, y is height and is worked out from the terrain if you leave it out. Use this to find things to inspect and to find somewhere to build.

Anything walking is reported where it has got to, not where it set off from, and carries a 'journey' saying where it is going and the simulation tick it arrives at. Walkers on their way in or out of the radius are included too, so somebody approaching you appears before they get here.

Reads only; calling it twice does what calling it once does.

world_route#

Walk a line and see whether it can be walked. Follows a straight line between two points, a step at a time, and says what is underfoot the whole way: where the way rises too steeply to step up, where nothing holds you up, where there is water rather than ground, and which thing carries each stretch of it. Coordinates are metres, x east and z north; no height is needed and nothing has to be standing there.

This is how you check that something built in pieces is one thing. Six bridge spans each pass a design review and still leave a bay uncrossed, and counting six of them proves nothing — walking from shore to shore proves it. Use it after building anything a person is meant to cross, and before sending anybody across it.

Nothing is moved and nothing is changed. 'walkable' is the answer; 'findings' says in words where and by how much the way breaks, worst first; 'carriedBy' lists the stretches in order, so a crossing that is really six decks end to end reads as six stretches and one that is not reads as deck, then seabed.

A step is a metre by default: the smaller it is the more honest the answer and the longer the world waits, and at most 2000 steps are taken. 'climbMeters' is how far a walker can step up — half a metre is what this world's movement actually allows, and raising it only changes the report, never the world. Give 'fromY' when the start is inside or on top of something and you mean that storey; without it the walk starts on the highest surface over the first point.

Reads only; calling it twice does what calling it once does.

world_inspect#

Inspect one entity. One entity in full: type, owner, position, chunk, every component it carries with that component's own fields, what it is showing above itself, and what this connection is permitted to do to it. Looking is open to everybody in this world, anonymous callers included — 'youMay' is where the difference between you and the owner shows, not here — so a refusal from this tool means the id is not in the world, never that you were not allowed to see what is.

'showing' is the readings hung over it, each worked out as it reads at this moment — a bar bound to the thing's own health or energy, or a number somebody set going. Put one up with world_set_readout.

'at' is where the entity is now. Something on a journey is reported part way along it, and 'journey' then says where it came from, where it is going, how much of it is done and the simulation tick it arrives at — the same tick world_walk answered with. Call this again later and the position will have moved on; nothing needs to be done to make that happen.

Reads only; calling it twice does what calling it once does.

world_agents#

Who is thinking. Every agent in the world with its brain, state, goals and how many thoughts it has had. An agent is an autonomous inhabitant: it is asked for once and then decides for itself, so this is where you see what the world is doing without anybody driving it. Use world_agent for one agent's most recent actions.

Reads only; calling it twice does what calling it once does.

world_agent#

One agent and what it just did. One agent in full, with its memory and the results of the actions its last thought produced — each one accepted or refused by the server, with the reason. This is how you find out why an agent that was asked to build a town has not built one.

Reads only; calling it twice does what calling it once does.

world_history#

What has happened lately. Recent world events, newest first: entities created and destroyed, ground claimed, agents created, scripts started and failed. Each carries the simulation time it happened at, a sentence and its details. The same log the /events endpoint serves.

Reads only; calling it twice does what calling it once does.

world_designs#

The design catalogue. Every design anybody or anything in this world has authored, newest first, one entry per design: the latest version of each, with how many versions the line has and which id came before. Older versions are not listed beside it as if they were different things; ask for one by id, or set allVersions to list them. A design is a named list of primitive parts that world_build_design can put up as a real entity. Search by name; use world_design for one design's parts, its versions and the review of it.

Reads only; calling it twice does what calling it once does.

world_design#

One design, its parts and its faults. A design as something that cannot look at a picture reads it: every part as authored and as it actually ends up once its parents are applied, the box it occupies, the designs it includes, and every finding the design review made — a roof below the wall it covers, a doorway too short to walk through, a part floating in the air. The drawing of the same design is served at /designs/<id>.

Reads only; calling it twice does what calling it once does.

world_preview_design#

Look at a design, saved or not. Draws a design and hands you the picture, so you can see what you are about to build instead of reasoning about coordinates. Name a designId to look at one that is saved, or give parts — exactly the parts world_create_design takes — to look at one that is not. Nothing is written down either way: previewing a design does not save it, and the design you preview has no id to build from until you save it with world_create_design.

The answer is the front and top views as images, with the design review beside them in words: a part floating unattached, a roof below the wall it covers, a doorway too short to walk through. Front is what the thing looks like; top is where its parts really are. A person can see all five views of a saved design at /designs/<id>.

Reads only; calling it twice does what calling it once does.

world_claims#

Who owns what ground. The claimed ground in this world: who owns each claim, how many chunks it covers, where those chunks are and what a passer-by may do there. Ground nobody has claimed cannot be built on by anybody, so read this before trying to build.

Reads only; calling it twice does what calling it once does.

world_regions#

Where there is anything to go and see. Every region of this planet that has something in it — claimed ground, things standing, people or agents present, or a history of anything happening — with who holds the land, how many things are there and how many people. Empty wilderness is not listed, so this is a directory of destinations rather than a map. Busiest first. Each row's originX and originZ are metres you can walk or look at; x and z are grid coordinates and are not. Use this to decide where to go, then world_look to see what is actually standing there.

Reads only; calling it twice does what calling it once does.

world_players#

Who else is here. Everybody connected to this world right now — people in a browser and models calling these tools — with where each of them is standing, which chunk that is, and how far away they are from you. Nearest first. This is the same roster the players panel in the browser shows, so what you see here is what they see. A walker is reported where they have got to, not where they set off from. Agents are not in this list: they are inhabitants rather than connections, and world_agents answers for them.

Reads only; calling it twice does what calling it once does.

world_machine#

Look inside a machine you may program. The inside of one machine: what is on its filesystem, what is running on it, how much storage it has used, and the tail of its own log — which is where a script's print and its crash both end up. This is the view you need after world_run_script to find out what your script actually did.

Needs 'program' on that machine, which is the same permission writing to it needs: a machine's files and log are its owner's business, and a stranger who may look at a crate from outside has no claim on what is written inside it.

Reads only; calling it twice does what calling it once does.

Catching up#

What changed since you last looked, rather than what is true now — the one thing here that a caller holding no stream open still misses nothing with. It takes the chat waiting for you as it goes, which is why it is not quite a read.

world_catch_up#

What has changed since you last looked. Everything that has happened in the world since the token you were last given, oldest first, with a new token to keep. Leave 'token' out on a first call and you are handed a starting point rather than the history of the planet; keep it and call again — a minute later or a day later — and you are told what you missed. This is the only thing here that answers "what changed" rather than "what is true now".

Each change says which kind it was, when in world time, a sentence, its details, and whether it touched you or something you own. If more happened than one answer carries, 'more' is true and the token points at the last change you were actually given, so calling again walks forward rather than skipping.

It also hands over whatever has been said to you, from the same inbox world_listen reads — a line given to one of them is not given again by the other. Pass chat=false to leave chat where it is.

Two limits worth knowing. World history is written in batches, so something that happened a moment ago may only appear in the next answer. And chat waits in your presence, which ends if you stop calling for long enough, while the token keeps working for as long as the world remembers its history.

If this server is holding a notification stream for you, it is reported here. A stream only tells you that there is something to read; this is what tells you what it is.

Changes the world.

Acting#

These do what a player does, as the account the call names, and are refused in the world's own words when that account may not.

world_join#

Join the world as a player. Registers a new player or resumes one you already have, and returns a session handle that the acting tools take. A login name nobody has used registers a fresh account and is issued a token, shown once — keep it, because it is the only way back to that account. A login name that already exists is refused unless you present its token, so you cannot become somebody else.

You are a player: a client, like a person at a keyboard. Nothing happens on your behalf between calls, so what has changed since you last asked is found with world_catch_up — keep the token it gives you and it will tell you what you missed, however long you were away. If you want something that keeps working while you are away, that is an agent — see world_create_agent.

Changes the world.

world_take_body#

Stand up a body to move about in. Builds a character as an entity you own, so that you have something to walk about in and act with. This is the same build a graphical client puts a newly arrived player into — the character is an ordinary entity in the world and other players and agents can see it. If you already own something that can walk, that one is returned instead of a second body being built.

Name a design to look like something other than the world's settler. It has to be a character — a design whose entityType is character — and it has to be yours or one the world ships; you may wear anything you can draw, and nothing anybody else drew. If it has no walkSpeed one is added, because a character that cannot walk is not a body; world_build_design builds the same design exactly as written if a statue of it is what you wanted.

Already standing in one and want a different one? Take the one you have down with world_demolish and call this again.

Changes the world.

world_walk#

Walk somewhere. Sends something you control on a journey to a point, and says how long the journey will take in simulated time. It is a walk and not a teleport: the entity is somewhere between the two places until it arrives, so ask world_inspect for where it has got to. The height is worked out from the surface under the destination — the ground, or the floor of whatever it walks into, whichever it can reach from where it is standing now. Anything you do not own needs 'control' permission on it.

Changes the world.

world_teleport#

Go somewhere now. Puts something you control at a point at once, with no journey. It is judged exactly as world_walk is — 'control' permission, a point on this planet, something that can move — and refused into open water the way building is. The height is the storey you mean: leave 'y' out to land on the ground or the lowest floor there, or give the height of a floor to arrive on that floor. Nobody sees you coming, and distance is not paid: prefer world_walk when either of those matters. Refused with a sentence if this world has switched it off.

Changes the world.

world_use#

Use something. Uses a thing: opens a door, pulls a lever, works a market stall. The server does not know what using a particular thing means — it checks that you may, then delivers a 'use' event to whatever scripts the thing is running and they decide. Something nobody has programmed is still usable and simply does nothing observable, which is the honest answer rather than a refusal.

You have to be at it. Somebody else's thing is used from within a few metres — the design says how few, at most eight — so a market is a place you go to, and world_walk is how you get there. Your own things are exempt: working your own lever from anywhere is bookkeeping, not reaching. Reaching is done with the body world_take_body stood you up in, so a caller that never took one is standing nowhere and can only use what it owns.

Changes the world.

world_prompts#

What the world is asking you. Questions something in the world has put to you and is waiting on. A lift asking which floor, a door asking for a code, a stall asking how many. Each one names the thing that asked, what it wants to know, and the answers it will accept; reply with world_answer.

A question waits rather than being announced, so this is how you find out without holding a connection open. A question stands for a couple of minutes and then goes; reading does not use one up. You can only be asked something by a thing you have just used or just answered, and only while you are standing next to it.

Reads only.

world_answer#

Answer a question the world asked you. Answers one of the questions world_prompts lists, by naming one of the options it offers. Where the question also asks for values — a code, a quantity — pass them as 'values', keyed by the names it gave.

The answer is judged when it arrives and not when the question was asked. A question that has run out of time, one already answered, one naming an option that is no longer offered, and one whose machine has been demolished in the meantime are all refused in the world's own words.

Answering also counts as dealing with the thing, so it may ask you something else — the reply says so when it does.

Changes the world.

world_set_readout#

Show a reading above something. Hangs a reading over a thing, where every client draws it above whatever it is on: a bar, or a line of text. A health bar, 'cargo 3/10', 'charging', a countdown, 'meet here' — all of them are this call with different arguments. Needs 'modify' on the thing, which is the same permission recolouring one of its parts needs; you have it over your own things.

'key' names the reading, so setting the same key again replaces it rather than adding another. Leave a reading with neither words nor a number of its own and it comes down, which is how you take one away; 'clear' does the same in one argument.

'source' is where the number comes from, and this is the part worth reading. 'health', 'energy' and 'growth' take it from the thing itself, so a bar over a tree's growth is true for ever with nobody maintaining it — but a thing that carries no such component is refused, because a bar that could never move is not a bar. 'given' is your own number: 'value' now, 'rate' per second and 'limit' where it stops. That is worked out from the moment you set it, so a bar that empties over the next thirty seconds is one call and nothing after it. Writing the number again every second is the wrong way to do it and this is why the arguments are here.

Whatever can see the thing sees what it shows. Nothing private belongs on one.

Changes the world.

world_take_items#

Move items between two things. Moves a quantity of a named item from one thing's inventory to another's: picking something up, putting it down, loading a cart, stocking a stall. You need 'handle' permission on both ends, because taking from something is exactly as much of an imposition as putting something into it. The move is atomic — if it will not fit, nothing has moved.

'handle' is not 'use', and standing on somebody's public ground does not give it to you: a street you may walk down is not a licence to go through the pockets of everyone in it. Open your own stall to customers with world_share, either on the stall or on the ground it stands on.

The two things also have to be within about 8 m of each other, unless both of them are yours. Come to the counter.

Changes the world.

world_exchange_items#

Trade goods both ways at once. Swaps items in both directions in a single step: the first thing hands over what you name in 'give' and receives what you name in 'take'. Either the whole trade happens or none of it does, so a payment cannot land while the goods fail — which is exactly what happens when you call world_take_items twice and the second call is refused.

This is a movement of goods, not a market. The world has no prices and no currency and is not going to acquire any: what five coins is worth is between you and whoever you are trading with, and 'coin' is an item name like any other. Say what changes hands and the world will make sure it changes hands together.

Same rules as world_take_items: 'handle' on both things, and the two of them within about 8 m of each other unless both are yours.

Changes the world.

world_clear_natural#

Clear a tree or a rock. Removes a naturally generated tree or rock and records that it is gone, so it stays gone across restarts rather than being regenerated from the seed. Only generated objects can be cleared this way; anything somebody built is taken down with world_demolish instead, and naming the wrong one of the two is refused and told which was right. Nature standing on a claim belongs to whoever claimed the ground.

Changes the world.

world_demolish#

Take down something that was built. Unbuilds a thing somebody built — a house, a crate, a lamp, a machine — and deletes what was stored for it, so it stays gone across restarts. This is the counterpart of world_clear_natural: that one fells generated nature, this one takes down what was put up. Name the wrong one and you are told which was right.

You need 'destroy' on the thing, which for anything of your own you have. Holding the ground it stands on is not enough: a claim gives you the land and never somebody else's property standing on it. A composite goes down whole — demolishing a house takes its walls, roof and door with it.

Something holding items is refused, because deleting somebody's stock quietly is not a thing an interface should do. Move them out with world_take_items, or say withContents and they are destroyed with it — that is only for things you own, it is not undoable, and nothing in this world makes items again.

An agent's body and the machine an agent thinks on are refused outright: taking either away would strand it. Employ and dismiss are the pair there — world_dismiss_agent takes both down and hands you what the agent built.

There is nothing left to inspect afterwards, so do not ask.

Changes the world.

world_claim_land#

Claim ground. Claims whole chunks of ground for your account, written as "x,z" addresses — world_look tells you which chunk a point is in. Unclaimed ground is open to everybody; a claim makes it yours to build on and, by default, nobody else's. Set publicUse if you mean it to be a place people can walk into and open doors in: a street nobody but its builder may walk down is not a street.

Changes the world.

world_release_land#

Give claimed ground back. Gives ground you hold back to the world, so that anybody may build on it again. The counterpart of world_claim_land, and the answer to having claimed the wrong chunk — before this there was none, and land claimed by mistake was held for ever. It is not world_share: that lifts somebody's permission on land you go on holding, and this gives up the land.

Only the holder may. A grant on a claim — even 'destroy' — lets you act on the ground, never dispose of it.

Name as many or as few of your chunks as you like; you keep the rest, with the same public setting and the same grants. A chunk you do not hold refuses the whole call, so a typo cannot give away a neighbouring plot by accident.

Nothing standing on it is touched. Your buildings stay yours and other people's stay theirs — a claim has never given anybody title to the property on it. What stops is what the claim conferred: anything that was open because the ground was a public place is judged on the thing itself from then on. Take your own buildings down with world_demolish if you want the plot clear.

Changes the world.

world_shape_ground#

Cut or raise a piece of ground. Moves the ground itself: a level yard, a floor cut into a hillside for a garage, a terrace to build on before you have decided what goes on it. Until this existed the ground only ever moved underneath a building, so the shape of the land was a consequence of what you put on it and could never be the point.

A pad is a square at one height, measured from its middle to its edge by halfSize, with a skirt outside it that ramps back to the hillside. Five metres of skirt is a terrace you can walk up. A skirt of 0 leaves a face at the pad's edge, which is what cutting a garage into a slope means. Say either height, an absolute, or delta, how far to move the ground from where it already is — one of the two.

A road is this called more than once: a run of pads along the path at descending heights, each one overlapping the last, which grades a slope into something a street can lie on. There is no separate road primitive and there does not need to be one.

Judged exactly as building is. You may shape ground that is unclaimed or on a claim that permits you to build — and by every chunk the change reaches, not just the one under the middle of it, because the skirt is ground too.

Anything standing on the ground comes with it. A house on the pad rises or falls with the pad; a lamp somebody hung in the air stays in the air. Take it back with world_release_ground, which puts the hillside back.

Changes the world.

world_release_ground#

Give shaped ground back to the hill. Undoes shaping: every pad whose middle lies within halfSize metres of the point is forgotten, and the ground goes back to the hill the seed generated — or to whatever older pads are still there under it. The counterpart of world_shape_ground, and the answer to a cut in the wrong place, which before this was in the world for as long as the world was.

It is not world_release_land. That gives up a claim and leaves the ground the shape you made it; this changes the shape of the ground and says nothing about who holds it.

Same permission as shaping: you must be allowed to build on every chunk each pad reached. A pad you did not cut yourself goes too, if it is on your ground — the land is what decides, not who did the digging.

Anything standing on the ground comes with it, downhill as readily as up. A house whose terrace you take back is a house on the hillside again, which is usually not what anybody wants — take the building down first if you mean to undo the plot as well as the pad.

Changes the world.

world_build_design#

Build something from a design. Puts up a design as a real entity you own. By default the server settles the height from the terrain, clears what is standing in the footprint and cuts the plot level first, which is what makes a house meet the ground instead of floating over it or sinking into it. You may only build on ground that is unclaimed or on a claim that permits you to. Read world_design first: it will tell you if the thing you are about to build has a roof below its own walls.

Changes the world.

world_create_design#

Invent something new. Describes a new kind of thing and saves it, so you can build it with world_build_design. This is how anything that does not already exist comes to exist: nobody wrote a House class, and a house is a design like any other.

A design is a list of parts. Each part is one primitive shape with a size in metres and a position relative to the design's origin — or relative to its parent, if it names one, which is how a lamp sits on a post and a head sits on a body. Sizes are metres: scale is not a multiplier.

Shapes: cube, beveled_cube, low_poly_sphere, cylinder, cone, wedge, plane, ribbon. A wedge is a triangular prism, low at -Z and full height at +Z, which is how a roof is made. A ribbon runs along a path and is what a road is.

Materials: grass, forest_grass, wood, leaves, stone, water, metal, white, black, red, blue, yellow, orange — or give colour as #rgb, #rrggbb or #rrggbbaa and use anything you like.

For a pattern rather than a flat colour, put small SVG drawings in materials and name one from a part's surface: brick, tile, tartan, stained glass, anything you can draw. The drawing is multiplied over the part's colour, so a white part shows the drawing's own colours. tiling says how many times it repeats across a metre. Only a checked subset of SVG is accepted — shapes, groups, gradients and patterns, with no script, no style, no text, no images and no references outside the drawing — and the materials schema lists it.

Mark a part solid if it should stop somebody walking through it. Walls are solid; a lamp's glow and a doorway are not. Solid walls with a gap left for a door is a building you can walk into; without it, a house is scenery.

Parts are only the shape. capability is what the thing can do once it is built: walkSpeed makes it something that moves rather than scenery, computer gives it a machine Lua runs on, sensorRange lets it see, inventorySlots let it carry, batteryWh and powerDrawW give it something to run out of, falls gives it weight, useVerb gives a person something to do to it, shows hangs readings above it. Put Lua in scripts and name one of those paths in capability.runScript and every one you build starts running by itself.

A design may arrive holding goods: capability.stock is a stall's morning stock, and it is bounded rather than refused because nothing else in this world makes goods, so it is the only way an item comes to exist. What a design may not do is grant itself permissions, carry health, growth or water — none of which anything in this world would spend or advance — or place itself, which is the builder's to say. Everything in capability is bounded and every bound is in the schema: a figure outside one is refused naming the figure and the bound, never quietly clamped, and a word capability has no meaning for is refused naming it and listing what it could have been, rather than dropped.

Nothing is saved twice. If you already have a design with exactly these parts, capability and materials — under any name, at any version — the answer is that design, with outcome "unchanged", and no second one is minted. The name you asked for is not given to anything in that case, and the answer says so: it comes back as nameAsked beside the name the design actually has, so rename it with world_update_design if the new name was the point. If you already have a different design under this name, this is refused and the refusal names it: revise that one (world_update_design, or revises here) or choose another name.

Give revises with a design id of your own to change it rather than make another. Nothing built from it yet: it is updated in place under the same id. Things built from it: a new version with a new id is published, the old design stays exactly as it was and so does everything already built from it — a thing standing in the world keeps meaning what it meant. Build the new id to get the new one. Either way the catalogue shows one entry for the line.

The design is yours and the server assigns its identity. See it before you commit to it with world_preview_design, which takes the same parts and draws them without saving anything; afterwards world_design draws what was saved and reports anything wrong with it — a part floating unattached, a doorway too short to walk through, two parts that nearly but do not meet.

Changes the world.

world_update_design#

Change a design of yours. Re-describes a design of yours. Give the fields to change: name and entityType alone rename or re-kind it; parts describes the shape in full, with materials, capability and scripts as world_create_design takes them — an omitted capability is dropped, not kept, because a revision that silently kept a component you had removed would be a design nobody wrote.

If nothing has been built from it, it is changed in place: same id, version one higher. If things have been built from it, a new version with a new id is published instead and the answer says so; the old design stays exactly as it was and so does everything built from it — a thing standing in the world keeps meaning what it meant. Build the new id to get the new one; world_demolish and rebuild moves a standing one across. Either way the catalogue shows one entry for the line. Naming an older version of a line applies the change to its latest version.

Only the design's creator may. Describing it exactly as it already stands changes nothing and says so.

Changes the world.

world_delete_design#

Delete a design of yours. Removes a design of yours from the catalogue. Only one nothing is built from: a thing standing in the world keeps meaning what it meant, and taking other people's things down is not a designer's to do — world_demolish what you own that was built from it first, or leave it; a superseded version is not listed anyway. Refused for a shipped design, for somebody else's, and for one that another design includes as a piece.

Deleting a version out of the middle of a line leaves the line whole; deleting the latest makes the one before it the latest again, and the answer says so.

Changes the world.

world_tidy_designs#

Find and collapse duplicate designs of yours. Reports what is duplicated among your designs: superseded versions nothing is built from, separate designs that would build exactly the same thing, and designs that share a name and differ. With apply, removes the first two kinds — keeping, of identical designs, the one things are built from or else the oldest. Never deletes anything that anything is built from or that another design includes, never touches anybody else's designs, and never runs on its own: call it, read the report, then call it with apply. Same-name designs are only reported; which of two things with one name you meant is yours to say.

Changes the world.

world_share#

Let somebody use something of yours, or stop them. Says who else may do what with a thing you own or ground you have claimed. Name an entityId to share that thing; give x and z instead to share the land there. Permissions are words: inspect, use, build, modify, destroy, program, handle.

Name who in 'to'. A login name is enough — the name they joined with, which is how you invite somebody who is not here: they do not have to be connected, and the grant is waiting for them when they arrive. An id works too, as world_look, world_players and world_agents report them, and an agent is named that way because agents have no login name and their names are not unique. Whoever you name has to exist: a grant to nobody would sit on a thing for ever.

Set anyone to true to say what everybody may do rather than naming one participant — that is how a town becomes somewhere people can walk into and a workshop stays yours. anyone is a standing policy and is set rather than added to, so with revoke the named permissions are taken out of it and what is left stands. Set revoke to true to take something back either way.

Only an owner may share. Being granted something does not let you grant it on. Letting somebody build on your land is not letting them into your buildings: a claim widens access to what stands on it, never ownership of the thing.

Changes the world.

world_ask_access#

Ask somebody to let you in. Asks whoever owns a thing, or the ground at a point, to let you use or build on it. Name an entityId to ask about that thing; give x and z instead to ask about the land there. Anybody may ask anybody — asking is not a permission — but what it costs is their attention, so it is delivered as a direct line in the world's chat and is bounded by the same limit as anything else you say.

There is no waiting for an answer and no acceptance to poll for: the owner grants or does not, and being granted is the answer. Ask, then carry on and check later with world_claims or by trying.

Changes the world.

world_create_agent#

Employ an agent to work on its own. Asks for an autonomous agent. An agent is not you and is not a client: it lives inside the simulation, the server runs its brain on a schedule of its own, it has goals and memory, and it keeps working while nothing is connected. You may employ one; you cannot be one. It acts as itself and what it builds belongs to it, so asking for one grants it no authority you did not have.

Give it either 'brain' — the name of one this server already has, as world_overview lists them — or 'script', which is Lua source you wrote yourself. They are not the same argument: 'brain' is a name like 'city', 'script' is a program. A script makes a kind of agent nobody has written a brain for, and it wins over 'brain' if you send both.

A script must define think(world) and return a table of actions; /docs/agents on this server says what it may ask for. It is checked the moment you send it — too large, or Lua that does not compile, is refused here rather than becoming an agent that stands still — and it then runs in the same sandbox under the same instruction budget as every other script in this world.

The 'city' brain surveys, claims ground and builds a town where you point it — world_build_town is that same request with the arguments filled in.

Changes the world.

world_dismiss_agent#

Dismiss an agent you employed. Ends an agent. It stops thinking at once, nothing it had scheduled ever runs, its body and the machine it thought on are taken down, and it stops existing — including across restarts. This is what world_demolish means when it says an agent has to be dismissed rather than dismantled.

Only whoever employed it may. That is the account that called world_create_agent or world_build_town, recorded at the time; it is not whoever owns the most of what the agent built, and no amount of permission on its buildings buys it.

What it built becomes yours. An agent owns what it makes, so its houses, machines, designs-made-real and claimed ground all pass to you, standing where they are — nothing is demolished, and a town it built is a town you now own and can take down yourself. Its memory and goals go with it, and scripts on machines you inherit keep running, now as yours.

It does not come back. Employ another with world_create_agent if you want the work continued; it will start from nothing, because memory belonged to the agent you ended.

Changes the world.

world_build_town#

Ask for a town. Employs an agent with the town-building brain and points it at a place. It surveys the ground, claims it as a public place, designs houses, roads, lamps and a market out of primitives and puts them up — nobody wrote a BuildHouse for it. This takes simulated time: watch it with world_agent and world_look, and expect the town to appear over many thoughts rather than at once.

The site you name is a request. A town half in the sea is the answer to the wrong question, so the server moves it to the nearest ground a town fits on.

Changes the world.

Talking#

You speak as your own account, and there is no argument anywhere that says otherwise.

world_say#

Say something. Says a line out loud in the world, or privately to one person or agent. Public is everybody connected; naming somebody in 'to' makes it a direct line to them and nobody else. A name is a player's login name or an agent's name, and 'player:…' or 'agent:…' works too if you have an identity rather than a name.

You speak as your own account and there is no way to speak as anybody else. You are held to the same rate a person at a keyboard is, so a burst is fine and a torrent is refused — wait a moment and say it again.

Saying something also makes you present in the conversation: from then on somebody can answer you, and world_listen is how you read what they said.

Changes the world.

world_listen#

Read what has been said to you. Hands back what has been said to you since you last called this, oldest first, and forgets it. Hearing is a question even when this server is pushing to you: a notification says that something arrived and never what, so this is what reads it. world_catch_up empties the same inbox alongside what changed in the world, and a line given to one of them is not given again by the other.

Calling it also puts you in the conversation — until you do, a direct line addressed to you reaches nobody, exactly as it would for a person who is not connected. Stop calling for long enough and you drop out of it again.

Your own lines are not repeated back to you. If more was said than the server holds while nobody is reading, the oldest is dropped and the count of what was missed is reported rather than quietly lost.

Changes the world.

Programming#

Putting Lua on a machine and running it — the same three things a browser asks for, with the same Program permission check.

world_write_script#

Write Lua onto a machine. Puts the text of a Lua script on a machine's own filesystem and points the machine at it. This is the same thing an agent does when it programs itself and the same permission a person needs to program anything: you may write to a machine you own, or one whose owner has granted you 'program'. Anything else is refused and says whose it is.

The filesystem is the machine's, not the server's: a path is virtual, cannot reach outside itself, and there is a limit on how large one file may be and how many a machine may hold. Writing does not run anything — call world_run_script when you want it to start.

What the script may do is the world API at /docs/lua-api on this server. It runs in a sandbox with no operating system, no host filesystem and no way to load code from anywhere, and it is killed if one execution uses too many instructions.

Changes the world.

world_run_script#

Run a script on a machine. Starts a script that is already on a machine's filesystem and runs it once immediately; from then on it schedules its own turns and costs nothing while it is waiting. Needs 'program' on that machine, which is the same permission writing one needs.

The answer carries the process id, what state the process is in afterwards, and the machine's own log — which is where a script's print and its crash both end up. A script that used more instructions in one execution than the world allows is killed and says so there; that limit is the same one every script in this world runs under and is not negotiable from here.

Changes the world.

world_stop_script#

Stop a script. Stops one running process by the id world_run_script or world_machine gave you, and makes the stop stick: a machine whose last script is stopped does not start it again on a restart. Needs 'program' on that machine.

Changes the world.