# edui.app (module)
The `edui` reactive core. An `App` owns one `ui.*` screen and turns the
string-callback-id protocol into ordinary closures.
`ui.*` dispatches interaction through string ids because closures cannot cross
the FFI boundary: a widget carries `props.onClick = "<id>"`, and the screen's
registered env receives `onCallback(id, data)`. An `App` hides that — during a
build it allocates an id per closure and records id→closure, and its single
`onCallback` looks the id up, calls the closure, and rebuilds.
## Surface
- `new(screenName, opts?) -> App` — `opts.layer` is a render-layer mask applied
via `ui.setScreenRenderLayer` on first register; `opts.callbackKey` overrides
the env key.
- `App:mount(builderFn)` — register the callback env, run the first build.
`builderFn(app) -> widgetTree` is re-run on every rebuild.
- `App:cb(closure, key?) -> id` — the id to place in a widget's `on*` prop. Pass
a stable `key` so the id survives a rebuild, which is required for anything
the renderer tracks by id (focus, drag, `ui.widgetState`).
- `App:dispatch(id, data) -> handled` — what the broadcast calls. Returns false
for an id belonging to another surface so a host can keep routing.
- `App:markDirty()` / `App:rebuild()` — a rebuild requested *during* a build is
coalesced into a single follow-up, so a handler that mutates state and a
builder that reads it never recurse.
- `App:unmount()` — release the env and unregister the screen.
- `current()` — the app whose builder is running right now, or nil outside a
build. The `edui` primitives read this, which is why an author passes a
closure and never threads the app through every call.
Builder errors are logged rather than thrown, so one bad build never wedges the
editor.
```luau
local edui = require("modules.edui")
local app = edui.createApp("myPanel")
app:mount(function(a)
return {
type = "vertical",
children = {
{ type = "button", props = {
text = "Save",
onClick = a:cb(function() save() end, "save"),
} },
},
}
end)
```
# cmdPalette
The editor's command palette: the whole engine tool registry under one
keystroke. The menu bar's Tools button (Ctrl+K) opens a floating card —
type to search every toolbox by name and purpose, pick a tool, and its
typed argument schema renders as a form of real controls: text for
strings, numeric fields for numbers, a checkbox for booleans, option
chips for string-literal unions, three axis fields for a Vec3, and an
options table expanded one level into its own typed rows. Run executes
the tool and shows the returned value and stdout in place.
The form is generated from `tools.get`'s schema, so every registered
tool is reachable and a new tool appears with no UI work. Consumed by
`edui.topbar`, which mounts it beside the menu bar and re-mounts it
through `modules.watch` when this module's source changes.
# create
What the editor's Add menu creates. `edui.create` makes an empty entity,
each built-in primitive the mesh registry resolves (cube, sphere, plane,
...), a point light, a spot light and a camera, five metres along the
editor camera's view and no lower than half a metre above the ground, as
one undoable step, and selects what it made.
`declare` puts each of them in the editor command registry under the
`add` menu (`add.cube`, `add.light.point`, `add.camera`, `add.empty`, ...).
The top bar's Add menu and the Hierarchy's `+` menu both list every
command declared under `add`, so a world or a panel that declares one of
its own (`commands.declare{ id, title, category, menu = "add", order, run }`)
appears in both.
# editorLayout
An editor dock arrangement as an asset: a `<name>.editorLayout/` folder whose
`layout.yaml` names either the panels the arrangement holds, each with the
region it seeds into, or a captured arrangement in `dock.json` that the Save
layout dialog wrote from the live dock. Registering an instance adds it to the
editor shell's layout list, so it applies by name from the Window menu, the
`editor.layout` tool, or `--layout <name>` at boot.
```yaml
# recording.editorLayout/layout.yaml
title: Recording # the name the layout switch shows
title_key: layouts.recording.title # optional: a catalog key; the switch reads the title from the catalogs in the editor's language
description: The scene and the first agent's terminal side by side.
description_key: layouts.recording.description # optional: the same for the description
slot: a # optional: a | b, the side of the layout switch this layout stands for until a person assigns another
mode: full # full | simple: simple keeps the layout's panel set; a panel that registers later waits in the Window menu
toolstrip: shown # optional: hidden takes the gizmo buttons, who-is-here counters and live indicator off screen
panels:
- { id: viewport, dock: center }
- { id: agent, dock: right }
fractions: { right: 0.42 }
```
The editor switches between two layouts, side A and side B. A layout declaring
`slot: a` or `slot: b` is what that side stands for until a person assigns
another layout to it; the shell keeps the person's choice per world on their
own machine. A world layout of the same name stands in for the built-in one.
`title_key` and `description_key` name catalog messages, looked up in the
world's `locales/`, then the editor's own, then the library's. While a catalog
holds the key, the Window menu and the layout switch show its message in the
editor's language; otherwise they show `title` and `description` as written.
A layout the editor ships lives in the built-in library; one a person saves
lives in the world at `/zero/source/editor/layouts/`. Both are the same asset,
and a world layout of the same name stands in for the built-in one.
## In the Inspector
Layout: the layout's title, description, switch side and mode, whether it carries a captured dock, each panel it places and where, and **Apply layout**, which arranges the editor this way (and says why when it cannot).
# editorPanel
A dock tab in the editor, as an asset. A `<name>.editorPanel/` folder carries an
`init.luau` that returns the tab's spec:
```luau
local edui = require("@builtin::~edui.framework")
return {
title = "My Tab", -- the tab's label (`label` is accepted too)
order = 60, -- sort position in the menu
dock = "bottom", -- seeds the FIRST arrangement: left | right | bottom | center
menu = "scene", -- which top-bar menu lists it; an unknown name creates that menu
startClosed = true, -- registered closed; opened from the menu
build = function() -- the tab's body, called again whenever it should change
return edui.panel{ body = edui.text{ text = "hello" } }
end,
}
```
`build` is the only required field. The tab id defaults to the folder stem
(`myTab.editorPanel` → `myTab`); an explicit `id` overrides it, and a duplicate
id replaces the prior registration. An init may return a LIST of specs when one
asset carries several tabs — a spec this registration no longer declares has its
tab taken down.
The spec is forwarded whole to `edui.shell.addPanel`, so anything the shell
accepts (`badge`, `badgeColor`, …) works here; `man edui.shell` is its contract.
`build` may return `nil` to mean "nothing changed, keep what is drawn" — the
shell rebuilds open tabs on a timer, and a panel that re-publishes an identical
tree pays for it. Only the ACTIVE tab of a dock leaf is rebuilt at all.
An `init.luau` that fails to load does not break the editor: its tab comes up
carrying the failure — the path and the error, selectable — so a panel that will
not compile says so where you would look for it.
Every instance of this type becomes a tab: the ones in the open world, and the
ones the built-in library ships, on the same terms.
Adding a tab to a project is creating a new `editorPanel` asset: it comes from
the template above and registers its tab at once, wherever under `/source` it
was made (`editorPanels/` is the type's conventional folder). Editing the
`init.luau` re-registers the tab, deleting the folder removes it. Nothing
registers panels by name anywhere.
`guides { path = "editor/edui/edui" }` — the guide beside this type, inside
the edui package — covers the build model, where panel state lives, and the
`edui.*` surface a body draws with.
## In the Inspector
Panels: each panel id this file registers (`panelRef:panelIds()`), whether it is open, an **Open** action for it, and **Open** for the source. A file whose init.luau does not load says why.
# edui guide
Building editor panels: creating the `editorPanel` asset, the spec it returns,
how a panel is drawn and redrawn, the whole widget vocabulary, and how a panel
talks to the selection and the dock. The content lives in `guide.md`; this
README is the asset summary.
# edui (module)
The editor UI framework, built on the CSS-parity `ui.*` surface. `edui` is
**editor-only** — gameplay and normal UI author raw `ui.*` widget trees
(`{ type, style, props, children }`) and need no framework. `edui` provides the
one thing a framework earns its keep for: editor chrome — a reactive app, a
dock shell, and chrome primitives (panels, trees, toolbars, inspector rows,
context menus, drag-and-drop). It replaces the deprecated `zui` for the editor.
## The reactive core (`edui.app`)
`ui.*` dispatches interaction through **string callback ids** — a widget
carries `props.onClick = "<id>"`, and the screen's registered env receives
`onCallback(id, data)`. Closures can't cross the FFI boundary, so raw `ui.*`
makes you manage those ids by hand.
An `edui` **app** hides that. During a build it allocates an id per closure and
records id→closure; its single `onCallback` looks the id up, calls the closure,
and rebuilds:
```lua
local edui = require("@builtin::modules.edui")
local count = 0
local app = edui.createApp("counter", { layer = editorMask })
app:mount(function(a)
return {
type = "vertical",
children = {
{ type = "label", props = { text = "count: " .. count } },
{ type = "button", props = { text = "+1",
onClick = a:cb(function() count += 1 end, "inc") } },
},
}
end)
```
- `app:cb(closure, key?)` — allocate a callback id for `closure`. Pass a stable
`key` so the id survives rebuilds (required for focus / drag / `ui.widgetState`).
- `app:dispatch(id, data)` — what the broadcast calls; routes id→closure and
rebuilds. Returns whether this app owned the id.
- `app:markDirty()` — request a rebuild (coalesced during an in-progress build).
- `app:rebuild()` / `app:mount(fn)` / `app:unmount()` — lifecycle.
- `edui.current()` — the app whose builder is running (the primitives use it so
you don't thread the app through every call).
Builder and handler errors are logged, never thrown — one bad build never
wedges the editor.
# help
The editor's Help menu and the dialog it opens. `edui.help.open(page)`
shows one page over the editor:
- `start`: Getting started, the first things a person does in the editor
(add an object, select it, move it, look around and move the view, play,
save the scene, build with DotBot, change the layout, find more). Its
Help menu entry names moving the view, the first thing a person asks.
- `shortcuts`: the keyboard shortcuts, read from the live keymap every
time the page builds: each control a live input map binds to the
keyboard or the mouse, keys and mouse input named the way a person
names them (`Left Ctrl`, `Mouse movement`, `Mouse wheel`), a control
whose gate waits for the right mouse button held prefixed with that
hold, and each command declared on a key no control already answers
(`edui.help.shortcuts()` returns the same rows as data).
- `about`: the editor and the world it is bound to.
`declare` puts `help.start`, `help.shortcuts`, `help.docs` (the Docs
panel, its search field focused) and `help.about` in the editor command
registry under the `help` menu. The top bar's Help menu lists every
command declared under `help`, so a world or a panel adds an entry by
declaring one there.
# edui.inspector
The Inspector as an ordered list of **sections**. A subject — an asset, or a
component on an entity — gets generic sections, merged with the sections its
declarer's `inspector.luau` adds or replaces, in the order that file names.
```luau
local Inspector = require("@builtin::editor.edui.inspector")
local sections, ctx = Inspector.assetSections(ref, asset.inspect(ref))
local nodes = Inspector.render(sections, ctx) -- section cards
local nodes = Inspector.renderAsset(guid) -- the same, from an asset id
local sections, ctx = Inspector.componentSections(entityId, "Camera")
local nodes = Inspector.render(sections, ctx, { nested = true }) -- a component card's body
```
## Sections
A section is `{ id, title, icon?, open?, build(ctx) -> { node } }`. The generic
asset sections, in default order, are `identity`, `problems` (present only
when `asset.validate` reports any), `tags`, `move`, `settings`, `preview` and
`operations` (see `assetSections.module`). A type declares its
own in the file its `type.yaml` names:
```yaml
inspector: { type: "inspector.luau" }
```
That file returns `{ sections?, replace?, order? }`: sections it adds (placed
before `operations`), generic sections it replaces by id, and the ids to put
first. `material.assetType/inspector.luau` is a worked example, and
`@builtin::assetTypes.assetType.shared.inspector` documents the declaration.
A component on an entity has one generic section, `settings`: its public
fields as typed controls over the live component, three-number colour and
vector aliases as one grouped control, each edit checked against the schema
and written as one undoable operation. A component that ships an
`inspector.luau` beside its `init.luau` (named by `component.assetType`'s
`inspector: { instance: "inspector.luau" }`) adds, replaces and orders
sections of its card the same way; its sections read `ctx.component` and
`ctx.selection.id`. `SceneModule.component/inspector.luau` is a worked example.
A declaration that cannot be read, or that names a section that is not there,
shows its problem as a first `inspector-problem` section while every other
section still renders. Every build runs through
`Inspector.buildSection(section, ctx) -> (rows, problem?)`: a build that raises,
or returns anything but a list, shows its error inside that section alone.
## The Context
Every `build(ctx)` receives one Context, made by `Inspector.valuesContext`:
| Field | What it is |
|---|---|
| `ref` | the inspected asset (on an entity, the component asset) |
| `info` | `asset.inspect(ref)` |
| `schema` | `asset.schema(ref)`, `settingsOf` resolved |
| `schemaProblem` | why a declared schema did not resolve |
| `settings` | the current values |
| `setSettings(patch)` | checks the patch with `Field.checkSchema`, then writes it as one undoable operation named for the field; answers `(ok, violations)` |
| `rejected` | field path -> the message of its last rejected edit, for this subject only |
| `selection` | `{ scope = "asset" \| "entity", id, component?, name? }`; on an entity, `component` is the component's identity and `name` the name the entity lists it by |
| `component` | the live component proxy (entity scope) |
| `nameOf(id)` | the name an entity-reference field shows for an entity id (entity scope) |
| `widgets` | the edui framework table (`field`, `schemaField`, `section`, `button`, `text`, `vbox`, `hbox`, ...) |
| `keyPrefix` | the callback-key namespace for this subject |
| `refresh()` | rebuild the Inspector after a write that moves no revision |
| `actions` | when set, the ids of the Settings actions offered (`{ reset = true }`); nil offers every action that applies |
| `parts` | the building blocks a section composes: facts, lists, tables, asset and entity links, actions, a file opener, problems, swatches, a content-versioned cache, an lsp check and typed values (`parts.module`) |
`Inspector.valuesContext{ subject, schema?, schemaProblem?, values?, write, ref?,
keyPrefix?, info?, selection, component?, nameOf?, actions? }` is the one way to make a Context: `write(patch)`
performs a patch already checked against the schema.
## The rest of the API
- `Inspector.mergeSections(generic, decl, problem, file)` — the merge and order.
- `Inspector.componentSections(entityId, componentName)` — a component card's
sections and Context; `Inspector.componentSettingsRows(ctx)` is its generic
`settings` section's body.
- `Inspector.componentValuesSignature(entityId, componentName)` — text that
moves whenever one of the component's declared fields holds a different
value (an edit, an undo, a script's write); a panel folds it into its build
signature.
- `Inspector.typeSections(ref)` — the sections `ref`'s type declares, plus
Settings when it has values; what the inline editor under an asset chip shows.
No other generic section is built for it, so it runs no validation. Nil when
the type declares no `type:` inspector.
- `Inspector.render(sections, ctx, { nested = true })` — titled groups inside a
card, for the inline editor.
- `Inspector.signature(assetId)` — text that moves whenever what the asset
view shows can have moved: the asset folder's content version (the change
dispatcher moves it after a write inside the asset reaches its type's hook —
an edit, an undo or redo, a peer's write) and the settings values file's. A
panel folds it into its build signature; `edui.widgets.openEditorsSignature()`
is the same for every open inline editor.
- `Inspector.buildSection(section, ctx)` — runs one section's build and judges
it: `(rows, nil)`, or one error row and the problem text.
- `settingsSection.fields(ctx)` — the field rows of the whole schema without
the actions beneath them.
- `settingsSection.fieldRows(ctx, fields)` / `settingsSection.actionRow(ctx)`
— the two halves of `settingsSection.build`, for a section that shows part of
a schema and acts on all of it.
- The Context, Section and Declaration shapes are exported as types:
`Inspector.Context`, `Inspector.Section`, `Inspector.Declaration`.
- `Inspector.release(keyPrefix)` — forget the rejections, section
disclosures and parts state (action failures, file checks, and cached values
no other open Context read) kept under a Context's key prefix and the
prefixes nested in it; a closed inline editor calls it for its own.
- `Inspector.epoch()` — moves on every disclosure, rejection and write the
Inspector records; a panel folds it into its build signature.
- `Inspector.settingsSection` — the Settings section (`settingsSection.module`).
- `@builtin::editor.edui.inspector.presetActions` — the Settings section's
Save as preset / Apply preset… actions, and `presetsFor(declarer)`, the
presets whose target is a declarer. `preset.assetType/inspector.luau` is
the preset's own view: its target and its values edited through the
target's schema.
# agentView
The scene in the centre and DotBot on the right, nothing else, with the toolstrip hidden. It is the layout a fresh editor comes up in, and the one the Agent view side of the layout switch stands for until a person assigns another layout to layout A.
# agents
The scene above the three harness terminals, Claude Code, the Codex CLI and the Cursor CLI, with the Hierarchy and Inspector beside it.
# default
Full UI: the authoring layout, with the Hierarchy on the left, the Scene in the centre, the Inspector on the right, and Files with the Console below, Files in front. It is layout B until a person assigns another layout to it, and it keeps the name `default` for `--layout default` and `editor.layout`. Every other panel is a Window menu entry away.
# minimal
The scene alone, viewport first, with the toolstrip hidden: for sessions driven through agents outside the window.
# recording
The scene and the first agent's terminal side by side and nothing else, so a recorded agent run shows what the agent did and what it saw.
# watch
The scene fills the centre and the newest frame an agent captured on this
engine sits below it, so the person watching sees the same picture the agent
got without opening anything. Apply it from the Window menu, with `editor.layout`
or with `--layout watch`.
# assets
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# capture
The newest frame a capture produced on this engine, drawn full-pane, with the
shot's number, where it was rendered from, which pass it holds and its pixel
size on the toolbar.
The frames come from `@builtin::tools.capture.feed`, which every capture
publishes to. A frame still on the GPU is drawn from its own render target, so
the picture is the one the engine already holds; a capture given a `path` is
drawn from the file it wrote there. The `watch` layout puts this tab under the scene, so
the person at the window sees the same frame the agent got.
# clientView
The viewport of the sub-client an agent works in, live, as the VIEW action on
the agent's row of the people dropdown chose it, with how long ago the picture
was taken on the toolbar.
While the tab is open it asks the engine once a second to keep the view going
(`__presence.viewClient`). The engine takes a small capture of that sub-client's
viewport about once a second, the same capture an agent's `capture` makes there,
and writes it into this session's scratch under `/source/tmp/client-view/`,
which the tab draws. The sub-client's own view and the user's are untouched, and
the engine stops taking pictures a few seconds after the tab closes.
# code
The editor's code panel: the file the Files panel opens on a double-click, in
a code editor with line numbers, folding for Luau, syntax colour from
`modules.highlight`, the LSP's diagnostics under the lines they name, and a
Save button. The same panel shows a diff (`openDiff`) — the change an agent
made, hunk by hunk with both line-number gutters.
Save writes the file's source in play as in edit: the saved text reloads into
the running play session and is still the file's text after Stop.
The code panel is the user's own editor. An agent that wants the user to read
a file opens it in a panel of its own with the `show` toolbox: `show.file`
for a file, folder or asset, `show.text` for text the agent wrote.
## Reading a symbol
In a Luau file the pointer over an identifier shows what it is where it
stands. `lsp.symbolAt(path, line, col, name, chain)` runs the same typed pass
a check of the file runs — the API surface, the globals the file's context
injects, and the module every `require` names — so a local bound to a
required module shows that module's exports, and a value reached through it
shows the type the module declared. The hover leads with a header in code:
`function entity.spawnSynced(name: string) -> entityProxy`,
`local total: number`, `(parameter) n: number`, `(field) crate.component: {
12 members }`, `namespace entity: { 41 members }`, `module Highlight: { 6
members }`. Under it comes the documentation — the comment block above a
declaration the file makes, the header comment of a required module, or the
API page filed under the access path — then the parameters it documents, its
examples as code, then a table's members by name. A word in a
comment or a string is no reference, so nothing shows for it, and a file that
is not Luau shows nothing at all.
A secondary click on an identifier opens a menu on it:
- **Go to Definition** puts the caret on the declaring line and scrolls it
into view (`revealLine` + `revealEpoch` on the editor), when the file
introduced the name; an API global has no line to go to and the item is
dimmed.
- **Inspect** puts the hover's header on the toolbar's status line.
## Exports
The panel record carries `openFile(path)`, `openDiff(title, files)`,
`pathHealth(path)` and `healthEpoch()` for the panels that reach it through
`edui.shell.panel("code")`.
# docs
The editor's Docs panel: an index of every `guide` asset the engine can
reach, grouped by its identity segment and narrowed by a filter box, beside
the open guide rendered as markdown.
The index follows the guides the VFS holds. A guide written, copied, removed,
renamed or moved anywhere under `/zero/source/` (the world's own guides, its
packages' and its libraries'), on its own or inside a folder that holds it, is
listed as it stands on the panel's next build, with no reopen or reload. The
open guide shows its current text, stays open through a move, and gives way to
the index when it is removed.
## Links
A `[text](target)` in a guide is a link. Clicking it, or pressing Enter or
Space once Tab has brought the keyboard focus to it, goes where it points:
- another guide, by any spelling `open` takes (`[Bindings](controlsKit.bindings)`);
- a heading, by its anchor: `#anchor` in the same guide, `guide#anchor` in
another (`[Slots](save-kit#save-slots)`). A heading's anchor is its text in
lower case, with punctuation removed and spaces turned into `-`;
- a file or an asset, by its VFS path, a path relative to the guide's own
folder (`[the module](../saveKit.module)`), or its name, identity or guid,
which opens in a tab of its own;
- a web address (`https://...`), which is copied to the clipboard for a
browser.
A link that names nothing, or a heading the guide does not hold, puts a note
above the guide saying so.
## Exports
The panel record carries `open(nameOrIdentity)`, `invalidate()`,
`renderMarkdown(md, opts?)` and `followLink(target, from?)`. `invalidate` drops the index so the next build reads the
registry again; the panel does that itself on every guide change. `open` takes
any spelling `guides.read` opens a guide by: the name the index shows, the
guide's asset identity (`controlsKit.my-guide`), the path `guides.list` lists
it under (`controlsKit.package/my-guide`), its guid, the VFS path of its
folder, or a shorter spelling that names one guide. `renderMarkdown` is the
same markdown-to-widgets rendering the panel shows a guide with, for another
panel that shows prose (the World panel's body, a markdown file's preview);
its links are live, a relative path and a `#anchor` read against `opts.from`
alone, and a link that ends in a note brings the Docs panel forward to show
it. `followLink`
follows a link the way a click does and answers what it reached (`"guide"`,
`"heading"`, `"file"`, `"web"`, or nil with the note saying why).
# edui_panels.entities (module)
The Entities/hierarchy panel on edui — the first editor panel ported from zui.
It queries the live ECS entity snapshot (`queryEntitiesTable`), nests it by
`parentId` under each entity's scene layer, and renders it with `edui.tree`: a
real outliner with chevron disclosure, an icon + name + live-asset chip +
sync/lock badges per row, a per-layer visibility toggle, single-click selection
wired to the shared `selection` service (so the viewport outline follows), and a
toolbar of the common entity ops (spawn / duplicate / delete / focus) plus a
search filter that keeps matches in breadcrumb context.
## Selection round-trip
A row click calls `selection.set(entityScope, …)`; the panel also subscribes to
that scope, so a selection made anywhere else (viewport, gizmo, another panel)
rebuilds the shell and moves the tree highlight. Refs carry stable ids, so a
rename or reparent never invalidates the selection.
## Registration
Requiring the module registers it into `edui.shell` (`M.register()` at load).
The `edui_panels` barrel requires it, so pulling in the barrel brings this panel
up. Ops route through `editor_ops` (undo-wrapped delete/duplicate) and the
`entity` / `layers` globals.
# execute
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# files
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# health
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this editorPanel provides and who
consumes it, then delete both comment lines. -->
TODO: describe this editorPanel.
# input
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# edui_panels.inspector
The Inspector panel on edui — the selected entity's identity, relationships and
components, or the selected asset, rendered on the CSS-parity `ui.*` surface
through the edui field layer.
It reads the shared entity selection (`modules.api.editor.selection`).
Sections cover the entity header, Hierarchy (parent/children navigation),
Networking (sync), Transform (position/rotation/scale), and each component as
a card with an enable toggle.
A component card's body is the component's sections, rendered through
`edui.inspector` (`Inspector.componentSections` + `Inspector.render`): the
generic `settings` section shows the component's public fields — the schema
`asset.schema(component)` reads from its `public` table — as typed controls,
checks each edit against that schema and writes it to the live component as
one undoable operation. A component that ships an `inspector.luau` (the file
`component.assetType` names as `inspector: { instance }`) adds, replaces and
orders sections of its card; `SceneModule` and `Generator` replace `settings`
with their own.
A selected asset shows as its ordered sections (`Inspector.renderAsset`):
identity, tags, move, settings, preview and operations, merged with the
sections its type's `inspector.luau` declares.
Component schema is read through the backing asset, never through Rust.
# lsp
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# luauProfile
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# Memory
The Memory panel shows what the agents working in this world remember, so
the person can read it, correct it and take back what they do not want
followed. The World tab lists the world's memories, newest first: each with
its name, description, who wrote it (the agent, its harness and the person it
works for) and when. Selecting one opens its description and text to edit,
with Save, Discard edits and Remove (a second click confirms).
Recent changes lists every write, edit, removal and undo, newest first, each
with Undo, which puts the memory back as it stood before that change. The
search box narrows the list to the memories whose name, description or text
mention a word, with the matching lines.
A save made while an agent wrote a newer version, or an undo of a change the
memory has moved on from, shows both versions side by side and lets the
person keep one. The panel opens from the Agents menu and from the DotBot
panel's Memory button; `reveal(name)` opens it with a memory selected and
`search(text)` narrows it. Its tab is the world's memories, the scope the
editor's own code reaches; the person's personal memories answer their
agents' tool calls.
# multiplayer
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# physics
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# profiler
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# rendering
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# edui.panels.runtime (module)
The Runtime panel on edui — live engine-runtime readouts in three collapsible
cards, sampled at the shell's liveness-refresh cadence.
## Data
- `getLuauVmDataTable()` → `{ memory_kb, scripts = [{ name, avg_update_ms }] }`.
- `getMemoryDataTable()` → `{ process_rss_bytes, heap_allocated_bytes,
asset_cache_bytes, gpu = { buffers_bytes, textures_bytes, budget_bytes },
ecs = { entities, archetypes, component_kinds } }`.
- Heap history is sampled from `memory_kb` each build (bounded ring).
## Actions
- Force GC → `luauGcCollect()`.
- Snapshot → forces a re-read on the next build (no distinct API call).
Values are colour-coded against good/warn thresholds. Registered as
`{ id = "runtime", side = "right", order = 50 }`.
# edui.panels.scene (module)
The Scene panel on edui — a right-side dock panel that lists the world's scene
assets and loads or saves them.
## Data
- `asset.list("scene")` → AssetRef handles; their `.identity` strings are split
into **saved** scenes (no `::`) and **library** scenes (`prefix::path`,
grouped by prefix).
## Actions
- Click a scene → `layers.load(identity)`.
- Save-as row (text input + Save button) → `layers.active:save({ to = name })`.
Registered as `{ id = "scene", side = "right", order = 40 }`. Requiring the
module registers it (`M.register()` at load).
# Scene changes
The Scene changes tab reviews the open scene's recorded edits. The Scene
changes button below the viewport's camera selector opens it as a persistent
dock tab; the scene-name entry in the top bar and the Scene menu also open it.
The tab uses the editor's docking and resizing controls and stays visible while
the viewport receives input.
The review names added, removed, moved, renamed and modified entities. Movement
values are rounded for display. It shows persistence status, save errors and
conflict counts. Compact rows distinguish additions, removals and edits with
action labels. Search matches object names across all pages; change-type filters
show their counts. Pages contain at most twenty fields. Expand a row for source
context, values and Show in scene, which selects and frames the live object.
The review refreshes automatically. Save scene is available for unsaved changes
or a failed save; it is disabled when the scene is saved.
When this editor's edit of an object collided with another participant's edit,
the status reads Conflict and a card names the object and the field, with the
other participant's value and this editor's latest one. Keep mine and Keep
theirs settle every one of this editor's operations on it that still conflicts.
# scripts
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# edui.panels.settings (module)
The Settings panel on edui — the world settings document rendered as an editable
form, one card per `[section]`.
## Data
- `settings.all()` → nested `[section].key = scalar` document (cached at mount,
re-read on Reload).
## Actions
- Edit a field → `settings.set("section.key", value)`, coerced to the original
scalar's type (bool → toggle, whole number → int, else float / string).
- Reload → clears the cache and re-reads `settings.all()`.
Registered as `{ id = "settings", side = "right", order = 60 }`.
# sourceControl
The editor's Source Control panel (Content menu): the open world's version state over the `world.*` namespace.
- The branch and its head in the toolbar; the branch name opens the branch menu, the refresh button reads the status again.
- The commit box and **Push** / **Pull** stay above the list while it scrolls, and the outcome of the last action shows below them, so the line appearing never moves a control. The message field is emptied once a commit lands.
- **Commit** commits what is staged (an install or a library update staged counts). With nothing staged it makes no commit and says so, naming the changes to stage (or the unsaved scene edits to save first). A commit names its id and the entries it holds, and the unsaved scene edits it left out. Commit and Push run one at a time: a press while either runs does nothing.
- **Push** names the commits it published (those above the newest one the remote holds) by their messages, the branch and the remote head, and the changes it left on this machine because no commit holds them.
- One list of four sections, each folded by its header: **Staged** and **Changes** (rows grouped by the asset they belong to, with Stage, Unstage and Discard on rows and Stage All, Unstage All and Discard All on section headers (Discard All takes the whole list back in one operation, files no commit holds included, the world's `.world_settings` and `.world_entrypoint.luau` excepted while no commit holds them; each press asks twice); each scene's unsaved edits (its autosave overlay) show as one `<scene>: N unsaved scene edits` entry that counts in Changes, with Save (writes the edits into the scene file, a change to stage; while play runs it makes no save and says to press Stop first) and Discard; a click on a file opens its diff in the Code panel), **Installed** (each installed asset as one entry, to stage or discard as one) and **History** (the recent commits; a commit row opens its diff).
## Cost
The list is windowed: every row is one height, and a build creates widgets for the rows in view and a margin around them, so a build and its layout cost the size of the window however many files changed. `displayRows` flattens the sections into the rows the list windows over, and `windowBounds` names the band of them that exists as widgets.
The status is read when the source tree was written since the last read (a `vfs.watch` on `/zero/source/` marks it), after an action of this panel, on a branch switch and on the refresh button, at most once per five seconds. A read that finds what the panel already shows changes nothing on screen. The reads, and the grouping and flattening of their rows, run across frames through `modules.frame_budget`, a few milliseconds of each.
# terminal
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# viewport
The edui **Scene** panel — a live 3D view of the world inside a dock tab.
A dedicated editor camera renders the scene (`all !ui !EditorUI`, so the panel
never draws the editor UI it lives in) into a GPU render-target texture, which
the `viewport` widget displays. The camera is reclaimed by name across
hot-reloads, so editing the module never spawns a second camera or leaks the
texture; the render target resizes to the panel's rect.
A framing toolbar orbits, tilts, zooms and resets the view. Requiring the module
registers it into the edui shell (`dock = "center"`), so it sits in the middle
of the default desktop arrangement between the Hierarchy and the Inspector.
# world
The edui **World** panel: the bound world as ZeroMind records it, in a dock
tab like any other, so it moves, resizes and closes. The Zero menu's "World
details" opens it.
It shows the world's cover, title, visibility, owner and guid, its tags, its
one-line description, and its page (the body, markdown rendered through the
Docs panel's `renderMarkdown`) in a scroll area that fills the tab, with the
editor address under it. The record is read through the trusted
`zeromind.world` dispatcher (`getWorld`) when the tab opens for a world it has
not shown, and again on Refresh.
## Exports
The panel record carries `refresh()` for the menu that opens it.
# edui.shell (module)
The editor dock shell on the CSS-parity `ui.*` surface. One edui app owns a
`ui.*` native `dockArea` whose children are a `dockPanel` per registered edui
panel — real `egui_dock` tabs, splits and drag, with the arrangement persisting
across rebuilds because the dockArea and each dockPanel carry a stable `id`.
## Why a separate registry
The shell keeps its own panel registry (`addPanel` / `removePanel` /
`panelsSorted`), distinct from the deprecated zui `editor.registry`. That keeps
the zui editor completely untouched while panels migrate to edui one at a time:
the zui dock renders the zui-framework panels it always has, and the edui shell
renders the edui panels registered here. The two registries fold into one at
cutover, when the zui dock is retired.
## One app, one reactive loop
`App.rebuild` sets the shell as the building app before it calls `buildShell`,
so a panel's `build()` — which uses `edui.current()` to register its closures —
wires every callback onto the ONE shell app. All interaction for every panel
flows through the shell's single callback env, and a click anywhere rebuilds the
whole dockArea. That is why the shell needs no per-tab scheduler (unlike zui's
`dockApp`): the edui App is the scheduler.
## Usage
```lua
local edui = require("@builtin::modules.edui")
edui.shell.addPanel{
id = "entities", title = "Entities", order = 10,
build = function()
return edui.panel{ title = "Entities", body = edui.tree{ ... } }
end,
}
edui.shell.mount() -- registers the screen on the EditorUI layer
-- each editor-update frame:
edui.shell.update(dt) -- liveness rebuild every `refresh` seconds
```
`mount(opts?)` takes `{ refresh? }` (seconds between liveness rebuilds, default
0.5). `refresh()` forces an immediate rebuild; `unmount()` tears the screen down
but keeps the panel registrations for a later `mount`.
# edui.shown
Panels opened to put a file in front of the user. `edui.shown.open(path,
{ line?, title? })` opens a new dock tab around an `edui.document` and brings
it to the front — one tab per call, beside whatever the user has open. The tab
is editable where the file is text and follows the file on disk. Unsaved edits
mark its tab, and closing it — the tab's X, or `close(id)` — asks the user to
save or discard them first; `close` then answers `false` and why. Closing
releases the document; no saved layout records it.
`resolve` turns an asset name, identity or guid into its VFS path;
`scratchPath(title, ext)` names an unused file under `/zero/source/tmp/show/`
for text with no file behind it. The `show` toolbox is the agent surface over
this module.
# edui.widgets (module)
Editor-chrome primitive builders for `edui`. Each returns a styled `ui.*`
widget subtree; the common ones are re-exported flat onto `edui`
(`edui.panel{...}`, `edui.text{...}`, `edui.iconButton{...}`, …).
Two things make these "framework" primitives rather than raw `ui.*`:
1. **They read the active theme's editor tokens** (`editor-row-height`,
`editor-selection-bg`, `editor-hover-bg`, `border`, `radius-md`, …) via
`ui.getToken`, so chrome looks like the editor by default and restyles with
the theme. `edui.palette()` returns the resolved set.
2. **Interactive builders register their closures with the currently-building
`edui` app** (`edui.current()`), so you pass `onClick = function() end` and
never touch a callback id.
## Builders
- Containers: `vbox`, `hbox`, `spacer`, `divider`, `panel`, `toolbar`.
- Content: `text`, `svgIcon`, `iconButton`, `button`.
- `panel{ title? | toolbar?, body }` is the standard dockable-panel shell (a
header over a height-filling body).
- `nodeGraph{ key, nodes, edges, selected?, height?, onSelect?, onMove?, onConnect?,
onDisconnect?, onDelete?, onOpen?, onField?, redraw? }` — a node graph on one
canvas: titled nodes with output and input ports, wires between them, and a value on
every input port that has no wire into it. Drag the background to pan, scroll to
zoom, drag a node to move it, drag from a port to another port to connect, drag a
connected input away to pick its wire up, click a value to edit it where it stands,
press Delete to remove the selection. The widget draws and reports; the owner holds
the graph and applies what `onField`, `onConnect`, `onDisconnect`, `onMove` and
`onDelete` report. Nodes with no position are laid out left to right over the wires.
`edui.nodeGraphView(key)` answers where the view stands and, through its `locate`,
where a port or a value is on the canvas.
- `iconButton{ d, tooltip?, active?, onClick, key }` — a hoverable/active icon
square; `d` is an SVG path (or full `<svg>`).
Icons are inline SVG (feather/lucide-style 24-view stroke paths), matching the
editor's icon language — pass a path `d` and it is wrapped for you.