# 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 (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.

# 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.

# assetType (asset type) An asset type says what a kind of asset is: the files an asset of the kind is made of, the code that gives it behaviour, the interface a person uses to work with it, and how it is found, pictured and checked. A `<typename>.assetType/` folder declares a type called `<typename>`, and every `<name>.<typename>/` folder is an asset of it. `assetType` is itself a type, so a type is an asset like any other: it is created, versioned, installed and contributed the same way. ## Making a type `asset.create("assetType", "<typename>")` scaffolds a type. The type registers the moment its folder is written, anywhere under `/zero/source/`, and from then on `<name>.<typename>/` folders are its assets. An asset of a type that is not registered yet is not an asset, so make the type first. A type folder is a root: `~.x` in any file inside it names the type's own `x`, wherever the type is installed. Keep the type's whole implementation inside its folder and reach it that way. What a type folder must hold is set by this type's own `type.yaml`, the same way every type's `type.yaml` sets what its assets hold. `asset.validate` on a type reports anything missing, and the scaffold produces a folder that passes. ## What sets your type's schema (`type.yaml`) `type.yaml` is the structural contract every asset of the type is checked against. The keys below are the ones the engine reads; a key not listed here is ignored. | Key | What it controls | |---|---| | `suffix` | The folder suffix of the type's assets. Defaults to `.<typename>`. | | `primary` | The file or files that are the asset's content: what the asset resolves to when it is used. | | `entry_files`, `primary_aliases` | Further files that load as the asset or share its identity. | | `is_container` | Whether the suffix stays in the identities of what the asset holds. | | `is_opaque_walker` | Whether a walk of the tree stops at the asset and registers only its primary. | | `plural_dir`, `classify_exts` | Loose files in a folder of this name, or with these extensions, are assets of the type. | | `is_text_default` | Whether the asset's files are text unless stated otherwise. | | `broadcasts_subassets` | Whether assets nested inside an asset of the type are found by their own short name. | | `root` | `true` makes every asset of the type a root, so `~.x` inside one names that asset's own `x`. | | `contract_ref: { field, category }` | A key of the primary file that names another asset the asset is built on. | | `files: { required, optional }` | The files an asset holds (below). | | `allow_unlisted` | `false` reports every file the type does not declare. | | `aliases_from: [{ file, key }]` | Further names an asset answers to, read from its own files. | | `settings:` | Typed per-asset settings (below). | | `inspector:` | The interface people use for the type and its assets (below). | | `preview:` | How an asset is pictured (below). | | `references:` | Names of other assets the type's files carry (below). | | `indexing:` | What search reads for each asset (below). | | `describe:` | How a missing description is generated (below). | ### The files an asset holds Each entry under `files.required` or `files.optional` is `{ path, kind: file | folder, one_of_group?, content? }`. `*` in a path matches within one segment. Entries that share a `one_of_group` are satisfied by any one of them. `content` lists checks on the file's bytes: | Check | Passes when | |---|---| | `non_empty` | the file has content | | `json_field { key, type?, non_empty?, accept? }` | the JSON holds the key (a dotted path) with that shape | | `yaml_field { key, type?, non_empty?, accept? }` | the same for YAML | | `described { keys?, headings?, message? }` | the file says what the asset is (see "Ask your assets to say what they are") | Each check takes a `message`, which is what the author is told when it fails. ### Settings `settings: { values, schema: { type | instance, export? } }` gives every asset typed settings. `values` names the file an asset's values live in; `schema.type` declares one schema for the whole type, and `schema.instance` names a file each asset declares its own in. `asset.create` writes the resolved values, and a write to the values file reaches `onChange` with what changed. ## The human side (`inspector.luau`) A type is used by people through its Inspector, and without one the type is usable only from code. The Inspector is the type's interface for a person: for a procedural graph it is the graph editor, for a kit it is the tracking view of what the kit holds and what is still missing. Writing it is part of writing the type. `inspector: { type, instance? }` in `type.yaml` names the files. `type` is the interface for the type itself and for its assets; `instance` names a file an asset may ship to add its own. Each returns: ```luau return { sections = { { id = "graph", title = "Graph", build = function(ctx) ... end } }, replace = { contents = { ... } }, -- replace a default section by id order = { "graph", "contents" }, -- section order } ``` `build(ctx)` receives the asset and builds the section. A section's `title`, and the text its rows carry, is a string or an `i18n.text` value read from a catalog (`i18n.text("inspectors.mesh.title")`), which follows the editor's language. `asset.create("assetType", ...)` scaffolds a working `inspector.luau` to start from. `asset.validate` on a type that names no inspector, or names one that does not load, reports it. ## Say what your type is for (`about.yaml`) Every type carries an `about.yaml` that says what the type is for, in three plain-language texts: ```yaml intent: "Sets the typeface of the text in your game: UI, labels, signs and 3D lettering." function: "A font, from a TTF, OTF or WOFF file, made available to all of Zero's text, including 3D text." usage: "You choose it by name for your UI or your text, and the text appears in that typeface." ``` - **`intent`** is what the type is for in someone's game, in the words a game maker uses. Up to 800 bytes. - **`function`** is how it works today: what an asset of it is made of and what the engine does with it. Up to 1500 bytes. - **`usage`** is what a person or an agent does with one. Up to 1200 bytes. Write about the type as a whole, not one asset of it, and say what it does now. Agents read these texts to learn when to reach for the type and how; people searching find the type by them. The scaffold starts each text with `[[describe]]` and a note on what to write; a text that still starts that way counts as not written. `services describe` can write them. They show up in `asset.inspect` as `detail.about`, in `assetTypeRef:getAbout()`, at the end of the type's `types/<typename>` guide, and at the top of the type's Inspector. ## Ask your assets to say what they are A type can require each asset to carry a description: a file, written by the author or generated, saying what the asset is and what it is for. Declare it with a `described` check: ```yaml files: required: - path: "README.md" kind: "file" content: - { check: "described", message: "Say what this widget is for and where it goes." } ``` A file that is missing, empty or still has a line starting with `[[describe]]` fails the check, and so does a YAML file whose named `keys` are missing or over their `max_bytes`, or a Markdown file missing a named heading. `asset.validate` names the asset, and a push that carries it is refused with `message`. `services describe` finds such assets and writes their descriptions. `describe:` steers what is generated: ```yaml describe: guidance: "Say what the widget shows, what input it reacts to, and where it fits in a UI." examples: - "<identity of an asset of this type whose description reads well>" ``` An example is an asset of your type whose description is a true, written one, never a placeholder and never the asset being described; with none, leave `examples` empty. A type whose assets the model cannot perceive (a sound, a motion) says so in `guidance`, and the description is drawn only from what the asset's own files state. Start the file unwritten in your `template/`: a heading and one line starting with `[[describe]]`, never example content, which every new asset would carry verbatim. A type whose assets say what they are through their own content (a mesh, a texture) declares no check. ## The type's code (`behavior.luau`) `behavior.luau` returns one table. These are the keys the engine reads from it; anything else on the table is the type's own. ### What the type's assets can do | Key | Shape | What the engine does with it | |---|---|---| | `ref` | `{ [name] = function(self, ...) }` | Every function becomes a method on every asset of the type: `ref:name(...)`. | | `modules` | `{ [name] = require(".x") }` | Code the type's assets reach with `asset.containing(__FILE__).modules.<name>`. | | `events` | an events schema | Events an asset fires. Readers subscribe through `ref.events.<name>:connect(...)`; the type fires them. | | `refShapes` | `{ [method] = function(self) -> (typeExpr, source?) }` | The result type of a `ref` method for one particular asset (below). | | `namePattern` | a Lua pattern | The names `asset.create` accepts for the type's assets. Default `^[A-Za-z][A-Za-z0-9_]*$`. | | `derive` | `{ output, module, compute, fingerprint, matches?, required?, timeout? }` | A file computed from the asset when it is committed; a `required` one holds the commit until it lands. | Some `ref` names mean the same for every type, and the engine calls them: - **`instantiate(self, target?, opts?) -> (root, idMap)`**: puts the asset in a scene. Defining it is what makes the type scene-instantiable. Its return is a contract (below). - **`inspect(self) -> detail`**: what `asset.inspect` reports for the asset beyond the common record (below). - **`preview(self, opts)`**: renders the asset's picture; it wins over the type's `preview:` recipe. - **`previewMaterial(self) -> { material }`**: the material a `surface` preview paints. - **`saveDefinition(self)`**: writes the asset's in-memory edits back to its files in edit mode. Some names are answered for every asset before the type is asked, so a `ref` entry of the same name is never reached: `getSource`, `getBytes`, `getText`, `exists`, `deps`, `canInstantiate`, `canPreview`, `preview` (which calls yours when you define one), `meta`, `runtime`, `events`, `typeRef`, `modules`, and the residency flags `has_backing_asset`, `has_runtime_changes`, `cpu_resident`, `gpu_resident`. ### When the engine calls the type | Hook | Signature | When it runs | |---|---|---| | `onCreate` | `(name, opts) -> { [path] = contents }` | On `asset.create`. Returns the files of the new asset, laid over the type's `template/`. Annotate `opts`: its type is the schema `asset.create` checks the caller's arguments against. A `""` key writes a single loose file. | | `onReplace` | `(dest, files) -> files` | On an `asset.create` over an asset already at `dest`, after `onCreate`, so what the author added can be carried into the replacement. | | `onRegister` | `(self)` | Once per asset, when it first registers: when the world loads, on a live `asset.create`, and when an asset arrives later (installed, pulled, synced). This is what makes an asset take effect the moment it is written. | | `onChange` | `(ref, change)` | On every write to a file inside an asset of the type. `change` is `{ path, asset, type, kind, origin }`, plus `settings` and `settingsChanged` for a write to the settings values file; `kind` is `edited` or `seeded`, `origin` is `local` or `remote`. Filter on `change.path`. Writes to one asset arrive in order, each after the hook for the one before has finished, and the hook may wait on what it reads. A write the hook makes inside its own asset arrives later like any other, so keep the hook convergent. | | `onDependencyChange` | `(ref, change)` | When a module the asset's code requires is re-run, or a name the asset carries starts resolving. `change.kind` is `dependency`. | | `onDelete` | `(ref)` | When an asset of the type leaves the world: deleted, or the world it is in is swapped away. | | `validate` | `(ref) -> { { code, message, severity?, path? } }` | On `asset.validate`, after the `type.yaml` checks, for the type's own rules. `severity` defaults to `error`. Runs on every push, so a type's rules hold at publish. A hook that fails reports `validate.hook_failed`. | ### Settings hooks | Hook | When it runs | |---|---| | `settingsDefaults(name, opts, asked) -> table` | Once per `asset.create`, for values the schema's defaults do not give. | | `settingsCorrections(values, name, opts) -> (corrections?, reasons?)` | On every settings write. A correction to a field the writer named refuses the write, giving the reason. | | `settingsDerivedDefaults(values, explicit, changed)` | On a settings write, for fields derived from others. | | `normalizeSettings(values, stored?)` | On every read and write, to map an earlier spelling of a field to the current one. | | `settingsHealed(values, stored)` | On a read, to repair stored values. | | `settingsSchemaProblem(schema, ref) -> string?` | When an asset's own schema is read; a returned string refuses the schema. | `creationInputs` (`{ [opt] = true | selectorOpt }`) names `asset.create` options that are inputs to the type rather than settings. ### Reloading An edit to `behavior.luau` reaches existing assets with no restart. ## How an asset is pictured (`preview:`) | `kind` | The picture is | The type provides | |---|---|---| | `instantiate` | the asset placed in the preview studio through its `instantiate` | `ref.instantiate` | | `image` | a file the asset holds, fitted to the frame | `source: { files }`, the candidate files in order | | `surface` | the asset painted on a mesh | `mesh`, and `ref.previewMaterial` | | `custom` | whatever `ref.preview` returns | `ref.preview` | ```yaml preview: kind: surface mesh: sphere ``` `angle: [yaw, pitch]` turns the camera. The studio owns the light, the backdrop and the framing, so an asset pictures the same in every world. A type with no `preview:` that defines `instantiate` still answers `ref:preview()`. A picture is rendered when something asks to view it (the editor showing the asset, `ref:preview()`), when previews are generated on request (`assets.generatePreviews`), and when the asset is staged. An edit alone renders nothing. The picture records what it was made from, so a stale one is told from a current one. ## The names your type's assets hold (`references:`) Where your type's own format or API carries the name of another asset, declare it here: ```yaml references: keys: # a top-level key of the type's files that holds a name, or a table of them - { key: "shader", type: "shader" } args: # an argument of a call, counting from 1 - { call: "g:node", position: 2, type: "procNode" } fields: # a field of the options table a call takes - { call: "fx.beam", field: "material", type: "material" } ``` `type` is the category the name resolves in. `asset.declareReferenceKey`, `asset.declareReferenceArg` and `asset.declareReferenceField` declare the same from a script. ## What search reads (`indexing:`) `indexing:` is how assets are found. Search reaches an asset only through what its type's `indexing:` names, and adds nothing of its own. That includes you: an asset indexed badly is one you cannot find later, when you are making something else and need it. A type whose assets are never looked for says `indexing: none`. ```yaml indexing: data: # text, read from the asset's files - role: identity extractor: verbatim source: { file: "README.md" } - role: interface extractor: symbols source: { files: ["init.luau"] } - role: implementation extractor: verbatim source: { files: ["init.luau"] } content: # the picture - role: identity modality: image source: { file: "preview.png" } facets: # what a query filters and re-ranks by file: ".metadata" rigged: { type: bool, from: { components: { contains: SkinnedModel } } } roughness: { type: number, filter: range, from: { file: "mat.yaml", field: "floats.roughness" } } ``` **Roles.** Each `data` and `content` entry has a `role`, and a query matches in two slots: - **`identity`**: what an asset is. For anything you look at, the picture; for anything else, the text that says what it is. - **`capability`**: what it does and how it is made. `interface` (the signatures or shape a caller uses) and `implementation` (the body) both count as capability, and a type with code usually declares both. Ask what a person would recognise an asset of the type by, and what it does, and point each role at the file that says it. For text, that is the asset's description: the file your template starts with a `[[describe]]` block, which the author writes or `services describe` fills in (see "Ask your assets to say what they are"). **`data`.** `extractor: verbatim` embeds a file's text as it is; `symbols` embeds the declared signatures of code. `source` is `{ file }` or `{ files: [...] }`. Never index a file name (`source: { field: name }`): one or two words carry nothing to match. **`content`.** `modality: image` embeds the picture itself, so a text query matches what the asset looks like. A type whose assets are looked at makes the picture its identity. **`facets`.** What a query narrows and re-ranks the matches by. `file` is embedded whole, so keys nobody declared in it are still found. Each further key is computed for every asset and states a value for every one, including `false`: a file can imply "not rigged" but never say it, and a query separates rigged from unrigged only because the unrigged ones say `rigged: false`. A key is `{ type: bool | number | enum, filter?: range, from }`, where `from` is `{ file, field }` (a field of one of the asset's files, dotted for nesting), `{ metadata: key }`, or `{ components: { contains | any_outside } }` (what the asset's entities carry). ## What blocks a push A push checks every asset it carries against its type. These refuse it: - a required file that is missing, a `content` check that fails, a `described` file not written yet; - an error from the type's `validate`. Unlisted files and warnings do not. A `described` file blocks only a push that changes the asset. When a push is refused, the message names each asset and what it lacks. `world.publishBlockers()` and `zm status` read the same list without pushing. ## Typing a result from the asset (`refShapes`) A `ref` method whose result depends on the asset (one entry per child folder, per row of a config, per control a map declares) can only be annotated as `{ [string]: Thing }`, which accepts any key. `refShapes` states the result for each asset instead: a function returning a Luau type expression for that asset, and the module whose types the expression uses. Read the asset; never run it. ```lua -- inputMap.assetType/behavior.luau M.refShapes = { activate = function(self): (string, string) local names = {} for _, control in ipairs(M.ref.controls(self)) do table.insert(names, control.name .. ": Handle") end if #names == 0 then return "", "" end return "{ " .. table.concat(names, ", ") .. " }", "@builtin::modules.zinput.scheme" end, } ``` With it, `map.jump:onPressed(fn)` is checked and `map.noexisting` is reported. A per-asset type applies where the call site names which asset: a component field whose default names it, or an annotation `AssetRef<"inputMap", "<identity>">`. `asset.resolve(name, category)` carries only the category, and a name computed at runtime carries nothing, so calls on those keep the declared return. The type belongs to the call's result: index it there, or bind what you need from it there, and the names stay checked. `require("@builtin::assetTypes.assetType.shared.refShapes").published()` shows what was published: `categories` (each type's method surface) and `returns` (per-asset results by identity, then method). An identity missing from `returns` was never published. Results are recomputed when an asset is written; at most 64 assets of one type are read. ## Putting an asset in a scene (`ref.instantiate`) A caller writes one piece of code against every instantiable type, so what `instantiate` returns is fixed: ```lua local Instantiable = require("@builtin::assetTypes.assetType.shared.instantiable") M.ref = { instantiate = function(self, target, opts) local root = Instantiable.root(self, target, opts) -- compose the asset under `root`, now return Instantiable.result(self, root, idMap) end, } ``` **In.** `target` is the entity the asset lands under, or onto for a hierarchy type; with none, the type spawns a new root. `position`, `rotation` (three numbers in degrees, or a quaternion), `scale`, `name` and `temporary` mean the same for every type: `Instantiable.root` applies them to a root you make, `Instantiable.place` to one you adopt. Document any options of your own in the hook's `--!arg` docs. **Out.** `(root, idMap)`. `root` is the composed root, live when you return: build synchronously, never defer to a component's `awake`. `idMap` maps each original id to the spawned one, so a component that composes the asset again on every load can pass it back in and keep references into the composition. Every call goes through `Instantiable.result`, which refuses a root that is not live and turns a missing `idMap` into `{}`. ## Inspecting an asset (`ref.inspect`) `asset.inspect(ref)` builds a record every asset shares (`identity`, `name`, `guid`, `source`, `typeName`, `typeDefinitionPath`, `scope`, `origin`, `description`, `tags`), then calls `ref.inspect(self)` for the type's own `detail`: ```lua M.ref = { inspect = function(self) -- read the asset's own files, never runtime state: inspect works on an asset -- that has not been compiled, uploaded or registered return { --[[ what makes this asset what it is ]] } end, } ``` Without it, the record is the shared part alone, and an agent inspecting the asset learns nothing of what it is. A hook that raises leaves `detail` empty and sets `record.warning`. ## Discovery - `asset.list("assetType")`: every registered type. - `asset.inspect("<typename>")`: the type, its README and its `about.yaml` texts. - `asset.resolve("<typename>", "assetType")`: the type itself.

# edui The editor UI framework, on the CSS-parity `ui.*` surface. An editor-only toolkit: panels author closures instead of callback ids, a dock shell over `ui.*` native docking, and typed editor-chrome primitives. Gameplay and normal world UI author raw `ui.*` trees and need none of this. **`edui.guide` beside this file is how to use it** — creating a panel, the spec it returns, how a panel is drawn and redrawn, the whole widget vocabulary, and how a panel reaches the selection and the dock. ## What installs - **`framework`** — everything under one table. From outside the package, `require("@builtin::~edui.framework")`; inside it, `require("~.framework")`. It carries `app`, `widgets`, `shell`, `topbar`, `query`, `fileDialog`, `worldDialog`, `stats`, and the chrome primitives flat (`panel`, `tree`, `field`, `section`, `text`, `button`, `menu`, …). - **`app`** — maps a panel's closures to `ui.*` callback ids, dispatches to them, and coalesces redraws. - **`widgets`** — the primitives, plus the typed inspector layer (`widgets.tree`, `widgets.fields`, `widgets.controls`). - **`inspector`** — the Inspector as an ordered list of sections: the generic asset sections, the Settings section and its actions, and the merge with the sections a type's `inspector.luau` declares (`inspector.assetSections`, `inspector.settingsSection`), and the building blocks those sections compose (`inspector.parts`, reached as `ctx.parts`). - **`shell`** — the dock: one `ui.*` `dockArea` holding a `dockPanel` per registered panel, and the panel registry behind it. ## Referencing - Inside this package, modules reference siblings with `~.` — e.g. `require("~.app")`, `require("~.widgets.fields")`. - Editor content built on the framework references it by package identity — `require("~edui.framework")`, `require("~edui.shell")`.

# Module (asset type) A module is a reusable, stateless (or globally-stateful) Luau library that other code pulls in with `require()`. Modules are the unit of factored-out logic in a world: helpers, math libraries, format parsers, registries, shared algorithms. ## When to use one - You have logic you want to share across multiple components, services, scenes, or tools. - You have a registry, lookup table, or shared cache that callers all read from / write to. - You want a stable API surface (`M.fn`) other code can depend on. If the logic is bound to one entity, use a `.component`. If you want a named UI of fields rather than functions, use a `.preset`. ## Where it lives - Source: `/zero/source/.../<name>.module/` - Identity: the source path with `/` written as `.` and each segment's type suffix dropped — `/zero/source/demo/beats.module` is `demo.beats`, and `/zero/source/kit.package/beats.module` is `kit.beats`, the container's name kept and its `.package` suffix gone. `asset.create` returns this string, `asset.resolve(...).identity` reads it back, and the `require` forms below write it as `<identity>`. - Folder shape: - `init.luau` (or `init.lua`) — module body. **Required.** Returns a table (conventionally named `M`). - `README.md` — instance-level documentation. **Required.** - `.metadata` — agent-editable tags + free-form fields. **Required.** ## How to create one ```luau asset.create("module", "<name>") -- Creates: /zero/source/<name>.module/ -- init.luau (canonical `local M = {} … return M`) -- README.md (instance README template) -- `folder` places it in a subfolder of /source, and that subfolder -- leads the identity: `{ folder = "lib" }` produces `lib.<name>`. -- `into` authors it inside a resolved container (a package, a toolbox), -- whose own identity leads the same way: asset.create("module", "<name>", { folder = "lib" }) asset.create("module", "<name>", { into = asset.resolve("myPkg.package") }) ``` ## How it operates 1. **Registration.** Writing `init.luau` into a `.module/` folder indexes the asset and registers the module path with the resolver. 2. **Loading.** The first `require("<identity>")` runs the file's body and caches the returned table. Subsequent requires from anywhere return the **same table** — this is the shared-state lever for "module-local" registries. The body runs in an environment of the module's own: a name it declares without `local` is readable by the module's own functions and by no other script, so an export reaches its callers through the returned table and nothing else. Requiring a component's folder runs its chunk the same way, once, and its `update`, `start` and `public` stay in that environment; a component runs on an entity through `entity(id).component.add(name)`. 3. **Hot reload.** Editing the file re-runs the module body and folds what it returns into the table already loaded, so that table keeps its identity: a caller that captured it with `require` reads the new source's functions and values through the reference it already holds, and a later `require` returns that same table. A key the new source drops goes away; a key something set at runtime stays. The body's own `local`s start again from their initial values, so state that must outlive an edit lives in `modules.state()` (`guides { path: "core/scripting-and-tasks" }`). 4. **Identity resolution.** A module is reached by its `<identity>`, and where the caller lives decides which spelling of it resolves. For a module in a **world**, from a caller in that same world — another module, a component, a scene entrypoint, or an `execute` chunk: - `require("<identity>")` — the identity on its own, resolved against the caller's own root. It carries every folder segment, so a module created with `{ folder = "demo" }` is `require("demo.beats")`. - `require("@root::<identity>")` — the same root-relative resolution, written out. - `require(".sibling")` — a module in the same folder, by its bare name; `..name` steps up one folder, `...name` two. Logs, stack traces and hot-reload notices name that same module `@local.source.<identity>` — its key under the world source root. The `<identity>` tail of that key is the form above, so a trace reading `@local.source.demo.beats` is `require("demo.beats")`. For a module in a **library** — content under `/zero/source/libs/@<lib>/` — `@<lib>::` addresses that library's root from anywhere: `require("@builtin::modules.transform")`. Mounting a world as a library moves its files under such a root and flips the caller root to `@<lib>::`, which is what keeps the root-relative forms above resolving across the move. ## Discovery - `asset.list("module")` — every registered module. - `asset.inspect("<name>")` — public functions, source path, this type README. - `ls /zero/source/<name>.module` lists the files the folder holds. ## Authoring conventions - Return a single `M` table from `init.luau`. Top-level statements with side effects run on first require — useful for one-time initialization, dangerous if they touch the engine before it's ready. - Write exported functions as `typed function`, not `function`: the argument types are enforced at the call and the checker knows the signature, so a caller's mistake is reported where they made it. - Annotate exported functions with `--!desc` / `--!arg` / `--!return` / `--!example` so the LSP, `tools.list`, and `asset.inspect` surface them. A function with no `--!desc` is reachable only by someone already reading this file. - Declare a VALUE with `Field.<kind>(default, mode, description)`, and a table whose members are reached through a metatable with `--!members <TypeName>` — the latter gives the surface its accepted member set, its type, and its documentation from one table. See `guides { path: "core/authoring" }` for all four rules and `modules/api/engine/entity.module/members.module` for a worked member table. - Keep module state in module-local upvalues or in `modules.state()`. A name the body declares without `local` lives in the module's environment, which every run of the module shares: a function the previous run left in place reads what the reload assigned. Module-locals start again from their initial values with each hot reload; the table `modules.state()` returns is the same table on both sides of every reload. - Prefer focused modules over kitchen-sink modules. If two halves of a module have no shared state, split them. ## Common pitfalls - **Cyclic requires.** A `require` chain that loops will return the partial table (the half built before the cycle was detected). Design for one-way dependencies. - **Engine-time side effects.** Don't `entity.spawn` at module top-level — the engine may not be ready. Expose an `M.init` and call it from a scene entrypoint. - **Hot-reload + module-local cache.** A module that caches expensive computation in upvalues loses that cache on reload — fine for dev, but be aware in performance work. - **`init.lua` vs `init.luau`.** Either works, `.luau` is canonical. - **Writing one while play runs.** A `/source` write made while play is running lands on the play shadow, and a guarded play-exit discards it unless it is kept. One `.module` write shadows `init.luau`, the `README.md` and the `.metadata` together. `vfs.write(path, bytes, { durable = true })` skips the shadow, and `vfs.promotePlayShadow` keeps what is already on it — the `core/vfs` guide has the model and what each route costs. ## Related types - `.component` — for entity-bound state + lifecycle hooks. - `.service` — generates content you don't have yet (a mesh, sound, texture, …) via a metered provider. - `.tool` — for a single agent-callable function with a YAML schema. - `.package` — to group several modules + components + scenes into one shippable folder. ## In the Inspector Exports: what the module exports (name, kind, signature), parsed from its source without running it, with **Check** (the LSP's diagnostics for its entry file) and **Open**.

# edui.inspector.assetSections The generic sections every asset's Inspector shows, in default order: | id | Title | Shows | |---|---|---| | `identity` | Asset | name, type, scope, guid and description | | `problems` | Problems | what `asset.validate` reports for the asset — a missing required file, a type's semantic problems — one notice each; present only when it reports any, and read once per content version of the asset and of its type's folder. A validation that raises, or answers without a problems list, shows as the one problem `inspector.validate_failed` naming why, and is read again on the next build | | `tags` | Tags | the asset's tags as removable chips, and an add row | | `move` | Move | the asset's folder path and a Move button; left out for an asset outside the world's own source tree | | `settings` | Settings | the typed, editable settings (`settingsSection.module`); left out when the asset has neither values nor a schema problem | | `preview` | Preview | the live preview (drag to orbit, wheel to zoom) or the still picture; left out when the asset has neither | | `operations` | Operations | every ref method the type declares except `setSettings`, each a disclosure row whose signature becomes a typed argument form run against the asset; collapsed when the type declares an inspector of its own | ```luau local AssetSections = require("@builtin::editor.edui.inspector.assetSections") local sections = AssetSections.generic(ctx) -- ctx from edui.inspector's valuesContext local settingsOnly = AssetSections.generic(ctx, { settings = true }) ``` `generic(ctx, only)` builds only the sections `only` names; one it leaves out is not read at all. Each section's controls carry callback keys under `ctx.keyPrefix`, so two subjects never share one. The open operation rows, their argument forms, the last result and the pending tag and move inputs are kept per asset; `AssetSections.releaseExcept(id)` drops every other asset's, and the validation problems read for them.

# edui.inspector.parts The building blocks a type's `inspector.luau` composes its sections from. Every Context carries this module as `ctx.parts`, so an inspector file requires nothing from `@builtin::editor`: ```luau return { sections = { { id = "summary", title = "Summary", build = function(ctx) local rows = ctx.parts.facts(ctx, { { label = "Vertices", value = 24 }, { label = "Size", value = ctx.parts.bytes(1536) }, }) local n = #rows for _, node in ipairs(ctx.parts.action(ctx, "rebuild", "Rebuild", function() ctx.ref:rebuild() end)) do n += 1 rows[n] = node end return rows end, } } } ``` Every function takes the section's Context first and returns a list of edui nodes, unless stated. | Part | What it shows | Callback key | |---|---|---| | `format(v)` | a value as text: integers plain, other numbers to 4 significant digits, booleans yes/no, a list as its length, a map as its entry count (returns a string) | — | | `bytes(n)` | a byte count as text: `84 B`, `1.5 KiB`, `2.00 MiB` (returns a string) | — | | `facts(ctx, rows, empty?)` | label/value rows (`{ label, value, mono? }`); the value takes the width its label leaves and wraps within it; a row whose value is nil shows "—", so a value that could not be read is seen to be missing. A row that does not apply to the subject is left out of `rows` by the section; with no rows `empty` shows | — | | `list(ctx, items, { max?, empty?, mono? })` | one text row per item, at most `max` (40), then "… and N more" | — | | `table(ctx, key, columns, rows, empty?)` | a table of records, each cell through `format` | `<keyPrefix>:tbl:<key>` (widget id) | | `links(ctx, refs, { max?, empty? })` | one button per asset (an AssetRef, a `{ __ref = guid }` envelope, or a guid or name), named and typed; clicking selects it. An item that does not resolve is listed as text | `<keyPrefix>:link:<guid>` | | `entityLinks(ctx, ids, { max?, empty? })` | one button per entity, by name; clicking selects it. An id whose entity no longer exists is listed as text, marked despawned | `<keyPrefix>:ent:<id>` | | `action(ctx, id, label, run, { primary? })` | a button running `run`; a run that raises shows its message beneath the button until the next run | `<keyPrefix>:act:<id>` | | `openFile(ctx, path, label?)` | an action opening `path` in the Code panel; nothing when the file is absent | `<keyPrefix>:act:open:<path>`, the path relative to the subject's folder | | `problems(ctx, problems, clean?)` | one notice per `{ message, code?, severity?, line? }` (error tone, or info for a warning, info or hint), or `clean` ("No problems.") | — | | `swatch(ctx, color, label)` | a colour square (`{ r, g, b }` in 0..1) beside its label and hex (returns one node) | — | | `cached(key, paths, compute)` | `compute()`'s value, computed again only when the content version of one of `paths` moves (returns the value). Read through `ctx.parts`, it is held while a Context that read it stays open; read through the module itself, until the next `Inspector.release` | — | | `state(ctx)` | the table a Context's sections keep state in between builds (a picked zoom, a chosen tab), forgotten when the Context is released (returns the table) | — | | `check(ctx, path)` | a "Check" action running `lsp.check(path)`, then the counts and diagnostics of the last check of the file's current content | `<keyPrefix>:act:check:<path>`, the path relative to the subject's folder | | `values(ctx, { subject, schema?, values?, write?, readOnly? })` | typed controls over any values: one control per schema field, each edit checked with `Field.check` and written through `write` inside one undoable operation; `readOnly` shows the values with no control that writes. The same subject shown by two Contexts keeps two states | `<keyPrefix>:val:<subject>:set:<field>` | ## Rules a section keeps - **No write in `build`.** A build only reads; writes happen in an action's `run`, in `ctx.setSettings`, or in a `values` part's `write`. - **Expensive reads are once per content version.** A build that decodes a payload, walks a file or asks the LSP goes through `cached` (keyed on the files the value comes from) or runs behind an action. `check` holds each file's last result for as long as the file's content is unchanged. - **Every callback key starts with `ctx.keyPrefix`**, so two subjects — the panel's asset and an inline editor of the same asset — never share one. - **What the parts hold goes with the Context.** `ctx.parts` is the parts as that Context reads them. `Inspector.release(keyPrefix)` forgets the Context's action failures, file checks and state, and every cached value no other open Context read.

# edui.inspector.presetActions The Settings section's preset actions, offered on an asset's Settings section and on a component card's: - **Save as preset** opens a name field beneath the section. Save captures the values the section shows as a typed preset targeting the declarer that governs them (`preset.capture`), and selects the new preset. A bare name lands in `/source/presets`; a path ending in `.preset` lands where it says. A name the capture refuses shows its reason beneath the section. - **Apply preset…** lists the presets whose target is that declarer. Picking one applies it to the section's subject (`preset.apply`) as one undo step, and the outcome — the fields written, and any the target refuses — shows beneath the section. ```luau local PresetActions = require("@builtin::editor.edui.inspector.presetActions") local subject, declarer = PresetActions.subjectOf(ctx) -- asset ref, or { entity, component } for _, c in ipairs(PresetActions.presetsFor(declarer)) do -- { ref, guid, name } print(c.name) end local outcome = PresetActions.applyInto(c.ref, c.name, { subject }) -- { text, tone } ``` `SAVE` and `APPLY` are the two entries `settingsSection.ACTIONS` carries. `release(keyPrefix)` forgets the open action, typed name, listed presets and outcome kept under a Context's key prefix; `Inspector.release` calls it.

# presetDefaultsSection The Preset Manager as an inspector section, shown at the top of the Settings panel. It edits the world's ordered `[[presets]]` rows in `.world_settings` through the Settings section's typed fields: - **target**: a chip that takes a declarer something consults at creation (an assetType whose instances share its schema, an importer, a component). - **preset**: a chip that offers only presets for the row's declarer. - **filter**: a glob over the new thing's path under `/source`. Rows move up and down, are removed, and are added. An edit that leaves every row whole is one checked, undoable write of `.world_settings`. A row being filled in stays in the section until it is whole and shows what it still needs. Removing a row always writes, whatever the other rows hold, and a row that cannot apply shows why. ## Exports - `PresetDefaultsSection.context() -> Context`: the rows, the checked writer, the chip predicate (`admit`) and each row's problems. - `PresetDefaultsSection.section`: `{ id = "presetDefaults", title = "Preset Manager", build }`. - `PresetDefaultsSection.render() -> { any }`: the section rendered with a fresh context. - `PresetDefaultsSection.signature() -> string`: moves whenever the rows or the section's draft move, for a panel's build signature.

# edui.inspector.settingsSection The Settings section: every field of `ctx.schema` as its typed control (a dropdown for an enum, a ranged number, a toggle, a colour, a vector, an asset chip, a nested group for a struct or `settingsOf`, an editable list), in the order the schema declares them, with `ctx.settings` as the values and `ctx.setSettings` as the one write. A field's last rejected edit shows its message beneath it. ```luau local SettingsSection = require("@builtin::editor.edui.inspector.settingsSection") local Inspector = require("@builtin::editor.edui.inspector") local ctx = Inspector.valuesContext{ subject = "my-values", schema = schema, values = values, write = function(patch) --[[ store the checked patch ]] end, selection = { scope = "asset", id = "my-values" }, } local nodes = SettingsSection.build(ctx) ``` `build(ctx)` reads only `ctx.schema`, `ctx.schemaProblem`, `ctx.settings`, `ctx.setSettings`, `ctx.rejected`, `ctx.widgets` and `ctx.keyPrefix`, so any source of values renders through it: an asset's `settings.yaml`, a component's live values, a preset's stored values. ## Actions `SettingsSection.ACTIONS` is the list of buttons offered beneath the fields: `{ id, label, applies(ctx) -> boolean, run(ctx), panel?(ctx) -> { node }? }`. Every action whose `applies(ctx)` is true renders, in list order, with the callback key `<ctx.keyPrefix>:setact:<id>`; while an action is open its `panel(ctx)` returns the nodes shown beneath the row (a name field, a list to pick from). Appending an entry offers that action on every Settings section. It ships with: - `reset` ("Reset to defaults") — writes every declared default through `ctx.setSettings`. - `saveAsPreset` ("Save as preset") — a name field and Save: captures the values as a preset targeting their declarer (`preset.capture`) and selects it. - `applyPreset` ("Apply preset…") — lists the presets whose target is this subject's declarer; picking one applies it as one undo step. The two preset actions are `edui.inspector.presetActions`; they apply to an asset's Settings section and to a component card's. A Context whose `actions` is set offers only the actions it names: `actions = {}` offers none, which is what a preset's own values use. `SettingsSection.release(keyPrefix)` forgets what the actions keep under a Context's key prefix.

# 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`.

# 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.

# assetType runtime The machinery that reads a `<typename>.assetType/behavior.luau` and turns its declarations into live behaviour. A `behavior.luau` is a table of declarations — `ref` methods, `modules` shared code, an `events` schema, a `namePattern`, `refShapes`, and the `onCreate` / `onRegister` / `onChange` / `onDelete` / `validate` / `settingsDefaults` / `settingsCorrections` hooks. None of it runs itself. This is the code that runs it, and it lives here because reading a type's declarations is the **assetType type's own behaviour** — the same way `material.assetType` owns what a `.material` does. ## Sub-modules | Module | Reads | Responsibility | |---|---|---| | `ref.module` | `ref`, `modules` | Builds every `AssetRef` envelope, attaches the shared metatable, and dispatches per-type methods and shared modules onto it. Also owns edit-mode write-behind persistence. | | `create.module` | `onCreate`, `namePattern`, `validate` | Backs `asset.create`: resolves the type, checks the name against its pattern, runs `onCreate` (or clones `template/`), and writes the instance. `validate.module` beside it checks a creation `opts` table against the type's `createSchema`. Before running `onCreate`, resolves the type's settings chain (below) and hands the result to the hook as `opts.settings`. | | `settings.module` | `settings`, `settingsDefaults`, `settingsCorrections` | A type's declared settings schema and where its values live (`type.yaml`'s `settings:` block). `Settings.resolveForCreate` layers the schema's own defaults, the type's own `settingsDefaults(name, opts, asked)` hook (a DEFAULT the schema can't express — a name-derived convention, a fact read off a payload the caller handed it, a value following a field `asked` shows a higher layer naming; any later layer overrides it), the Preset Manager, an importer's settings, the caller's `settings` table, then the type's own `settingsCorrections(values, name, opts)` hook (a CROSS-FIELD CONSTRAINT the schema can't express, applied last over the fully merged values). A correction over a default/preset/importer value lands silently; a correction that would override what the caller's own `settings` table explicitly asked for refuses the creation instead, naming the field and why. Neither hook is ever handed a table to mutate; each returns what it wants changed (`settingsCorrections` may also return a `{ [field]: reason }` table for that refusal message). `Settings.cloneValues` deep-copies a values table — `create.module` hands `onCreate` a copy, never the table it stamps. `Settings.valuesOf` / `writeValues` read and write an asset's own values file. | | `typeYaml.module` | `type.yaml` | The folder a type lives in and its parsed `type.yaml`, decoded once per content version of the file. `settings.module` and `inspector.module` read their blocks through it. `about` / `aboutAt` read a type's `about.yaml` (`intent`, `function`, `usage`), leaving out any key that is empty or still starts with `[[describe]]`; `aboutRows` and `aboutMarkdown` lay the texts out for the Inspector and the `types/<name>` guide. | | `inspector.module` | `type.yaml`'s `inspector:` block | Which inspector a type declares for its assets (`inspector: { type: ... }` or `{ instance: ... }`), and the declaration that file returns — the sections it adds, the generic ones it replaces, and their order — or the problem that kept it from loading. | | `onRegister.module` | `onRegister` | Fires an instance's once-only registration hook — on arrival, on world load, and for `@builtin` library instances. | | `changeDispatch.module` | `onChange`, `onDelete`, `refShapes` | Routes a VFS source write or a folder delete to the enclosing typed asset's type hooks. | | `refShapes.module` | `refShapes`, `ref` | Publishes what every `AssetRef<category>` answers to, so a member read on an asset-typed value is checked against that category's real surface. | | `events.module` | `events` | The per-asset event runtime behind `ref.events`. | | `instantiable.module` | `ref.instantiate` | The instantiation contract an asset type opts into: `root` stands the root entity, `place` applies the base placement opts to one the type adopted, and `result` shapes the `(root, idMap)` every `instantiate` returns. Also registers the `sceneInstantiable` field-constraint validator. | | `declaration.module` | `type.yaml` | The type's decoded declaration, read once and held until a write inside an `.assetType` folder; what every question about a type as a whole reads. | | `previewRecipe.module` | `type.yaml` `preview:` | How an instance's `preview.png` is produced: which of the four recipes (`instantiate`, `image`, `surface`, `custom`) the type declares, and what that recipe needs. | ## Reaching it ```luau local rt = require("@builtin::assetTypes.assetType.shared") rt.ref.loadTypeBehavior("material") ``` Fields resolve lazily. The prelude requires the sub-modules directly, in dependency order (`ref`, then `changeDispatch`, `onRegister.install()`, `refShapes.install()`) — a table that required all six on load would take that ordering away from it.

# Package (asset type) A package is an asset — a `<Name>.package/` folder that bundles components, modules, scenes, presets, tools, and any other typed sub-assets under one identity, installed into a world as one unit. Packages are how authoring sets get distributed across worlds. A **library** is the addressable root scope content resolves under (`@builtin`, `@<name>`) — a whole world mounted into this one under a namespace, via `zeromind.installLib` / `world.installLibrary`. A package is an asset that lives inside such a root, and one library holds as many packages as its author put there. A package is installed by guid the way every asset is (`zeromind.installAsset`). ## When to use one - You're authoring a coherent feature suite (character controller stack, voxel engine, UI kit, animation library) and want to ship it as one install target. - You want a stable identity worlds can install and resolve sub-assets against (`@<lib>::pkg.sub_module`). - You want versioning + a per-package metadata layer that travels with the contents. If you're authoring inside a single world and don't need a separate install lifecycle, you don't need a package — drop your `.component` / `.module` / etc. directly in `/zero/source/`. Packages are for cross-world distribution. ## Where it lives - Source: `/zero/source/.../<Name>.package/` (or, for legacy packages, a folder containing `package.yaml` at its root). - Identity: `<Name>` (the `.package` suffix collapses in identity — mirrors `.module`). A file at `<Name>.package/<sub>/init.luau` resolves under the same identity it would at `<Name>/<sub>/init.luau`. - Folder shape (container-style — open child set): - `package.yaml`: metadata (name, version, description) and the packages it depends on (`dependencies`). **Required.** - `README.md` — instance documentation. **Required.** - `.metadata` — agent-editable tags + free-form fields. **Required.** - Sub-asset folders: any combination of `.component/`, `.module/`, `.scene/`, `.preset/`, `.tool/`, `.toolbox/`, `.material/`, `.shader/`, etc. The validator permits unlisted children (`allow_unlisted: true`) by design — packages are open containers. ## How to create one ```luau asset.create("package", "<Name>") -- Creates: /zero/source/<Name>.package/ -- package.yaml (metadata scaffold) -- README.md (instance README template) -- `folder` places it in a subfolder of /source instead of the root: asset.create("package", "<Name>", { folder = "systems" }) ``` Then scaffold sub-assets inside it: ```luau local pkg = asset.resolve("<Name>.package") asset.create("component", "Spinner", { into = pkg }) asset.create("module", "util", { into = pkg }) ``` ## `package.yaml` ```yaml name: inkBlocks # optional; the folder stem when absent version: "1.0.3" description: "Ink and paper style blocks" dependencies: - { name: starterBlocks, version: "1.0.8" } - styleKit # a bare name states no version ``` `dependencies` lists the packages this package needs. Each entry's `name` is a reference the package records, the same kind of reference a `require` or an asset name in a data file makes: - **It resolves in the author's world.** Install the dependency here first (`zeromind.installAsset`); the entry then names the copy this world holds. A push refuses a package whose dependency resolves to nothing, naming it. - **An install brings it along.** Installing the package installs every dependency it lists, at the version this world holds when the package is pushed, under `/source/deps/<owner world>/`, deduplicated against what the installing world already holds. `zeromind.preview` lists each one before anything is written, and the install's `deps` lists what it brought. Uninstalling the package leaves a dependency that another installed package still uses. - **`version` is checked, not chosen.** A stated `version` has to equal the `version` the dependency's own `package.yaml` states in this world; `asset.validate` (and so the push) refuses the package naming both when they differ. To depend on another version, install that version here. ## How it operates 1. **Registration.** Writing `package.yaml` indexes the package with the package registry. 2. **Install.** A package is read before it is installed: `zm ls-tree @<guid>` in the shell lists what it contains, and `zm show @<guid>:<path>` and `zm grep <pattern> @<guid>` read it, so candidates are compared by what they do. The one that fits is installed by guid, the way every asset is: `zeromind_install` over the engine's MCP, or `tools.use("zeromind", "installAsset", <guid>)` inside the engine. The install writes the package's files (and the deps its `.refs` record, the packages its `package.yaml` lists under `dependencies` included) into this world's source, so its sub-assets resolve here. `tools.use("zeromind", "preview", <guid>)` reports what an install would write before it writes anything. 3. **Sub-asset resolution.** Because `.package` collapses in identity, sub-asset paths work whether the package folder is suffixed (`<Name>.package/<sub>`) or not (`<Name>/<sub>`). 4. **Updates.** `tools.use("zeromind", "updates")` lists installed content with upstream changes available; re-running the install pulls them. 5. **Metadata.** `package.yaml::name` overrides the folder stem if present (rare); `version` + `description` are surfaced in the package index. 6. **Hot reload.** Edits to sub-assets hot-reload as normal; edits to `package.yaml` reload package metadata. ## Discovery - `asset.list("package")` — every registered package. - `asset.inspect("<name>")` — sub-asset catalog, source, this type README. - `ls /zero/source/<Name>.package` lists the files the folder holds. - `library.list()` — the library assets registered in this world, including the ones packages under an installed library contribute. ## Authoring conventions - Name packages by their feature (`voxels`, `cameraRigs`, `dialogSystem`), not by their owner — the host library is the `@<lib>::` scope prefix. - Cluster cohesive sub-assets together. A "character controller" package should ship the controller component, its preset configs, its supporting modules, and a demo scene — not just the component. - Document the package's surface in `README.md` — what install installs, what each sub-asset does, how they relate. Agents reading `cat /zero/source/<Name>.package/README.md` get the full picture in one shot. - Version conservatively — breaking a package means breaking every world that installed it. Use semantic version bumps. ## Common pitfalls - **Missing `package.yaml`.** Without it the folder isn't recognized as a package even if it has a `.package/` suffix. - **A dependency named only by a string the code builds.** A package whose files reach another package only through a name assembled at runtime records no reference to it, so an install arrives without it. List that package under `dependencies` in `package.yaml`. - **Identity collapse.** Sub-asset paths skip the `.package` suffix. Don't include `.package` in `require` strings. ## Referencing inside a package: the `~` rule `~` means **this package**, resolved structurally from the referring file's own location. It is the only package-specific syntax. It is rename-safe (no package name is ever written) and library-agnostic (it never names the host library, so it survives `@builtin` being renamed or the package being mounted elsewhere). `~.tail` maps to `<pkg>.package/tail` from anywhere inside the package. | Referencing from | Use | Example | |---|---|---| | An asset/module **inside this package** | `~.tail` | `require("~.modules.myThing")`, `shader: "~.shaders.myThingBlend"` | | A **different package** under the same root | root-relative identity | `require("@root::systems.otherPkg.modules.x")` | | A **different library's** public API (a deliberate external dependency) | `@otherlib::…` | `require("@physics::modules.rigidbody")` | **Never write `@builtin::` (or any host-library name) to reference your own package** — that couples the package to the library it currently lives in and breaks if the library is renamed or the files move. Use `~.`. It works from Luau `require()` and from asset-reference strings in data files (a material's `mat.yaml` `shader:` field, a component's default asset ref); the engine resolves it against the referring file's own package. `asset.resolve` takes a `~.` name the same way, against the package of the file that calls it: `asset.resolve("~.materials.myThingStandard", "material")`. `~.` is the package-relative self-reference; `@root::` is the root-relative one (the library root, or the world source tree for non-library content). The `core/requiring-modules` guide covers the root model in full. A package that ships substantial functionality should include a `.guide` asset (a `<name>.guide/guide.md` folder anywhere under the package); the `guides` tool discovers it live, so collaborators find the system the way they find built-in guides. A package's test suite reaches the shared `Test` framework through its enclosing asset: `local Test = asset.containing(__FILE__).modules.shared` (`asset.containing` returns the deepest enclosing typed asset, the `.testSuite`, not the outer `.package`). ## Related types - Any of `.component`, `.module`, `.scene`, `.preset`, `.tool`, `.toolbox`, `.material`, `.shader`, `.style`, `.service`, `.importer` — packages bundle these. ## In the Inspector Package: the name, version and description package.yaml declares, how many things the package holds and what they are, and **Open** for package.yaml. A package.yaml that does not decode is listed under Problems with the decoder's error.