--- title: "tools" description: "The tools namespace — the engine's Luau API reference for tools." section: "API Reference" slug: "api-tools" canonical: "https://origozero.ai/docs/api-tools" updated: "2026-09-07T03:15:14.026337611+00:00" tags: ["api", "reference"] --- # tools The `tools` namespace — 422 functions. ## globals/tools/bind {#globals-tools-bind} ```lua tools.bind(identity: string, positional: { any }?, named: { [string]: any }?, opts: BindOpts?) -> BindResult ``` Resolve a call's arguments against a tool's declared parameters, turning named arguments into the positional call the tool actually takes. This is the binder behind `zero --name value` and the `use_tool` MCP tool's named `args`, so a name resolves the same way whichever surface the caller reached for. Reads the schema from `tools.get`, matches each name to a parameter (exactly first, then case-insensitively), and reports the first unresolvable name, a name that a positional argument already filled, a call longer than the signature, and a required parameter skipped over while a later one is filled. Resolves the call only — running it is `tools.use`. **Parameters** - `identity` `string` — Tool identity (`"."`, with or without the leading `tools.`). - `positional` `{ any }` _(optional)_ — Arguments already given by position, filling slots from 1. - `named` `{ [string]: any }` _(optional)_ — Arguments given by name, `{ [parameterName]: value }`. - `opts` `BindOpts` _(optional)_ — `order` — the order to visit `named` in, so the first problem reported is the caller's first (defaults to sorted, for a stable answer). `prefix` — written in front of every argument name in the failure message, `"--"` for a shell flag. `whole` — read `named` as ONE table argument when not one of its keys names a parameter, and as the first argument written inline when only some of them do, for a surface whose payload is ambiguous between the two readings. `positionalCount` — how many slots `positional` fills, for a caller that passed an explicit `nil` and so cannot be measured by length. **Returns** `BindResult` — `{ ok, call, count, failure? }`. Call the tool with `table.unpack(call, 1, count)`; on failure `call` is empty and `failure` carries the reason. ```lua bind("camera.lookAt", {}, { target = { 0, 5, 0 } }) bind("MaterialAuthor.fromColor", {}, { color = { 1, 0, 0 } }, { whole = true }) ``` ## globals/tools/create {#globals-tools-create} ```lua tools.create(args: { [string]: any }) -> { ok: boolean, path: string?, identity: string?, signature: string?, error: string? } ``` Create a new tool on disk inside an EXISTING toolbox. Scaffolds the `.tool/` folder via `asset.create("tool", …)`, then writes the supplied code wrapped in a documented typed function into `init.luau` (the `--!desc`/`--!arg`/`--!return`/ `--!example` doc block + signature built from the structured metadata), the tags into `.metadata`, and a brief `README.md` — so the authored tool is indistinguishable from a builtin. Errors cleanly if the parent toolbox doesn't exist — call `tools.createToolbox` first so the toolbox starts out with a real description instead of the placeholder template body. The engine's normal hot-reload pipeline picks up the new files and binds the tool's global on the next pass. Every toolbox created via `tools.createToolbox` ships a `shared.module/` (the template default has `ok`/`fail` result-envelope constructors; users can extend or replace it via `sharedCode` at create time or by editing the module later). The generated `init.luau` automatically declares `local shared = require(".shared")` before your function body, so the `code` you pass can reference `shared.ok(...)` / `shared.fail(...)` (or whatever the toolbox's custom helpers expose) directly. If a toolbox doesn't have a `shared.module/` for some reason, the require is skipped so there's no dangling import to fail. **Parameters** - `args` `{ [string]: any }` — Structured tool definition. Required: `name` (leaf, e.g. `"hello"`), `toolbox` (parent toolbox, e.g. `"mytools"`), `code` (the Luau function body — not a full module, just the statements that will become the function's body), `description` (one or more sentences describing what the tool does). Optional but recommended: `args` (array of `{name, type, description}` argument records), `returns` (`{type, description}` for the return value), `examples` (array of call-site code strings), `tags` (array of strings for search). **Returns** `{ ok: boolean, path: string?, identity: string?, signature: string?, error: string? }` — `{ ok, path?, identity?, signature?, error? }`. `path` — the new `.tool/` folder's VFS path. `identity` — the tool's `.` identity. `signature` — the derived `name(args) -> ret` signature. ```lua tools.create({ name = "hello", toolbox = "mytools", description = "Greet.", code = "return 'hi'" }) ``` ## globals/tools/createToolbox {#globals-tools-createtoolbox} ```lua tools.createToolbox(args: { [string]: any }) -> { ok: boolean, path: string?, identity: string?, error: string? } ``` Create a new toolbox folder. A toolbox is the namespace container for tools — `.toolbox/` on disk; once tools are authored inside it they are invoked as `tools.use("", "", …)`. This call scaffolds the `.toolbox/` folder via `asset.create("toolbox", …)` and overwrites the placeholder `README.md` with a real description so the toolbox doesn't ship the template stub. Optionally seeds `shared.module/` if the caller supplies cross-tool helper code. Authoring a tool inside this toolbox is the separate `tools.create` call. **Parameters** - `args` `{ [string]: any }` — Structured toolbox definition. Required: `name` (the toolbox's leaf name, e.g. `"mytools"` — becomes `.toolbox/` on disk and the namespace for tool identities), `description` (one or more sentences describing the surface this toolbox exposes — what problem space the tools cover and who calls them). Optional: `sharedCode` — replacement body for the toolbox's `shared.module/init.luau`. The toolbox template ALWAYS ships a `shared.module/` with default `ok`/`fail` result-envelope constructors so tools in this toolbox can `require(".shared")` from day one. Supply `sharedCode` only when you want to override that default with custom cross-tool helpers (parsers, registries, …); the module body is left untouched if you omit it. `path` — explicit VFS destination (`/zero/source/...` form). Defaults to `/zero/source/tools/` if omitted; pass an explicit path to author a library-scoped or package-internal toolbox. **Returns** `{ ok: boolean, path: string?, identity: string?, error: string? }` — `{ ok, path?, identity?, error? }`. `path` — the new `.toolbox/` folder's VFS path. `identity` — the toolbox's registered identity (``). ```lua tools.createToolbox({ name = "mytools", description = "Custom tooling for my workflow." }) ``` ## globals/tools/delete {#globals-tools-delete} ```lua tools.delete(identity: string) -> { ok: boolean, path: string?, error: string? } ``` Remove a previously-authored tool by identity. Deletes the `.tool/` folder and its contents from the VFS via `vfs.remove(..., { recursive = true })`. The engine drops the tool's global on the next hot-reload pass. Refuses to operate on a path that doesn't exist (returns `{ ok = false }` with an explanatory error). **Parameters** - `identity` `string` — Tool identity (`"."`). **Returns** `{ ok: boolean, path: string?, error: string? }` — Table shaped `{ ok, path?, error? }`. ```lua tools.delete("mytools.hello") ``` ## globals/tools/get {#globals-tools-get} ```lua tools.get(identity: string) -> ToolMeta? ``` Read back a tool's assembled metadata — description, typed signature, per-argument docs, return, examples, and tags — gathered from the four canonical sources in its `.tool/` folder. Individual tools aren't entries in the asset index (only their parent toolboxes are), so this resolves the toolbox via `asset.resolve(toolbox, "toolbox")` and reads the tool relative to it. Returns `nil` when the toolbox or tool is missing. **Parameters** - `identity` `string` — Tool identity (`"."`, with or without the leading `tools.`). **Returns** `ToolMeta?` — The assembled metadata `{ name, signature?, description, args, varargs, returns?, examples, typeDefs, tags }`, or nil if not found. Each entry in `args` is `{ name, type, description, optional }` in signature order, so a caller can tell a required parameter from an optional one without parsing the rendered signature. `varargs` is true when the tool accepts trailing arguments beyond the named parameters. `typeDefs` carries `{ name, definition }` for every named type the signature refers to, resolved transitively, so a signature reading `spawn(opts: SpawnOpts)` can be called without opening the tool's source. ```lua local meta = tools.get("entityOps.modify"); print(meta.signature) ``` ## globals/tools/list {#globals-tools-list} ```lua tools.list(tier: (number | string)?, toolbox: string?) -> { stdout: string, value: any } ``` Discover registered code-mode tools, grouped by toolbox. Default tier returns just `{ = { name, name, … } }` plus a formatted `stdout` listing every toolbox on one line with its tools — compact enough that listing the whole catalogue doesn't flood agent context. Higher tiers enrich each entry with its one-line description (tier 2) or its full assembled metadata — signature, args, returns, examples (tier 3). Pass a toolbox name to restrict the output to one toolbox. **Parameters** - `tier` `(number | string)` _(optional)_ — Verbosity level: `1` (default) toolbox summary, `2` adds one-line descriptions, `3` adds the full assembled metadata. Pass a string instead to restrict to that toolbox at tier 1. - `toolbox` `string` _(optional)_ — Optional toolbox name to restrict the output to (e.g. `"entityOps"`). Passing a string as the first arg also works. **Returns** `{ stdout: string, value: any }` — Table shaped `{ stdout: string, value: }`. For tier 1, `value` is `{ [toolbox] = { toolName, … } }`. For tier ≥ 2, `value` is `{ [toolbox] = { { name, identity, signature?, description, … }, … } }`. ```lua tools.list() -- default: every toolbox, names only tools.list(2) -- include first-line descriptions tools.list("entityOps") -- only the `entityOps` toolbox at tier 1 tools.list("entityOps", 2) -- only `entityOps`, with descriptions ``` ## globals/tools/search {#globals-tools-search} ```lua tools.search(query: string?, opts: { toolbox: string?, limit: number? }?) -> { stdout: string, value: any } ``` Search registered code-mode tools by relevance, the canonical in-engine tool-discovery entry point — callable from `execute` Luau so an agent can find the tool it needs without leaving the engine. Enumerates every tool across every toolbox (reusing the same filesystem discovery `tools.list` uses), then scores each against the query: a token hit in the tool NAME weighs most, then its DESCRIPTION, then its TAGS. Tools scoring above zero are returned best-first. With an empty/omitted `query` and no `toolbox` filter, returns the whole catalogue (name + signature + toolbox) so the agent can browse. Each returned `name` is the tool's `.` identity; invoke it with the `use_tool` MCP tool (`toolbox` + `tool` + `args`, an array in signature order or an object naming the parameters), the form each entry's `examples` are rendered in. **Parameters** - `query` `string` _(optional)_ — Free-text search string. Tokenized lowercase on non-alphanumeric boundaries; each token is matched against tool name, description, and tags. Empty or nil with no `toolbox` filter lists every tool. - `opts` `{ toolbox: string?, limit: number? }` _(optional)_ — Optional filters table. `toolbox` — keep only tools whose owning toolbox exactly matches. `limit` — maximum entries to return (default `10`; pass a larger value to return more, up to every match — there is no upper cap). **Returns** `{ stdout: string, value: any }` — Table shaped `{ stdout: string, value: { SearchEntry } }`. `value` is the ranked array; each entry is `{ name = ".", signature?, description, toolbox?, tags?, examples? }`. `stdout` is a one-line human summary of the match count. ```lua tools.search("spawn camera") tools.search("material", { limit = 5 }) tools.search("", { toolbox = "physics" }) -- list a toolbox tools.search("") -- list everything ``` ## globals/tools/toolboxes {#globals-tools-toolboxes} ```lua tools.toolboxes() -> { stdout: string, value: { { toolbox: string, purpose: string, toolCount: number } } } ``` Discover the registered toolboxes as a grouped overview — one row per toolbox with its one-line purpose and tool count. The toolbox-first entry point to tool discovery: an agent navigates by DOMAIN (which toolbox), then drills into a toolbox's tools with `tools.search("", { toolbox = "" })`. `purpose` is sourced from the toolbox's `README.md` (its first descriptive line), falling back to the `.metadata` `description`. **Returns** `{ stdout: string, value: { { toolbox: string, purpose: string, toolCount: number } } }` — Table shaped `{ stdout: string, value: { { toolbox, purpose, toolCount } } }`. `value` is toolbox-name-sorted; each entry is `{ toolbox = "", purpose = "", toolCount = }`. ```lua tools.toolboxes() ``` ## globals/tools/tryUse {#globals-tools-tryuse} ```lua tools.tryUse(toolbox: string, tool: string, ...: any?) -> ToolCall ``` Invoke one code-mode tool and report the outcome as a value. Takes the same arguments as `tools.use` and resolves the toolbox the same way, and returns `{ ok, value, error, toolbox, tool }` for every outcome — an unknown toolbox, an unknown tool, a tool that reported failure, and a tool that raised all arrive as `ok = false` with the reason in `error`. The fields are the ones the `use_tool` MCP surface reports, so a script comparing several calls in one pass reads the same names it would over MCP, and reads them without wrapping each call in `pcall`. **Parameters** - `toolbox` `string` — The owning toolbox — an ambient toolbox by its name (`"entityOps"`) or a library toolbox by its scoped identity (`"@lib::ns"`). - `tool` `string` — The tool's leaf name within that toolbox (`"spawn"`). - `...` `any` _(optional)_ **Returns** `ToolCall` — `{ ok, value, error, toolbox, tool }`. `value` carries the tool's own value when `ok` is true; `error` carries the reason when it is false. ```lua tryUse("entityOps", "spawn", { Model = { model = "cube" } }) ``` ## globals/tools/use {#globals-tools-use} ```lua tools.use(toolbox: string, tool: string, ...: any?) -> ...any ``` Invoke one code-mode tool by naming its toolbox and tool explicitly — the Luau-code counterpart to the `use_tool` MCP tool. The normal path is the `use_tool` MCP tool; this is the escape hatch for editor panels and shipped modules that script a tool from engine Luau. Resolves the toolbox from the runtime store (builtin, library, and user-authored runtime toolboxes all work), calls the named tool with the remaining args, and returns the tool's value directly — unwrapping the `ZmToolResult` envelope and RAISING a Luau error when the tool fails. Because every call names both toolbox and tool, it can never read as a `tools.` namespace. `tools.tryUse` takes the same arguments and reports the outcome as a value instead of raising. **Parameters** - `toolbox` `string` — The owning toolbox — an ambient toolbox by its name (`"entityOps"`) or a library toolbox by its scoped identity (`"@lib::ns"`). - `tool` `string` — The tool's leaf name within that toolbox (`"spawn"`). - `...` `any` _(optional)_ **Returns** `...any` — Everything the tool returned, in the order it returned it — a tool declaring `(path, reason, frame)` hands back all three, so a second and third value the tool states are read the way the tool's own signature says. Raises on an unknown toolbox / tool or a tool-reported failure. These are the tool's OWN values, not the `{ ok, value }` envelope the `use_tool` MCP surface reports — reach for `tools.tryUse` when the call's outcome is what you want. ```lua use("entityOps", "spawn", { Model = { model = "cube" } }, { position = {0, 2, 0} }) ``` ## tools/MaterialAuthor/composeFolder {#tools-materialauthor-composefolder} ```lua MaterialAuthor.composeFolder(folder: string, opts?: ComposeFolderOpts) -> AssetRef ``` Scan `folder` for textures (loose images and `.texture` assets), infer each one's PBR slot from its name, and compose them into a single new Material. Errors when no slot-mappable texture is found. Returns the new `AssetRef`. **Parameters** - `folder` `string` - `opts` `ComposeFolderOpts` _(optional)_ **Returns** `AssetRef` ```lua "/zero/source/textures/brick" "/zero/source/pbr/metal", { name = "Metal", metallic = 1 } "/zero/source/pbr/tiles", { name = "Tiles", tiling = 8 } ``` ## tools/MaterialAuthor/duplicate {#tools-materialauthor-duplicate} ```lua MaterialAuthor.duplicate(source: string | AssetRef, newName: string, overrides?: MaterialOverrides) -> AssetRef ``` Duplicate a material under `newName`, applying `overrides`. The source is resolved by AssetRef / identity / name; its `mat.yaml` definition is cloned (shader + every property + every texture binding carry over) under the new identity with `overrides` merged in, then written as the new material. Returns the new `AssetRef`. **Parameters** - `source` `string | AssetRef` - `newName` `string` - `overrides` `MaterialOverrides` _(optional)_ **Returns** `AssetRef` ```lua "Gold", "WetGold", { roughness = 0.05 } goldRef, "GoldEmissive", { emissive = { 1, 0.8, 0, 1 } } ``` ## tools/MaterialAuthor/fromColor {#tools-materialauthor-fromcolor} ```lua MaterialAuthor.fromColor(color: Color, opts?: FromColorOpts) -> AssetRef ``` Create a flat-colour material in one call. `color` is `{r,g,b}` / `{r,g,b,a}` (array) or `{ r=, g=, b=, a= }` (keyed), channels in [0,1]. Returns the new `AssetRef`. **Parameters** - `color` `Color` - `opts` `FromColorOpts` _(optional)_ **Returns** `AssetRef` ```lua { 1, 0, 0 }, { name = "Red" } { 1, 0.84, 0 }, { name = "Gold", metallic = 1, roughness = 0.2 } ``` ## tools/MaterialAuthor/fromTexture {#tools-materialauthor-fromtexture} ```lua MaterialAuthor.fromTexture(texture: string | table, opts?: FromTextureOpts) -> AssetRef ``` Create a new material that binds `texture` to one slot. Accepts a `renderer.texture` handle, an `AssetRef`/`.texture` identity, or a VFS image path. The slot is taken from `opts.slot`, else inferred from the texture name (`*_normal` → `normal_texture`, …), else `base_color_texture`. Returns the new `AssetRef`. **Parameters** - `texture` `string | table` - `opts` `FromTextureOpts` _(optional)_ **Returns** `AssetRef` ```lua "logo.texture" tex, { name = "Brick", slot = "base_color_texture", roughness = 0.6 } tex, { name = "Ground", tiling = 300 } ``` ## tools/animation/observe {#tools-animation-observe} ```lua animation.observe(target?: (string | EntityRef)) -> AnimObserveResult ``` What the engine is posing right now, one line per body: whether its pose is actually changing, the clip driving it with its playhead, how many of its bones that clip reaches, and — when it is not moving — the one reason why. Call it with no arguments for every body in the scene, or pass an entity to narrow it to that one (a character root resolves down to the skinned body under it). **Parameters** - `target` `(string | EntityRef)` _(optional)_ **Returns** `AnimObserveResult` ```lua "hero" ``` ## tools/animation/play {#tools-animation-play} ```lua animation.play(animation: string | AssetRef, entityArg: string | EntityRef, opts?: AnimPlayOpts) -> AnimPlayResult ``` Play an animation clip on an entity's skinned body for a test window, then clean up. Resolves `animation` by identity or name and `entity` by id or name, finds the SkinnedModel to drive, and plays it through the canonical AnimGraph — the same path ClipPlayer uses. Returns `{ ok = false, error }` when the clip, the entity, or a SkinnedModel under it cannot be found. When the body already runs an animation the clip overrides it for the window and the original resumes untouched on cleanup. **Parameters** - `animation` `string | AssetRef` - `entityArg` `string | EntityRef` - `opts` `AnimPlayOpts` _(optional)_ **Returns** `AnimPlayResult` ```lua "A_Walk_F_Masc", "hero" "Idle", "hero", { offset = "5s", loop = true, duration = 8 } ``` ## tools/api/docs {#tools-api-docs} ```lua api.docs(...) -> string ``` Browse engine VFS documentation under `/zero/docs`. No args lists top-level categories. Partial paths list a directory's entries (one entry per line, trailing `/` on directories). Full paths return the document content as a string. Each argument is a single path segment — they are joined with `/` to form the lookup path. **Returns** `string` ```lua -- list categories "api" -- list namespaces "api", "physics" -- list physics methods "api", "physics", "raycast" -- full raycast docs ``` ## tools/api/searchDocs {#tools-api-searchdocs} ```lua api.searchDocs(query: string) -> string ``` Search the engine's documentation: the generated reference pages under `/zero/docs` AND the prose guides that explain the concepts behind them. The query is split on whitespace; a doc matches when EVERY word appears (case-insensitive substring) in its PATH or its BODY text. Path matches rank first, then body-only matches. Searches content, so a concept like "global illumination" or "indirect light" surfaces the tools/components/guides that describe it — not just docs named that. Every returned line is a path `vfs.read` accepts. **Parameters** - `query` `string` **Returns** `string` ```lua "velocity" "global illumination" "indirect light" "voxel pivot" ``` ## tools/appearance/replaceWithContent {#tools-appearance-replacewithcontent} ```lua appearance.replaceWithContent(targets: eo.Targets, source: string, opts?: ReplaceOpts) -> ReplaceReport ``` Replace one or many entities with a content asset, resolution-first: pass a name / path / identity STRING (limit the search with `type`), and the tool resolves it and reports the canonical asset it hit. Each target entity (and its WHOLE subtree) is removed, and a fresh spawn of the content takes its slot — same parent, local position, rotation, and name; scale kept unless `keepScale = false`. Components on the removed entities do not carry over. Targets are entity names or ids, one or a list, or a `scene.find` QUERY resolved for you — `{ name = { "tree" } }`, `{ component = { "Light" } }`, `{ under = { "forest" } }`. `dryRun = true` resolves everything and returns the plan (which entities would be removed, how big each subtree is, what would spawn) without mutating. **Parameters** - `targets` `eo.Targets` - `source` `string` - `opts` `ReplaceOpts` _(optional)_ **Returns** `ReplaceReport` ```lua "rider_blockout", "a_snowboarder" { "tree_1", "tree_2", "tree_3" }, "pine", { type = "bundle" } { "tree_1", "tree_2" }, "pine", { dryRun = true } ``` ## tools/appearance/setModel {#tools-appearance-setmodel} ```lua appearance.setModel(root: string, model: string | table, opts?: AppearanceOpts) -> AssignSummary ``` Assign a model (mesh) to the Model / SkinnedModel-bearing entities found by searching an entity hierarchy from `root`. Sets the `model` field on each match's Model / SkinnedModel. You don't have to locate the exact entity; give the root and the model, and this walks the subtree. By default it assigns to EVERY match under the root; pass `{ first = true }` for only the first match. **Parameters** - `root` `string` - `model` `string | table` - `opts` `AppearanceOpts` _(optional)_ **Returns** `AssignSummary` ```lua "Rocks", "sphere" "Rocks", boulderMeshRef, { match = "rock_%d+" } ``` ## tools/appearance/swapMaterials {#tools-appearance-swapmaterials} ```lua appearance.swapMaterials(material: string | AssetRef, opts?: SwapMaterialsOpts) -> AssignSummary ``` Batch-assign one material across entity hierarchies in a single call. `material` is a string — combed against EVERY material in the project (exact identity wins, then exact leaf name, then the first case-insensitive substring match) — or an AssetRef envelope, used directly. Targets come from component schemas: every targeted entity's components are enumerated, and every public field declared `Field.resource("material", …)` / `Field.assetRef("material", …)` (on Model, SkinnedModel, and any other component that declares one) is set to the resolved material. `opts.roots` selects the hierarchies — one entity id/name, an array of ids/names/entity proxies, or absent for the ENTIRE scene; each is scanned recursively, and entities reached through more than one root are assigned once. A blue outline flashes on each affected entity for visual confirmation. **Parameters** - `material` `string | AssetRef` - `opts` `SwapMaterialsOpts` _(optional)_ **Returns** `AssignSummary` ```lua "weathered_stone" -- whole scene goldRef, { roots = "Castle", first = true } "brick", { roots = { "wall_a", "wall_b" }, match = "wall" } ``` ## tools/appearance/swapShader {#tools-appearance-swapshader} ```lua appearance.swapShader(roots?: (string | { any }), shader: string | AssetRef, opts?: AppearanceOpts) -> ShaderSwapResult ``` Convert every material in use across entity hierarchies to a new shader, in one call — "convert every single material in this scene to the ps1 shader". Scans the targeted hierarchies recursively, reads every component public field declared `Field.resource("material", …)` / `Field.assetRef("material", …)` (discovered from the component schemas, so any component carrying a materialRef field participates), collects the DISTINCT materials those fields hold, and routes each through the material asset's `setShader` — which preserves texture links and property values by canonical role (`MAIN_TEX`→`albedo`→`base_color_texture` and friends), rewrites the material asset's `mat.yaml`, and marks every instance dirty so the change persists and propagates. For a material you already hold, call `matRef:setShader(shader)` directly — this tool is for discovering the materials you'd otherwise have to enumerate yourself. **Parameters** - `roots` `(string | { any })` _(optional)_ - `shader` `string | AssetRef` - `opts` `AppearanceOpts` _(optional)_ **Returns** `ShaderSwapResult` ```lua nil, "@builtin::shaders.ps1" -- whole scene "Castle", unlitShaderRef { "wall_a", "wall_b" }, "pbr" ``` ## tools/assets/backfillSearchMeta {#tools-assets-backfillsearchmeta} ```lua assets.backfillSearchMeta(opts?: BackfillOpts) -> BackfillResult ``` Re-derive the search `.metadata` (component set, humanoid flag) for every existing asset of the given types by invoking each asset's `reindexSearchMeta` ref method. Assets minted before the deriver existed carry no `.metadata.components` / `.metadata.humanoid`, so their search facets read false until this runs. Idempotent — re-running recomputes the same values. Only assets whose type exposes `reindexSearchMeta` are touched; the rest are counted as scanned and left alone. **Parameters** - `opts` `BackfillOpts` _(optional)_ **Returns** `BackfillResult` ```lua { types = { "bundle" } } ``` ## tools/assets/describe {#tools-assets-describe} ```lua assets.describe(assetName: string, opts?: DescribeOpts) -> string ``` Describe an asset in agent-readable markdown: identity, type, scope, origin, description (README lead), tags, a **Behavior** section listing the operations any asset of this type answers to (its assetType's `ref:method(...)` surface, with signatures and descriptions), and a type-specific detail section (fields, events, and the component's own instance methods for a component; exports for a module; the call contract for a tool; ...). Every method, event, and field is rendered as a full signature so nothing needs the source read. Resolves `assetName` the same way `assets.find` results resolve. Pairs with `assets.find` (find -> describe). **Parameters** - `assetName` `string` - `opts` `DescribeOpts` _(optional)_ **Returns** `string` ```lua "@builtin::components.Camera" ``` ## tools/assets/fetchInUse {#tools-assets-fetchinuse} ```lua assets.fetchInUse(targets?: (string | EntityRef | { string | EntityRef })) -> FetchSummary ``` Fetch the unique set of asset references in use on the targeted entities — materials, meshes, textures, bundles, and every other category a component field can hold. `targets` is one entity id/name, an array of ids/names/entity proxies, or nil for EVERY entity in the scene; root targets are scanned recursively through their children. For each entity, every component's public data is scanned (nested tables to depth 8) for AssetRef envelopes; refs are deduped by guid and returned with the entities that use them — the agent's one-call inventory of what the targeted content is made of. **Parameters** - `targets` `(string | EntityRef | { string | EntityRef })` _(optional)_ **Returns** `FetchSummary` ```lua -- everything the scene references "Castle" -- everything the Castle hierarchy uses { "wall_a", "wall_b" } ``` ## tools/assets/find {#tools-assets-find} ```lua assets.find(substring: string, category?: string, opts?: { subassets: boolean? }) -> FindSummary ``` Find every asset in the entire project whose identity contains `substring` (case-insensitive). Searches the full asset index — every category, every library — and returns the matches grouped by category. Pass `category` to restrict the search to one kind (discover the available kinds via `asset.categories()`). **Parameters** - `substring` `string` - `category` `string` _(optional)_ - `opts` `{ subassets: boolean? }` _(optional)_ **Returns** `FindSummary` ```lua "car" "stone", "material" "wheel", nil, { subassets = true } ``` ## tools/assets/fromEntity {#tools-assets-fromentity} ```lua assets.fromEntity(targets?: (string | EntityRef | { string | EntityRef }), opts?: FromEntityOpts) -> FromEntitySummary ``` Capture everything an entity is carrying at RUNTIME — every live procedural mesh / texture handle held in a component's resource field, across the whole hierarchy — as durable assets, and repoint each field at the new persistent asset. A runtime mesh (`renderer.mesh.create`) has no asset behind it, so anything keyed to it (a GI bake, a saved scene) is session-only; this makes it permanent in one call. Every public resource field of every component participates (discovered by field reflection), so it reifies ALL of an entity's runtime content, not a single hard-coded type. Persistent references (already assets) are left untouched. In edit mode the new assets persist to the world's source; in play mode they land in the ephemeral runtime store, so run this in EDIT to make content durable. Runtime resources shared across several fields are reified once and every field is repointed at the one asset. **Parameters** - `targets` `(string | EntityRef | { string | EntityRef })` _(optional)_ - `opts` `FromEntityOpts` _(optional)_ **Returns** `FromEntitySummary` ```lua -- freeze every runtime resource in the scene "cornellRoom" -- freeze the cornellRoom hierarchy's runtime meshes nil, { dryRun = true } -- report what would be reified, write nothing ``` ## tools/assets/generatePreviews {#tools-assets-generatepreviews} ```lua assets.generatePreviews(opts?: GeneratePreviewsOpts) -> GenerateSummary ``` Queue a render of the missing `preview.png` for every world material, texture, and bundle under `root` (default: the whole world source), and remove empty leftover `README.md` files inside the visited assets. Skips assets whose preview already exists unless `force` is set. Returns as soon as the scan finishes; the queued renders drain serially in the background — poll `assets.previewStatus` until `pending` is 0. **Parameters** - `opts` `GeneratePreviewsOpts` _(optional)_ **Returns** `GenerateSummary` ```lua { root = "/source/projects/mygame" } ``` ## tools/assets/new {#tools-assets-new} ```lua assets.new(source: string | RuntimeHandle, name?: string, opts?: NewOpts) -> AssetRef ``` Persist a LIVE runtime GPU resource into a durable asset. `source` is a resource handle from `renderer.mesh.create` / `renderer.texture.create`, or a bare guid string naming a GPU-resident resource (paired with `opts.category`). The resource is read back from the GPU (yields a frame or two), encoded, and written as a new asset via `asset.create`, so anything keyed to it — a GI bake, a saved scene, a material slot — survives a reload instead of regenerating with a fresh identity. In edit mode the asset persists to the world's source; in play mode it lands in the ephemeral runtime store, so reify in EDIT to make content durable. Raw in-hand geometry/pixels with no GPU resource go through `asset.create(, name, data)` directly — this tool freezes a live handle. **Parameters** - `source` `string | RuntimeHandle` - `name` `string` _(optional)_ - `opts` `NewOpts` _(optional)_ **Returns** `AssetRef` ```lua renderer.mesh.create({ positions = p, indices = i }), "tree" meshGuid, "terrain", { category = "mesh" } ``` ## tools/assets/previewStatus {#tools-assets-previewstatus} ```lua assets.previewStatus() -> PreviewStatus ``` Report the preview work queue: renders still pending, the asset currently rendering, session totals, and the most recent failures. Poll after `generatePreviews` until `pending` reaches 0 and `active` is empty. **Returns** `PreviewStatus` ## tools/assets/typeBehavior {#tools-assets-typebehavior} ```lua assets.typeBehavior(name: string) -> BehaviorResult ``` What an asset of this TYPE can do — the operations every ref of it answers to (`ref:method(...)`), the lifecycle hooks it runs, and whether it can become an entity in a scene. This is the difference between knowing a type exists and knowing what it gives you: a type that already evaluates, instantiates, validates and recompiles itself is scaffolding to build inside, not a name in a list. Each operation carries the type author's own three answers: what it does (`description`), what to pass it and what it hands back (`signature`, the arguments and the declared return), and what that return means (`returns`). Read it with `assets.typeDoc` for the prose, and `assets.types` to find the name. **Parameters** - `name` `string` **Returns** `BehaviorResult` ```lua "procGraph" ``` ## tools/assets/typeDoc {#tools-assets-typedoc} ```lua assets.typeDoc(name: string) -> { [string]: any } ``` Read one asset type's own documentation — what the type IS, the shape of its folder, how it is authored, and what it is for. This is the type's README as its author wrote it, so it says things no signature can: which file is the source, what regenerates when, what the type does for you. Read this before building anything that resembles what the type describes. `assets.types` finds the name to pass here. **Parameters** - `name` `string` **Returns** `{ [string]: any }` ```lua "procGraph" "terrain" ``` ## tools/assets/types {#tools-assets-types} ```lua assets.types(query?: string) -> TypesResult ``` Every KIND of asset this engine can make — the scaffolding available to build inside, as opposed to `assets.find` (content that exists) or `search_tools` (operations you can call). Each row is a registered assetType: what it is, the `asset.create` call that makes one, and whether it can become an entity in a scene. Reach for this BEFORE writing a system of your own. A job that looks like "no tool does this, so I will write it" is usually a job with a type already shaped for it — a graph that regenerates from parameters, a terrain, a voxel template, a population — and building beside one of those is a few lines where building from scratch is a project. **Parameters** - `query` `string` _(optional)_ **Returns** `TypesResult` ```lua "procedural" "terrain" ``` ## tools/assets/users {#tools-assets-users} ```lua assets.users(assetArg: string | AssetRef) -> UsersSummary ``` Find every entity in the active layer that uses an asset. Give the asset as a word — the entire project is combed case-insensitively and the first matching asset is used — or as an AssetRef you already hold. Every entity's component data is scanned recursively for references to that asset, and each use site is reported with the entity, component, and field it lives in. **Parameters** - `assetArg` `string | AssetRef` **Returns** `UsersSummary` ```lua "pickup_car" goldMaterialRef ``` ## tools/baking/__all {#tools-baking-all} ```lua baking.__all(opts: AllOpts, scope?: (string | EntityRef | { string | EntityRef })) -> AllResult ``` **Parameters** - `opts` `AllOpts` - `scope` `(string | EntityRef | { string | EntityRef })` _(optional)_ **Returns** `AllResult` ## tools/baking/all {#tools-baking-all} ```lua baking.all(opts?: AllOpts) -> AllResult ``` Run the entire GI bake in one call — static-surface lightmaps, an auto-placed irradiance probe volume for moving entities, and auto-placed reflection probes — then report what remains. This is the finalize step for a static scene: it takes the scene from "everything recomputed every frame" to baked. Each stage can be skipped (`skipLightmaps` / `skipProbes` / `skipReflections`); `resolution` / `samples` tune quality. Returns each stage's result plus a fresh `remaining` coverage report. This runs for many seconds on a real scene and is handed back as a background task: check how far it has got with this toolbox's `status` tool, and a `lightmap bake finished` notice reports the end. **Parameters** - `opts` `AllOpts` _(optional)_ **Returns** `AllResult` ```lua -- bake everything in the scene { resolution = 128, samples = 128 } { scope = "arena", skipReflections = true } ``` ## tools/baking/clear {#tools-baking-clear} ```lua baking.clear(opts?: ClearOpts) -> ClearResult ``` Clear baked GI across a scope — restores each static surface's original material (removing its lightmap), despawns irradiance-probe volumes, unregisters reflection probes, and deletes the cubemap assets their bake wrote. A probe attached to a scene object loses its `ReflectionProbe` component and the object stays; an entity the bake placed to hold a probe is despawned. Use it to re-bake from a clean slate or strip GI from a region. Each category can be kept (`keepLightmaps` / `keepProbes` / `keepReflections`). Returns how many of each were cleared. **Parameters** - `opts` `ClearOpts` _(optional)_ **Returns** `ClearResult` ```lua -- clear everything in the scene { scope = "arena" } { keepReflections = true } ``` ## tools/baking/detect {#tools-baking-detect} ```lua baking.detect(scope?: (string | EntityRef | { string | EntityRef })) -> DetectReport ``` Report what in the scene needs baking / re-baking and why — the bake-coverage check. Scans the scene (or a `scope`) for the state that quietly wrecks performance and leaves indirect light missing: static geometry with no bake (no lightmap and no probe-field coverage), shadow-casting point/spot lights re-rendering their shadow every frame, movers outside every probe volume's field, and reflective scenes with no reflection probe. Each finding names the one call that fixes it. Returns `clean = true` with an empty findings list when the scene is already covered. **Parameters** - `scope` `(string | EntityRef | { string | EntityRef })` _(optional)_ **Returns** `DetectReport` ```lua -- whole scene "interior" ``` ## tools/baking/lightmaps {#tools-baking-lightmaps} ```lua baking.lightmaps(opts?: LightmapOpts) -> LightmapResult ``` Bake static-geometry lightmaps across a scope in one call — resolves the static surfaces under `scope` (every visible `Model` whose `resolveMobility()` is `"static"`; movable geometry, physics bodies, and players sample probe volumes instead) and bakes full irradiance into a per-surface lightmap, no per-entity setup. Surfaces whose UVs tile or overlap are bound to the covering probe volume instead (counted in `probeLit`); set `Model.mobility` to override a wrong mobility derivation. `match` narrows to surfaces whose name contains a substring; `resolution` / `samples` / `intensity` set quality. Returns how many baked, how many went to the probe field, how many were skipped, and a per-surface report. This runs for many seconds on a real scene and is handed back as a background task: check how far it has got with this toolbox's `status` tool, and a `lightmap bake finished` notice reports the end. **Parameters** - `opts` `LightmapOpts` _(optional)_ **Returns** `LightmapResult` ```lua -- whole scene { scope = "level_geo", resolution = 128, samples = 32 } { match = "floor" } ``` ## tools/baking/mobility {#tools-baking-mobility} ```lua baking.mobility(opts?: MobilityOpts) -> MobilityResult ``` Report (and optionally batch-set) geometry mobility across a scope. Every `Model` in `scope` is listed with its authored `mobility` field and what it resolves to — static geometry receives lightmaps and occludes baked light; movable geometry samples probe volumes. Pass `set` to override the field on every matched Model in one call (the exclusion switch when the automatic derivation gets an entity wrong); omit it to just inspect. `match` narrows by name substring. **Parameters** - `opts` `MobilityOpts` _(optional)_ **Returns** `MobilityResult` ```lua -- report the whole scene { match = "crate", set = "static" } { scope = "props", set = "movable" } ``` ## tools/baking/probes {#tools-baking-probes} ```lua baking.probes(opts?: ProbeOpts) -> ProbeResult ``` Place irradiance light-probe volumes automatically and bake them — the whole light-probe pass in one call, no hand placement. Gathers the scene's point/spot lights (limited by `scope`), CLUSTERS them by influence overlap, and drops one right-sized volume per cluster (so separated rooms get separate volumes, not one box over the dead space between them). Probe density comes from `spacing` (world units between probes) with a hard `maxProbes` cap per volume, so a big volume gets coarser probes rather than a runaway grid; `maxVolumes` bounds the volume count by merging the nearest clusters. When a scene has no point/spot lights (sun/ambient only), it falls back to one volume over the scene's geometry bounds. Each baked field publishes into the renderer's irradiance-volume set and persists into the scene's baked-lighting container — every standard-PBR fragment inside a volume (movers, avatars, freshly spawned props) samples it with no per-entity setup, and a fresh boot restores it with no re-bake. Returns each placed volume (id, bounds, grid resolution, probe count) plus totals. The same placement is available to component/`execute` code as `require("@builtin::systems.globalIllumination.volumeProbe").autoPlace(opts)`. **Parameters** - `opts` `ProbeOpts` _(optional)_ **Returns** `ProbeResult` ```lua -- whole scene, defaults { spacing = 2, samples = 128 } { scope = "interior", maxProbes = 4096 } ``` ## tools/baking/reflections {#tools-baking-reflections} ```lua baking.reflections(opts?: ReflectionOpts) -> ReflectionResult ``` Place reflection probes across the scene automatically and bake them — the whole reflection pass in one call, no hand placement. The tool bounds the scene's geometry (limited by `scope`), spreads a small set of probes evenly through that volume, and bakes each into its cubemap; reflective surfaces then sample the nearest probe(s), proximity-blended by the renderer. `count` defaults to a value derived from the scene size and is clamped to the renderer's 8-probe budget; `radius` defaults to a size that overlaps neighbours for seamless coverage; `bake = false` places without baking. Returns the placed probes (id, position, radius) and how many baked. **Parameters** - `opts` `ReflectionOpts` _(optional)_ **Returns** `ReflectionResult` ```lua -- whole scene, auto count { count = 4 } { scope = "lobby", count = 1, radius = 20 } ``` ## tools/baking/showProbes {#tools-baking-showprobes} ```lua baking.showProbes(opts?: ShowProbesOpts) -> ShowProbesResult ``` Visualize the baked irradiance field — drop an unlit, color-coded marker at every probe position so an invisible SH bake becomes something you can see and judge. Each marker is tinted by the light that probe captured (brighter where the bake gathered more light, dark in occluded corners), so you can read the falloff through the volume and catch a bake that came back empty. Reads the volume's baked probe buffer (bake first). `volume` targets one volume (default: every VolumeProbe in the scene); `gain` scales brightness (default auto-normalizes to the brightest probe); `stride` thins a dense grid; `scale` sizes the markers. Re-run to refresh; `baking.clear` (or deleting the `gi_probe_viz` entity) removes it. **Parameters** - `opts` `ShowProbesOpts` _(optional)_ **Returns** `ShowProbesResult` ```lua -- every baked volume { gain = 4, scale = 0.2 } { volume = "probe_volume_1", stride = 2 } ``` ## tools/baking/status {#tools-baking-status} ```lua baking.status() -> BakeStatus ``` Report the running bake's progress: whether one is going, how many receivers it has FINISHED (`done`, which `percent` is derived from) and how many it has REACHED (`started`) out of the total it resolved, which one it is on, and how long it has been running. A bake is handed off as a background task, so this is how you check on it while it works; the `lightmap bake finished` notice reports the end. **Returns** `BakeStatus` ```lua -- while a bake is running -- poll until `running` is false ``` ## tools/cam/frame {#tools-cam-frame} ```lua cam.frame(entityId: string | EntityRef, opts?: FrameOpts) ``` Position a camera to frame a target entity from a distance + angle, then point it at the entity in one call. `opts.angle` accepts three forms (matches `capture.fromEntity`): a number (elevation pitch in degrees — legacy scalar), `{yaw, pitch}` (array form), or `{yaw=, pitch=}` (named form). `opts.yaw` is still respected as a fallback when `opts.angle` is a number or doesn't carry a yaw entry. **Parameters** - `entityId` `string | EntityRef` - `opts` `FrameOpts` _(optional)_ ```lua 'my_cube' 'my_cube', { distance = 20, angle = 45, yaw = 90 } 'my_cube', { angle = {90, 60} } ``` ## tools/cam/get {#tools-cam-get} ```lua cam.get(camId?: (string | EntityRef)) -> CamGetResult ``` Read camera info — transform + fov. Defaults to the active camera (`camera.active()`) when `camId` is omitted. Returns `{ error = ... }` when no camera is active, and when the reference names no entity. **Parameters** - `camId` `(string | EntityRef)` _(optional)_ **Returns** `CamGetResult` ```lua 'cam2' ``` ## tools/cam/lookAt {#tools-cam-lookat} ```lua cam.lookAt(camIdOrX: string | EntityRef | number, xOrY: number, yOrZ: number, zOrNil?: number) ``` Point a camera at a world position. Computes a look-at rotation (yaw + pitch) and writes it to the camera's `localRotation`. Two call shapes: `cam.lookAt(x, y, z)` (uses active camera) and `cam.lookAt(camId, x, y, z)` (specific camera). Logs and returns when no camera / target is available, when the camera has no position, or when the camera is already at the target (length < 0.001). **Parameters** - `camIdOrX` `string | EntityRef | number` - `xOrY` `number` - `yOrZ` `number` - `zOrNil` `number` _(optional)_ ```lua 0, 0, 0 'cam2', 5, 3, 0 ``` ## tools/cam/spawn {#tools-cam-spawn} ```lua cam.spawn(name: string, ...) -> string ``` Spawn a camera entity with a `Camera` component at a position. Supports four call shapes for the position: no args (origin), `({x,y,z}, opts?)`, `(opts)` (opts only), or `(x, y, z, opts?)`. When `opts.renderTarget` is set, creates a GPU texture and points the camera at it via `Camera:setTargetTexture`; sample it by `entity(id).component.get("Camera").textureHandle` and free it with `renderer.destroy` when done. **Parameters** - `name` `string` **Returns** `string` ```lua "main", 5, 5, 5 "rt_cam", { renderTarget = { name = "feed", width = 256, height = 256 } } ``` ## tools/camera/bindToPlayer {#tools-camera-bindtoplayer} ```lua camera.bindToPlayer(camera?: (EntityRef | string)) -> BindToPlayerResult ``` Make the joining player use this camera in play — bind it to the active scene's PlayerPrototype. The prototype's `camera` role must be a descendant of its subtree (it is cloned with the player on spawn), so this re-parents the camera into the prototype (keeping its world pose) and sets the prototype's `camera` ref to it. This is how you choose the player's camera: pair it with a static behavior (`camera.set { behavior = "@builtin::controller.menu" }`) for a fixed PS1-style camera the player moves within, or a follow behavior (`orbital_follow`, `third_person_follow`, `first_person`, …) for a tracking one. On spawn the player's body is bound as the camera's follow target; a static behavior ignores that and holds its pose. Errors when the scene has no PlayerPrototype (a player-less scene has no player camera to bind). Returns `{ prototype, camera }`. **Parameters** - `camera` `(EntityRef | string)` _(optional)_ **Returns** `BindToPlayerResult` ```lua "fixedCam" ``` ## tools/camera/create {#tools-camera-create} ```lua camera.create(name: string, position?: (vec3 | number), opts?: CameraCreateOpts) -> shared.CameraInfo ``` Spawn a new camera entity at a position, with any starting parameters. `opts` accepts `fov`, `near`, `far`, `priority`, `renderLayers` (a layer-name spec like `"all !ui"`), `debugChannel`, `follow` (an entity the camera behavior tracks), `behavior` (a `cameraBehavior`-tagged component), `lookAt` (a world position or entity to aim at), and `target` (render-to-texture: `true` or `{ width, height, name }` renders offscreen; omit for the viewport). The scene's primary camera is spawned for you from the PlayerPrototype — use this for ADDITIONAL cameras (a security view, a cutscene angle, a render-texture feed). Returns the new camera's full parameter record. **Parameters** - `name` `string` - `position` `(vec3 | number)` _(optional)_ - `opts` `CameraCreateOpts` _(optional)_ **Returns** `shared.CameraInfo` ```lua "securityCam", { 0, 6, 12 }, { fov = 50, renderLayers = "all !ui" } "feedCam", { x = 2, y = 3, z = 2 }, { target = { width = 512, height = 512 }, lookAt = "player" } ``` ## tools/camera/frame {#tools-camera-frame} ```lua camera.frame(camera?: (EntityRef | string), target: EntityRef | string, opts?: CameraFrameOpts) -> shared.CameraInfo ``` Position and aim a camera to frame a target entity in one step: place the camera at `distance` from the target on the `yaw`/`pitch` angle, then look at it. `opts` accepts `distance` (default 10), `yaw` (default 0), and `pitch` (default 20), all degrees. Pass `nil` for the first argument to frame with the active camera. Returns the camera's updated parameter record. **Parameters** - `camera` `(EntityRef | string)` _(optional)_ - `target` `EntityRef | string` - `opts` `CameraFrameOpts` _(optional)_ **Returns** `shared.CameraInfo` ```lua "securityCam", "player", { distance = 8, yaw = 30, pitch = 15 } nil, "statue" ``` ## tools/camera/get {#tools-camera-get} ```lua camera.get(camera?: (EntityRef | string)) -> shared.CameraInfo ``` Read the full parameter record for one camera — position, rotation, fov, near, far, priority, render-layer spec, debug channel, render-target guid, behavior, and follow target — beside whether it is `enabled` (the switch that decides whether it renders at all), whether it is `rendering`, the `reason` it is not, the projection the renderer built for it in `frame`, and `mismatch` naming every field where that frame disagrees with the record above. Pass a camera name/id/proxy, or nothing to read the active (on-screen) camera, falling back to the scene's main camera. **Parameters** - `camera` `(EntityRef | string)` _(optional)_ **Returns** `shared.CameraInfo` ```lua "securityCam" ``` ## tools/camera/list {#tools-camera-list} ```lua camera.list() -> { shared.CameraRow } ``` List every camera in the scene, enumerated from the live ECS so a just-spawned, hidden, or runtime camera is never missed, sorted by descending priority (the order the renderer resolves the on-screen camera). Each row marks whether it is the `active` camera (drawn this frame), whether it is `enabled` — the per-camera switch that decides whether it competes for the viewport or renders into a target at all — whether it is `rendering` and the `reason` it is not, whether it is the `player` camera (the one the PlayerPrototype uses — the joining player's view), and its `role` — `"main"` (highest-priority active non-editor), `"editor"` (the editor fly-camera), or `""` — plus its priority, fov, render-layer spec, and render-target guid. For the projection the renderer actually built for each camera, and what each cost, read `camera.observe()`. **Returns** `{ shared.CameraRow }` ## tools/camera/lookAt {#tools-camera-lookat} ```lua camera.lookAt(camera?: LookAtRef, target?: LookAtRef) -> shared.CameraInfo ``` Aim a camera at a world position or at another entity. The target is an entity name/id or a position `{ x, y, z }` / `{ x =, y =, z = }`. Pass a single target to aim the active camera, or a camera plus a target to aim a specific one. Returns the camera's updated parameter record. **Parameters** - `camera` `LookAtRef` _(optional)_ - `target` `LookAtRef` _(optional)_ **Returns** `shared.CameraInfo` ```lua "securityCam", "player" { 10, 0, 5 } ``` ## tools/camera/set {#tools-camera-set} ```lua camera.set(camera?: (EntityRef | string | CameraSetParams), params?: CameraSetParams) -> shared.CameraInfo ``` Change one or more parameters on a camera in a single call. Accepts `fov`, `near`, `far`, `priority`, `debugPass` (the diagnostic view this camera renders, BY NAME — `"final"` (lit), `"normal"`, `"depth"`, a content view like `"lightmap"`, …; `renderer.debugPass.list()` enumerates them; the live viewport draws the active camera's pass), `renderLayers` (a layer-name spec like `"all !ui"` — a bare name includes a layer, `!name` excludes it), `behavior` (a `cameraBehavior`-tagged component ref), and `follow` (the entity the behavior tracks). `debugChannel` accepts the raw numeric channel for the same effect. Pass no camera (or `nil`) to change the active camera; pass `{ ... }` as the only argument for the same. Returns the camera's updated parameter record. **Parameters** - `camera` `(EntityRef | string | CameraSetParams)` _(optional)_ - `params` `CameraSetParams` _(optional)_ **Returns** `shared.CameraInfo` ```lua "securityCam", { fov = 50, priority = 5 } { debugPass = "normal" } { debugPass = "final" } -- back to the lit image ``` ## tools/capture/cleanup {#tools-capture-cleanup} ```lua capture.cleanup() -> number ``` Clear every file in `/source/tmp/capture/`. Walks the directory with `vfs.list` and removes each non-directory entry via `vfs.remove`. Safe to call on a missing / empty directory. **Returns** `number` ## tools/capture/collage {#tools-capture-collage} ```lua capture.collage(opts: CaptureCollageOpts) -> (shared.CaptureResult?, string?) ``` Render a GRID of frames into one image and write it before returning. What varies from cell to cell is what you pass, and a collage says so rather than assuming: `setups` gives a cell per whole camera set-up — the contact sheet of a shot list, each entry written the way a single capture is aimed — `viewpoints` gives a cell per named view of one subject (front, back, left, right, top, bottom, iso — or "sides" for all six), `passes` gives a cell per render pass (final, albedo, normal, depth, motion_vectors, and any content-registered capture view), and `duration` gives a cell per sample across that many seconds of gameplay. Naming a station axis (`setups` or `viewpoints`) AND `passes` lays out a 2D grid: a row per station, a column per pass, so reading across a row is one set-up under every pass and reading down a column is one pass from every set-up. A collage with no axis is refused naming all of them; `setups` and `viewpoints` both say where the camera stands and cannot combine; and `duration` combines with none of them — a cell differing both in what it looks at and in when it was taken answers neither question. The grid shape is worked out from the number of cells; pass `grid` ("3x2") to state it. `width` and `height` are the whole SHEET, and a cell is rendered at the box the grid divides out of it — so a cell holds the same picture a single capture at that cell's own `width`/`height` holds, whatever the grid's shape, and a round subject reads round in every cell of a `4x1`. Every cell comes back labelled on the result with the station it was rendered from and the pixels it was rendered at, so a grid is readable from the response instead of guessable from the pictures. **Parameters** - `opts` `CaptureCollageOpts` **Returns** `(shared.CaptureResult?, string?)` ```lua { setups = { { position = { -14.6, 1.35, 4.5 }, lookAt = { -16.3, 1.1, 1.6 }, fov = 28, label = "shot 1" }, { position = { 8, 3, 12 }, lookAt = { 0, 1, 0 }, fov = 50, label = "shot 2" } }, grid = "2x1" } { entity = "crate", viewpoints = "sides", basis = "local", projection = "orthographic", isolate = true } { entity = "crate", basis = "local", viewpoints = { "front", "iso" }, passes = { "final", "normal" } } { passes = { "final", "albedo", "normal", "depth" } } { entity = "salt_pan", viewpoints = "sides", basis = "local", clearAir = true } { duration = 3, grid = "3x3", path = "/source/tmp/capture/motion.jpg" } ``` ## tools/capture/fromCamera {#tools-capture-fromcamera} ```lua capture.fromCamera(camera: string | EntityRef, opts?: (string | FromCameraOpts)) -> (string?, string?, shared.CaptureFrame?) ``` Render the scene from a specific NAMED camera, writing the PNG before returning — the returned path exists on success. By DEFAULT it uses the camera's exact authored settings — its world-space pose plus its own `fov`, `near`, `far`, and the scene layers it draws: the camera's own `renderLayers` with the editor's chrome (`EditorUI`) and the authoring overlays (`debug`) taken off, since those are drawn for whoever is editing rather than by that camera into the world. So the frame is precisely what that camera draws of the scene, without changing what is on screen. Pass `opts` to OVERRIDE any of those for this one capture WITHOUT touching the camera: `pass` (what the frame HOLDS, by name — `"final"`, a built-in diagnostic pass like `albedo` / `normal` / `depth` / `roughness`, or a capture view a render feature published; it picks the channel rendered, the layers that pass is read under, and whether the post-process chain runs over it — a diagnostic buffer is read flat), `view` (a capture view named directly, by the name a render feature published it under — `renderer.captureView.list()` enumerates them, and a name no feature published is refused against that list), `renderLayers` (a layer-name spec like `"all !ui"`), `debugChannel` (the same channel selection by number), `fov`, `near`, `far`, `width`, `height`, and `path`. Use it to check any specific camera — a security view, a cutscene angle, a render-texture feed — and to preview it under different layers or a diagnostic pass. **Parameters** - `camera` `string | EntityRef` - `opts` `(string | FromCameraOpts)` _(optional)_ **Returns** `(string?, string?, shared.CaptureFrame?)` ```lua "securityCam" "securityCam", { pass = "normal" } "securityCam", { view = "overdraw" } "securityCam", { renderLayers = "all !ui", debugChannel = 0 } "securityCam", "/source/tmp/capture/sec.png" ``` ## tools/capture/fromEntity {#tools-capture-fromentity} ```lua capture.fromEntity(opts: CaptureEntityOpts) -> (string?, string?, shared.CaptureFrame?) ``` Render the scene framed on an entity (or several) and write the PNG before returning — the returned path exists on success. The camera auto-fits the union world-space bounds of the target(s), so the subject fills the frame at any scale; pass `distance` to orbit at a fixed radius instead. **Parameters** - `opts` `CaptureEntityOpts` **Returns** `(string?, string?, shared.CaptureFrame?)` ```lua { entity = "player" } { entity = "player", pass = "normal" } { entity = "crate", viewpoint = "front", basis = "local" } { entity = "crate", viewpoint = "top", basis = "local", projection = "orthographic", isolate = true } { entity = { "house", "tree" }, angle = {90, 15}, path = "/source/tmp/capture/yard.png" } { entity = "player", deterministic = true } { entity = "salt_pan", clearAir = true } ``` ## tools/capture/fromPosition {#tools-capture-fromposition} ```lua capture.fromPosition(opts: CapturePositionOpts) -> (string?, string?, shared.CaptureFrame?) ``` Render the scene from a world-space position and write the PNG before returning — the returned path exists on success. Spawns an ephemeral offscreen camera, renders once, reads the target back and writes it; all resources clean up before the call returns. **Parameters** - `opts` `CapturePositionOpts` **Returns** `(string?, string?, shared.CaptureFrame?)` ```lua { position = {0, 5, 10}, lookAt = {0, 0, 0} } { position = {0, 5, 10}, lookAt = {0, 0, 0}, pass = "albedo" } { path = "/source/tmp/capture/front.png", position = {0, 5, 10}, lookAt = {0, 0, 0} } { position = {0, 5, 10}, lookAt = {0, 0, 0}, deterministic = true } { position = {0, 5, 10}, lookAt = {0, 0, 0}, clearAir = true } ``` ## tools/capture/oneshot {#tools-capture-oneshot} ```lua capture.oneshot(opts?: CaptureOneshotOpts) -> (CaptureHandle?, string?) ``` Spawn an ephemeral offscreen camera configured from `opts`, trigger one render, and return the handles so the caller can read the render target back synchronously and clean up. Unlike `fromPosition` / `fromEntity` / `viewport`, this does NOT spawn a task to handle readback — it returns immediately, making it usable from MCP in edit mode where the task scheduler does not tick. **Parameters** - `opts` `CaptureOneshotOpts` _(optional)_ **Returns** `(CaptureHandle?, string?)` ```lua { source = "entity", entity = "Player", distance = 8, angle = {45, 20}, pass = "normal" } ``` ## tools/capture/viewport {#tools-capture-viewport} ```lua capture.viewport(opts?: (string | ViewportOpts)) -> (string?, string?, shared.CaptureFrame?) ``` Capture the current viewport and write the PNG before returning — the returned path exists on success. Mirrors the on-screen camera through the shared capture core (`source = "screen"`), so the frame is taken from that camera's pose, through that camera's own lens, under the render layers it draws the screen with, the editor's own chrome left out: the chrome stands around the viewport's picture, and the frame holds that picture — the scene, its debug overlays and the content UI drawn into it. Pass `opts` to OVERRIDE any of that for this one capture: `width` / `height` for a raster other than the viewport's own size, `renderLayers` (a layer-name spec like `"all !EditorUI !debug"`) for the frame without the editor's chrome over it, `pass` for what the frame HOLDS (`"final"`, a built-in diagnostic pass like `albedo` / `normal` / `depth`, or a capture view a render feature published), `clearAir` for the frame with the air between the camera and a surface taken out, and `postProcessing` to take the frame with the grade off. **Parameters** - `opts` `(string | ViewportOpts)` _(optional)_ **Returns** `(string?, string?, shared.CaptureFrame?)` ```lua "/source/tmp/capture/screenshot.png" { path = "/source/tmp/capture/clean.png", renderLayers = "all !EditorUI !debug" } { path = "/source/tmp/capture/half.png", width = 960, height = 540 } { path = "/source/tmp/capture/still.png", deterministic = true } { path = "/source/tmp/capture/normals.png", pass = "normal" } { path = "/source/tmp/capture/own_colour.png", clearAir = true } ``` ## tools/characterController/install {#tools-charactercontroller-install} ```lua characterController.install(entityId: string, opts?: InstallOpts) -> InstallResult ``` Install `CharacterController` + `Locomotion` + `MovementState` on an entity, with an optional third-person camera child. Applies an optional preset (e.g. `'synty'`) for default property values, then layers user overrides on top. Idempotent per component — running `install` twice on the same entity is a no-op for already-present components. The camera child carries a `Camera` component plus the `orbital_follow` controller targeting the owning entity; skip it with `camera = false`. **Parameters** - `entityId` `string` - `opts` `InstallOpts` _(optional)_ **Returns** `InstallResult` ```lua "Player", { preset = "synty" } player.id(), { preset = "humanoid", overrides = { moveSpeed = 8.0 } } entityId, { camera = false } -- no camera child ``` ## tools/characterController/uninstall {#tools-charactercontroller-uninstall} ```lua characterController.uninstall(entityId: string) -> UninstallResult ``` Tear down everything `characterController.install()` added on an entity: `AnimDebug` (if present), `Locomotion`, `MovementState`, `CharacterController`, and any child entity carrying an `orbital_follow` controller targeting this entity. Idempotent — missing components are skipped silently. Returns the count of despawned camera children so callers can verify cleanup. **Parameters** - `entityId` `string` **Returns** `UninstallResult` ```lua "Player" player.id() ``` ## tools/cutscene/pause {#tools-cutscene-pause} ```lua cutscene.pause() -> shared.ZmToolResult ``` Freeze the cutscene playing now. The clock stops and so does the scene under it — components stop updating, physics stops stepping, animation stops advancing — which is what keeps one shot on screen for as many captures and edits as the work needs. `cutscene.resume` starts both again. **Returns** `shared.ZmToolResult` ## tools/cutscene/play {#tools-cutscene-play} ```lua cutscene.play(source: string, paused?: boolean) -> shared.ZmToolResult ``` Play a cutscene now, from the module its definition is returned from — the same call a scene entrypoint or a `CutsceneTrigger` makes, so what you see here is what a player sees. Starting one while another is playing ends that one first. **Parameters** - `source` `string` - `paused` `boolean` _(optional)_ **Returns** `shared.ZmToolResult` ```lua "mygame.scenes.intro" "mygame.scenes.intro", true ``` ## tools/cutscene/rate {#tools-cutscene-rate} ```lua cutscene.rate(r: number) -> shared.ZmToolResult ``` Set the playback rate of the cutscene playing now. 1 is real time, 0.25 slow motion, 2 double speed; a negative rate runs it backwards. The cutscene itself is untouched — only how fast its clock moves. **Parameters** - `r` `number` **Returns** `shared.ZmToolResult` ```lua 0.25 -1 ``` ## tools/cutscene/resume {#tools-cutscene-resume} ```lua cutscene.resume() -> shared.ZmToolResult ``` Start the cutscene playing now again after `cutscene.pause`. **Returns** `shared.ZmToolResult` ## tools/cutscene/seek {#tools-cutscene-seek} ```lua cutscene.seek(t: number) -> shared.ZmToolResult ``` Move the clock of the cutscene playing now to an exact moment. The frame it lands on is the frame that time would have produced — the camera, the fade and the subtitle are all re-derived — so a shot can be checked without watching the cutscene up to it. **Parameters** - `t` `number` **Returns** `shared.ZmToolResult` ```lua 6.5 ``` ## tools/cutscene/skip {#tools-cutscene-skip} ```lua cutscene.skip() -> shared.ZmToolResult ``` Skip the cutscene playing now to its closing fade — what a player pressing the skip key does. Cues between here and the end still fire, so a cutscene that opens a door on its way out opens it. **Returns** `shared.ZmToolResult` ## tools/cutscene/status {#tools-cutscene-status} ```lua cutscene.status() -> shared.ZmToolResult ``` Report the cutscene playing now — its name, where its clock is, which shot is on screen, and whether it is paused or running at an unusual rate. Reads the cutscene whatever started it, so this answers about the one a scene is playing, not a private copy. **Returns** `shared.ZmToolResult` ## tools/cutscene/stop {#tools-cutscene-stop} ```lua cutscene.stop() -> shared.ZmToolResult ``` End the cutscene playing now. The camera, the overlay and the player's controls all go back the way they were, the same as when a cutscene reaches its end on its own. **Returns** `shared.ZmToolResult` ## tools/debug/inspect {#tools-debug-inspect} ```lua debug.inspect(target: string | { any }, opts?: InspectOpts) -> InspectResult ``` Inspect entity component state for every entity matching the target. A name resolves to every matching entity; an id to itself; arrays and entity proxies work too. Each match reports its script components (serialized public data) and native ECS components, selected by `opts.include`. **Parameters** - `target` `string | { any }` - `opts` `InspectOpts` _(optional)_ **Returns** `InspectResult` ```lua 'player' 'lamp', { include = "ecs" } 'enemy_*', { types = { "Health" }, limit = 5 } ``` ## tools/debug/playSession {#tools-debug-playsession} ```lua debug.playSession(enabled?: boolean) -> { playSession: boolean } ``` Show or hide the debug overlay in play mode. Edit mode always shows the overlay; play mode shows it only while this session is on — the way to watch bones, colliders, or bounds on a running, animating scene. The flag lives in memory only and is never saved, so debug visibility can never be permanently toggled on by accident; it resets on engine restart. **Parameters** - `enabled` `boolean` _(optional)_ **Returns** `{ playSession: boolean }` ```lua true false ``` ## tools/debug/problems {#tools-debug-problems} ```lua debug.problems(opts?: ProblemsOpts) -> ProblemsResult ``` Return the errors and warnings the engine has logged since your last call — the non-crashing failures (contract violations, component `awake`/`update` throws, auto-disabled components, unresolved requires, bridged renderer/asset errors) that otherwise never surface in `execute` results. Each call advances a read-cursor, so repeated calls report only what is new, oldest first (the root-cause error surfaces ahead of the cascade it triggered). **When something you built does not behave, call this FIRST** — the engine has usually already logged why. **Parameters** - `opts` `ProblemsOpts` _(optional)_ **Returns** `ProblemsResult` ```lua { level = "error", limit = 20 } { all = true } ``` ## tools/debug/scope {#tools-debug-scope} ```lua debug.scope(target?: (string | { any })) -> { scoped: { string }, count: number } ``` Limit every enabled debug category to a set of entities, so the overlay is focused on specific objects. Call with no argument (or an empty list) to clear the focus and draw for every entity again. **Parameters** - `target` `(string | { any })` _(optional)_ **Returns** `{ scoped: { string }, count: number }` ```lua 'player' { 'player', 'enemy' } ``` ## tools/debug/set {#tools-debug-set} ```lua debug.set(category: string, enabled?: boolean) -> { [string]: boolean } ``` Show or hide a debug-visualization overlay category. The overlay is ambient editor tooling drawn for the whole scene; this flips which categories draw. A category is settable before the package that draws it has registered — the state is kept and applies when it arrives — so a script that configures overlays does not depend on how far along the session is. `debug.state` lists what is set. **Parameters** - `category` `string` - `enabled` `boolean` _(optional)_ **Returns** `{ [string]: boolean }` ```lua 'colliders' 'bones', true 'all', false ``` ## tools/debug/state {#tools-debug-state} ```lua debug.state() -> DebugState ``` Read the current debug-visualization state: which categories draw, the entity scope, whether the play-mode session is on, and the engine mode. `categories` covers every category the session knows — those a package has registered to draw, plus any set before its provider arrived — so what this lists is what `debug.set` accepts. **Returns** `DebugState` ## tools/detail/resident {#tools-detail-resident} ```lua detail.resident(axis?: string) -> { [string]: any } ``` Report what a world has resident of its detail right now. Covers terrain's LOD cut, a voxel world's chunk meshes, spatial streaming's cell store and mesh LOD's level selection, each read from the system's own state rather than from the component fields that asked for it. Every voxel chunk carries what became of its mesh build, so a world that stands with the right block count and draws nothing reads as what it is. The same reading is served at `/zero/runtime/observations/streaming`. **Parameters** - `axis` `string` _(optional)_ **Returns** `{ [string]: any }` ```lua "voxel" ``` ## tools/detail/whyNotDrawn {#tools-detail-whynotdrawn} ```lua detail.whyNotDrawn(subject: any) -> { [string]: any } ``` Answer why a piece of a world's detail is not on screen. The reason is the nearest cause from a closed set — `drawn`, `notManaged`, `notBuilt`, `buildQueued`, `buildFailed`, `builtEmpty`, `emittedNothing`, `outsideRadius`, `evicted`, `coarserLevel`, `finerLevel`, `noSuchLevel`, `hidden` — so it names the thing to change rather than a consequence of it, and `detail` carries the engine's own message when a mesh build was dropped. Reads the four detail systems' state rather than the components' fields. **Parameters** - `subject` `any` _(optional)_ **Returns** `{ [string]: any }` ```lua "Vox" ``` ## tools/diagnostics/errors {#tools-diagnostics-errors} ```lua diagnostics.errors(entityFilter?: (string | EntityFilterTable)) -> { EntityErrors } ``` Get all component/entity errors in the scene. With no argument, returns errors for all entities (enumerated via `vfs.list("/runtime/layers/main/entities")`). With an entity name or ID, returns errors for that entity only. Each entity's errors are read from `/runtime/layers/main/entities//errors` — values of `"(none)"` or `""` are treated as no errors. Read-only — does not modify anything. **Parameters** - `entityFilter` `(string | EntityFilterTable)` _(optional)_ **Returns** `{ EntityErrors }` ```lua "lamp" ``` ## tools/diagnostics/summary {#tools-diagnostics-summary} ```lua diagnostics.summary() -> SceneSummary ``` Get a summary of the current scene. Enumerates entities via `vfs.list("/runtime/layers/main/entities")`, counts each entity's components by listing `/runtime/layers/main/entities//components`, counts entities with non-empty error files, and reports `Camera` component instances separately. Also surfaces rendering culling mode + stats via `__rendering.getCullingMode` / `__rendering.getCullStats` when available — GPU culling has no readback path so its stats slot becomes a notice string instead. Read-only — does not modify anything. **Returns** `SceneSummary` ## tools/diagnostics/validate {#tools-diagnostics-validate} ```lua diagnostics.validate() -> ValidationReport ``` Validate scene integrity: check for broken materials, missing model assets, and entity errors. Enumerates entities via `vfs.list("/runtime/layers/main/entities")`, reads each entity's `errors` file, and parses messages of the form `material '...' does not exist` / `Material:...not found ...'...'` / `mesh '...' not found` / `Model:...not found ...'...'` to surface broken references. Read-only — does not modify anything. **Returns** `ValidationReport` ## tools/editor/observe {#tools-editor-observe} ```lua editor.observe() -> { [string]: any } ``` What each editor action committed, and why it committed less than it was asked for. `lastDrag` is the most recent gizmo drag: the handle it held, the pivot it reconstructed against, what the pointer asked for and what the drag applied after snapping, and — per entity — the transform before, the transform handed to the engine, and the transform the engine HOLDS, read back from the engine. `lastGrab` is a press that landed on a handle and began no drag, with the reason. `lastDelete` / `lastDuplicate` carry the ids removed and created and the ones that refused; `lastCommand` tells a missing command from a disabled one from a broken predicate from a body that raised; `lastSelect` carries the ids before and after with the difference taken both ways. Every record names an `outcome` and, when that is not a clean commit, one `reason` from the closed set `reasons` enumerates. Answers in edit mode as well as play mode. **Returns** `{ [string]: any }` ## tools/entityOps/addComponents {#tools-entityops-addcomponents} ```lua entityOps.addComponents(targets: Targets, components: Components, opts?: AddComponentsOpts) -> { AddResult } ``` Attach component(s) to one or many entities in a single call. Targets are entity NAMES or ids (arrays and scene.find records work too), or a `scene.find` QUERY resolved for you — `{ name = { "wheel" } }`, `{ component = { "Light" } }`, `{ under = { "car" } }` — so you operate on a selection without looking it up first. Components are given as a name, an array of names, or a `{ Name = dataTable }` map carrying each component's setup data — names accept the leaf (`"Physics"`), the full identity (`"@builtin::components.Physics"`), a VFS path (resolved to its identity), or a case-insensitive partial resolved to the one component it can mean, all before anything mutates; a name matching nothing, or several components, is an error naming what it could not settle rather than a half-applied call. `create = true` spawns a fresh root entity for any string target that matches nothing, so one call can both create the entity and give it its setup. Returns one `{ id, name, added, created? }` record per entity. **Parameters** - `targets` `Targets` - `components` `Components` - `opts` `AddComponentsOpts` _(optional)_ **Returns** `{ AddResult }` ```lua "crate", { Physics = { kind = "dynamic" } } { "crate_1", "crate_2" }, { "Physics", "Audio" } "spinner", { Rotator = { speed = 2 } }, { create = true } ``` ## tools/entityOps/component {#tools-entityops-component} ```lua entityOps.component(componentType: string, opts?: ComponentInspectOpts) -> ComponentInfo ``` Inspect a component TYPE so you set fields that exist instead of guessing. Resolves the component by name / identity / VFS path and reports its public FIELDS (each with name, type, and current value), its callable METHODS, its lifecycle HOOKS (awake / update / onDestroy / …), asset-ref fields with their AssetRef type, and a one-line description. Pass `on` (an entity name or id that carries the component) and every field's `value` is that entity's LIVE value, read off its component proxy — a vector / struct / list as its plain table, a reference by the identity of what it points at (an asset as a `{ __ref, identity, name, type }` envelope, an entityRef as the entity id). Omit `on` and each `value` is the DECLARED DEFAULT as written in the component's source. Use this before `entityOps.addComponents` / `entityOps.spawn` to learn the exact field names and value shapes. **Parameters** - `componentType` `string` - `opts` `ComponentInspectOpts` _(optional)_ **Returns** `ComponentInfo` ```lua "Camera" "Model", { on = "my_prop" } "@builtin::components.Light" ``` ## tools/entityOps/duplicate {#tools-entityops-duplicate} ```lua entityOps.duplicate(targets: Targets, opts?: DuplicateOpts) -> { shared.TransformState } ``` Copy entities that already exist — a duplicate of a prop, or a numbered run of them spread along an axis. Targets resolve by NAME or id, an array of them, `scene.find` records, or a QUERY resolved for you (`{ name = { "crate" } }`, `{ component = { "Light" } }`, `{ under = { "room" } }`), so a whole selection is copied without looking its ids up first. `count` makes that many copies of EACH source (default 1). `offset` is a `{x,y,z}` world-space step that ACCUMULATES: copy 1 sits one offset from the source, copy 2 sits two, and so on — every copy is placed relative to the SOURCE, not to the copy before it. `name` names each copy and a `%d` in it becomes the copy's 1-based index (`"crate_%d"` → `crate_1`, `crate_2`); without it copies are named after their source. Copies carry the source's render layer. An unrecognised option key is an error naming the accepted set, and a count below 1 is an error, so a mistyped call never reads back as a successful no-op. Returns the full `{ id, name, position, localPosition, rotation, localRotation, eulerAngles, scale, parent }` state of every copy, in creation order. **Parameters** - `targets` `Targets` - `opts` `DuplicateOpts` _(optional)_ **Returns** `{ shared.TransformState }` ```lua "crate" "crate", { count = 5, offset = { 2, 0, 0 } } "pillar", { count = 4, offset = { 0, 3, 0 }, name = "pillar_%d" } { name = { "tree" } }, { offset = { 10, 0, 0 } } ``` ## tools/entityOps/fromAsset {#tools-entityops-fromasset} ```lua entityOps.fromAsset(source: string, opts?: FromAssetOpts) -> FromAssetResult ``` Instantiate an existing asset into the scene. Resolution-first: pass a name / path / identity STRING and the tool resolves it (limit the search with `type` to avoid name clashes), dispatches by the resolved category, and REPORTS the canonical asset it hit so you learn what it resolved to. A `bundle` or `avatar` instantiates via its own `:instantiate()` — `link` (default true) keeps the live Asset-component link so the source drives the hierarchy, `link = false` bakes the hierarchy into the scene. A `mesh` becomes a renderable (Model + mesh Collider). A `material` becomes a sphere carrying it. A `texture` becomes a plane sampling it. Anything else goes through the uniform scene-instantiation contract — a `gaussianSplat` capture becomes an entity drawing that cloud, and every other type whose assetType defines the hook works the same way, else a legible error. `parent` (an entity ref, id, or name) spawns the instance under that entity — it lands on the parent, and `position` then places it in the parent's space; an unresolvable parent fails the call before anything spawns. `position` / `rotation` / `scale` place it; `synced` replicates gameplay edits to peers. **Parameters** - `source` `string` - `opts` `FromAssetOpts` _(optional)_ **Returns** `FromAssetResult` ```lua "@builtin::avatars.humanoid" "oak_chest", { type = "bundle", position = {2, 0, 0} } "truck_model", { type = "bundle", parent = "truck_rig" } "gold", { type = "material" } "/zero/source/generated/meshes/a_statue.bundle", { link = false } ``` ## tools/entityOps/modify {#tools-entityops-modify} ```lua entityOps.modify(targets: Targets, ops: ModifyOps) -> { ModifyResult } ``` Change entity state — one tool for delete / enable / disable / internal / temporary / reparent / rename, over one or many entities. Targets are entity NAMES or ids (arrays and scene.find records work too), or a `scene.find` QUERY resolved for you — `{ name = { "wheel" } }`, `{ component = { "Light" } }`, `{ under = { "car" } }` — so you operate on a selection without looking it up first. Boolean ops take true, false, or "toggle". `delete` removes the entity and its whole subtree and wins over every other op. `enabled` drives the entity's active state, `internal` marks it engine plumbing — taken out of the default entity listings and the inspector default view, while it keeps rendering, `temporary` marks it as not-persisted. `parent` (a name or id) reparents; `unparent = true` makes it a scene root; `keepWorldTransform = false` keeps the local transform instead of the world pose when reparenting. `rename` sets a new name (single target only). `components` sets field values on components the entity ALREADY carries — `{ Camera = { fov = 60 }, Light = { intensity = 2 } }`, the same shape `spawn` takes, so creating with a value and changing it later are written alike; component names resolve the same forgiving way `addComponents` resolves them, and an entity that does not carry one named is an error rather than a silent skip. An unrecognised key is an error naming the accepted set, so a typo fails the call rather than reporting an empty `applied`. Returns one `{ id, name, applied }` record per entity. **Parameters** - `targets` `Targets` - `ops` `ModifyOps` **Returns** `{ ModifyResult }` ```lua "debug_probe", { internal = true } { "probe_a", "probe_b" }, { delete = true } "old_character", { enabled = "toggle" } "hat", { parent = "player_head" } "lamp", { components = { Light = { intensity = 4 } } } { component = { "Light" } }, { components = { Light = { intensity = 0 } } } ``` ## tools/entityOps/removeComponents {#tools-entityops-removecomponents} ```lua entityOps.removeComponents(targets: Targets, components: Components) -> { RemoveResult } ``` Detach component(s) from one or many entities in a single call — the counterpart to `entityOps.addComponents`. Targets resolve by NAME or id, an array of them, `scene.find` records, or a QUERY resolved for you (`{ component = { "Light" } }`, `{ name = { "lamp" } }`, `{ under = { "room" } }`), so you can strip a component from everything carrying it without naming a single entity. Components are given as a name or an array of names, and each name matches loosely: the leaf (`"Light"`), the full identity (`"@builtin::components.Light"`), a VFS path, or a case-insensitive partial (`"light"`) resolved to the one component it can mean — the response reports the CANONICAL name it landed on, so a half-remembered name both works and teaches you the real one. A name matching several components is an error listing the candidates rather than a guess, and a name matching none is an error too, so nothing is silently skipped. Every entity comes back as `{ id, name, removed, absent }`: `removed` lists what it actually carried and lost, `absent` lists what it never had — so a call that changed nothing is visible instead of reading like a success. **Parameters** - `targets` `Targets` - `components` `Components` **Returns** `{ RemoveResult }` ```lua "lamp", "Light" { "crate_1", "crate_2" }, { "Physics", "Audio" } { component = { "Light" } }, "Light" "lamp", "light" ``` ## tools/entityOps/roots {#tools-entityops-roots} ```lua entityOps.roots(targets: Targets) -> { RootHit } ``` Find the root ancestor of one or many entities — walks each up its parent chain to the top-level entity. Targets are entity names or ids (a single one, an array, or `scene.find` records), or a `scene.find` QUERY resolved for you — `{ name = { "wheel" } }`, `{ component = { "Light" } }`, `{ under = { "car" } }`. Returns one record per target with its resolved root id + name and the hop distance; a target that is already a root reports itself with depth 0. **Parameters** - `targets` `Targets` **Returns** `{ RootHit }` ```lua "player_hand" { "wheel_fl", "wheel_fr" } ``` ## tools/entityOps/spawn {#tools-entityops-spawn} ```lua entityOps.spawn(components: SpawnComponents | SpawnBatch, opts?: SpawnOpts) -> SpawnResult | { SpawnResult } ``` Spawn entities from a template — you name the components they carry and their field values, plus a transform. Spawn MANY in ONE call by passing a `{ defaults, items }` list: `defaults` holds what every entity shares and each `items` entry overrides only what differs, so a six-walled room is one call rather than six. Per-item keys win over the matching `defaults` key, and `components` merges per COMPONENT — an item naming `Model` replaces only that entry and keeps the shared `Collider`. Every item is validated before any entity is created, so a typo fails the whole call instead of leaving a half-built scene. Or pass a single `{ [ComponentName] = { field = value } }` map plus opts to spawn ONE entity. Each component is an AUTHORED component (leaf name like `"Model"`, a full identity, or a VFS path) added with its data so it serializes — native ECS components are intentionally not exposed, so you never author something that renders at runtime but vanishes on save. `position` places it; `rotation` takes a `{x,y,z,w}` (or `{x=,y=,z=,w=}`) quaternion or `{pitch,yaw,roll}` (or `{pitch=,yaw=,roll=}`) euler degrees; `scale` a number or `{x,y,z}`; `name` defaults to the first component's name. A spawn is recorded into the scene as it is made, so it is there again the next time the scene loads; `temporary` leaves an entity out of that record — nothing is written for it as it spawns and no save carries it — which is the spelling for content a build reproduces for itself. `internal`, `synced` (replicate gameplay edits to peers), and `attributes` carry the rest of the lifecycle. An unrecognised key is an error naming the accepted set — in `opts`, at the top level, in `defaults`, and in an item alike. Pass an empty components map to spawn a bare entity. Returns the spawned id, name, and component leaf names — one record for the single form, an array in item order for the list form. **Parameters** - `components` `SpawnComponents | SpawnBatch` - `opts` `SpawnOpts` _(optional)_ **Returns** `SpawnResult | { SpawnResult }` ```lua { Model = { model = "cube" }, BoxCollider = {} }, { position = {0, 1, 0} } { Light = { kind = "point", intensity = 5 } }, { name = "lamp", position = {0, 3, 0} } { Text3D = { content = "Hello", fontSize = 48 } }, { position = {0, 2, 0}, rotation = {0, 45, 0} } { defaults = { components = { Model = { model = "cube" }, BoxCollider = {} }, scale = { 4, 3, 0.2 } }, items = { { name = "wall_n", position = { 0, 1.5, -2 } }, { name = "wall_s", position = { 0, 1.5, 2 } }, { name = "wall_e", position = { 2, 1.5, 0 }, rotation = { 0, 90, 0 } }, { name = "wall_w", position = { -2, 1.5, 0 }, rotation = { 0, 90, 0 } } } } { defaults = { components = { Light = { kind = "point", intensity = 4 } } }, items = { { name = "lamp_a", position = { -3, 3, 0 } }, { name = "lamp_b", position = { 3, 3, 0 }, components = { Light = { kind = "point", intensity = 9 } } } } } ``` ## tools/entityOps/swap {#tools-entityops-swap} ```lua entityOps.swap(target: string | EntityRef, replacement: string | EntityRef, opts?: SwapOpts) -> SwapPlan ``` Replace one entity with another entity that already exists in the scene. The replacement is MOVED into the target's slot — same parent, local position, and rotation; the target's scale unless `keepScale = false`; the target's name unless `keepName = false` — and the target (with its whole subtree) is removed. Both arguments are entity names, ids, or EntityRef proxies. `dryRun = true` reports exactly what would move and what would be removed, without mutating. **Parameters** - `target` `string | EntityRef` - `replacement` `string | EntityRef` - `opts` `SwapOpts` _(optional)_ **Returns** `SwapPlan` ```lua "DefaultBody", "my_knight" "placeholder_car", "sports_car", { keepName = false } "DefaultBody", "my_knight", { dryRun = true } ``` ## tools/entityOps/transform {#tools-entityops-transform} ```lua entityOps.transform(targets: Targets | { TransformTarget }, ops?: TransformOps) -> { shared.TransformState } ``` Move, rotate and scale entities that already exist — set an absolute position / rotation / scale, apply a relative offset / rotation / scale multiplier, or snap to a grid, over one or many entities. Targets resolve by NAME or id, an array of them, `scene.find` records, or a QUERY resolved for you (`{ name = { "wall" } }`, `{ component = { "Light" } }`, `{ under = { "building" } }`) so you can move things without looking their ids up first. Absolute ops: `position` and `rotation` are world-space, `localPosition` and `localRotation` are parent-relative, `scale` is a number or `{x,y,z}`. Relative ops: `offset` adds a position delta, `rotate` applies a rotation on top of the current one, `scaleBy` multiplies the current scale; `space` ("world" default, or "local") governs those relative ops. `snap` quantizes the resulting position to grid steps. Rotations take a `{x,y,z,w}` quaternion or `{pitch,yaw,roll}` euler degrees, the same forms `entityOps.spawn` accepts. Absolute and relative forms of one channel are exclusive and passing both is an error, and an unrecognised option key is an error naming the accepted set, so a mistyped key never reads back as a successful no-op. Pass a LIST of `{ target = ..., }` records to give each entity its own values in a single call; a bad entry there fails the whole call before any entity moves. Called with NO ops it is a pure read. Always returns the resulting `{ id, name, position, localPosition, rotation, localRotation, eulerAngles, scale, parent }` per entity, so the call is both the write and the read. **Parameters** - `targets` `Targets | { TransformTarget }` - `ops` `TransformOps` _(optional)_ **Returns** `{ shared.TransformState }` ```lua "lamp", { position = { 0, 3, 0 } } { "wall_n", "wall_s" }, { offset = { 0, 2, 0 } } { name = { "wall" } }, { offset = { 0, 2, 0 } } "crate", { rotation = { 0, 45, 0 }, scale = 2 } "prop", { offset = { 1, 0, 0 }, space = "local", snap = 0.5 } "lamp" ``` ## tools/gui/bounds {#tools-gui-bounds} ```lua gui.bounds(id?: ElementId) -> (ElementRect | { [string]: ElementRect })? ``` Read a UI element's on-screen layout rect by id - `{ x, y, w, h }` plus content bounds/centres, in logical points. Omit the id for a map of every recorded element's rect. This is the space `gui.clickAt` and anchors use. **Parameters** - `id` `ElementId` _(optional)_ **Returns** `(ElementRect | { [string]: ElementRect })?` ```lua "glass/vertical@8" ``` ## tools/gui/captureElement {#tools-gui-captureelement} ```lua gui.captureElement(screen?: (string | CaptureElementArgs), element?: (string | { string }), opts?: CaptureElementOpts) -> CaptureElementResult ``` Render one UI element — or several composited by their on-screen positions — to a texture and save it as a JPG under `/source/tmp`, so you can READ it to see exactly how those elements render. Each element (by its `elementTree` id) is rendered into a right-sized render texture the same way a camera renders into a render texture; the result is read back, encoded JPG, written, and the texture destroyed (nothing stays GPU-resident). Pass one id for a single element, or a list of ids to capture several LAYERS together — the image covers their union bounds and each element is drawn at its real relative offset, so a panel and an icon sitting on different screens composite into one picture. Ids may span different screens; each element's screen is taken from its id. Find ids with `gui.elementTree`. The screen must have rendered at least once (so the element has a measured size). **Parameters** - `screen` `(string | CaptureElementArgs)` _(optional)_ - `element` `(string | { string })` _(optional)_ - `opts` `CaptureElementOpts` _(optional)_ **Returns** `CaptureElementResult` ```lua "glass", "glass/vertical@10" ``` ## tools/gui/click {#tools-gui-click} ```lua gui.click(callbackId: string, value?: any) ``` Simulate a widget click by callback ID. Forwards to `ui.click(callbackId, value)`, which dispatches the registered `onCallback` handler associated with `callbackId`. **Parameters** - `callbackId` `string` - `value` `any` _(optional)_ ```lua "reset_btn" "volume_slider", 0.5 ``` ## tools/gui/clickAt {#tools-gui-clickat} ```lua gui.clickAt(x: (number | ClickAtArgs), y?: number, opts?: { button: (number | string)? }) -> ClickAtResult ``` Click at a logical screen position - a REAL pointer down+up. Coordinates are logical UI points (the space `gui.size` / `gui.bounds` / anchors use), not capture pixels. **Parameters** - `x` `(number | ClickAtArgs)` - `y` `number` _(optional)_ - `opts` `{ button: (number | string)? }` _(optional)_ **Returns** `ClickAtResult` ```lua 640, 360 ``` ## tools/gui/clickElement {#tools-gui-clickelement} ```lua gui.clickElement(id: (string | ClickElementArgs), opts?: { button: (number | string)?, duration: number? }) -> ClickElementResult ``` Click a UI element by its `elementTree` / layout id: a REAL pointer down+up at the element's centre. Works on any visible widget (no author-assigned callback needed) - the complement to `gui.click`, which needs a callback id. Find ids with `gui.elementTree`. **Parameters** - `id` `(string | ClickElementArgs)` - `opts` `{ button: (number | string)?, duration: number? }` _(optional)_ **Returns** `ClickElementResult` ```lua "glass/vertical@10" ``` ## tools/gui/dragElement {#tools-gui-dragelement} ```lua gui.dragElement(from: (string | DragElementArgs), to?: string, opts?: { button: (number | string)? }) -> DragElementResult ``` Drag between two UI elements by their `elementTree` ids: press at the first element's centre, move to the second, release. **Parameters** - `from` `(string | DragElementArgs)` - `to` `string` _(optional)_ - `opts` `{ button: (number | string)? }` _(optional)_ **Returns** `DragElementResult` ```lua "slider_nub", "slider_end" ``` ## tools/gui/elementTree {#tools-gui-elementtree} ```lua gui.elementTree(screen: string | { screen: string }) ``` List a screen's rendered element hierarchy with each element's on-screen layout rect. Each node is `{ id, type, bounds, children }` where `bounds` is `{ x, y, w, h }` in logical points, present once the element has been measured. `id` is the `id` set on the node when the author gave it one, otherwise `/@`. Pass an id (or several) to `gui.captureElement` to screenshot that panel or widget. **Parameters** - `screen` `string | { screen: string }` ```lua "glass" ``` ## tools/gui/focus {#tools-gui-focus} ```lua gui.focus(id?: ElementId) -> FocusResult ``` Focus a widget by id so it takes keyboard input; call with no id (or `""`) to blur the current focus. Forwards to `ui.focus` / `ui.blur`. **Parameters** - `id` `ElementId` _(optional)_ **Returns** `FocusResult` ```lua "search_input" ``` ## tools/gui/fonts {#tools-gui-fonts} ```lua gui.fonts(system?: (boolean | { system: boolean })) -> { any } ``` List every font family a `style.fontFamily` can select, with the aliases that also select it, the concrete face in each weight/style slot, and whether it came from the host OS. Read from the registry the UI text renderer resolves a family through, so a family listed here is one a label renders in. A `fontFamily` naming something absent from this list paints in the default proportional face and is reported as `unknown-font-family` through `gui validate`. Forwards to `ui.listFonts()`. **Parameters** - `system` `(boolean | { system: boolean })` _(optional)_ **Returns** `{ any }` ```lua true ``` ## tools/gui/getTree {#tools-gui-gettree} ```lua gui.getTree(name: string) ``` Get the widget tree of a screen (for reading state). Forwards to `ui.getScreenTree(name)`. The returned tree mirrors the registered widget list and is suitable for inspection / diff-based test assertions. **Parameters** - `name` `string` ```lua "hud" ``` ## tools/gui/hide {#tools-gui-hide} ```lua gui.hide(name: string) -> shared.ScreenVisibility ``` Hide a screen and report the visibility it now carries. Forwards to `ui.hideScreen(name)` — the registered screen remains in the registry and can be re-shown via `gui.show`. Raises when no screen answers to `name`, naming the ones that do. **Parameters** - `name` `string` **Returns** `shared.ScreenVisibility` ```lua "hud" ``` ## tools/gui/hoverElement {#tools-gui-hoverelement} ```lua gui.hoverElement(id: ElementId) -> HoverElementResult ``` Move the pointer to a UI element's centre by its `elementTree` id, so the element's hover state paints. The cursor stays put - follow with `gui.captureElement` to see the hovered look. **Parameters** - `id` `ElementId` **Returns** `HoverElementResult` ```lua "glass/vertical@9" ``` ## tools/gui/panel {#tools-gui-panel} ```lua gui.panel(name: string, widgets: { any }, opts?: { layer: number?, visible: boolean? }) -> shared.ScreenVisibility ``` Create a UI screen from a widget list and report the visibility it now carries. Registers the screen via `ui.registerScreen` at `opts.layer`, then leaves it shown — or hidden when `opts.visible` is false, so a screen can be built ahead of the moment it appears. Each widget is `{ type, text?, id?, value?, color?, children?, onCallback?, ... }`. **Parameters** - `name` `string` - `widgets` `{ any }` - `opts` `{ layer: number?, visible: boolean? }` _(optional)_ **Returns** `shared.ScreenVisibility` ```lua "hud", { { type = "label", text = "Score: 0", id = "score" }, { type = "button", text = "Reset", onCallback = "reset_btn" } } ``` ## tools/gui/screens {#tools-gui-screens} ```lua gui.screens() ``` List every registered screen with `{ name, visible, layer, hasRoot }` - the top-level map of what UI exists right now. Forwards to `ui.listScreens`. ## tools/gui/scroll {#tools-gui-scroll} ```lua gui.scroll(dx: number, dy: number) ``` Simulate scroll input. Forwards to `ui.scroll(dx, dy)`. **Parameters** - `dx` `number` - `dy` `number` ```lua 0, -10 ``` ## tools/gui/scrollElement {#tools-gui-scrollelement} ```lua gui.scrollElement(id: (string | ScrollElementArgs), offsetY?: number) -> ScrollElementResult ``` Scroll a `scrollArea` to a vertical offset (pixels from the top) by its `elementTree` id — the reliable, element-targeted scroll. Prefer this over `scroll` (a mouse-wheel simulation) when you know which area to move. **Parameters** - `id` `(string | ScrollElementArgs)` - `offsetY` `number` _(optional)_ **Returns** `ScrollElementResult` ```lua "app/scrollArea@1.0.1", 240 ``` ## tools/gui/setTheme {#tools-gui-settheme} ```lua gui.setTheme(name: string) ``` Set the active UI theme. Forwards to `ui.setTheme(name)` — subsequent screen draws use the new theme. **Parameters** - `name` `string` ```lua "dark" ``` ## tools/gui/show {#tools-gui-show} ```lua gui.show(name: string) -> shared.ScreenVisibility ``` Show a screen and report the visibility it now carries. Forwards to `ui.showScreen(name)`. The screen must already be registered (via `gui.panel` or `ui.registerScreen`); a name no screen answers to raises, naming the ones that do. **Parameters** - `name` `string` **Returns** `shared.ScreenVisibility` ```lua "hud" ``` ## tools/gui/size {#tools-gui-size} ```lua gui.size() ``` Return the UI coordinate space `{ width, height }` in logical points - the space `gui.bounds`, anchors, and `gui.clickAt` use (not a capture's pixel size). Forwards to `ui.screenSize`. ## tools/gui/state {#tools-gui-state} ```lua gui.state(id: ElementId) -> WidgetResponse? ``` Read a widget's live interaction snapshot by id: `{ clicked, hovered, focused, changed, value }`. Assert what a UI is doing after you drive it. Forwards to `ui.response`. **Parameters** - `id` `ElementId` **Returns** `WidgetResponse?` ```lua "volume_slider" ``` ## tools/gui/themes {#tools-gui-themes} ```lua gui.themes() -> { string } ``` List registered themes. Forwards to `ui.listThemes()`. **Returns** `{ string }` ## tools/gui/toggle {#tools-gui-toggle} ```lua gui.toggle(name: string) -> shared.ScreenVisibility ``` Flip a screen's visibility and report the visibility it now carries. Reads the screen's current state from `ui.listScreens()`, then calls `ui.hideScreen` or `ui.showScreen`. Raises when no screen answers to `name`, naming the ones that do. **Parameters** - `name` `string` **Returns** `shared.ScreenVisibility` ```lua "hud" ``` ## tools/gui/update {#tools-gui-update} ```lua gui.update(screenName: string, widgetId: string, props: { [string]: any }) ``` Update a specific widget inside a screen by widget ID. Reads the current widget tree via `ui.getScreenTree(screenName)`, walks it to find the widget with the matching `id`, copies every key from `props` onto the matched node, and writes the modified tree back via `ui.updateScreen`. If the screen does not exist, prints a warning and returns without erroring. **Parameters** - `screenName` `string` - `widgetId` `string` - `props` `{ [string]: any }` ```lua 'hud', 'score', { text = 'Score: 500' } ``` ## tools/gui/validate {#tools-gui-validate} ```lua gui.validate(screen?: (string | { screen: string })) -> any ``` Return the diagnostics from the last render of a screen (or all screens when no name is given): unknown widget types, bad props, decode/build errors. First stop when a screen renders wrong. Forwards to `ui.lastValidation`. **Parameters** - `screen` `(string | { screen: string })` _(optional)_ **Returns** `any` ```lua "glass" ``` ## tools/gui/widgetProps {#tools-gui-widgetprops} ```lua gui.widgetProps(typeName: string) -> table? ``` Get property definitions for a widget type. Forwards to `ui.getWidgetProps(typeName)` — the returned table describes every property a widget of this type accepts (name, type, default). **Parameters** - `typeName` `string` **Returns** `table?` ```lua "button" ``` ## tools/gui/widgetTypes {#tools-gui-widgettypes} ```lua gui.widgetTypes() -> { string } ``` List available widget types. Forwards to `ui.getWidgetTypes()`. **Returns** `{ string }` ## tools/ik/bones {#tools-ik-bones} ```lua ik.bones(of: string | EntityRef, filter?: string) -> BonesResult ``` List a rigged body's bones with their world positions and parents. Resolves the body itself or the first descendant carrying a rigged skeleton, so it can be called on a character root without knowing where inside the spawned hierarchy the skeleton lives. Also returns the canonical role map when the rig has one, which is what `IKLimb.role` and `IKRig` resolve through; a rig with no retarget profile returns an empty map, and its chains have to be named bone by bone. **Parameters** - `of` `string | EntityRef` - `filter` `string` _(optional)_ **Returns** `BonesResult` ```lua "hero" "hero", "hand" player.avatar.id() ``` ## tools/ik/reach {#tools-ik-reach} ```lua ik.reach(of: string | EntityRef, chain: string, target?: (string | EntityRef)) -> ReachResult ``` Report a chain's reachable band and, when a target is given, whether that target falls inside it. A limb reaches as far as its bones are long and no further: beyond that the chain extends straight toward the target and stops, which is correct and indistinguishable from a broken solver. Under `minReach` (the fold limit) it cannot fold tightly enough. Everything is reported in world units, so the rig's model space — where a 0.61 m arm reports a reach near 61 — does not have to be reasoned about. **Parameters** - `of` `string | EntityRef` - `chain` `string` - `target` `(string | EntityRef)` _(optional)_ **Returns** `ReachResult` ```lua "hero", "rightarm" "hero", "rightarm", "doorknob" "crane", "boom_base..boom_tip", "hook" ``` ## tools/ik/state {#tools-ik-state} ```lua ik.state(of: string | EntityRef) -> StateResult ``` Gather every IK component on an entity and report each one's state, so "is anything solving at all" is a single call. Each entry carries a `status` in words: a body spawned from a bundle takes a few frames to arrive, and a paused engine never advances those frames, so "not ready" on its own does not distinguish a wait that clears from one that never will. Where a component reports a distance to its target, that number is the residual after solving — small means the solve arrived, and it is not the distance to compare against a limb's reach (use `ik.reach`). **Parameters** - `of` `string | EntityRef` **Returns** `StateResult` ```lua "hero" player.avatar.id() ``` ## tools/importers/await {#tools-importers-await} ```lua importers.await(path: string, timeoutSecs?: number) -> AwaitResult ``` Wait until the import job for `path` reaches a terminal state — `imported`, `failed`, `skipped`, or `unclaimed` — or the timeout elapses. Returns the job record (still `running` on timeout). When no job exists for the path at all, returns the gate explanation instead, so the call always answers what happened. **Parameters** - `path` `string` - `timeoutSecs` `number` _(optional)_ **Returns** `AwaitResult` ```lua "/zero/source/models/gun.fbx" "/zero/source/models/gun.fbx", 60 ``` ## tools/importers/cancel {#tools-importers-cancel} ```lua importers.cancel(path?: string) -> CancelResult ``` Cancel a queued source before it imports, or every queued source at once. Pass a `path` to cancel just that one; omit it to cancel ALL queued sources (an accidental 1k-file drop). Sources already importing are left to finish. A cancelled source settles as a `cancelled` job, visible in `importers.status`. **Parameters** - `path` `string` _(optional)_ **Returns** `CancelResult` ```lua "/zero/source/models/gun.fbx" ``` ## tools/importers/explain {#tools-importers-explain} ```lua importers.explain(path: string) -> ExplainResult ``` Explain what the importer system would do with `path` right now, without importing: whether the file exists and reads, which importers claim it, and which gate (if any) blocks an import. `verdict` is `would-import` or `blocked`; when blocked, `reason` names the gate — `missing` (no such file), `unreadable`, `no-claimant` (no importer claims the extension/content), `already-in-own-bundle` (the source already lives inside its produced asset), or `unchanged-content` (the bytes match the last import; `output` points at the existing asset). **Parameters** - `path` `string` **Returns** `ExplainResult` ```lua "/zero/source/models/gun.fbx" ``` ## tools/importers/imported {#tools-importers-imported} ```lua importers.imported() -> ImportedResult ``` List every imported asset in the world with its source and the importer that produced it. Each row: `{ asset, source = { guid, path }, importer (guid), importerName, iteration, at }`, newest import first. The stored importer link is the guid; `importerName` resolves it for display. **Returns** `ImportedResult` ```lua use_tool { toolbox = "importers", tool = "imported" } ``` ## tools/importers/list {#tools-importers-list} ```lua importers.list() -> { count: number, importers: { { name: string, identity: string } } } ``` List every registered importer with its name and identity. Importers are `.importer/` assets, each a `canImport(path, bytes)` + `import(ctx)` pair; a written source file is offered to each claimant in registration order and the first to produce output wins. **Returns** `{ count: number, importers: { { name: string, identity: string } } }` ## tools/importers/queue {#tools-importers-queue} ```lua importers.queue() -> QueueResult ``` The live import backlog: queued sources first (still waiting behind the bounded concurrency, in FIFO order) then the ones importing right now. A bulk drop of N files imports one at a time, so this is where you watch the queue drain. Cancel queued items with `importers.cancel`. **Returns** `QueueResult` ## tools/importers/run {#tools-importers-run} ```lua importers.run(target: string | { string }, opts?: RunOpts) -> RunResult ``` Import/reimport one target, many targets, or a folder. A produced asset reimports in place (source resolved from its provenance); a loose source imports; a folder is scanned (recursive by default), its imported assets reimported and loose sources imported, filtered by `opts.mode` ("all" | "new" | "existing"). `mode` governs folder scanning; explicit path/array targets are always processed. **Parameters** - `target` `string | { string }` - `opts` `RunOpts` _(optional)_ **Returns** `RunResult` ```lua "/zero/source/guns" ``` ## tools/importers/status {#tools-importers-status} ```lua importers.status(opts?: { state: ImportJobState?, path: string?, limit: number? }) -> StatusSummary ``` List recent import jobs, newest first, with the live queue depth. Every dispatch is recorded: `queued` (waiting behind the bounded concurrency), `running` (import in flight), `imported` (done — `output` is the produced asset path), `failed` (the importer threw — `error` carries the message), `unclaimed` (every importer deferred), `skipped` (gated — `reason` is `already-in-own-bundle`, `unchanged-content`, `no-claimant`, or `unreadable`), and `cancelled` (a queued source cancelled before it ran). `backlog` is the exact queue depth (`{ queued, running }`), `active` lists the jobs importing right now, and `totals` tallies every recorded job by state — poll those three to watch a bulk drop drain. See the full backlog list with `importers.queue`; drop queued items with `importers.cancel`. Filter the `jobs` window with `opts.state` (one state), `opts.path` (substring match on the source path), and `opts.limit` (default 25). **Parameters** - `opts` `{ state: ImportJobState?, path: string?, limit: number? }` _(optional)_ **Returns** `StatusSummary` ```lua { state = "failed" } { path = "weapons", limit = 5 } ``` ## tools/inputAuthor/catalog {#tools-inputauthor-catalog} ```lua inputAuthor.catalog() -> { any } ``` Every control the catalog knows, with what each is bound to on keyboard, gamepad and touch. Naming one of these in `map` or `control` gets all three filled in. **Returns** `{ any }` ## tools/inputAuthor/check {#tools-inputauthor-check} ```lua inputAuthor.check(map: string) -> any ``` Read a `.inputMap` and report every problem across its controls — a missing device class, a malformed record, a button whose class is not an array. Reports all of them at once rather than stopping at the first, and activates nothing, so a scheme can be checked before a world runs it. **Parameters** - `map` `string` **Returns** `any` ```lua "racer" ``` ## tools/inputAuthor/control {#tools-inputauthor-control} ```lua inputAuthor.control(mapPath: string, control: any) -> string ``` Add a control to an existing `.inputMap`, carrying keyboard, gamepad and touch. A catalog name arrives pre-filled; anything else needs all three classes from you. **Parameters** - `mapPath` `string` - `control` `any` _(optional)_ **Returns** `string` ```lua "/zero/source/inputMaps/racer.inputMap", "jump" mapPath, { name = "horn", label = "Horn", kind = "button", kbm = '{ B.key("KeyH") }', gamepad = '{ B.padButton("north") }', touch = '{ B.touchButton({ zone = "right-lower" }) }' } ``` ## tools/inputAuthor/map {#tools-inputauthor-map} ```lua inputAuthor.map(name: string, controls: { any }, opts?: MapOpts) -> any ``` Write a `.inputMap/` and every control it declares, each carrying keyboard, gamepad and touch. **Parameters** - `name` `string` - `controls` `{ any }` - `opts` `MapOpts` _(optional)_ **Returns** `any` ```lua "racer", { "move", "brake", { name = "boost", from = "sprint", label = "Nitro" } } "shooter", { "move", "look", "attack", "aim", "reload", "jump" } "driving", { "move", "brake" }, { group = "vehicle", suppresses = { "player" } } ``` ## tools/inputSim/bindings {#tools-inputsim-bindings} ```lua inputSim.bindings() -> { any } ``` Every control that is live right now: its name, the label a player sees, its kind, and which activated map contributed it. **Returns** `{ any }` ## tools/inputSim/click {#tools-inputsim-click} ```lua inputSim.click(opts?: ClickOpts) ``` Click a mouse button — press, optional hold, release — optionally moving the cursor to `(x, y)` first. **Parameters** - `opts` `ClickOpts` _(optional)_ ```lua { x = 400, y = 300 } { button = 1 } ``` ## tools/inputSim/device {#tools-inputsim-device} ```lua inputSim.device(class?: string) -> string ``` Read the active device class, or force one. With no argument this reports what the session currently looks like: "kbm", "touch" or "gamepad". **Parameters** - `class` `string` _(optional)_ **Returns** `string` ```lua "touch" "auto" ``` ## tools/inputSim/drag {#tools-inputsim-drag} ```lua inputSim.drag(dx: number, dy: number, steps?: number) ``` Drag across the on-screen look zone by `(dx, dy)` pixels, in `steps` increments so the per-frame deltas a look binding reads are real rather than one impossible jump. **Parameters** - `dx` `number` - `dy` `number` - `steps` `number` _(optional)_ ```lua 200, 0 ``` ## tools/inputSim/fired {#tools-inputsim-fired} ```lua inputSim.fired(peek?: boolean) -> { any } ``` Every control that fired since this tool last ran, with how many times and on which device class. Reading CLEARS the record, so two calls around an action answer "did that input reach the game" without the previous test's results bleeding in. **Parameters** - `peek` `boolean` _(optional)_ **Returns** `{ any }` ```lua true ``` ## tools/inputSim/held {#tools-inputsim-held} ```lua inputSim.held() -> any ``` Everything the session is holding down right now: keys, mouse buttons, touch contacts, the on-screen stick, and connected pads with the buttons they hold. `atRest` is true when it holds nothing. **Returns** `any` ## tools/inputSim/key {#tools-inputsim-key} ```lua inputSim.key(key: string, duration?: number) ``` Tap a key — down, optionally held for `duration` seconds, then up. Queues the simulated events, yields a frame so they drain, and ticks so subscribers fire before the call returns. **Parameters** - `key` `string` - `duration` `number` _(optional)_ ```lua "Space" "KeyW", 2 ``` ## tools/inputSim/keyDown {#tools-inputsim-keydown} ```lua inputSim.keyDown(key: string) ``` Press a key and leave it HELD until `keyUp` releases it. A second `keyDown` on a held key produces no new press edge — pair every `keyDown` with a `keyUp`, or use `key` for a whole tap. **Parameters** - `key` `string` ```lua "ShiftLeft" ``` ## tools/inputSim/keyUp {#tools-inputsim-keyup} ```lua inputSim.keyUp(key: string) ``` Release a key. Only the release re-arms the next press edge. **Parameters** - `key` `string` ```lua "ShiftLeft" ``` ## tools/inputSim/layout {#tools-inputsim-layout} ```lua inputSim.layout() -> any ``` What the touch overlay is drawing right now: each visible button with its label and centre, the stick and look zones, and whatever overflowed behind the fan. **Returns** `any` ## tools/inputSim/listMacros {#tools-inputsim-listmacros} ```lua inputSim.listMacros() -> { AssetRef } ``` Enumerate every registered `.inputMacro` asset in the project. Thin wrapper over `asset.list("inputMacro")`. Returns an array of `AssetRef` handles suitable for direct passing to `sim.macro`. **Returns** `{ AssetRef }` ## tools/inputSim/lockPointer {#tools-inputsim-lockpointer} ```lua inputSim.lockPointer(locked: boolean) -> boolean ``` Lock the pointer (cursor captured and hidden) or release it. A mouse-look binding is usually gated on the lock, so a look test that moves the cursor without locking first reads as no movement at all. **Parameters** - `locked` `boolean` **Returns** `boolean` ```lua true ``` ## tools/inputSim/macro {#tools-inputsim-macro} ```lua inputSim.macro(refOrEvents: MacroEventList | MacroEventsWrapper | AssetRef | string) ``` Play a macro of timed input events. Accepts: - inline event list: `{ { t = 0, op = "keyDown", arg = "KeyW" }, ... }` - `AssetRef` — loaded via `asset.resolve` + `vfs.read` - identity / path string of an `.inputMacro` asset. Each event: `{ t, op, arg }`. `t` is seconds since macro start (events are sorted on play). `op` is one of: `keyDown`, `keyUp`, `mouseDown`, `mouseUp`, `mouseMove`, `scroll`, `lockPointer`, `tap`, `click`. `arg` shape matches the op. No game-specific recipes — drive a player, drive a car, or drive a UI test through the same primitive. Author macros by hand or record them via `sim.recordMacro` and persist via `sim.saveMacro`. **Parameters** - `refOrEvents` `MacroEventList | MacroEventsWrapper | AssetRef | string` ```lua { { t = 0.0, op = "mouseDown", arg = 1 }, { t = 0.0, op = "keyDown", arg = "KeyW" }, { t = 0.5, op = "mouseMove", arg = { dx = 200, dy = 0 } }, { t = 1.5, op = "keyUp", arg = "KeyW" }, { t = 1.5, op = "mouseUp", arg = 1 } } asset.ref("my_walkthrough", "inputMacro") ``` ## tools/inputSim/mouseDown {#tools-inputsim-mousedown} ```lua inputSim.mouseDown(button?: number) ``` Press a mouse button and leave it HELD until `mouseUp`. **Parameters** - `button` `number` _(optional)_ ```lua 1 ``` ## tools/inputSim/mouseMove {#tools-inputsim-mousemove} ```lua inputSim.mouseMove(x: number, y: number) ``` Move the cursor to `(x, y)` in screen coordinates. The delta from the previous position is what a mouse-look binding reads, so two calls in a row produce a look movement. **Parameters** - `x` `number` - `y` `number` ```lua 640, 360 ``` ## tools/inputSim/mouseMoveBy {#tools-inputsim-mousemoveby} ```lua inputSim.mouseMoveBy(dx: number, dy: number) ``` Move the pointer by `(dx, dy)` pixels, the motion a mouse device reports. The same motion repeated keeps producing look movement, so a look axis can be held, or steered by a controller issuing a correction each tick. **Parameters** - `dx` `number` - `dy` `number` ```lua 0, 140 ``` ## tools/inputSim/mouseUp {#tools-inputsim-mouseup} ```lua inputSim.mouseUp(button?: number) ``` Release a mouse button. **Parameters** - `button` `number` _(optional)_ ```lua 1 ``` ## tools/inputSim/pad {#tools-inputsim-pad} ```lua inputSim.pad(name?: string) -> number ``` Connect a simulated pad and return the slot it took. `name` is the device name the pad reports, which is what decides the button legends a prompt draws — pass an Xbox, PlayStation or Nintendo name to check a scheme's prompts on that family. **Parameters** - `name` `string` _(optional)_ **Returns** `number` ```lua "Xbox Wireless Controller" "Sony DualSense Wireless Controller" ``` ## tools/inputSim/padDown {#tools-inputsim-paddown} ```lua inputSim.padDown(button: string, slot?: number) ``` Push a canonical pad button down and leave it held until `padUp`. **Parameters** - `button` `string` - `slot` `number` _(optional)_ ```lua "right_trigger" ``` ## tools/inputSim/padOff {#tools-inputsim-padoff} ```lua inputSim.padOff(slot?: number) ``` Disconnect the pad in `slot`. Anything it still held is released first, so a held action ends rather than sticking. **Parameters** - `slot` `number` _(optional)_ ```lua 0 ``` ## tools/inputSim/padPress {#tools-inputsim-padpress} ```lua inputSim.padPress(button: string, duration?: number, slot?: number) ``` Press a canonical pad button — down, optionally held, then up. Buttons are named by POSITION, not by the letter printed on them, so the same call works whatever pad is connected: south, east, west, north, left_shoulder, right_shoulder, left_trigger, right_trigger, left_stick, right_stick, select, start, guide, dpad_up, dpad_down, dpad_left, dpad_right. **Parameters** - `button` `string` - `duration` `number` _(optional)_ - `slot` `number` _(optional)_ ```lua "south" "left_shoulder", 1.5 ``` ## tools/inputSim/padStick {#tools-inputsim-padstick} ```lua inputSim.padStick(stick: string, x: number, y: number, duration?: number, slot?: number) ``` Push a thumbstick to `(x, y)`, each -1..1 with y screen-down positive — the same convention the on-screen stick reports, so a binding reads the same shape from either. Holds until pushed back to zero, or for `duration` seconds if you pass one. **Parameters** - `stick` `string` - `x` `number` - `y` `number` - `duration` `number` _(optional)_ - `slot` `number` _(optional)_ ```lua "left", 0, -1 "right", 1, 0, 2 ``` ## tools/inputSim/padTrigger {#tools-inputsim-padtrigger} ```lua inputSim.padTrigger(trigger: string, value: number, duration?: number, slot?: number) ``` Squeeze a trigger to `value`, 0..1. Past half throw the trigger's digital button latches too, so a scheme binding either the analog travel or the button sees this. **Parameters** - `trigger` `string` - `value` `number` - `duration` `number` _(optional)_ - `slot` `number` _(optional)_ ```lua "right", 1 ``` ## tools/inputSim/padUp {#tools-inputsim-padup} ```lua inputSim.padUp(button: string, slot?: number) ``` Release a canonical pad button. **Parameters** - `button` `string` - `slot` `number` _(optional)_ ```lua "right_trigger" ``` ## tools/inputSim/pinch {#tools-inputsim-pinch} ```lua inputSim.pinch(amount: number, steps?: number) ``` Pinch two fingers together (negative) or spread them apart (positive) by `amount` pixels, over `steps` frames. What a zoom binding reads on a phone. **Parameters** - `amount` `number` - `steps` `number` _(optional)_ ```lua 150 ``` ## tools/inputSim/recordMacro {#tools-inputsim-recordmacro} ```lua inputSim.recordMacro(opts?: RecordMacroOpts) -> ({ MacroEvent }, number) ``` Capture real input over a window. Polls `Zin.state.*` every `sampleInterval` seconds (default `0.05`); emits a timed event whenever a key, mouse button, mouse delta, or scroll changes. Returns the events array and the spawned task handle. Caller decides whether to play immediately, save to disk via `sim.saveMacro`, or both. Generic — works for any input-driven scenario (player walk, car drive, UI flow, build sequence). Stops automatically after `duration` seconds, or earlier if `until_()` returns true. **Parameters** - `opts` `RecordMacroOpts` _(optional)_ **Returns** `({ MacroEvent }, number)` ```lua { duration = 3.0 } ``` ## tools/inputSim/release {#tools-inputsim-release} ```lua inputSim.release() -> any ``` Return the session to rest: lift every touch contact, drop the on-screen stick, release every key and mouse button that is down, and disconnect every connected pad. **Returns** `any` ## tools/inputSim/saveMacro {#tools-inputsim-savemacro} ```lua inputSim.saveMacro(name: string, events: { MacroEventRecord }) -> AssetRef ``` Persist a recorded or hand-authored event list to a `.inputMacro` asset on disk at `/zero/source/.inputMacro/events.json`. Returns the `AssetRef` of the saved macro for immediate playback. **Parameters** - `name` `string` - `events` `{ MacroEventRecord }` **Returns** `AssetRef` ```lua "walk_demo", { { t = 0.0, op = "keyDown", arg = "KeyW" }, { t = 1.0, op = "keyUp", arg = "KeyW" } } ``` ## tools/inputSim/scroll {#tools-inputsim-scroll} ```lua inputSim.scroll(dy: number) ``` Turn the mouse wheel by `dy`. Positive scrolls one way, negative the other; what that means is the binding's to decide. **Parameters** - `dy` `number` ```lua -3 ``` ## tools/inputSim/stick {#tools-inputsim-stick} ```lua inputSim.stick(x: number, y: number, duration?: number) ``` Push the on-screen movement stick to `(x, y)`, each -1..1, with y screen-down positive — the same convention a pad stick reports, so a binding reads the same shape from either. **Parameters** - `x` `number` - `y` `number` - `duration` `number` _(optional)_ ```lua 0, -1 -- full forward, held 0, 0 -- let go 1, 0, 2 -- hold right for two seconds, then release ``` ## tools/inputSim/tapButton {#tools-inputsim-tapbutton} ```lua inputSim.tapButton(label: string, duration?: number) ``` Tap the on-screen button labelled `label` — the text a player reads on it. The tap lands at the button's real centre, so it proves the control is reachable, not just that the action exists. **Parameters** - `label` `string` - `duration` `number` _(optional)_ ```lua "Jump" ``` ## tools/inputSim/touch {#tools-inputsim-touch} ```lua inputSim.touch(x: number, y: number, duration?: number) ``` Tap the screen at `(x, y)` — contact, optional hold, lift. The contact id is chosen for you; use `touchDown` / `touchMove` / `touchUp` when you need to drive several fingers at once. **Parameters** - `x` `number` - `y` `number` - `duration` `number` _(optional)_ ```lua 200, 600 200, 600, 0.5 ``` ## tools/inputSim/touchDown {#tools-inputsim-touchdown} ```lua inputSim.touchDown(x: number, y: number, pressure?: number) -> number ``` Put a finger down at `(x, y)` and leave it there. Returns the contact id `touchMove` and `touchUp` take, so several fingers can be driven at once — a two-finger pinch is two of these. **Parameters** - `x` `number` - `y` `number` - `pressure` `number` _(optional)_ **Returns** `number` ```lua 200, 600 ``` ## tools/inputSim/touchMove {#tools-inputsim-touchmove} ```lua inputSim.touchMove(id: number, x: number, y: number, pressure?: number) ``` Move the contact `id` to `(x, y)`. The per-frame delta is what a drag-look binding reads, so a look test is several of these in a row rather than one big jump. **Parameters** - `id` `number` - `x` `number` - `y` `number` - `pressure` `number` _(optional)_ ```lua id, 260, 580 ``` ## tools/inputSim/touchUp {#tools-inputsim-touchup} ```lua inputSim.touchUp(id: number) ``` Lift the contact `id`. **Parameters** - `id` `number` ```lua id ``` ## tools/lib/has {#tools-lib-has} ```lua lib.has(path: string) -> boolean ``` Check if a library asset exists at a path. Thin wrapper over `library.has(path)`. **Parameters** - `path` `string` **Returns** `boolean` ```lua "@builtin/models/Sample/DamagedHelmet" ``` ## tools/lib/list {#tools-lib-list} ```lua lib.list(assetType?: string) ``` List available library content. No args returns every registered library asset; pass an asset-type string to filter (e.g. "model", "shader", "material", "component"). Thin wrapper over `library.list(assetType)`. **Parameters** - `assetType` `string` _(optional)_ ```lua -- all library assets "model" -- just models ``` ## tools/lighting/addLight {#tools-lighting-addlight} ```lua lighting.addLight(name: string, position: Vec3, opts?: AddLightOpts) -> AddLightResult ``` Add a light to the scene: spawns an entity at `position` carrying a point Light (default) or SpotLight component. One consistent shape — use `setLight` to tweak it afterwards and `removeLight` to delete it. Lights cast shadows by default (a light whose objects cast none reads as broken); pass `castsShadows = false` for a cheap fill light. `intensity` means the same thing to both kinds: the two are rows of one light buffer shaded by `color * intensity * falloff`, so the same number at the same radius puts the same light on a surface either kind faces from the same place. A spot delivers it to the cone it opens on rather than all around itself, so it lights a smaller part of the room at that number — aim it and read the surface it lands on, and reach for `radius` and `angle` before reaching for a bigger `intensity`. **Parameters** - `name` `string` - `position` `Vec3` - `opts` `AddLightOpts` _(optional)_ **Returns** `AddLightResult` ```lua "torch1", { x = 5, y = 3, z = 0 }, { color = {1, 0.6, 0.2}, intensity = 1.5, radius = 8 } "beam", { x = 0, y = 6, z = 0 }, { kind = "spot", intensity = 1.5, radius = 8, angle = 30 } ``` ## tools/lighting/get {#tools-lighting-get} ```lua lighting.get() -> GetLightingResult ``` Read the scene's lighting + sky state. Returns every light (entity name, id, kind, values), the sky entity and its component type + current values, and — when the sky is a material Skybox — the material's editable parameter names/kinds/values (what `setSky` `params` accepts). `sky.source = "fallback"` means the scene has NO explicit sky entity and renders the engine fallback (adds the missing-sky warning; `setSky` fixes it). Each light also reports `mobility` (how GI baking treats it), `enabled` (the component's own switch) and `contributing` — whether this light reaches the frame. Each kind answers it from what carries a light of that kind: a punctual light from the row the renderer holds for it, a directional light from whether it holds the sun, an ambient light from whether it holds the scene's ambient term. So it is false for a switched-off light of any kind, which holds neither a row nor a singleton, for a punctual light the renderer holds no row for, for a directional light that does not hold the sun, for an ambient light that does not hold the ambient term, and for a baked static light whose light comes from the bake rather than from the light itself. A light the renderer holds reports what it is doing with the light's shadow, beside the `castsShadows` flag the scene authored: `shadowing` is whether a shadow map is being drawn for it this frame, `shadowSlot` the point-shadow cube slot a point light was seated in, and `shadowLayer` the spot-shadow atlas layer a spot or rect filed into. Each is `-1` for a caster the pool had no room for, which renders lit and throws no shadow. The same row carries `layerMask`: the render layer mask of the entity carrying the light, which cameras whose include mask intersects it are lit by. A punctual, directional or ambient light answers `contributing`, `shadowing`, `shadowSlot`, `shadowLayer` and `holdsAmbient` from the light set the renderer resolved on its LAST frame, so one authored earlier in the same call reads `enabled = true` with `contributing = false` and no shadow fields; read it again a frame on and the renderer has an answer for it. A directional light reports `holdsSun`: the scene's sun is one field set with one holder, so `holdsSun = true` marks the light whose direction, colour, intensity and `castsShadows` the scene is lit and shadowed by. The values of a directional light that does not hold it are authored and unread until it takes the sun back. An ambient light reports `holdsAmbient` on the same rule: the scene's ambient term is one field set with one holder, so `holdsAmbient = true` marks the light whose colour and intensity the ambient term carries, and the values of the ambient lights beside it are authored and unread. A sky with `syncSunToLight` on drives the sun holder from its time of day, so that light's `direction`, `color` and `intensity` are what the sky put there rather than what the scene authored. When the two differ the record carries `resolved` — the values the geometry is lit by — and `drivenBy`, naming what is writing them. `directionals` and `ambients` are the scoped collections: one record per light entity, each carrying `entityId`, `layerMask` (the render layer mask of the entity carrying it — cameras whose include mask intersects it are lit by it), `color` and `intensity`, plus `direction` and `castsShadows` on a directional record. A light on an entity with no explicit render layer records the default layer. **Returns** `GetLightingResult` ## tools/lighting/removeLight {#tools-lighting-removelight} ```lua lighting.removeLight(name: string) -> RemoveLightResult ``` Remove a light entity by name (exact, then substring — ambiguity errors and lists the scene's lights). Despawns the entity. **Parameters** - `name` `string` **Returns** `RemoveLightResult` ```lua "torch1" ``` ## tools/lighting/setAmbient {#tools-lighting-setambient} ```lua lighting.setAmbient(opts: AmbientOpts) -> SetAmbientResult ``` Set the scene's ambient light. Modifies the entity carrying the scene's ambient light, spawning one when the scene has none, and reports the entity it wrote. Read-merge-write: ONLY the fields you pass change — `{ intensity = 0.5 }` keeps the authored color. **Parameters** - `opts` `AmbientOpts` **Returns** `SetAmbientResult` ```lua { color = {0.4, 0.4, 0.6}, intensity = 0.3 } { intensity = 0.5 } ``` ## tools/lighting/setLight {#tools-lighting-setlight} ```lua lighting.setLight(name: string, opts: SetLightOpts) -> SetLightResult ``` Update a light by entity name — exact match first, then substring (ambiguity errors and lists the scene's lights). Only the fields you pass change. Works on point, spot, area and distant lights and the sun/ambient entities. **Parameters** - `name` `string` - `opts` `SetLightOpts` **Returns** `SetLightResult` ```lua "torch1", { intensity = 3 } "sun", { direction = {-0.2, -1, -0.1} } ``` ## tools/lighting/setSky {#tools-lighting-setsky} ```lua lighting.setSky(sky?: string, opts?: SkyOpts) -> SetSkyResult ``` Set or reconfigure the scene's sky in one call. `sky` is a word: a procedural preset (`clear_day`, `sunset`, `sunrise`, `overcast`, `night`) applies that look via a ProceduralSky component; `studio` is the solid gray sky (Skybox over `sky_solid`); `none` turns the sky off explicitly (Skybox kind="none"); any other word resolves against the project's materials FILTERED to sky-domain shaders (exact identity → leaf name → substring) and the sky renders that material via a Skybox. Omit `sky` to reconfigure the current sky with `opts` only. The tool finds the scene's sky entity (creating a "sky" entity when absent) and writes the component — changes persist, replicate, and survive reload. **Parameters** - `sky` `string` _(optional)_ - `opts` `SkyOpts` _(optional)_ **Returns** `SetSkyResult` ```lua "sunset" "aurora", { params = { exposure = 1.4 } } nil, { timeOfDay = 3, autoCycle = true } "none" ``` ## tools/lighting/setSun {#tools-lighting-setsun} ```lua lighting.setSun(opts: SunOpts) -> SetSunResult ``` Set the scene's directional sun light. Modifies the entity carrying the scene's directional light, spawning one when the scene has none, and reports the entity it wrote. Read-merge-write: ONLY the fields you pass change — `{ intensity = 2 }` keeps the authored direction and color. A sky with `syncSunToLight` on drives the sun from its time of day, so setting the sun here takes it back: that switch goes off and the result reports `releasedFromSky` with the sky entity's name. Move the sun by `timeOfDay` (`setSky`) to keep the sky driving it. **Parameters** - `opts` `SunOpts` **Returns** `SetSunResult` ```lua { direction = {-0.5, -1, -0.3}, color = {1, 0.95, 0.8}, intensity = 1.2 } { intensity = 2 } ``` ## tools/lighting/setup {#tools-lighting-setup} ```lua lighting.setup(opts: SetupOpts) -> SetupResult ``` Set up the whole scene lighting rig in one call. Only provided sections change. `sun`/`ambient` are partial updates on the entities carrying those lights; `sky` + `skyOpts` follow `setSky` semantics (preset word, sky-material word, procedural controls / material params); `lights` is a map of light name → `addLight` opts with a `position` — each is created if missing, updated if present. Naming `sun` takes the sun back from a sky driving it from its time of day: that sky's `syncSunToLight` goes off and `releasedFromSky` reports its entity name. **Parameters** - `opts` `SetupOpts` **Returns** `SetupResult` ```lua { sun = { intensity = 1.2 }, sky = "sunset", lights = { torch1 = { position = {x=5,y=3,z=0}, color = {1,0.6,0.2} } } } ``` ## tools/localContent/forget {#tools-localcontent-forget} ```lua localContent.forget(path: string) -> string ``` Stop holding a path under `/source/local/` on this machine. The file goes and the record of it goes too, so the next boot does not restore it. A folder takes its contents with it. Content already promoted with `localContent.persist` is untouched — that copy belongs to the world. **Parameters** - `path` `string` **Returns** `string` ```lua "gestures/wave.json" ``` ## tools/localContent/list {#tools-localcontent-list} ```lua localContent.list() -> HeldContent ``` List everything this machine holds under `/source/local/` — the content a session wrote that stays on the device instead of going to the world. Each entry reports its path and its size in bytes, in path order, with the total alongside. Pairs with `localContent.persist` (list -> persist). **Returns** `HeldContent` ## tools/localContent/persist {#tools-localcontent-persist} ```lua localContent.persist(path: string, destination?: string) -> { string } ``` Copy content this machine has been holding under `/source/local/` into the world, at the same relative path under `/source/` unless `destination` says otherwise. Takes a file or a whole folder. The local copy stays where it is — persisting is a promotion, not a move, so a failed publish never costs the only copy. Refused while play is running: a `/source` write during play lands on the play shadow and would not persist, which is the exact failure this tool exists to end. Pairs with `localContent.list` (list -> persist). **Parameters** - `path` `string` - `destination` `string` _(optional)_ **Returns** `{ string }` ```lua "gestures/wave.json" ``` ## tools/logs/clear {#tools-logs-clear} ```lua logs.clear() -> ClearResult ``` Drop the buffered log entries, so a following search sees only what happened after the clear. Lifetime per-level counts are preserved, so "were there ever any errors" stays answerable. Rarely the right move: `summary` returns a `cursor` which, passed back to `search` as `since`, isolates what an action logged without discarding lines anybody else may want. **Returns** `ClearResult` ## tools/logs/errors {#tools-logs-errors} ```lua logs.errors(opts?: (string | ErrorsOpts)) -> ErrorsPage ``` Recent errors and warnings, newest first. A snapshot — the same lines however many times it is called. That is the difference from the `problems` tool in the `debug` toolbox, which drains: it advances a read-cursor and reports only what has not been seen, so that one answers "what is new" while this answers "what is there". Accepts the same filters as `search`. **Parameters** - `opts` `(string | ErrorsOpts)` _(optional)_ **Returns** `ErrorsPage` ```lua { level = "error", limit = 10 } { within = 120 } "shader" ``` ## tools/logs/search {#tools-logs-search} ```lua logs.search(opts?: (string | SearchQuery)) -> SearchResult ``` Search what the engine logged. Filter by severity, subsystem, substring or regex, the script or entity that logged it, and a time window — every filter is optional and they narrow together. This is the general view over the same ring the `problems` tool in the `debug` toolbox drains: reach for it when you need a specific message, a specific entity, a specific minute, or the lines that led up to a failure. The same ring reads as plain text at `/zero/runtime/logs/engine`, which is the shorter reach for a string you can already name; this is the view that filters it. **Parameters** - `opts` `(string | SearchQuery)` _(optional)_ **Returns** `SearchResult` ```lua { level = "error", within = 60 } { entity = "ent_9f3c", limit = 20 } { level = "error", context = 5 } { level = "warn", group = true } { contains = "shader", type = "RENDERER" } "shader" ``` ## tools/logs/summary {#tools-logs-summary} ```lua logs.summary(opts?: (string | SummaryOpts)) -> SummaryReport ``` How many lines the engine logged, of what severity, from which subsystems and entities, and which messages repeat — the shape of the noise before you go looking inside it. Also the cheapest "did anything go wrong" check, and the source of the cursor for incremental polling: read `cursor` before an action, pass it back to `search` as `since` afterwards, and you see only what that action logged. Accepts the same filters as `search`, so it can describe a slice as well as the whole. **Parameters** - `opts` `(string | SummaryOpts)` _(optional)_ **Returns** `SummaryReport` ```lua { level = "error" } { within = 300 } ``` ## tools/logs/tail {#tools-logs-tail} ```lua logs.tail(opts?: (string | TailOpts)) -> TailPage ``` The most recent lines the engine logged, any level, oldest first — the last line is the newest. The view for when you do not yet know what you are looking for; once you do, `search` narrows it. Accepts the same filters as `search`. **Parameters** - `opts` `(string | TailOpts)` _(optional)_ **Returns** `TailPage` ```lua { limit = 40 } { type = "SCRIPT" } "shader" ``` ## tools/notices/drain {#tools-notices-drain} ```lua notices.drain() -> Drained? ``` Take every pending notice and return the formatted delivery block — the same text that would otherwise be attached to your next tool result. DRAINING: what this returns is no longer queued, so read it. Returns nil when nothing is pending. For a caller that pulls its own context; if you read notices off your tool results, you do not need this. Overflow content is written to /source/tmp/notices/ and named in the block. **Returns** `Drained?` ## tools/notices/list {#tools-notices-list} ```lua notices.list() -> NoticesList ``` Show the currently pending notice keys and the suppressed set. Each pending row carries its key, template, severity, origin, count, and source; each suppressed row carries its key and the number of times it has fired while muted. Use a key from here with `suppress`. **Returns** `NoticesList` ## tools/notices/suppress {#tools-notices-suppress} ```lua notices.suppress(key: string) -> { suppressed: string } ``` Mute a notice key you have acknowledged. It keeps counting (visible in `list`) but never renders on a tool call again this session. Available to the operating agent; a loaded world component cannot mute its own notices. **Parameters** - `key` `string` **Returns** `{ suppressed: string }` ```lua "user:atlas:texture rebuilt" ``` ## tools/notices/unsuppress {#tools-notices-unsuppress} ```lua notices.unsuppress(key: string) -> { unsuppressed: string } ``` Un-mute a notice key you previously suppressed, so it renders on a tool call again. Available to the operating agent. **Parameters** - `key` `string` **Returns** `{ unsuppressed: string }` ```lua "user:atlas:texture rebuilt" ``` ## tools/phys/addBody {#tools-phys-addbody} ```lua phys.addBody(id: string, bodyType?: ("dynamic" | "static" | "kinematic"), opts?: BodyOpts) -> string ``` Add Physics + Collider components to an entity in one call. `bodyType` selects the rigid-body kind: * `"dynamic"` — falls / responds to forces and collisions * `"static"` — immovable, only collides * `"kinematic"` — script-driven, ignores forces Flashes a purple outline (0.5s) so the change is visible. **Parameters** - `id` `string` - `bodyType` `("dynamic" | "static" | "kinematic")` _(optional)_ - `opts` `BodyOpts` _(optional)_ **Returns** `string` ```lua 'my_cube' -- dynamic box 'floor', 'static', { shape = 'box' } -- static floor 'ball', 'dynamic', { shape = 'sphere', radius = 0.5 } ``` ## tools/phys/addConstraint {#tools-phys-addconstraint} ```lua phys.addConstraint(entityId: string | EntityRef, constraintType: ConstraintKind, targetEntityId: string | EntityRef, opts?: ConstraintOpts) -> string | EntityRef ``` Add a transform constraint to an entity. Constraint types: * `"position"` — follow target's position * `"rotation"` — follow target's rotation * `"scale"` — follow target's scale * `"lookat"` — orient toward target * `"parent"` — full local-space parent relationship * `"aim"` — orient one axis toward target The constraint runs on the constraints system every frame, not the physics solver — so it works on entities without Physics bodies too. **Parameters** - `entityId` `string | EntityRef` - `constraintType` `ConstraintKind` - `targetEntityId` `string | EntityRef` - `opts` `ConstraintOpts` _(optional)_ **Returns** `string | EntityRef` ```lua "follower", "lookat", "player" "camera", "position", "car", { offset = {0, 4, 8}, weight = 0.9 } ``` ## tools/phys/addJoint {#tools-phys-addjoint} ```lua phys.addJoint(entityIdA: string, entityIdB?: (string | AddJointOpts), opts?: AddJointOpts) -> string ``` Add a physics joint between two entities. Both must have Physics components. Two call shapes are accepted: * `phys.addJoint(entityA, entityB, opts?)` — explicit two-entity form. * `phys.addJoint(entityA, opts)` where `opts.target` is the second entity name or ID — matches the README's `phys.addJoint("crate", { target = "wall", ... })` shape and the Joint component's `target` alias. Validates joint kind against the supported set (`fixed`, `hinge`, `ball`, `prismatic`, `spring`, `rope`), resolves names to entity IDs, normalises vec3 args (`localAnchor`, `remoteAnchor`, `axis`), and rejects `stiffness` / `damping` on `kind = "fixed"` and `kind = "rope"` since neither has a motorable axis (Closes #1062 for the silently-discarded case; Closes #527 for the silent no-op when entities were missing). `kind = "rope"` requires `maxDistance > 0` — the maximum distance between the anchor points; slack is free, taut resists extension. `breakForce` (newtons of linear reaction) and `breakTorque` (the angular row of the same reaction) release the joint once the reaction it carries exceeds either; the break is reported through `Physics.onJointBreak` and the joint's own `onBreak`, and a joint given neither is unbreakable. **Parameters** - `entityIdA` `string` - `entityIdB` `(string | AddJointOpts)` _(optional)_ - `opts` `AddJointOpts` _(optional)_ **Returns** `string` ```lua "door", "frame", { kind = "hinge", axis = {0, 1, 0} } "crate", { target = "wall", kind = "spring", stiffness = 200, damping = 10 } "ball", { target = "hook", kind = "rope", maxDistance = 8 } "crate", { target = "wall", kind = "fixed", breakForce = 1200, breakTorque = 800 } ``` ## tools/phys/ignoreCollision {#tools-phys-ignorecollision} ```lua phys.ignoreCollision(entityIdA: string, entityIdB: string, ignore?: boolean) -> string ``` Set whether two entities ignore collisions between each other. `ignore` defaults to `true`; pass `false` to re-enable collisions. Useful for "drop pickup through self" and similar paired-entity rules without touching collision groups. **Parameters** - `entityIdA` `string` - `entityIdB` `string` - `ignore` `boolean` _(optional)_ **Returns** `string` ```lua "player", "pickup" "player", "pickup", false -- re-enable ``` ## tools/phys/lockRotation {#tools-phys-lockrotation} ```lua phys.lockRotation(entityId: string | EntityRef, lockX: boolean, lockY: boolean, lockZ: boolean) -> string | EntityRef ``` Lock rotation axes on an entity's rigid body. Each flag is independent — `(true, false, true)` lets the body spin only around Y. Useful for top-down characters, hinged doors, and constrained vehicles. **Parameters** - `entityId` `string | EntityRef` - `lockX` `boolean` - `lockY` `boolean` - `lockZ` `boolean` **Returns** `string | EntityRef` ```lua "cube", true, false, true -- only rotate around Y ``` ## tools/phys/lockTranslation {#tools-phys-locktranslation} ```lua phys.lockTranslation(entityId: string | EntityRef, lockX: boolean, lockY: boolean, lockZ: boolean) -> string | EntityRef ``` Lock translation axes on an entity's rigid body. Each flag is independent — `(true, true, false)` lets the body only slide along Z (e.g. a rail / track). **Parameters** - `entityId` `string | EntityRef` - `lockX` `boolean` - `lockY` `boolean` - `lockZ` `boolean` **Returns** `string | EntityRef` ```lua "rail", true, true, false -- only move along Z ``` ## tools/phys/removeBody {#tools-phys-removebody} ```lua phys.removeBody(id: string) -> string ``` Remove an entity's Physics component and whichever collider component it carries. Strips the collider before Physics so the engine never sees a collider without a body during the transition. **Parameters** - `id` `string` **Returns** `string` ```lua "my_cube" ``` ## tools/phys/removeConstraint {#tools-phys-removeconstraint} ```lua phys.removeConstraint(entityId: string | EntityRef, index?: number) -> string | EntityRef ``` Remove transform constraints from an entity. Pass an 0-based `index` to remove a specific constraint; omit it to remove all of them. **Parameters** - `entityId` `string | EntityRef` - `index` `number` _(optional)_ **Returns** `string | EntityRef` ```lua "follower" -- remove all "follower", 0 -- remove just the first ``` ## tools/phys/removeJoint {#tools-phys-removejoint} ```lua phys.removeJoint(entityId: string | EntityRef) -> string | EntityRef ``` Remove all joints from an entity. Thin wrapper over `Physics.removeJoint(entityId)` — included in the toolbox so add/remove joint flows live behind the same `phys.*` surface. **Parameters** - `entityId` `string | EntityRef` **Returns** `string | EntityRef` ```lua "crate" ``` ## tools/phys/setBodyType {#tools-phys-setbodytype} ```lua phys.setBodyType(entityId: string | EntityRef, bodyType: "dynamic" | "kinematic" | "static") -> string | EntityRef ``` Change a rigid body's type at runtime. Preserves mass, colliders, and joints — only the body's response to forces and position writes changes. Useful for ragdoll activation (freeze pose as kinematic until hit, then flip to dynamic), freeze / unfreeze mechanics, and switching platforms between kinematic (scripted motion) and static. An unknown `bodyType` string raises a Luau error with the valid set. **Parameters** - `entityId` `string | EntityRef` - `bodyType` `"dynamic" | "kinematic" | "static"` **Returns** `string | EntityRef` ```lua "player", "kinematic" -- freeze "player", "dynamic" -- unfreeze, respond to forces ``` ## tools/phys/setCollisionGroups {#tools-phys-setcollisiongroups} ```lua phys.setCollisionGroups(entityId: string | EntityRef, membership: number, filter: number) -> string | EntityRef ``` Set collision group bitmasks on an entity's colliders. The two bitmasks encode "what am I" (`membership`) and "what do I collide with" (`filter`) separately — two entities collide iff each entity's `filter` contains a bit from the other entity's `membership`. **Parameters** - `entityId` `string | EntityRef` - `membership` `number` - `filter` `number` **Returns** `string | EntityRef` ```lua "player", 0x1, 0x2 -- Player on group 1 collides only with terrain (group 2) ``` ## tools/phys/spawnDynamic {#tools-phys-spawndynamic} ```lua phys.spawnDynamic(name: string, url?: (string | AssetRef), x?: number, y?: number, z?: number, opts?: SpawnOpts) -> string ``` Spawn an entity with a Model + dynamic Physics body in one call. The returned id is the unique `ent_...` handle from `entity.spawn` (not the display name), matching `sc.spawnModel`'s contract (#579). Pops the entity in with a purple viz pulse. **Parameters** - `name` `string` - `url` `(string | AssetRef)` _(optional)_ - `x` `number` _(optional)_ - `y` `number` _(optional)_ - `z` `number` _(optional)_ - `opts` `SpawnOpts` _(optional)_ **Returns** `string` ```lua 'my_box' 'ball', 'sphere', 0, 5, 0, { mass = 1 } ``` ## tools/phys/spawnStatic {#tools-phys-spawnstatic} ```lua phys.spawnStatic(name: string, url?: (string | AssetRef), x?: number, y?: number, z?: number, opts?: SpawnOpts) -> string ``` Spawn an entity with a Model + static collider in one call. Static = immovable, only collides. The returned id is the unique `ent_...` handle from `entity.spawn`, matching `sc.spawnModel`'s contract (#579). **Parameters** - `name` `string` - `url` `(string | AssetRef)` _(optional)_ - `x` `number` _(optional)_ - `y` `number` _(optional)_ - `z` `number` _(optional)_ - `opts` `SpawnOpts` _(optional)_ **Returns** `string` ```lua 'floor', 'cube', 0, 0, 0, { scale = { 10, 1, 10 } } ``` ## tools/phys/whyStill {#tools-phys-whystill} ```lua phys.whyStill(entityId: string | EntityRef) -> { [string]: any } ``` Answer why the solver is not moving an entity's rigid body. The reason is the nearest cause from a closed set — `noBody`, `simulationNotStepping`, `disabled`, `static`, `kinematic`, `infiniteMass`, `translationLocked`, `gravityDisabled`, `asleep`, `outsideIsland`, `resting`, `aboutToMove` — so it names the thing to change rather than a consequence of it. A body the solver IS advancing reports `moving = true` and no reason. Every value comes off the simulation, so a write the solver refused or clamped reads back as what it kept. Answers in edit mode as well as play mode. **Parameters** - `entityId` `string | EntityRef` **Returns** `{ [string]: any }` ```lua "crate" ``` ## tools/phys/worldState {#tools-phys-worldstate} ```lua phys.worldState() -> { [string]: any } ``` Report what the physics simulation is actually holding: bodies by type, how many are awake and asleep, colliders, joints, contact pairs / touching pairs / contact points, the bodies the last step integrated, world gravity, the timestep, whether the pipeline is stepping at all, and what the last step cost. Counted off the solver, so a body that failed to build is missing here while its `Physics` component still exists. Answers in edit mode as well as play mode. **Returns** `{ [string]: any }` ```lua -- no arguments ``` ## tools/pixelArt/add {#tools-pixelart-add} ```lua pixelArt.add(opts: PaletteAdd) ``` **Parameters** - `opts` `PaletteAdd` ## tools/pixelArt/addFrame {#tools-pixelart-addframe} ```lua pixelArt.addFrame(opts: AnimAddFrame) -> number? ``` **Parameters** - `opts` `AnimAddFrame` **Returns** `number?` ## tools/pixelArt/anim {#tools-pixelart-anim} ```lua pixelArt.anim(opts: AnimOpts) -> number? ``` Multi-frame animation control. Pick the action via `opts.op`. All ops take `target` (handle/id/name). Frames share the canvas palette + size; draw into a frame by making it active (`setActiveFrame`) then using `Pixel.draw`. **Parameters** - `opts` `AnimOpts` **Returns** `number?` ```lua { op = 'duplicateFrame', target = s } { op = 'setFps', target = s, fps = 8 } ``` ## tools/pixelArt/bounds {#tools-pixelart-bounds} ```lua pixelArt.bounds(opts: QueryBounds) -> any ``` **Parameters** - `opts` `QueryBounds` **Returns** `any` ## tools/pixelArt/circle {#tools-pixelart-circle} ```lua pixelArt.circle(opts: DrawCircle) ``` **Parameters** - `opts` `DrawCircle` ## tools/pixelArt/clear {#tools-pixelart-clear} ```lua pixelArt.clear(opts: DrawClear) ``` **Parameters** - `opts` `DrawClear` ## tools/pixelArt/clone {#tools-pixelart-clone} ```lua pixelArt.clone(opts: SpawnClone) -> Handle ``` **Parameters** - `opts` `SpawnClone` **Returns** `Handle` ## tools/pixelArt/countByName {#tools-pixelart-countbyname} ```lua pixelArt.countByName(opts: QueryCountByName) -> any ``` **Parameters** - `opts` `QueryCountByName` **Returns** `any` ## tools/pixelArt/create {#tools-pixelart-create} ```lua pixelArt.create(opts: SpawnCreate) -> Handle ``` **Parameters** - `opts` `SpawnCreate` **Returns** `Handle` ## tools/pixelArt/deleteTemplate {#tools-pixelart-deletetemplate} ```lua pixelArt.deleteTemplate(opts: PersistDeleteTemplate) -> boolean ``` **Parameters** - `opts` `PersistDeleteTemplate` **Returns** `boolean` ## tools/pixelArt/destroy {#tools-pixelart-destroy} ```lua pixelArt.destroy(target: Handle | string | number) ``` Despawn a pixel canvas. `target` is a handle, entity id, or name. **Parameters** - `target` `Handle | string | number` ```lua "hero" ``` ## tools/pixelArt/draw {#tools-pixelart-draw} ```lua pixelArt.draw(opts: DrawOpts) ``` Raster drawing onto a canvas's ACTIVE frame. Pick the primitive via `opts.op`. All ops take `target` (handle/id/name) + `color` (palette name; nil clears) plus op-specific coords. **Parameters** - `opts` `DrawOpts` ```lua { op = 'fillCircle', target = s, cx = 8, cy = 8, r = 6, color = 'red' } { op = 'rows', target = s, rows = {'rr','rr'}, legend = { r = 'red' } } ``` ## tools/pixelArt/duplicateFrame {#tools-pixelart-duplicateframe} ```lua pixelArt.duplicateFrame(opts: AnimDuplicateFrame) -> number? ``` **Parameters** - `opts` `AnimDuplicateFrame` **Returns** `number?` ## tools/pixelArt/ellipse {#tools-pixelart-ellipse} ```lua pixelArt.ellipse(opts: DrawEllipse) ``` **Parameters** - `opts` `DrawEllipse` ## tools/pixelArt/fillCircle {#tools-pixelart-fillcircle} ```lua pixelArt.fillCircle(opts: DrawFillCircle) ``` **Parameters** - `opts` `DrawFillCircle` ## tools/pixelArt/fillRect {#tools-pixelart-fillrect} ```lua pixelArt.fillRect(opts: DrawFillRect) ``` **Parameters** - `opts` `DrawFillRect` ## tools/pixelArt/frameCount {#tools-pixelart-framecount} ```lua pixelArt.frameCount(opts: QueryFrameCount) -> number ``` **Parameters** - `opts` `QueryFrameCount` **Returns** `number` ## tools/pixelArt/getPixel {#tools-pixelart-getpixel} ```lua pixelArt.getPixel(opts: QueryGetPixel) -> string? ``` **Parameters** - `opts` `QueryGetPixel` **Returns** `string?` ## tools/pixelArt/line {#tools-pixelart-line} ```lua pixelArt.line(opts: DrawLine) ``` **Parameters** - `opts` `DrawLine` ## tools/pixelArt/listTemplates {#tools-pixelart-listtemplates} ```lua pixelArt.listTemplates(_opts: QueryListTemplates) -> { string } ``` **Parameters** - `_opts` `QueryListTemplates` **Returns** `{ string }` ## tools/pixelArt/palette {#tools-pixelart-palette} ```lua pixelArt.palette(opts: PaletteOpts) ``` Palette editing. `op='set'` replaces the whole palette (cell indices preserved, so it recolors every frame in place); `op='add'` adds/updates one entry. **Parameters** - `opts` `PaletteOpts` ```lua { op = 'add', target = s, name = 'blue', color = {0,0,1} } ``` ## tools/pixelArt/persist {#tools-pixelart-persist} ```lua pixelArt.persist(opts: PersistOpts) -> string | boolean ``` Template persistence. `op='saveAsTemplate'` exports a canvas (all frames) as a reusable `pixelTemplate` asset; `op='deleteTemplate'` removes one. Instantiate saved templates with `Pixel.spawn(op='template')`. **Parameters** - `opts` `PersistOpts` **Returns** `string | boolean` ```lua { op = 'saveAsTemplate', target = s, name = 'hero' } { op = 'deleteTemplate', name = 'hero' } ``` ## tools/pixelArt/pixel {#tools-pixelart-pixel} ```lua pixelArt.pixel(opts: DrawPixel) ``` **Parameters** - `opts` `DrawPixel` ## tools/pixelArt/play {#tools-pixelart-play} ```lua pixelArt.play(opts: AnimPlay) ``` **Parameters** - `opts` `AnimPlay` ## tools/pixelArt/query {#tools-pixelart-query} ```lua pixelArt.query(opts: QueryOpts) -> any ``` Read-only queries against a canvas (or the template library). Pick via `opts.op`. Per-canvas ops take `target` (handle/id/name). **Parameters** - `opts` `QueryOpts` **Returns** `any` ```lua { op = 'getPixel', target = s, x = 0, y = 0 } { op = 'listTemplates' } ``` ## tools/pixelArt/rect {#tools-pixelart-rect} ```lua pixelArt.rect(opts: DrawRect) ``` **Parameters** - `opts` `DrawRect` ## tools/pixelArt/removeFrame {#tools-pixelart-removeframe} ```lua pixelArt.removeFrame(opts: AnimRemoveFrame) ``` **Parameters** - `opts` `AnimRemoveFrame` ## tools/pixelArt/rows {#tools-pixelart-rows} ```lua pixelArt.rows(opts: SpawnRows) -> Handle ``` **Parameters** - `opts` `SpawnRows` **Returns** `Handle` ## tools/pixelArt/saveAsTemplate {#tools-pixelart-saveastemplate} ```lua pixelArt.saveAsTemplate(opts: PersistSaveAsTemplate) -> string ``` **Parameters** - `opts` `PersistSaveAsTemplate` **Returns** `string` ## tools/pixelArt/set {#tools-pixelart-set} ```lua pixelArt.set(opts: PaletteSet) ``` **Parameters** - `opts` `PaletteSet` ## tools/pixelArt/setActiveFrame {#tools-pixelart-setactiveframe} ```lua pixelArt.setActiveFrame(opts: AnimSetActiveFrame) ``` **Parameters** - `opts` `AnimSetActiveFrame` ## tools/pixelArt/setFps {#tools-pixelart-setfps} ```lua pixelArt.setFps(opts: AnimSetFps) ``` **Parameters** - `opts` `AnimSetFps` ## tools/pixelArt/spawn {#tools-pixelart-spawn} ```lua pixelArt.spawn(opts: SpawnOpts) -> Handle ``` Generic pixel-canvas creation + placement. Pick behavior via `opts.op`: 'create' (blank/seeded sheet), 'rows' (paint from text + a legend), 'template' (instantiate a saved pixelTemplate), or 'clone' (duplicate an existing canvas). Returns a handle. **Parameters** - `opts` `SpawnOpts` **Returns** `Handle` ```lua { op = 'create', width = 16, height = 16, palette = { red = {1,0,0} } } { op = 'rows', rows = {" r ","rrr"," r "}, legend = { r = "red" }, palette = { red = {1,0,0} } } { op = 'template', name = 'hero', position = { 0, 1, 0 } } ``` ## tools/pixelArt/stop {#tools-pixelart-stop} ```lua pixelArt.stop(opts: AnimStop) ``` **Parameters** - `opts` `AnimStop` ## tools/pixelArt/template {#tools-pixelart-template} ```lua pixelArt.template(opts: SpawnTemplate) -> Handle ``` **Parameters** - `opts` `SpawnTemplate` **Returns** `Handle` ## tools/pp/add {#tools-pp-add} ```lua pp.add(name: string, opts?: PostEffectOpts) -> string ``` Add a post-processing effect. Use a built-in preset name (`bloom`, `color_correction`, `colorGrade`, `fog`, `grayscale`, `invert`, `lut`, `sepia`, `tonemap`, `vignette`) or provide custom WGSL via `opts.source` (author only `fn fragment(in: PostInput) -> vec4`, declare named material properties via `opts.properties`). Forwards to `postprocess.add(name, source, { properties, priority, enabled, layer })`, applies each property value via `postprocess.setProperty(name, prop, value)`, and binds each texture via `postprocess.setTexture(name, prop, path)`. Every property the effect's schema declares is settable by its own name in this call — the schema is what decides which keys `opts` takes, so a key it does not declare is refused against that set rather than dropped. `postprocess.describe(name)` lists the schema of a registered effect and the value each property holds; `asset.resolve("@builtin::shaders.post.", "shader"):getProperties()` lists a preset's before it is added. `opts.layer` picks which composited image the effect grades: `"scene"` runs it before the UI is drawn, so it grades the rendered picture and leaves every widget on screen as authored, and `"all"` (the default) runs it after the UI has landed, so the interface is graded along with the picture. A custom `opts.source` reads the scene's depth at a pixel with `zero_scene_depth(in.uv)`, which a defocus, a distance haze or a depth-keyed grade drives from. **Parameters** - `name` `string` - `opts` `PostEffectOpts` _(optional)_ **Returns** `string` ```lua 'vignette', { intensity = 0.42, radius = 0.8, softness = 0.55 } 'bloom', { threshold = 1.0, intensity = 1.5, radius = 12 } 'color_correction', { brightness = 0.1, saturation = 0.3 } 'tonemap', { mode = 'ACES', exposure = 1.2 } 'lut', { texture = lut.install('dusk', lut.fromGrade({ temperature = -0.2 })).guid } 'myeffect', { source = 'fn fragment(in: PostInput) -> vec4 {...}', properties = {{name='k', type='float', default={1}}}, k = 0.25 } ``` ## tools/pp/list {#tools-pp-list} ```lua pp.list() -> { string } ``` List the currently-active post-processing effects. Forwards to `postprocess.list()`. **Returns** `{ string }` ## tools/pp/presets {#tools-pp-presets} ```lua pp.presets() -> {string} ``` List the built-in preset effect names sorted alphabetically. The same names are accepted by `pp.add`. **Returns** `{string}` ## tools/pp/remove {#tools-pp-remove} ```lua pp.remove(name: string) ``` Remove a post-processing effect by name. Forwards to `postprocess.remove(name)`. Removing an effect that does not exist follows the underlying API's contract. **Parameters** - `name` `string` ```lua 'vignette' ``` ## tools/pp/setEnabled {#tools-pp-setenabled} ```lua pp.setEnabled(name: string, enabled: boolean) ``` Enable or disable a post-processing effect without removing it. Forwards to `postprocess.setEnabled(name, enabled)`. **Parameters** - `name` `string` - `enabled` `boolean` ```lua 'bloom', false ``` ## tools/primitives/cube {#tools-primitives-cube} ```lua primitives.cube(name: SpawnTarget, x?: number, y?: number, z?: number, opts?: CubeOpts) -> string ``` Spawn a visual cube at a position. No physics by default — add `Physics` and `Collider` components explicitly if collision is wanted. Set `opts.scale` to size the cube — a number for a uniform cube, or three components as `{x, y, z}` or `{ x = , y = , z = }` for a box. Set `opts.animate=true` to play a viz.popIn entrance (default off — at bulk-spawn rates the per-call string.format + tween-source compile dominates spawn time). **Parameters** - `name` `SpawnTarget` - `x` `number` _(optional)_ - `y` `number` _(optional)_ - `z` `number` _(optional)_ - `opts` `CubeOpts` _(optional)_ **Returns** `string` ```lua "box1", 0, 5, 0 { name = "crate", position = { 4, 0, 2 } } "backdrop", 0, 0, -10, { scale = 5 } "beam", 0, 1, 0, { scale = { 4, 0.4, 0.4 } } "falling", 0, 5, 0 ``` ## tools/primitives/ground {#tools-primitives-ground} ```lua primitives.ground(name: SpawnTarget, x?: number, y?: number, z?: number, color?: shared.ColorInput, size?: number) -> string ``` Spawn a flat ground plane with optional color tint and size. The base mesh is 1x0.1x1 unit; `size` scales it uniformly in XZ. Always has static physics (it's a ground plane). **Parameters** - `name` `SpawnTarget` - `x` `number` _(optional)_ - `y` `number` _(optional)_ - `z` `number` _(optional)_ - `color` `shared.ColorInput` _(optional)_ - `size` `number` _(optional)_ **Returns** `string` ```lua "floor", 0, 0, 0 { name = "floor", position = { 0, -1, 0 } } "red_floor", 0, 0, 0, {r=200, g=50, b=50} "blue_floor", 0, 0, 0, {50, 90, 200} "big_floor", 0, 0, 0, nil, 100 ``` ## tools/primitives/groundHex {#tools-primitives-groundhex} ```lua primitives.groundHex(name: SpawnTarget, x?: number, y?: number, z?: number, color?: shared.ColorInput) -> string ``` Spawn a hexagonal ground tile with optional color tint. Includes static physics so objects rest on it. **Parameters** - `name` `SpawnTarget` - `x` `number` _(optional)_ - `y` `number` _(optional)_ - `z` `number` _(optional)_ - `color` `shared.ColorInput` _(optional)_ **Returns** `string` ```lua "hex_tile", 0, 0, 0 { name = "hex_tile", position = { 3, 0, 3 } } "grass_hex", 0, 0, 0, {r=80, g=160, b=60} "sand_hex", 0, 0, 0, {200, 180, 120} ``` ## tools/primitives/tree {#tools-primitives-tree} ```lua primitives.tree(name: SpawnTarget, x?: number, y?: number, z?: number, preset?: TreePreset, seed?: number) -> string ``` Spawn a procedural tree from a preset. Includes static physics collider so objects collide with it. **Parameters** - `name` `SpawnTarget` - `x` `number` _(optional)_ - `y` `number` _(optional)_ - `z` `number` _(optional)_ - `preset` `TreePreset` _(optional)_ - `seed` `number` _(optional)_ **Returns** `string` ```lua "oak1", 5, 0, 3, "oak" { name = "oak1", position = { 5, 0, 3 } }, nil, nil, nil, "oak" "tree_" .. i, math.random(-20, 20), 0, math.random(-20, 20), "pine", i * 42 ``` ## tools/procgen/adjust {#tools-procgen-adjust} ```lua procgen.adjust(args: AdjustArgs) -> AdjustResult ``` Adjust a live generator in place: merge values into its param overrides (each key overrides the graph input of the same name), switch which output it realizes, or toggle autoBake. The change queues a cook on the generator's async runner and returns immediately — a heavy graph keeps cooking across frames while this call reports back. Watch it with `procgen.cooks`, cancel it with `procgen.cancel`. **Parameters** - `args` `AdjustArgs` **Returns** `AdjustResult` ```lua { entity = "LegoSculpture", params = { model = "@builtin::meshes.torus" } } ``` ## tools/procgen/apply {#tools-procgen-apply} ```lua procgen.apply(args: ApplyArgs) -> ApplyResult ``` Flatten a live generator and detach it: the current output is written as durable content (real mesh assets), spawned as permanent children, and the Generator component is removed — the result stands on its own with no graph and no generator at runtime, like applying a modifier. **Parameters** - `args` `ApplyArgs` **Returns** `ApplyResult` ```lua { entity = "LegoSculpture" } ``` ## tools/procgen/bake {#tools-procgen-bake} ```lua procgen.bake(args: BakeArgs) -> BakeResult ``` Evaluate a `.procGraph` graph target and realize it into the live scene as durable content, then verify it rendered. Geometry becomes a `.mesh` asset + a Model entity; an InstanceSet becomes live per-instance entities; a Bundle/Prefab becomes durable live entities that survive the edit->play reload. Pass `replace` to swap an existing entity in place (inheriting its position); `position` to place it; `material` to tint a Geometry bake. **Parameters** - `args` `BakeArgs` **Returns** `BakeResult` ```lua { graph = "/source/proc/tower.procGraph", name = "tower", position = { 0, 0, 0 } } ``` ## tools/procgen/cancel {#tools-procgen-cancel} ```lua procgen.cancel(args: CancelArgs) -> CancelResult ``` Cancel the in-flight cook on an entity's Generator. The previous output stays; the next param change cooks fresh. **Parameters** - `args` `CancelArgs` **Returns** `CancelResult` ```lua { entity = "LegoSculpture" } ``` ## tools/procgen/collapse {#tools-procgen-collapse} ```lua procgen.collapse(args: CollapseArgs) -> CollapseResult ``` Extract `nodes` out of a `.procGraph` into a new `.procGraph` named `name`, written as its own `init.luau` — a graph to keep editing. Every ref crossing the extracted cluster's boundary becomes a declared child input (outside producer -> extracted node) or child output (extracted node -> outside consumer); identical boundary sources/sinks share one socket. The host graph is left as it was; `procgen.reference` is the call that rewrites its source to use the child, and this returns the exact one to make. **Parameters** - `args` `CollapseArgs` **Returns** `CollapseResult` ```lua { graph = "/source/proc/scene.procGraph", nodes = { "pts", "inst" }, name = "Scatter" } ``` ## tools/procgen/cooks {#tools-procgen-cooks} ```lua procgen.cooks() -> CooksResult ``` List the active cooks and the recent cook history — progress, status, and failure detail (which node failed). A finished record's `durationMs` spans the whole regen: evaluation plus realizing the output and refreshing the bake snapshot. The scene-wide cook monitor. **Returns** `CooksResult` ## tools/procgen/diff {#tools-procgen-diff} ```lua procgen.diff(args: DiffArgs) -> DiffResult ``` Compare two `.procGraph` graphs and report changed/added/removed nodes plus per-node op/param/input deltas (structural, via the content hash). **Parameters** - `args` `DiffArgs` **Returns** `DiffResult` ```lua { a = "/source/proc/box.procGraph", b = updatedGraph } ``` ## tools/procgen/explain {#tools-procgen-explain} ```lua procgen.explain(args: ExplainArgs) -> ExplainResult ``` Agent-oriented natural-language summary of a `.procGraph` graph: its size, declared inputs (with types), the op of each node, the composite references, and where each output comes from. **Parameters** - `args` `ExplainArgs` **Returns** `ExplainResult` ```lua { graph = "/source/proc/box.procGraph" } ``` ## tools/procgen/find {#tools-procgen-find} ```lua procgen.find(args?: FindArgs) -> FindResult ``` Discover procedural graphs by what they produce. Lists every `.procGraph` asset, opens each, reads its declared outputs' types, and filters on `name` (substring over name/id), `tag`, `category`, and/or `produces` (an output type or producing-op substring, e.g. "Bundle", "Geometry", "mesh."). Returns each match with its resolved outputs — so you can find a graph by its result, not just its description. **Parameters** - `args` `FindArgs` _(optional)_ **Returns** `FindResult` ```lua { produces = "Bundle" } ``` ## tools/procgen/flatten {#tools-procgen-flatten} ```lua procgen.flatten(args: FlattenArgs) -> FlattenResult ``` Inline every composite of a `.procGraph` graph into a single composite-free graph (the opt-in bake). Child nodes are namespaced under the composite id, inputs rewired to the bound values, composite outputs repointed at the inlined child outputs. Nested composites flatten recursively; cross-graph cycles error with the full path chain. **Parameters** - `args` `FlattenArgs` **Returns** `FlattenResult` ```lua { graph = "/source/proc/bank_vault.procGraph", out = "/source/proc/bank_vault_flat.procGraph" } ``` ## tools/procgen/generators {#tools-procgen-generators} ```lua procgen.generators() -> GeneratorsResult ``` List every live procedural generator in the scene — the entities carrying a Generator component — with each one's bound graph, selected output, current param overrides, realized child count, and cook state (whether it's cooking right now, its progress, and its last finished cook's outcome). Use it to find what's generating — or why a generator's output looks stale — before adjusting (`procgen.adjust`) or flattening (`procgen.apply`). **Returns** `GeneratorsResult` ## tools/procgen/inspect {#tools-procgen-inspect} ```lua procgen.inspect(args: InspectArgs) -> InspectResult ``` Inspect one node of a `.procGraph` graph: its op, declared input/param/output sockets (from the registry), the InputRefs feeding it (producers), and the nodes that consume its outputs (consumers). **Parameters** - `args` `InspectArgs` **Returns** `InspectResult` ```lua { graph = g, node = "box" } ``` ## tools/procgen/modify {#tools-procgen-modify} ```lua procgen.modify(args: ModifyArgs) -> ModifyResult ``` Apply structural edits to a `.procGraph` graph, type-check the result, and persist it — a step above `procgen.patch`. Each edit is a `{ op }` table: `{ op = "add_node", id, node }` (node = the op id, e.g. "mesh.box"); `{ op = "set_param", node, name, value }`; `{ op = "connect", node, socket, from }` (from = `{ node, output? }` for a node output, else a constant); `{ op = "set_output", name, from }` (declare/rebind a graph output); `{ op = "rename_node", from, to }` (updates every reference); `{ op = "remove_node", node }`. **Parameters** - `args` `ModifyArgs` **Returns** `ModifyResult` ```lua { graph = "/source/proc/tower.procGraph", edits = { { op = "add_node", id = "n", node = "mesh.sphere" }, { op = "set_output", name = "mesh", from = { node = "n" } } } } ``` ## tools/procgen/ops {#tools-procgen-ops} ```lua procgen.ops(query?: string, pack?: string, kind?: string, limit?: number) -> OpsResult ``` Search the procedural OP REGISTRY — every operation a graph node can name. Every op belongs to a pack: the families this package ships, the `terrain.*` ops, and any `.procPack` authored in a world, all listed the same way; a `.procNode` asset contributes one op addressed by its guid. Filter by free-text `query` over id and description, by the `pack` an op came from, or by `kind`. With no arguments it answers for the whole vocabulary. Every hit's `id` is what `procgen.schema` describes and what a node's `op` field takes, so this is the first call when composing a graph and the one that settles whether an op you remember actually exists. The answer comes in two halves: `catalogue` names EVERY matching op grouped by family, complete however many there are and small enough to read whole, and `results` describes the first `limit` of them. So one call maps the vocabulary and a second, narrowed by `query`, describes the corner you want. **Parameters** - `query` `string` _(optional)_ - `pack` `string` _(optional)_ - `kind` `string` _(optional)_ - `limit` `number` _(optional)_ **Returns** `OpsResult` ```lua "scatter" nil, nil, nil, 60 ``` ## tools/procgen/patch {#tools-procgen-patch} ```lua procgen.patch(args: PatchArgs) -> PatchResult ``` Apply a list of structured edits to a `.procGraph` graph, then optionally save it. Supported edits (each a table with `op`): `{ op = "set_param", node, name, value }` — set a node param; `{ op = "set_input", node, socket, value }` — rewire an input (value = `{ node = "", output? }` for a node output, else a constant); `{ op = "remove_node", node }` — delete a node. **Parameters** - `args` `PatchArgs` **Returns** `PatchResult` ```lua { graph = "/source/proc/box.procGraph", edits = { { op = "set_param", node = "box", name = "size", value = 3 } } } ``` ## tools/procgen/preview {#tools-procgen-preview} ```lua procgen.preview(args: PreviewArgs) -> PreviewResult ``` Evaluate a `.procGraph` graph target, visualize it (any output type), render it, and write image + stats artifacts under /source/tmp/proc-preview//latest/. **Parameters** - `args` `PreviewArgs` **Returns** `PreviewResult` ```lua { graph = "/source/proc/box.procGraph", target = "output:mesh" } { graph = "/source/proc/valley.procGraph", target = "node:snowBand", layer = "snow" } ``` ## tools/procgen/promote {#tools-procgen-promote} ```lua procgen.promote(args: PromoteArgs) -> PromoteResult ``` Publish the `.procGraph` at `graph` as an OPERATION — a `.procNode` bound to it, which puts the graph in the op registry where `ops` searches and any graph can reach it by name. Its params are the graph's declared inputs and its outputs are the graph's declared outputs, and it stays bound: editing the graph changes the op, and every graph using it re-cooks. A graph referenced directly as a node is private to whatever names it; an op is part of the shared vocabulary. Promote the graphs worth reusing. **Parameters** - `args` `PromoteArgs` **Returns** `PromoteResult` ```lua { graph = "/source/proc/Scatter.procGraph" } ``` ## tools/procgen/reference {#tools-procgen-reference} ```lua procgen.reference(args: ReferenceArgs) -> ReferenceResult ``` Replace `nodes` in the `.procGraph` at `graph` with a single node that references the `.procGraph` at `child`, and write the host back out as source. The host's boundary is derived exactly as `collapse` derives it, so the graph evaluates to the same result through the child that it did through the nodes — and because the host's `init.luau` is what the type compiles, this is the step that makes the change the host's actual definition. The host's source is REGENERATED from its graph: every node, wire and declared input survives, and comments in the file do not. **Parameters** - `args` `ReferenceArgs` **Returns** `ReferenceResult` ```lua { graph = "/source/proc/scene.procGraph", child = "/source/proc/Scatter.procGraph", nodes = { "pts", "inst" } } ``` ## tools/procgen/schema {#tools-procgen-schema} ```lua procgen.schema(id: string) -> any ``` Describe ONE procedural op: the input sockets it consumes and their types, the params it takes with their declared defaults and units, and the outputs it produces (with the one a wire picks by default). Accepts a builtin op id or a content op's guid, and describes a `.procNode` exactly as it describes a builtin. This is the call that settles what a node needs before it is wired — an op named from memory, or wired with a param it does not declare, is the usual reason a graph refuses to cook. Find the id with `procgen.ops`. **Parameters** - `id` `string` **Returns** `any` ```lua "terrain.erode" ``` ## tools/procgen/search {#tools-procgen-search} ```lua procgen.search(args?: SearchArgs) -> SearchResult ``` Search the procedural-graph library — every `.procGraph` this engine can see, the ones the world authored and the ones it ships. A free-text `query` matches the graph's name, its identity, the description its `.metadata` carries and its tags, so the word you would use for the thing finds it even when the graph is named something else. `tag` and `category` narrow it. Ask this before describing something from nothing: a graph that already makes what you need is two calls away, and rewriting one costs the work twice over. **Parameters** - `args` `SearchArgs` _(optional)_ **Returns** `SearchResult` ```lua { query = "scatter" } { tag = "terrain" } ``` ## tools/procgen/spawn {#tools-procgen-spawn} ```lua procgen.spawn(args: SpawnArgs) -> SpawnResult ``` Spawn a live procedural generator from a `.procGraph` graph: creates an entity with a Generator component bound to the graph, which immediately realizes the graph's output as the entity's managed children and keeps regenerating live as params change. This is the entry point for putting a graph in the scene — no manual entity.spawn / component.add needed. **Parameters** - `args` `SpawnArgs` **Returns** `SpawnResult` ```lua { graph = "/source/legoify.procGraph", name = "LegoSculpture", position = { 0, 3, 0 } } ``` ## tools/procgen/stats {#tools-procgen-stats} ```lua procgen.stats(args: StatsArgs) -> StatsResult ``` Structural counts of a `.procGraph` graph (nodes / composites / inputs / outputs). When `target` is given, also evaluates it and reports the output type, elapsed duration, and (for geometry) vertex/triangle counts. Timing is reported only — it never feeds graph evaluation (determinism). **Parameters** - `args` `StatsArgs` **Returns** `StatsResult` ```lua { graph = g, target = "output:mesh" } ``` ## tools/procgen/trace {#tools-procgen-trace} ```lua procgen.trace(args: TraceArgs) -> TraceResult ``` Dependency chain for a target: the node ids reachable from the target, in evaluation order (each node's producers appear before it — a post-order walk of the `node_output` edges). Composite/const/graph_input leaves stop the walk. **Parameters** - `args` `TraceArgs` **Returns** `TraceResult` ```lua { graph = g, target = "output:mesh" } ``` ## tools/procgen/tweak {#tools-procgen-tweak} ```lua procgen.tweak(args: TweakArgs) -> TweakResult ``` Set one or more node params on a `.procGraph` graph, then re-evaluate + preview in a single step — the parameter-tuning loop. Each entry of `params` is `{ node = "", name = "", value = }`. Persists the tweaked graph when `out` is given (else the edit is in-memory for this preview only). **Parameters** - `args` `TweakArgs` **Returns** `TweakResult` ```lua { graph = "/source/proc/tower.procGraph", params = { { node = "floors", name = "count", value = 12 } } } ``` ## tools/procgen/validate {#tools-procgen-validate} ```lua procgen.validate(args: ValidateArgs) -> ValidateResult ``` Type-check a `.procGraph` graph: missing inputs, type mismatches, cycles, invalid composite bindings. Returns the diagnostics list. **Parameters** - `args` `ValidateArgs` **Returns** `ValidateResult` ```lua { graph = "/source/proc/box.procGraph" } ``` ## tools/profiler/compare {#tools-profiler-compare} ```lua profiler.compare(before?: string, after?: string) -> string ``` Diff two recordings (made with `record`): the change in avg/p90 frametime, and the systems that moved the most between them. Record a baseline, make a change, record again, then compare to see whether the change helped and which system it moved. A positive frametime delta means B is slower than A. **Parameters** - `before` `string` _(optional)_ - `after` `string` _(optional)_ **Returns** `string` ```lua "baseline", "optimized" -- did 'optimized' beat 'baseline', and where ``` ## tools/profiler/flamegraph {#tools-profiler-flamegraph} ```lua profiler.flamegraph(seconds?: number, mode?: ("run" | "start" | "stop" | "snapshot"), label?: string) -> string ``` Sample the Luau call stack to find the hottest code paths — the depth view under a hot component or `task_scheduler`. `flamegraph(seconds)` runs the sampler for that long (resetting first) and returns the top stacks plus a folded-stack file for flamegraph rendering. `mode` picks a manual phase instead: "start" / "stop" a long session, or "snapshot" the current top stacks without stopping. **Parameters** - `seconds` `number` _(optional)_ - `mode` `("run" | "start" | "stop" | "snapshot")` _(optional)_ - `label` `string` _(optional)_ **Returns** `string` ```lua -- 3s sample, top stacks + folded file 5 -- 5s sample 0, "snapshot" -- top stacks right now without stopping a session ``` ## tools/profiler/frame {#tools-profiler-frame} ```lua profiler.frame(source?: string, which?: ("worst" | "typical"), minMs?: number) -> string ``` The current frame's time as a self-accounting tree: schedule -> system -> sub-timing, each row showing SELF (own time excluding children), TOTAL, calls, and % of frame. Time no schedule covers (the frame limiter / vsync wait, GPU present, event loop) shows as `present / idle`; each expensive component's update(dt) is listed by component + entity under `lua_update.vm_call`. Read the live frame with source "now", or a stopped recording by its label (its worst or typical frame). Read from top: the row with the largest SELF time is where the frame time actually goes. **Parameters** - `source` `string` _(optional)_ - `which` `("worst" | "typical")` _(optional)_ - `minMs` `number` _(optional)_ **Returns** `string` ```lua -- live frame, full attributed tree "combat", "worst" -- the worst frame of the 'combat' recording "combat", "typical" -- the typical (average) frame of that recording ``` ## tools/profiler/gpu {#tools-profiler-gpu} ```lua profiler.gpu(n?: number) -> string ``` GPU pass timings over the last resolved frames, from GPU timestamp queries. Each row is one label: the median of its per-frame total, the min/max that median sits in, the passes per frame, and how many of the window's frames carried it. A row marked `floor` ran but the device resolved no duration for it — its two timestamps retired within a few ticks of each other. The `last` column is how many resolved frames ago the label last recorded a pass: `now` is a pass running in the frame the table describes, and anything else is a row the window still holds after the work under it stopped. The readback is asynchronous, so the window lags the live frame by a few frames. Use this when `frame` shows the time under `present / idle` (GPU-bound) and you need to know which passes the GPU spends it on. **Parameters** - `n` `number` _(optional)_ **Returns** `string` ```lua -- top 20 GPU spans of the window 40 -- top 40 ``` ## tools/profiler/hits {#tools-profiler-hits} ```lua profiler.hits(label?: string, spikeMs?: number) -> string ``` Drain the frames a record-mode `watch` caught and report them as a spike-cluster distribution — every caught frame grouped by its dominant hotspot, so repeated hitches collapse to their handful of causes instead of a wall of individual frames. Draining clears the buffer. The snapshot is stored under `label` — drill into any cluster with `frame