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?) → void

`identity` spells its origin as a prefix: `@builtin::…` (engine-shipped), `@<lib>::…` (installed from a library), or no `@…::` prefix at all (born in this world). Pure string matching — no Rust accessor.

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 still raises — that is a question about the reference, not about presence, and a nil there would report absence for content that is present twice. 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`. as `asset.resolve`'s — so the two answer the same question and differ only in what a miss is. 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")

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

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

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

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. table's own level. `asset.categories()`.

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

declareReferenceKey(assetType: string, key: string, refType: string, type: ?) → void

Declare that, in a data file belonging to an `assetType` asset, the top-level `key` names an asset of `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.

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

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.

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`'s ancestors and return an `AssetRef` handle for the OUTERMOST category-folder containing it (e.g. `main.scene` for `"/source/scenes/main.scene/scene.json"`). Returns nil for paths outside any registered asset type.

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

import(path: string) → 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. 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.

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

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 settings = asset.get_field("tree", "settings") -- → a Luau table

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, "settings", { keepCpu = true })` keeps every other setting. 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", "settings", { keepCpu = true }) -- merges; sibling settings 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/<name>.<type>/`. 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 under `/source` to author the asset in, so generated content groups instead of accumulating at the source root, and the asset's identity carries that folder as its dotted prefix), `into` (author INSIDE a resolved container ref), `dest` (an absolute destination path), and `overwrite` (re-author in place, keeping the guid). `:serialize`, …). Disk-only: nothing is uploaded to CPU/GPU. `{ durable = true }` when the files are where the call filed them, and `{ durable = false, warning = …, playShadow = …, shadowed = { … } }` when the play shadow took them — live in this session, disk source untouched, discarded on a guarded play-exit unless kept, with `playShadow` naming the routes that keep them and `shadowed` the paths. `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 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 .. " " .. d.playShadow) end

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.

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

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), and `totals` — the aggregates those rows sum to, so the listing reconciles against `renderer.textureMemory()` and `renderer.gpuMemory()`. 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, so an asset that loaded a preview image instead of its payload shows the wrong filename rather than a successful load. 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. `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)