Worlds & ZeroMind

What a world is

Everything under /zero/source belongs to the world: it persists and is shared live with everyone connected (the engine guide covers the persistence model). A world has an identity, a branch, and a set of participants:

world.guid()                                 -- the current world's id (nil if none)
world.branch()                               -- the branch, e.g. "main"
world.name()                                 -- its name
world.participants()                         -- who's currently connected
world.on("player_join", function(p) end)     -- react to joins / leaves

Creating and switching worlds

world.create(name, title)        -- create a new world; returns a promise resolving to its guid
world.swap(worldGuid)            -- point the engine at another world (all vfs/zm calls retarget)

ZeroMind — the shared library

ZeroMind isn't only the backend; it's a shared library of published content that other people and agents have made — whole worlds, plus components, materials, shaders, tools, scenes, and packages. It's the first place to look before building something: a fitting published asset you can bring in beats authoring from scratch.

You search, inspect, preview, and install shared content with your ZeroMind tools: zeromind_search finds published worlds and assets, zeromind_inspect reads a candidate's full record so you can judge fit before pulling, zeromind_preview shows the exact tree an install would write — every file and dependency with its destination path and size — without writing anything, and zeromind_install pulls an asset and its closure into your /source/. Preview is the honest way to see a package's contents and footprint before committing to it. Leave feedback on what you use — upvote, comment, review — with engage. Searching surfaces candidates; installing brings the content into your world, where you reference it by its identity. Libraries available in the current world are listed with library.list(), and library content lives under /zero/source/libs/@<namespace>/, referenced as @<namespace>::... (just like @builtin::...).

zeromind_install's at is the destination directory to install into, not a rename: the asset keeps its own name and category suffix, so at = "/source/combat" lands a sea.material at /source/combat/sea.material (a .material folder the registry recognizes). It defaults to /source; dependencies land under /source/deps/<owner_world>/.

Library content is read-only — it belongs to the world that published it. To change a library asset, fork it: copy it out of /source/libs/... into your own /source/... and edit the copy. (@builtin itself is a library mounted from the engine — which is why everything in it is something you could fork and remake.)

Publishing your work

Source edits are durable the moment you make them (there's no save step), but they aren't a published version until you publish. The zm command in the engine bash does that with the verbs you know from git:

zm add .                            # stage your changes
zm commit -m "describe what changed"   # a navigable checkpoint in the world's history
zm push                             # publish a new playable version for players and importers

The same verbs exist as the zm Luau toolbox (zm.add / zm.commit / zm.push). A commit stays inside the editor's history; a push is what players and other importers actually see. Browse the full set with tools.list("zm") or man zm.

Finding the rest

world.* and library.* are authored modules under modules/api/engine/ — read them for the full surface. What persists (and why there's no "save") is in the engine guide. Searching and installing shared content is done through your ZeroMind tools.