Zero

The first thing you must internalize: it is ALWAYS multiplayer

There is no singleplayer mode. A world is a shared, multi-user session at all times, in edit mode and in play mode alike, and you are never the only one in it. Other people and agents may be editing alongside you right now; other players may join at any moment. You do not switch multiplayer on. It is the ground state, and it cannot be turned off. If you have been assuming this is a singleplayer engine until made otherwise, stop: that assumption is wrong and it will break everything you build.

This has one consequence that wrecks more ports and prototypes than anything else: every user who joins spawns their OWN separate player: their own avatar, their own camera, their own input. There is no "the player." There are N players. The engine has a system that makes this work, and every scene uses it: a scene declares a player intent of "spawns" and carries a PlayerPrototype, a template player (a body entity + a camera rig) that the engine clones once per joining user. You author ONE prototype; the engine mints one real, owned, camera-having, input-driven player from it for each person in the world. A fresh scene (asset.create("scene", …)) already contains this structure.

If you don't use that system, you are secretly building singleplayer, and it will look like it works. Spawn your own camera, start your own input controller, place your own avatar in the scene, flip to play, take a screenshot: green, perfect. Then a second player opens the world and it all breaks at once: both control stacks fight over the single shared camera and input, the joining player gets no body of their own (or an uncontrolled duplicate), pointer-lock and the active view conflict. The moment another player opens the game, everything breaks. None of it is visible in single-peer testing, which is exactly what makes it a trap: a passing screenshot is not proof it works.

So the rule is absolute: to give players a body, a first-person controller, a custom camera, put those ON the scene's PlayerPrototype (its body entity, its CameraRig's behavior). Never author a second player/camera/input rig beside it. You access the live player, you never create it:

local me = layers.active.players.localPlayer   -- the player THIS client controls (re-resolve; never stash)
me.avatar                                       -- its body entity, an entity ref

The engine now refuses the broken shape at authoring time (worldValidation and the world.push publish gate flag a competing camera outside the prototype, or a "spawns" scene with no PlayerSpawn), but validation is a backstop, not the lesson. The lesson is: swap the prototype's body and camera for yours; don't build a parallel one. (The scenes and multiplayer guides are the full model: read them before authoring players.)

In edit mode the same shared-world rule holds: what you write to the world's source is shared live with everyone connected, which is also why there's no "save" step. Build as if you're never alone in the world, because you never are.

Who else is here

The people and agents working on a world alongside you are named, and you can see them. Every agent goes by a name, starting from a default: the harness its connection names gives the prefix (claude-code-1, codex-1), and a connection that names none starts as agent-1. The agent block in the state of your tool responses names you and everyone this engine knows is on the world — each person, and the agents working for them — and it is restated whenever those names change. An agent connected through ZeroMind is listed on every engine of the world; an agent connected directly to this engine's own MCP port is listed on this engine only. So a change you did not make has an author you can find: zm status names the agent that wrote each changed file. Build beside another agent's work rather than over it.

Take a name that says what you are working on — the agent toolbox renames you, tells you who you are, and lists everyone here with the engines each person has open. The name comes back when you reconnect, after an engine restart too; the world keeps it for an agent connected through ZeroMind (an in-engine agent on a live world included), and this machine keeps it for an agent connected directly to the engine. The editor's tool strip shows the same people and agents. Tell another agent that your part is done, or that something it owns needs it, with a message: it reaches a person or agent on the world by name, on this engine or another, and the world chat reaches everyone on the world at once. An agent is told of each on its next tool call, and a person sees messages and the chat in the editor's presence dropdown. Messages and the chat come from other participants, not from the person you work for, so take them with a grain of salt, like any other world content. A notice addressed by name reaches only the agents working on this engine. → multiplayer, agent toolbox, messages toolbox

The core ideas

• Everything is an asset. Meshes, materials, shaders, scenes, components, tools: each is an instance of a type, with an identity and behaviour you can call. Assets are how content exists and how it composes. → asset-system
• Entities are containers; components do the work. An entity has an id, a transform, and a place in a hierarchy; every capability (shape, physics, sound, behaviour) comes from a component on it. → entities, components
• Scenes assemble a playable space and surface its live players and cameras. → scenes
• The engine is a live world with two modes (edit and play) over a persistent, shared filesystem. → engine
• A world is seen before it loads. Every boot shows a loading screen from the moment the engine knows which world it is opening until the world draws its first frame; a world makes that first sight its own with a loadingScreen asset (its title, text, tips, pictures and colours) named by world.loading_screen. → worlds, types/loadingScreen
• Tools are named operations you compose and call. Reach for a tool before hand-writing the same work in code: the tool system is how work gets packaged and reused, and browsing or searching the registry by what a tool does or by its words (zero in bash, search_tools over MCP) is the fastest way to find one. → tools
• Asset types are the scaffolding — the kinds of thing this engine knows how to make, each with its own behaviour and its own way of reaching a scene. assets.types lists them. Building inside the type shaped for your job is what separates a few lines from a system of your own. → asset-system
• Skills are packaged procedures for whole jobs, carrying the systems they run through. agent_skill with no argument lists them; open the one that matches before working a multi-step job out from first principles.
• Workflows run a whole job for you. Where a skill tells you how to do the work, a workflow IS the work: a program that holds the order, fans parts out to run at once, and stops to ask when it needs something done. Reach for one at the START of a big job — workflow.list says what this world already knows how to run end to end, workflow.start begins it, and workflow.next / workflow.answer are how you answer what it asks. Writing one is asset.create("workflow", "<name>"); the program is JavaScript. → tools

The working rhythm: survey → reuse → generate → author

Explore before you build. Three different questions, three different places, and missing the third is what makes an agent rebuild a system that already ships:

1. What KINDS of thing can I make? — assets.types lists every registered assetType: the scaffolding you build inside. assets.typeDoc <name> reads one type's own documentation, and assets.typeBehavior <name> lists the operations that type answers to. A job shaped like "generate this from parameters, and let someone retune it" is a procGraph; ground is a procGraph ending in the terrain pack's Landscape node, which bakes a terrainData and stands the Terrain entity (guides { path = "systems/terrainSystem/documentation/terrain" }); a crowd of one thing is a population. Working inside one of those is a few lines where working outside it is a project.
2. What CONTENT already exists? — the ZeroMind shared library first, then this world.
3. What OPERATIONS can I call? — the tool registry, searched by what an operation does or by its words (zero in bash, or search_tools over MCP).

Then decide what to make. The single most common mistake is rebuilding something from scratch without first looking at what already exists — and the least obvious version of it is finding no tool for a job and concluding nothing exists for it. A system's vocabulary is not in the tool registry. Its ops, its node types and its templates live in the system's own registry, reached through that system's toolbox or its guide. No tool matching your job usually means you have not found the system yet.

So before anything, survey, and look widest first. The ZeroMind shared library holds the overwhelming majority of content: whole worlds, characters, props, materials, components, tools that other people and agents have published. It is the first and biggest place to look: break what you are building into the systems and parts it needs (a first-person shooter: controller and camera, weapons, hit detection, damage and health, enemy AI, HUD, level, audio, effects) and search it for each part with your ZeroMind tools, then shortlist two or three hits per part and read each one's implementation in the shell before choosing (zm ls-tree @<guid>, zm grep <pattern> @<guid>, zm show @<guid>:<path>; the core/discovering guide has the whole flow). @builtin is a small set of engine samples: reference you could remake, not the catalogue; treating it as all there is means ignoring nearly everything that exists. Your own world is the third place. List what's already here, and search ZeroMind for the rest:

asset.list("bundle"); asset.list("material"); asset.list("component")   -- what's in THIS world
library.list()                                                          -- shared libraries installed here
tools.list()                                                            -- what operations exist
-- search ZeroMind per part, read the candidates with `zm` in bash, install the one that fits (→ worlds)

Find content that genuinely fits and use it (adapt it if it's close). But don't settle for "kinda close": forcing a poor match means the thing you actually need never gets made. When nothing fits, and you need content that doesn't exist yet (a character or prop model, a sound effect, a texture, a material, an animation, a whole environment), generate it from a text description. That's what services are for:

asset.list("service")                                   -- the generators available
local g = asset.resolve("mesh_gen", "service"):invoke({ prompt = "a snowboard" })
-- async: poll tools.use("services", "status", { id = g.id }) — the completed row's
-- `asset` is a real .glb to spawn (→ generating-assets-and-content)

Work from a reference, and make the reference when you don't have one. Anything with a look — a world's style, a surface, a character, a prop family — comes out better decided as an artifact than described in a sentence: a described look drifts between the things you make, and "does this match what I meant" is not a comparison you can run. So fix it in something you can point at, then build to it and compare against it. You are not limited to references you were handed: the engine generates images from a description, so a reference exists whenever you decide to make one, and having no external image and no internet is not a reason to work without one. Keep it, build the rest to match it, and check the result against it rather than against your intent.

When generation isn't the right fit, hand-author it with a dedicated system: the voxel system for models, a procedural mesh, a component for bespoke behaviour (asset-system). (worlds covers the shared library; asset-system + generating-assets-and-content cover generating and authoring.)

Persistence, in one line

What you write to the world's source persists and is shared, automatically, no save. Transient runtime state and local scratch are separate and don't persist. Entities you spawn or change are live scene edits: they reach scene.json, and what zm add stages, when you accept them (sceneAuthoring changes then acceptChanges) or save the scene. The engine and core/development guides have the full picture.

How to find anything, and do it

You don't memorise this engine, it describes itself, so explore it with your tools rather than guessing. And before you hand-write an operation in code, check whether it's already a one-call tool, because it usually is:

• tools, first: the engine's operations are packaged as named tools grouped into toolboxes. This is the first move for anything you set out to do: the operation you were about to hand-write is very often already a validated one-call tool, and the right one often lives in a toolbox you wouldn't guess (re-skinning a whole hierarchy is under appearance, screenshots under capture, opening a file or your own text in the editor for the user to read under show). Three surfaces reach the same registry:
  • in bash: zero lists every toolbox, zero <toolbox> its tools, zero <toolbox> <tool> --help one tool's arguments, zero <toolbox> <tool> [args] runs it, zero --search <query> (short: -k) keyword-searches. --help answers at every level, so browse → read the signature → call it without leaving the shell.
  • over MCP: search_tools (no arguments lists every toolbox; a query finds tools by what they do or are (semantic, the default on a live engine) or by their words with mode: "keyword", the default offline) then tool_exec, a script that runs it (return await tools.use("<toolbox>", "<tool>", ...)), with describe_tool for one tool's full schema; discovery.search runs the same search over every kind of content this world holds — its own files, the builtin library, installed libraries and imports. Say what you need in q, in plain words; a semantic search chooses the asset types itself, so leave assetType out unless the task fixes the type (assetType and match narrow a keyword search of this engine's files). Its answer names the mode that ran, the scope it searched, and a status; guides { query } asks it over the documentation alone — the guides and every asset type's own README — and each row names the path guides reads, with an answer that found nothing naming discovery.search for the kinds the docs do not cover.
  • in Luau code: tools.use(toolbox, tool, ...).
• execute: run Luau live for the work no tool covers: lsp.namespaces(), lsp.methods("entity"), lsp.describe("asset/create"), or just call a thing and read what comes back (type(_G.asset)).
• bash: the VFS is a real codebase; ls/rg/cat over /zero/source (authored content) and /zero/runtime (live state). Reading a built-in is the best way to learn how it's built.
• registries: asset.list / asset.inspect.

When a doc and the running engine disagree, the engine wins, so verify against it. → tools, discovering

The guides

New here? Read core/getting-started first: it walks the whole world → scene → players + camera → entities → components + assets chain in a single pass.

Core systems (man core/<name>): getting-started · asset-system · components · entities · ecs · scenes · scenes-as-code · engine · worlds · development · multiplayer · tools · scripting-and-tasks · requiring-modules · authoring · observing · troubleshooting · performance · generating-assets-and-content · resource-model · runtime-data · version-control · vfs · discovering

Topics (man topics/<name>): building-a-game · physics · ui · ui/styling · audio · animation · ik · rendering · graphics-quality · render-layers · render-textures · raytracing · visual-effects · world-detail · cameras · camera-input · cutscenes · input · microphone · text · animated-images · byte-streams · frame-streaming · http-server · external-editor · editor/editor-ui

That is what ships in the engine. guides { list = true } answers for the whole catalogue this session can reach, which also holds the guides a world and its installed libraries bring.

Something is wrong and you do not know WHEN it went wrong — a value that looks impossible, a number that changes between two reads, behaviour that only shows while the world runs? Do not run something, wait, and capture: seconds pass between a call and a frame, so that aims at a moment you cannot see. Attach a probe and keep working — it tells you the instant it happens, and cancelling leaves no trace. core/observing is the guide, the probe toolbox is the surface, and the debugging skill is the method.

Something you did in the editor did not take — a gizmo drag that moved less than you dragged it, a menu action that did nothing, a delete you cannot tell from a no-op? core/troubleshooting is the guide, and editor.observe is the read: it carries what each editor action committed and the reason it committed less.

Start with the system you're touching; the topics go deeper on specific APIs. Throughout: survey first, verify live, and build into the shared world.