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.

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
• 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 search_tools is the fastest way to find one. → tools

The working rhythm: survey → reuse → generate → author

Explore before you build. Start with search_tools to see what one-call operations already exist, then ls/rg/cat over /zero with bash, run Luau with execute to introspect, and query the registries. Then decide what to make. The single most common mistake is rebuilding something from scratch without first looking at what already exists.

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: search it with your ZeroMind tools (→ worlds). @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 + install ZeroMind's published content with your ZeroMind tools (→ 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: watch g.id, then g.asset_path is a real .glb to spawn (→ generating-assets-and-content)

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. The engine guide has 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:

• search_tools → use_tool: the engine's operations are packaged as named tools grouped into toolboxes. search_tools with no arguments lists every toolbox and what it's for; search_tools { query: "..." } keyword-searches. Found one? Run it with use_tool { toolbox, tool, args } (from inside execute, tools.use(toolbox, tool, args)). 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). Dropping to execute / bash is the fallback for when nothing fits.
• execute: run Luau live: 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, tools.list.

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 · scenes · engine · worlds · development · multiplayer · tools · scripting-and-tasks · troubleshooting · performance · generating-assets-and-content · vfs · discovering

Topics (man topics/<name>): building-a-game · physics · ui · audio · animation · shaders · materials · rendering · render-textures · input · compute

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.