swappedPairSuffix(category: string, name: any) → string

What to add to a refusal when the create names its category and its asset into each other's argument. `asset.create(category, name, opts)` names the category first; every other `asset.*` call that takes both names the asset first, so a create written the way its sibling check reads arrives here with an asset name where the category goes. Saying which way round the call reads is what turns "no such type" into the answer. Empty unless the name IS a category and the category is not one, so a create of a type the engine simply does not have keeps its own refusal.

walk_files(root: string) → void

Recursively walk a VFS folder → flat list of relative file paths.

load_type_behavior(typeName: string) → void

Load a type's `behavior.luau` and return the module table, or nil when the type ships none. The second return names a `behavior.luau` that EXISTS and raised while loading — the type declares creation logic that cannot run, so `M.create` reports it instead of writing the instance the type never described. `modules/asset_ref` owns the resolution: the same registry lookup and the same caller-independent require keys per-instance `ref:` dispatch uses, so a type reaches its hooks and its methods through one derivation.

on_create_of(behavior: { [string]: any }?) → void

The type's `onCreate` hook, or nil when it ships none.

name_pattern_of(behavior: { [string]: any }?) → string

The name pattern a type accepts. A type whose instances are addressed as Luau identifiers wants the default; one whose names are read as prose — `getting-started`, `01-overview` — declares its own by exporting `namePattern` from `behavior.luau`. An export that is not a usable pattern falls back to the default rather than letting a broken type definition reject every name.

template_root(typeName: string) → string

Resolve a type's `template/` skeleton folder. A type authored inside a package (`systems/foo.package/bar.assetType`) lives beside its package, not under the global assetTypes root, so resolve the type to its real folder and look for `template/` next to its `type.yaml` — the same package-aware path `load_type_behavior` uses to find `behavior.luau`. Falls back to the global root when the type can't be resolved (e.g. a brand-new type authored this frame that is not registered yet).

name_stem(name: string) → string

The structural validator compares a declared path to an entry by stem: the trailing extension falls off both sides, so a declared `init.luau` names an `init.lua` entry. A leading dot belongs to the name rather than to an extension, so `.metadata` stems to itself and `.metadata.meta` to `.metadata`.

declared_path_matches(pattern: string, candidate: string) → boolean

Whether a declared path names `candidate`. A type declares its parts by name; when the set of parts varies per instance it declares them by pattern instead, writing `*` for the part that varies. `*` stands for any run of characters within one path segment, so a pattern names entries beside each other. A path without `*` is compared literally.

contract_declares(contract: FileContract, entry: string) → boolean

Whether the contract declares `entry`, under the same stem-and-pattern reading the structural validator applies to an instance's root children.

file_contract(typeName: string) → FileContract

A type's declared file contract, read from the `type.yaml` beside its `template/`: every path the type declares (required and optional), the describe-this-asset sidecars among its required ones, and whether it admits paths it never declared. The read happens per call, so a `type.yaml` edited while the engine runs is answered from its current body. A type whose `type.yaml` is absent or unparseable declares nothing, and its instances are unconstrained — the same reading the structural validator takes. A required entry carrying `one_of_group` is one alternative of a set the validator satisfies with any member, so it states nothing about this path on its own and is left out of the sidecars a template owes.

substitute_name(body: string, name: string) → string

A type's `template/` carries `[name]` where the instance's own name belongs — its `name:`, its `suffix:`, its description, its headings. The assetType template says so in its own type.yaml ("`asset.create` rewrites `[name]` to your type name"), and until it is rewritten the placeholder reaches the created asset as text: two packages both register as `[name]` and collide. A body carrying a NUL is binary (a template may ship an image or a mesh payload) and is copied through untouched.

name_of_folder(folderPath: string, typeName: string) → string

The instance's own name, read back off the folder it already lives in: `/zero/source/scenes/Foo.scene` names `Foo`. A folder that does not carry the type's suffix is named by its last segment.

fireOnRegister(ref: { [string]: any }) → void

Resolve the freshly-written asset to its canonical `AssetRef` and return THAT. `asset.create`'s contract is "make the asset and hand back a usable ref" — one carrying `guid`/`__ref`/`path` AND the type's ref methods (`:ensureHandle`, `:serialize`, …). The old return was the internal create-pipeline descriptor (`{ dest, mode, files, … }`), which had none of those, so every caller had to `asset.resolve(name)` again. The registry resolve is a pure lookup (it does not read the asset's bytes), and for an already-registered TYPE it lands the same frame the asset is written — so the common path returns the fully-resolved ref (guid + per-type methods). But registry registration of a freshly-written asset is drained on a budget across frames, and a brand-new TYPE authored THIS frame is not registered as a type yet, so a same-frame resolve can miss. asset.create's contract is to make the asset and hand back a usable ref, NOT to block on the async registry — so on a miss, hand back a lightweight ref built from the known write info (path/type/name). Its `getBytes()`/path and per-type method dispatch work immediately; its `guid` + registry-backed lookups fill in once the registration drains (the bytes are already on disk — the asset is never lost). Interning happens on the next resolve, when the guid exists. Fire the type's optional `onRegister(self)` hook on a freshly-created instance — the live-create trigger that makes a runtime-authored asset take effect at once (the world-load sweep covers instances that already exist). The hook fires at most once per instance (path-keyed guard), so this and the sweep never double-register.

isReproducedContext( ) → boolean

Whether the running Luau context is one the world reproduces on every load — a script component's lifecycle callback, or a scene entrypoint. A create made here is re-made by the same code next load, so it files into the ephemeral store rather than the authored one. Origin via the optional `_G.__persist_origin`; a context that cannot be read is authored.

qualifiedIdentity(folder: string?, name: string) → string

The identity `name` carries when it is authored inside `folder`: the source path `/zero/source/a/b/name.<type>` derives `a.b.name`, so the same pair spells the same identity wherever the asset is filed.

created_ref(typeName: string, name: string, dest: string) → void

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

Create a new instance of asset type `typeName` named `name`. Runs the type's `onCreate(name, opts)` hook (or clones its `template/` skeleton) and writes the result to the authored destination. Returns the created asset's `AssetRef` (guid/path + the type's ref methods) — NOT a descriptor. Disk-only: it writes the asset's files (and the metadata system mints the guid on write); it never uploads anything to CPU/GPU. Materializing a mesh / texture / material onto the GPU is an explicit, separate step (e.g. `renderer.mesh.create` / a Model binding), so creating assets can never starve another client's memory.

ensureTemplateFiles(folderPath: string, typeName: string) → void

Describe asset type `typeName`'s creation contract as data: the parameters its `onCreate(name, opts)` hook accepts, plus the same human-readable contract rendering that validation errors print. Forwarded as `asset.describe` by `../init.luau`. Materialise the template files an existing asset folder OWES its type — the paths `type.yaml` declares required and the folder lacks. `M.create` clones the type's `template/` as the canonical instance structure, so an asset created through it satisfies its own type's content requirements. A writer that builds an asset folder some other way — the scene saver writes `scene.json` straight to disk — produces a folder the publish gate then refuses for a file the type declares required. This is the same template, applied to a folder after the fact. What the type declares OPTIONAL is left out. An optional template file is authored content the type offers rather than structure it owes: the scene type's `build.luau` declares a scene's entities, so writing it into a scene that never had one gives that scene content its author never wrote. A folder is completed to the contract it must satisfy and no further. Only missing paths are written, so existing content is never overwritten, and each body carries the same `[name]` rewrite `create` applies, against the name the folder itself already states. Returns the paths it created.

describe(typeName: string) → void