refuseSwappedPair(call: string, form: string, name: any, category: any) → void

The category and the asset, read into each other's argument. `asset.*` names the asset first and its category second in every call that takes both; `asset.create` alone names the category first, so the two halves of a create-then-check pair read opposite ways round. A call carrying a category where the asset goes, and something that is no category where the category goes, is that pairing written the wrong way round — and answering it reports absence for an asset that is present. Both halves have to hold. A category argument naming no category, beside a name that names none either, is a fair question about a category nothing carries yet: the type set is open at the bottom, a loose file contributing its own extension the moment one exists, and that question keeps its answer. `I.isKnownType` reads the wider set `asset.categories()` narrows — every category plus the type groups a category argument stands in for — so a `type` the engine accepts is never read here as naming no category. Called where the answer would otherwise be the negative one, which is the answer `asset.exists` is asked for, so the reading is two membership questions and the second is asked only when the first says the name is a category.

metadataPathOf(ref: any) → string

readMetadataTable(ref: any) → void

writeMetadataTable(ref: any, t: { [string]: any }) → void

deriveScopeOrigin(identity: string?, path: string?) → void

`identity` spells its scope as a prefix: `@builtin::…` (engine-shipped), `@<lib>::…` (installed from a library), or no `@…::` prefix at all (born in this world). An asset at `path` that the library carries by reference — its bytes are another world's, named by an install record — is installed from that world, whatever its scope.

readmeLead(sourcePath: string?) → string

An asset's README lead paragraph — the first run of contiguous non-heading prose, skipping leading `#` headings and blank lines and stopping at the first blank line after prose starts. Nearly every asset ships a README (only a fraction set `.metadata.description`), so this is the primary `description` source, ahead of the sidecar. Lines within the paragraph are joined with a space so a hard-wrapped README reads as one description sentence.

buildEnvelope(ref: any) → InspectRecord

Build the common half of an `InspectRecord` for a resolved `AssetRef` — every field except `detail`, which is the resolved type's job. Reads ONLY the ref's own envelope fields, its type's registered definition path, and its own `.metadata` / README — never runtime state.

promotion_candidate(ref: string) → void

An importer that promotes a loose file consumes the name it was uploaded under: `wall.png` becomes the container `wall.texture` and the loose file is removed, so every reference still written as `wall.png` stops resolving. The promoted asset keeps the stem, and the provenance the importer stamps records the file it consumed — together those are enough to answer the miss without a registry scan. `<stem>.<ext>` is the only shape a promotion can have consumed, so a reference without an extension skips this entirely and a miss stays a miss.

consumed_by_import(candidate: any, leaf: string) → boolean

Whether `candidate` is the asset an importer produced by consuming `leaf`. The check is the stamped provenance, not the name: an asset that merely shares a stem with the missed reference is not a promotion of it.

announce(ref: string, resolved: any) → void

resolve_promoted(ref: RefArg, type_hint: string?) → AssetRef

Resolve `ref` through an importer promotion, or nil when it is not one.

tryResolve(ref: RefArg, type: string?, base: string?) → AssetRef

The same lookup `asset.resolve` performs, answering a miss with nil instead of raising. Every name form, the same `type` narrowing, and the same handle on success — so "use it if it is there" needs no `pcall` around a call whose failure would otherwise be indistinguishable from a real error. This consults the asset REGISTRY, so it sees registered assets wherever their files live, `@builtin::` ones included. `asset.exists(name, type)` answers the narrower question of whether an asset's files are present in the current mode's store. A name that reaches more than one asset of `type` (or more than one asset, with no `type`) still raises: that is a question about the reference, and a nil there would report absence for content that is present twice. A name that only assets of other types answer to reaches no asset of `type`, and answers nil. It reaches the asset, so the name carries the same reference contract `asset.resolve`'s does: a literal is recorded as this source's dependency, a computed name is a dynamic resolve — free in a tool, refused on the gameplay path. `asset.exists(name, type)` is the probe a computed name can ask. A reference naming a file an importer has since promoted resolves to the promoted asset, the same as `asset.resolve`. its file: a data asset resolving the references it holds, such as a material resolving its `mat.yaml`. A `~` / `~.tail` ref expands against the root enclosing it, and a ref its `.refs` recorded reaches the asset recorded there. Without it, both are read at the calling Luau source, as `asset.resolve` reads them. if mat then applyMaterial(mat) end

local mat = asset.tryResolve(name, "material")

ref(ref: RefArg, type: string?) → AssetRef

Build a reference handle for an asset — the canonical ref envelope constructor. Identical shape to `asset.resolve`; preferred name for the author-side use case (embedding refs in YAML / JSON / Luau output). Naming the asset here reads exactly as naming it in `asset.resolve`, down to raising on a miss: a literal is recorded as this source's dependency, a computed name is a dynamic resolve — free in a tool, refused on the gameplay path. `asset.exists(name, type)` is the probe a computed name can ask.

local r = asset.ref("animations.idle", "animation")

deprecation(ref: RefArg) → Deprecation

Whether an asset is deprecated, why, and what replaces it. An asset is deprecated when its own `.metadata` carries `"deprecated": { "reason": "<one line why>", "replacedBy": "<identity>" }`, when a container holding it at any depth does (a package, a toolbox, a folder asset), or when its asset type does. A deprecated asset still resolves and loads by identity and guid; search surfaces do not offer it, and resolving it warns once per session. `"container"` or `"type"` and `source` is the folder holding the marker; nil when the asset is not deprecated.

local d = asset.deprecation("@builtin::deprecated.deprecatedParticles.DeprecatedParticleEmitter")

typeRef(target: RefArg) → string

Return the pinned asset_type reference (the type's guid) that the asset is an instance of. Resolve the full type with `asset.resolve(asset.typeRef(target))`. Returns nil for loose files / assets with no pinned type.

local t = asset.resolve(assert(asset.typeRef("brick")))

promoteDetail(record: InspectRecord, detail: any) → void

Lift a type's `detail` onto the record itself, and name what was lifted in `detailKeys`. `detail` is whatever the resolved type's `inspect` hook returns, so its shape differs per type and the record gives no sign of what is inside. A component's field schema lives at `detail.fields`; a reader scanning the record's keys sees only `detail` and has no reason to look further. Lifting the hook's own keys puts each where it is looked for (`record.fields`) while `detail` stays intact for callers that already read through it, and `detailKeys` tells a reader which keys came from the type rather than the envelope. Driven entirely by what the hook returned, so a type that grows a new detail key — or a new type entirely — surfaces it without changes here.

inspect(ref: RefArg, type: string?) → InspectRecord

Everything known about one asset in a single record: identity, guid, source, type, scope and origin, its description and tags, the ref methods its type exposes, and the type's own `inspect` detail when it declares one. The read-everything counterpart to `asset.resolve`, which hands back a ref. categories answer to the same bare name.

local rec = asset.inspect("@builtin::materials.default")

local rec = asset.inspect(name, "mesh"); print(rec.guid, #rec.tags)

source(ref: RefArg, type: string?) → string

Return the VFS source path for an asset. It reaches the asset, so the name carries the same reference contract `asset.resolve`'s does: a literal is recorded as this source's dependency, a computed name is a dynamic resolve — free in a tool, refused on the gameplay path. `asset.exists(name, type)` is the probe a computed name can ask.

local p = asset.source("brick") -- "/source/brick.material"

identity(ref: RefArg, type: string?) → string

Return the canonical identity for an asset.

local id = asset.identity("brick")

guid(ref: RefArg, type: string?) → string

Return the guid for an asset.

local g = asset.guid("@builtin::components.Camera")

meta(ref: RefArg, type: string?) → AssetMeta

Read the asset's engine-owned identity record (guid / checksum). Distinct from `.metadata` (agent-editable); for that use `asset.metadata`. An asset in the runtime asset store (`/zero/runtime/assets/`, where a create made from a component or a scene entrypoint lands) has a version too: its checksum is derived from its bytes, and every edit is a new one.

local m = asset.meta("brick") -- { guid = ..., checksum = ... }

deps(ref: RefArg, type: string?) → DepsResult

Return the asset's outbound dependency graph — every other asset recorded as a content dependency of it.

for _, d in asset.deps("main.scene").deps do print(d.asset_guid) end

interface(ref: RefArg, category: string?) → AssetInterface

What the asset declares it takes and gives, read from its source without running it: the interface its type's `interface:` block says its sources declare (a `.procNode` declares one). `description` is what it does; each of `inputs` carries its `name`, `type`, `default`, `min`, `max`, `options`, `optional` and `description` as the declaration states them (a vector default reads as `{ ["$vector"] = { x, y, z } }`); each of `outputs` its `name` and `from`, what makes it. `problems` lists each part of the declaration that is not written as literals, which a push refuses. The same data travels with the source's reference table to ZeroMind. the asset's type declares no interface or its source hands no builder.

local iface = asset.interface("@builtin::systems.procgen.nodes.points.disc", "procNode")

categories( ) →

List every asset category the engine currently recognises. Use to discover valid `type` argument values for the rest of `asset.*`.

for _, c in asset.categories() do print(c) end

listRevision( ) →

Two numbers that together move whenever what `asset.list` could answer changes: an asset made, removed, moved or renamed, a name it answers to added, a file created in or removed from an asset's folder (a new entity in the open scene writes one), or the index rebuilt. Rewriting a file that already exists leaves them still, and so does a write to a path no asset can sit at. The copies play makes resident in the runtime-asset layer move neither number. Hold the pair beside something derived from a listing and list again only when either differs, so a per-frame reader lists only on the frames where the answer can have changed.

local e, g = asset.listRevision() if e ~= held.e or g ~= held.g then held.list = asset.list("texture") end

rootKinds( ) →

The kind of every asset folder that is a root of its contents (its category declares `root: true`; a package is one too): a `~` written in a file inside such a folder names that folder. The same answer in every VM, the engine thread's and each worker's.

local roots = asset.rootKinds() -- { "effect", ... }

alias(ref: RefArg, alias: string) → boolean

Add a name the asset answers to. `asset.resolve`, leaf shorthand, and the typed-argument coercion that content refs travel through all reach the asset by the alias from here on, exactly as they do by its identity — so a material naming a shader by its alias resolves, and content written against an older name keeps working after a rename. The name survives writes to the asset's own files. Raises when the name already resolves to a DIFFERENT asset — an alias extends the identity namespace and never takes a name out of another asset's hands — and when it is shaped like a guid or a VFS path, forms that resolve before identity lookup, so an alias in that shape could never answer. (`standard`) or a scope-qualified path (`@builtin::shaders.legacy`). answered to it.

asset.alias("@builtin::shaders.pbr", "standard")

declareReferenceField(call: string, field: string, assetType: string, type: ?) → void

Declare that `call`'s options table names an asset of `type` in its `field`, so a string literal written there is recorded as a reference by whatever writes the file. This is what puts an API that takes an asset BY NAME into the reference graph: the named asset becomes a dependency, travels with the content that names it into a pack or a pull, and a name nothing answers to becomes an unresolved dependency `worldValidation` reports and the push gate refuses. A field holding a TABLE of names — a material's `textures` — records every name in it. Declare once, beside the API; a call taking its asset as the FIRST positional argument is already read and needs no declaration. Only a literal is recorded; a computed name resolves at runtime and is reported as a dynamic resolve. An asset type states the same declaration as content, in the `references.fields` of its `type.yaml`, which every reference table reads from the moment the type registers. table's own level. `asset.categories()`.

asset.declareReferenceField("fx.beam", "material", "material")

declareReferenceKey(assetType: string, key: string, refType: string, via: ("asset_ref" | "settings_of", type: ?) → void

Declare that, in a data file belonging to an `assetType` asset, the top-level `key` names an asset of `type` (`"*"` for any type) — a `.material`'s `mat.yaml` naming the shader it draws with and the textures it binds. The names a format holds are references as surely as ones written in code: recording them carries a material's shader along with the material into a pack or a pull, and turns a name nothing answers to into an unresolved dependency instead of a surface that renders as the magenta error material. A key holding a table of names records one per entry; a `{ __ref = <guid> }` envelope names its guid. `via` is the provenance the file's `.refs` records: `"asset_ref"` (default) for an asset the file uses, `"settings_of"` for the declarer whose settings schema the file's values follow. A type states the keys of its own files as content, in the `references.keys` of its `type.yaml`, which every reference table reads from the moment the type registers.

asset.declareReferenceKey("material", "shader", "shader")

asset.declareReferenceKey("preset", "target", "*", "settings_of")

declareReferenceArg(call: string, position: number, assetType: string, type: ?) → void

Declare that `call`'s argument at 1-based `position` names an asset of `type`, so a string literal written there is recorded as a reference. The positional counterpart of `asset.declareReferenceField`, for a call that takes its asset as a plain argument — including a world's own spawn helper, which is where a name most often stops being visible to the reference graph. A lookup whose asset is its FIRST argument (`asset.resolve` and its siblings) is already read and needs no declaration. Only a literal — or a name the file holds in a top-level string constant — is recorded; anything computed is reported as a dynamic resolve. An asset type states the same declaration as content, in the `references.args` of its `type.yaml`, which every reference table reads from the moment the type registers.

asset.declareReferenceArg("spawnModel", 3, "mesh")

aliases(ref: RefArg) →

The additional names this asset answers to, beyond its own identity — what `asset.alias` registered, plus the package-relative `~pkg.tail` form when the asset lives inside a package.

for _, n in asset.aliases("pbr") do print(n) end

list(type_or_opts: (AssetCategory | ListOpts, scope: ?, opts: ?) →

Query registered assets, returning each match as a resolved `AssetRef` handle. Every filter narrows the same enumeration and they compose: `path` selects a VFS subtree (the folder and everything under it), `type` keeps only those asset types within it, `scope` keeps only that scope, and `fields` keeps only assets whose `.metadata` matches. `type` and `path` each take one value or a list matching any of its entries, and `all` / `any` / `none` group whole filters — `none` excludes what it matches. `order`, `limit`, and `offset` shape the result: matches come back ordered by identity unless `order` names another field (`name` / `path` / `type` / `guid`). `subassets` decides how deep the enumeration reaches into composite assets. An enumeration returns the assets each container broadcasts, which its type declares: a `.package` and a `.toolbox` broadcast theirs, so their members are listed on their own, and a `.bundle` keeps its interior meshes, materials and rigs to itself, so they are reached through the bundle and a list of the folder holding it comes back without them. `subassets = true` enumerates those private interiors as well — what an asset is built out of, beside what the world offers. Each entry is the same envelope `asset.resolve` returns (`__ref` / `type` / `name` / `guid` / `identity` / `path`), so it can be passed anywhere an AssetRef is accepted, and the result carries `:first()` / `:random()` / `:filter()` / `:sort()` and friends. `type` takes the same values `asset.categories()` lists. The first positional argument is a path when it is absolute, a type otherwise. A `type` naming none of those values raises, naming it and any near spelling, so an empty result means a type the engine has. A type-group name stands for a family of those types rather than naming one (`model` for `glb`/`gltf`/`fbx`/`obj`, and `image`, `text`, `config` and `script` for theirs), so it lists whichever members the engine carries, and raises naming them when it carries none. An unknown key raises, as does a table setting both `type` and its older spelling `category`. A static (literal) type or path makes the enumeration part of the calling file's content dependencies when it is saved — the set travels with published content, so consumers get at-least the authoring world's assets. enumeration can be captured for publish), or the full query table.

local hero = asset.list({ path = "/zero/source/props", type = "mesh", fields = { tags = "hero" } }):first()

local parts = asset.list({ path = "/zero/source/models", type = "mesh", subassets = true }) -- a bundle's interior meshes too

containing(path: string) → AssetRef

Walk `path` and its ancestors and return an `AssetRef` handle for the INNERMOST registered category-folder containing it — the typed asset that directly owns the path (e.g. `main.scene` for `"/source/scenes/main.scene/scene.json"`; for a folder that is itself a registered asset, that asset). Returns nil for paths outside any registered asset.

local a = asset.containing("/source/scenes/main.scene/scene.json")

pathHolding(guid: string, checksum: string) → string

The VFS path holding the asset `guid` at exactly the version whose content checksum is `checksum` (the pair `asset.meta` reports): the guid's home when its bytes are that version, else a copy of that version held beside it, such as an installed dependency's. Returns nil when this world holds that asset at no such version.

local m = asset.meta(asset.resolve("@builtin::shaders.pbr", "shader")); local path = asset.pathHolding(m.guid, m.checksum)

isPrivateSubasset(path: string) → boolean

Whether the asset at `path` is a private subasset: nested inside another asset whose type does not broadcast its subassets — a `.bundle`'s interior meshes, materials and textures, an effect's own materials. A private subasset is part of its parent: it is not listed, searched or installed on its own, and it is excused from the files that describe an asset. Whether nested assets are private is the enclosing asset's type's to say: `broadcasts_subassets: true` in its `type.yaml` (a `.package`) makes its members public, and an asset nested in no other asset is never private. The same rule `asset.list` applies, where `subassets = true` is what reaches private subassets. path that names no asset.

asset.isPrivateSubasset("/zero/source/models/tree.bundle/material/Bark.material") -- true

import(path: string, opts: { importerSettings: { [string]: { [string]: any } }? }?) → string

Import a raw source file NOW and return the produced asset path (a `.bundle` for a model, `.texture` for an image, `.audio` for a sound, …), or nil if no importer claims it. While play runs and holds the source where it stands (`vfs.playHoldsInPlace`), the import is owed: this `owed`, and the import runs when play ends or pauses. This is the deterministic, on-demand counterpart to the engine's automatic import-on-write: it runs in the calling task and returns only when the import is complete. Pair it with a quiet write — `vfs.write(path, bytes, { quiet = true })` lands the raw bytes without firing the automatic importer, then `asset.import(path)` imports them under your control, so you can act on the result instead of polling for the import to appear. settings for this import only, laid over the claiming importer's own. A setting that importer does not declare is an error.

local bundle = asset.import("/zero/source/generated/chest.glb")

local bundle = asset.import("/zero/source/generated/chest.glb", { importerSettings = { model = { keepSource = false } } })

metadata(ref: RefArg, type: string?) → AssetMeta

Read the asset's agent-editable `.metadata` sidecar as a Lua table. Missing sidecar returns `{}`. Distinct from `asset.meta` (engine-owned).

local md = asset.metadata("brick")

set_metadata(ref: RefArg, data: AssetMeta) → void

Replace the asset's `.metadata` sidecar with the given table. Pass an empty table to clear all fields.

asset.set_metadata("brick", { author = "me", tags = { "wip" } })

get_field(ref: RefArg, key: string) → any

Read one top-level field from the asset's `.metadata`.

local author = asset.get_field("brick", "author")

local tags = asset.get_field("tree", "tags") -- → a Luau table

schema(ref: RefArg) → any

The typed settings schema governing this asset — the Field descriptors its type declares for every asset of that type, or the ones the asset declares for itself. Each descriptor carries its kind, default, constraint and description, so an editor renders it and an agent reads what a setting takes without guessing.

local schema = asset.schema(texRef); print(schema.filter.constraint.values)

settings(ref: RefArg) → any

This asset's settings values, with every declared default filled in.

if asset.settings(texRef).filter == "nearest" then ... end

setSettings(ref: RefArg, patch: { [string]: any }) → void

Write a partial settings patch. The patch is merged over the asset's current values, the type's cross-field constraints are applied — a field the patch does not name moves to the only value the rest allows (a texture given a high-precision `compression` stops generating mipmaps), and a field the patch names that cannot hold refuses the write, saying why — and the result is checked against its schema; a violation refuses the whole write, naming every problem, and leaves the asset on its last valid settings. A valid write re-runs the type's `onChange`, which is where the type re-cooks whatever the settings describe. Older field names are accepted and stored under the current ones, and a field whose default follows another moves with it when the write does not name it.

asset.setSettings(texRef, { filter = "nearest" })

isArrayTable(t: any) → boolean

A table is array-shaped when it is empty or carries a [1]; map-shaped otherwise. set_field deep-merges map values (sibling sub-keys preserved); arrays and scalars replace.

deepMergeMaps(dst: { [string]: any }, src: { [string]: any }) → void

set_field(ref: RefArg, key: string, value: any) → void

Set one field in the asset's `.metadata`, creating the sidecar if missing. Sibling fields are preserved. When the new value AND the existing value are both maps (objects), the new value DEEP-MERGES into the existing one, so writing one sub-key never drops the others — `set_field(ref, "provenance", { bakedBy = "agent" })` keeps every other provenance key. Arrays and scalars replace. Clear a whole field with `asset.remove_field`; replace the entire sidecar with `asset.set_metadata`.

asset.set_field("brick", "author", "me")

asset.set_field("tree", "provenance", { bakedBy = "agent" }) -- merges; sibling keys kept

remove_field(ref: RefArg, key: string) → void

Remove one top-level field from the asset's `.metadata`. No-op when the field isn't present.

asset.remove_field("brick", "author")

has_field(ref: RefArg, key: string) → boolean

True when the asset's `.metadata` carries the named field.

if asset.has_field("brick", "author") then end

tags(ref: RefArg) →

Convenience read of the `.metadata.tags` array.

for _, t in asset.tags("brick") do print(t) end

has_tag(ref: RefArg, tag: string) → boolean

True when the asset's `.metadata.tags` contains `tag`.

if asset.has_tag("brick", "wip") then end

add_tag(ref: RefArg, tag: string) → void

Add a tag to the asset's `.metadata.tags`. Idempotent. Creates the sidecar and the tags array if missing.

asset.add_tag("brick", "wip")

remove_tag(ref: RefArg, tag: string) → void

Remove a tag from the asset's `.metadata.tags`. No-op when the tag isn't present.

asset.remove_tag("brick", "wip")

list_fields( ) →

Distinct top-level field keys observed across every asset's `.metadata`. Useful for tooling discovering custom keys in use.

for _, k in asset.list_fields() do print(k) end

list_field_values(key: string) →

Distinct values seen for the named field across every asset's `.metadata`.

local authors = asset.list_field_values("author")

validate(ref: RefArg, type: string?) → ValidateResult

Validate an asset folder against its type's `type.yaml`, plus the type's own semantic validation. Structural problems come from `type.yaml` — missing required files, unsatisfied `one_of_group` alternatives, and (when `allow_unlisted: false`) unexpected children. `validated = false` when no `type.yaml` is registered — nothing structural to check. On top of that, when the asset's type ships a `behavior.luau` exporting a top-level `validate(assetRef) -> { { code, message, severity? } }`, its reported problems (severity defaults to `"error"`) are appended to `problems`; error-severity problems flip `ok` to false, warnings leave it untouched. A hook that raises or returns a non-table is itself reported as a `validate.hook_failed` error problem — a broken hook blocks. A type with no `validate` export behaves exactly as the structural check alone. `world.push` calls this per user asset, so a type's semantic validation is enforced at publish time with no further wiring.

local v = asset.validate("@builtin::components.Camera")

preview(ref: RefArg, opts: { [string]: any }?, type: string?) →

Render a preview of an asset. Resolves the ref and dispatches to its type's `preview` ref-method when present; otherwise returns the `{ available = false }` sentinel ("no preview available for this type").

local p = asset.preview("@builtin::materials.gold", { size = { width = 512, height = 512 } })

create(typeName: string, name: string, opts: { [string]: any }?) →

Instance a new asset of an existing type. Runs the type's `behavior.luau` `onCreate(name, opts)` hook to produce the asset's files, then writes them under `/source/<folder>/<name>.<type>/` (`/source/<name>.<type>/` when no `folder` is given). This is the single generic asset-creation API. Refuses to clobber an existing edit-mode asset unless `opts.overwrite = true`, which re-authors it in place and keeps the existing guid (only the checksum changes). Pairs with `asset.exists` for content generators that re-run over the same names. A create made from a script component's callback or a scene entrypoint is output the world reproduces on every load, so it is filed in the ephemeral `/runtime/assets/` store instead, where the saved manifest never carries a second copy of it. `name` and `folder` spell the same IDENTITY in either store, so a reference written against that identity resolves the asset wherever the call filed it, and one generator run from an `execute` and from a component names one asset. bare identity — pass `opts.folder` to place it in a subfolder rather than spelling a path here. The accepted shape is the type's to declare: `^[A-Za-z][A-Za-z0-9_]*$` unless its `behavior.luau` exports a `namePattern`, as `guide` does to take `getting-started` and `01-overview`. This call names the category FIRST and the asset second. Every other `asset.*` call taking both names them the other way round — `asset.exists(name, category)`, `asset.tryResolve(ref, category)` — so a create-then-check pair reads `if not asset.exists(n, t) then asset.create(t, n, opts) end`. A call whose two arguments are read into each other, at either end of that pair, is refused and told which way round the call reads. framework keys consumed here and never seen by the hook: `folder` (a relative subfolder path under `/source` to author the asset in, with `/` between its folders as in `game/materials`, so generated content groups instead of accumulating at the source root; those folders joined by dots prefix the asset's identity, `game.materials.<name>`), `into` (author INSIDE a resolved container ref), `dest` (an absolute destination path), `overwrite` (re-author in place, keeping the guid), and `durable` (file every content file this create writes on canonical `/source` with play still running, in place of the play shadow, and raise with the reason when they cannot become source, the same key, meaning the same thing, that `vfs.write` takes). Every type accepts all five whatever its own contract declares; `asset.describe(typeName).frameworkParams` names them, and a rejection prints them under the type's own parameters. returns. `ref.path` is the VFS path the asset was written to (its folder: `/zero/source/<folder>/<name>.<type>`, the `dest` or `into` destination when one is given, `/zero/runtime/assets/<identity>.<type>` for a create filed in the ephemeral store), `ref.primary` the content file inside it (a shader's `shader.wgsl`, a module's `init.luau`), and both read and write with `vfs.read` / `vfs.write` or the `read_file` / `write_file` tools as they stand. `ref.identity` is the dotted name references use (`<folder>.<name>`, folder separators spelled `.`) and is what `tostring(ref)` prints. `ref.guid` is the stable id, and the type's ref methods (`:getBytes`, `:ensureHandle`, `:serialize`, ...) ride on it. Returned from `execute`, the ref reads back with all of these fields. Disk-only: nothing is uploaded to CPU/GPU. `{ durable = true }` when the files are where the call filed them, and `{ durable = false, survivesRestart = …, warning = …, playShadow = …, shadowed = { … } }` when the play shadow took them: live in this session and undone by a guarded play-exit unless kept, with `survivesRestart` saying whether a restart of this engine keeps them, `playShadow` naming the routes that keep them and `shadowed` the paths. A create under `/source/tmp/` answers `durable = false` with `survivesRestart = false`, a `warning` opening `SCRATCH` and `scratch` naming the paths: scratch reads back while the engine runs and is gone when it stops or restarts. `durable` is present whatever the answer is, so its absence is never a reading, and one call answers once for every file it wrote. It is the same answer, off the same shadow set and in the same words, that the MCP `write_file` / `edit_file` / `capture` tools attach to their own results — ask `vfs.durability` for it directly at any other write site.

local m = asset.create("material", "brick", { shader = "pbr" })

local s = asset.create("shader", "glow", { folder = "fx" }) -- s.path: /zero/source/fx/glow.shader, s.primary: /zero/source/fx/glow.shader/shader.wgsl

local wgsl = vfs.read(s.primary) -- the created asset's content file, read by the path the ref names

local mesh = asset.create("mesh", "tree", { positions = {...}, indices = {...} })

local mesh = asset.create("mesh", "rock", { positions = {...}, indices = {...}, folder = "terrain/props" })

local mesh = asset.create("mesh", name, { positions = p, indices = i, overwrite = true }) -- idempotent rebuild

local clip, d = asset.create("soundClip", "hit", { pcm = buf, sampleRate = 48000, channels = 1 })

if not d.durable then log.warn(d.warning) end

local c = asset.create("soundClip", "step", { pcm = buf, sampleRate = 48000, channels = 1, durable = true }) -- lands on source during play

canCreate(typeName: string) → boolean

Whether `asset.create` can instance `typeName`: the type declares creation logic (a `behavior.luau` `onCreate` hook) or ships a `template/` skeleton the hookless fallback clones. A type with neither — one whose instances only arrive by import — answers false. The query a creation UI derives its offering from, so what it offers is what `asset.create` accepts.

if asset.canCreate(kind) then asset.create(kind, name) end

storeHoldsIdentity(identity: string, typeName: string, reproduced: boolean, name: ?) → boolean

Whether an asset of type `typeName` that `name` reaches has files in the store `asset.create` writes from this context — the authored `/source` tree, plus the ephemeral `/runtime/assets/` store when the caller is a script component or a scene entrypoint, which is where a create there files it. `name` is any name the registry answers to for that asset: its canonical identity (`"a.b.thing"`), a registered alias, or the bare leaf (`"thing"`) — the spelling `asset.list` publishes as an entry's `name` and the spelling `asset.create` was given alongside `opts.folder`. So the `if not asset.exists(n, t) then asset.create(t, n, opts) end` pairing is satisfied by its own create, spelled the way the create was, in either store and at any folder depth. A plain existence probe — it does NOT resolve a handle or pin a content dependency, so it is safe to call with a COMPUTED name (unlike `asset.resolve`, whose handle would become a static-pinned dependency). The name is read the way `asset.resolve` reads one; the ANSWER comes from the store, so a registered asset whose files live outside the store this context writes — every `@builtin::` asset among them — is `false`. `asset.tryResolve(name, typeName)` asks the registry the wider question and hands back the handle — and because it reaches the asset, the name it is given follows the reference rule every lookup follows: a literal is pinned, a computed one is a dynamic resolve. So a name this source computed is what `asset.exists` is for. This call names the asset FIRST and its category second, as every `asset.*` call taking both does except `asset.create(category, name, opts)`. A call carrying a category where the asset goes and a non-category where the category goes is refused, naming which way round the call reads, rather than reporting the asset absent. leaf — without the type suffix. `asset.categories()`.

if not asset.exists(meshName, "mesh") then asset.create("mesh", meshName, geo) end

if not asset.exists(n, "mesh") then asset.create("mesh", n, { folder = "props", positions = p, indices = i }) end

exists(name: string, typeName: string) → boolean

describe(typeName: string) → DescribeResult

The creation contract for an asset type: the parameters its `onCreate(name, opts)` hook accepts, as data. `kind` is "schema" (typed contract), "legacy" (untyped opts — anything passes), "none" (template scaffold — takes no opts), or "error" (the type's schema failed to parse; `error` says why). `contract` is the human-readable rendering validation errors print. `frameworkParams` and `frameworkContract` carry the options `asset.create` consumes itself: `folder`, `into`, `dest`, `overwrite`, `durable`, which every type accepts and none declares.

local contract = asset.describe("texture").contract

warmup(ref: RefArg, opts: WarmupOpts?) → WarmupResult

Warm an asset's bytes into CPU memory and follow its declared content dependencies to each referenced asset, deduped by guid. Type-agnostic (reads the generic ref graph) and CPU-only — never touches the GPU. Side-effect-free name resolution (uses `asset.guid`/`asset.deps`, not `asset.resolve`).

local w = asset.warmup("@builtin::scenes.test_arena")

cpuResident(ref: RefArg, typeName: string?) → boolean

True when the asset is CPU-resident — a live script-component context holds it (a component's assetRef field, or an imperative `asset.resolve`/`ref` made while a component is the caller), which is what warms its bytes into memory. The CPU pool is a different pool from the device's: `asset.observe().cpu` lists it, `asset.observe().textures` / `.meshes` list what the device holds, and an asset can be in one and not the other.

if asset.cpuResident(ref) then print("bytes are warm") end

gpuResident(ref: RefArg) → boolean

True when the device holds a texture or mesh under this asset's guid, read off the inventory the renderer publishes.

print(asset.gpuResident("@builtin::models.Sample.DamagedHelmet"))

reloadSeq(ref: RefArg, typeName: string?) → number

How many content-change reloads this asset has been through — the count of `onAssetReload` dispatches the engine has RUN for it. A write to a file inside an asset does not reload it on the spot: the writes of one authoring step are collected for a settle window and the reload runs on a later frame. Read this, write, then poll for a larger number to learn the write's reload has actually reached subscribers. Monotonic per asset and session-scoped; 0 for an asset whose content has not changed since boot.

local at = asset.reloadSeq(ref)

vfs.write(asset.source(ref) .. "/graph.json", encoded)

repeat task.wait() until asset.reloadSeq(ref) > at

pending( ) →

Every asset reference a component on this engine holds that no asset answers yet. A reference arrives ahead of its bytes when a peer delivers a component whose asset has not synced here, when the carried mount it names is still filling, or when a scene applies before the content it names. Each one applies by itself the moment its asset resolves: a component waiting on it runs its awake() then, and a write held for a component already running (`held`) lands then and reaches its `onPropertyChanged`. `state` is `pending`, or `refused` when the carried mount the reference names settled without its content; `reason` and `detail` say why. A refused reference applies if a later mount of that key brings the content. A reference inside a list or struct field waits the same way at its place in the field (`path`, such as `skins[2]` or `look.skin`), the field keeps every other value it holds, and the reference applies in place. Every peer of a world holds and applies the references it was delivered the same way. reference naming the entity, the component (`type`, `instance`, `instanceId`), the field, where the reference sits in it (`path`: the field's name for its own value), the spec of the slot holding it, the reference, `held`, `state`, `reason` and `detail`.

local waiting = asset.pending()

if waiting.count > 0 then print(waiting.entries[1].reference, waiting.entries[1].state) end

repeat task.wait() until asset.pending().count == 0

reloadPending(ref: RefArg, typeName: string?) → boolean

True while a write to this asset still owes it a reload — the write is inside the settle window that collects one authoring step's writes, or its reload is queued and the engine has not run it yet. False means every content change written so far has reached its subscribers, so a consumer bound to the asset now cannot be interrupted by a reload the earlier writes already earned. The recording is synchronous with the write, so a call made right after one already reads true.

repeat task.wait() until not asset.reloadPending(ref)

observe( ) → any

What the engine is holding for content right now, in one reading: `textures` and `meshes` (one row per resource the device holds, each with the bytes it costs, its dimensions or buffer split, and where it came from), `cpu` (one row per asset a live script-component context holds), `offDevice` (one row per mesh nothing displays, whose GPU buffers were given back: `held` is `"definition"` when the engine keeps the mesh's whole CPU definition and `"source"` when it keeps only the stored file `source` it reads the mesh from again, and `bytes` is the CPU memory that costs), and `totals`: the aggregates those rows sum to, so the listing reconciles against `renderer.textureMemory()` and `renderer.gpuMemory()` (`offDeviceBytes` sums the `offDevice` rows). Each pool is named because they are different pools: an asset can be on the device and not CPU-resident, or the reverse. `devicePublished` is false when no renderer has published an inventory and `cpuPublished` when the scripting VM has not published its pool — an engine that cannot answer reads differently from one answering with nothing resident.

local r = asset.observe() print(#r.textures, r.totals.textureBytes)

diagnose(ref: RefArg) → any

Why one asset can or cannot be used, read from the engine rather than from what the caller asked for. Always carries `usable`; when false, `reason` is one of `asset.unusableReasons()` and `detail` is the engine's own message. `primary` names the file the type's declared `primary` list resolved to, the file a load of the asset reads. The payload's bytes are read by the engine's own decoder wherever it has one for that container, so `usable` is the verdict a load would reach and the call costs that decode.

local d = asset.diagnose("myTex") if not d.usable then print(d.reason, d.detail) end

unusableReasons( ) →

Every reason `asset.diagnose` can report an asset unusable for, sorted.

for _, r in ipairs(asset.unusableReasons()) do print(r) end

primaryFile(ref: RefArg) → any

The file the asset type's declared `primary` list resolves to inside this asset, as the loader itself resolves it. A `*.<ext>` entry resolves the lowest-named file with that extension, and never the asset's `preview.png`, the picture rendered from it. `resolved` is false when no declaration matched and `path` is then absent; `declared` is the type's own primary list in match order.

print(asset.primaryFile("myTex").path)