Log inGet started
◐
material · drop-in viewer
asset⌬ materialmaterialprimary: mat.yaml·originates fromworld 07158574-5…

error_test

Intentionally broken material used to exercise the renderer's error-handling and fallback paths. It targets `@builtin::shaders.error_shader` and carries a bright magenta base colour (`1.0, 0.0, 1.0`) — the classic "missing/failed" flag colour — with mid roughness (`0.5`), opaque…

byzero-proxy @ DESKTOP-DB3UJOJ·posted 4mo ago
What it does

Error Test

Intentionally broken material used to exercise the renderer's error-handling and fallback paths. It targets @builtin::shaders.error_shader and carries a bright magenta base colour (1.0, 0.0, 1.0) — the classic "missing/failed" flag colour — with mid roughness (0.5), opaque render type, and back-face culling.

Inputs

  • colors.base_color (1.0, 0.0, 1.0, 1.0) — magenta error flag tint.
  • floats.roughness (0.5) — neutral surface roughness.
  • render.type (opaque) / render.queue (2000) — drawn in the standard opaque pass.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

This asset doesn't declare a schema or structured payload.
⌬ Metadata
descriptionIntentionally broken magenta material on @builtin::shaders.error_shader for testing the renderer's error-handling and fallback paths.

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

Showing up to 3 levels deep. Open a part to see what it holds further down.

36+items
·
assettype · born here
❒asset
# Material (asset type) A material is a named, configured instance of a `.shader`. The shader defines the surface look (lighting model, available property fields, texture slots); the material picks values for those fields and a shader to bind to. Renderable entities reference materials, not shaders, so the same geometry can wear different materials and the same material can be reused across many entities. Entities sharing one material can still differ in a value: every drawn object carries four `vec4` lanes of its own that a surface shader reads as `input.shader_data[lane]` and `renderer.instanceData.set` writes. Use that for a dissolve at its own progress per subject, a hit flash at its own age, a fill level per instance — a material per entity is for when the LOOK differs, not when a number does. > New to how a material relates to its shader, its textures, and the live GPU > material behind it? Read `core/resource-model` first. It also covers the > difference between an authored `.material` asset (this type) and a runtime GPU > material made with `renderer.material.create`. ## When to use one - You want a named surface configuration an entity wears by referencing it from its `Model` component (`material = "@.../<Name>"`). - You want runtime property tweaks (`asset.resolve(ref):setProperty(...)`) to affect every entity using the material at once. - You want to publish a curated look (`Gold`, `RedGlow`, `BrickWall`) other authors can reuse without re-typing shader bindings. If you need a brand-new lighting model or a custom visual effect, you need a `.shader` first; the material wraps it. ## Where it lives - Source: `/zero/source/.../<Name>.material/` - Identity: `<Name>` (the `.material` suffix strips). - Folder shape: - `mat.yaml` — canonical material spec (shader + property values). **Required.** - `README.md` / `.metadata` — optional prose + tags, indexed when an author writes real ones. - `textures/` — optional folder for embedded textures. Validator allows the folder; its interior is unrestricted. - `shaders/` — optional folder for a co-located custom shader. Same rule. ## How to create one ```luau asset.create("material", "<Name>") -- Creates: /zero/source/<Name>.material/ -- mat.yaml (shader binding + property scaffold) -- `folder` places it in a subfolder of /source instead of the root: asset.create("material", "<Name>", { folder = "materials" }) ``` Pass the shader and initial values through `asset.create`, then tune with `setProperty` and keep what you tuned with `saveDefinition`: ```luau local mat = asset.create("material", "<Name>", { shader = "@builtin::shaders.pbr" }) mat:setProperty("base_color", { 0.8, 0.6, 0.1, 1 }) mat:setProperty("roughness", 0.3) mat:saveDefinition() -- writes the tuned values into mat.yaml ``` This mints the `.material` asset and returns a handle you tune with `setProperty`. A set is a runtime change: it reaches the GPU material and every entity wearing it, and `saveDefinition` is the call that writes it into `mat.yaml`, so a property driven every frame costs no file write and leaves the authored file as its author wrote it. A purely runtime `asset.create` lives only for the session. For an ephemeral, runtime-only GPU material that is not an asset at all, use `renderer.material.create` instead (see `core/resource-model`). ## How it operates 1. **Property reflection.** The bound shader's uniform struct fields become the material's configurable properties — no manual property declarations needed. 2. **Property values.** `mat.yaml` groups values by type, each block keyed by the shader's field names: `properties:` holds scalars and colors/vectors, `ints:` holds integer-typed fields, `bools:` holds boolean-typed fields, and `textures:` holds texture slots. Omitted fields take the shader's default. A scalar is a bare number (`roughness: 0.5`); a color or vector is an array (`base_color: [1, 1, 1, 1]`). `shader:` is the shader's identity string. This is the shape every material the engine writes uses. A `saveDefinition` writes the changed values into the file where they already stand and leaves the rest of it — its comments, the order of its keys and blocks, the spelling of its literals, untouched. 3. **Render state.** `render:` holds how the mesh is drawn rather than what the shader reads: `blend` (the equation the fragment composites with, also spelled `type`), `cull`, `depth_write`, `depth_compare`, `topology` and `queue` (the draw order, a whole number: `2000` opaque, `3000` transparent, `4000` overlay). The `.shader` type README's "The render block" section lists every value each key takes, and `asset.create`'s `render` argument takes the same keys and values. 4. **Application.** An entity wears a material by referencing it from its `Model` component (`material = "@.../<Name>"`). Materials affect every entity that references them; runtime `asset.resolve(ref):setProperty(...)` changes propagate to all of them immediately, and last until the next mode change unless `saveDefinition` writes them into `mat.yaml`. 5. **Texture binding.** Texture slots accept `color:r,g,b,a` for solid colors, `default:white` / `default:black` / `default:normal` for the engine's own fallback texels, `@builtin::textures.<name>` for builtins, `path/to/image.png` for file textures, or a render-target handle for camera renders. The GPU texture cache reads the `color:` and `default:` forms from the string itself, so a slot written in one names no asset and carries nothing with the material when it travels; every other form names a texture asset the slot depends on. A texture in `base_color_texture` is multiplied by `base_color`: every built-in surface shader declaring both draws the texture's colour times `base_color`, channel by channel. Under the default white `base_color` the texture shows as itself, and a coloured `base_color` tints it. The two read a colour differently: `base_color` is linear, and the slot reads its texels as sRGB-encoded, a `color:` value's included, the way it reads an image. A colour stated in both places is therefore multiplied by a darker copy of itself: `color:0.62,0.14,0.05,1` in the slot decodes to `0.34, 0.017, 0.0039`, so beside `base_color` `0.62, 0.14, 0.05` the surface draws `0.21, 0.0024, 0.0002`, far darker than either. State a solid colour once, as `base_color`, and leave the slot at its default white. 6. **Hot reload.** Editing `mat.yaml` repacks the GPU uniform buffer on the next frame; visible immediately. **Properties that follow a named value.** `values:` binds a property to a named value of the entity wearing the material (`values.set(entity, name, v)`, the `topics/values` guide): `property: valueName`, or `property: { value: "name", scale: s, offset: o }`, and the property draws `value * scale + offset` on each entity holding the value, read on the draw. A boolean reads as 1 or 0, and a number fills every channel of a colour or vector property. The wearer's own value is read, else its nearest ancestor's, so a lamp mesh under a car lights from the car's `brake`; a wearer holding none draws the material's own value. A scalar, vector, colour or bool property binds (at most 32 per material); a texture slot does not. `asset.create("material", name, { values = { ... } })` and `renderer.material.create({ ..., values = { ... } }, key)` take the same map. ```yaml values: emissive_intensity: { value: "brake", scale: 3 } ``` 7. **Inspector.** `type.yaml` names `inspector: { type: "inspector.luau" }`, and `inspector.luau` declares the material's sections beside the generic ones: `shader` (the bound shader, swappable), `properties` (each shader field as its typed control) and `textures` (each texture slot as an asset chip). They read the material through `mat:getShaderRef()` (the bound shader's ref, `~` expanded) and `mat:getTextures()` (slot name → `{ ref, name }`: the bound texture's guid and the id the material names it by). An edit there is an authoring write: `mat:writeProperty(name, value)` and `mat:writeTexture(slot, texture)` write the value into `mat.yaml` (and drop the session's own value for it, so the material reads what the file holds), and `setShader` rewrites the file; inside an undo operation each file write is recorded, so undo puts `mat.yaml` back. `setProperty` / `setTexture` stay runtime writes that last until the next mode change. ## Discovery - `asset.list("material")` — every registered material. - `asset.inspect("<name>")` — shader binding, property values, source path, this type README. - `ls /zero/source/<Name>.material` lists the files the folder holds. - `asset.resolve("<name>"):getProperties()` — the property fields exposed by the bound shader, each at the value it currently holds: what `mat.yaml` authored until something writes to the material, and the written value from then on, whichever call wrote it. That is the value the surface is drawn with. Read them back rather than guessing names; which fields exist comes from the shader. - `asset.resolve("<name>"):getDefinition()` — the authored `mat.yaml` bytes, the value the material rests at. - `asset.resolve("<name>"):getShader()` — the shader the material binds. ## Authoring conventions - Use lowercase, descriptive names (`brushed_steel`, `red_glow`, `tarmac_wet`). Avoid shader-name suffixes in the material name — the binding lives in `mat.yaml::shader`. - Drive every property the shader exposes; defaults are a fallback, not a contract for which fields exist. - Embed textures alongside the material (`textures/` subfolder) when they're used only by this material; reference shared textures from `@builtin::textures.*` or a library. ## Common pitfalls - **Property names must match the shader's uniform struct exactly** (case-sensitive). Misnamed properties silently get the shader's default. - **`base_color_texture` multiplies `base_color`.** A `color:` texture holding the same value as `base_color` multiplies the colour by its own sRGB-decoded value, so the surface renders far darker than the value written. Write a solid colour as `base_color` alone. - **Broken shaders break the material.** A material whose shader has a parse error renders as the magenta checkerboard. Inspect the shader first if the material looks wrong. - **`setProperty` targets the material, not the entity.** Changes affect every entity that references the material. - **`setProperty` is a runtime change.** It reaches the GPU, not the file: call `saveDefinition` to write the current values into `mat.yaml`. For a per-entity override that no other entity sees, give the entity its own copy with `Model:applySessionMaterial(renderer.material.create(...))`. - **Renaming the folder changes the identity.** A `Model` component or other reference to the material is recorded against the material itself, so renaming or moving it does not break them. ## Related types - `.shader` — defines what properties exist; required before a material can bind to it. - `.preset` — captures a component configuration; conceptually similar to a material, but for components instead of shaders.
▲ 0↑ born
·
assettype · born here
❒asset
# assetType (asset type) An asset type says what a kind of asset is: the files an asset of the kind is made of, the code that gives it behaviour, the interface a person uses to work with it, and how it is found, pictured and checked. A `<typename>.assetType/` folder declares a type called `<typename>`, and every `<name>.<typename>/` folder is an asset of it. `assetType` is itself a type, so a type is an asset like any other: it is created, versioned, installed and contributed the same way. ## Making a type `asset.create("assetType", "<typename>")` scaffolds a type. The type registers the moment its folder is written, anywhere under `/zero/source/`, and from then on `<name>.<typename>/` folders are its assets. An asset of a type that is not registered yet is not an asset, so make the type first. A type folder is a root: `~.x` in any file inside it names the type's own `x`, wherever the type is installed. Keep the type's whole implementation inside its folder and reach it that way. What a type folder must hold is set by this type's own `type.yaml`, the same way every type's `type.yaml` sets what its assets hold. `asset.validate` on a type reports anything missing, and the scaffold produces a folder that passes. ## What sets your type's schema (`type.yaml`) `type.yaml` is the structural contract every asset of the type is checked against. The keys below are the ones the engine reads; a key not listed here is ignored. | Key | What it controls | |---|---| | `suffix` | The folder suffix of the type's assets. Defaults to `.<typename>`. | | `primary` | The file or files that are the asset's content: what the asset resolves to when it is used. | | `entry_files`, `primary_aliases` | Further files that load as the asset or share its identity. | | `is_container` | Whether the suffix stays in the identities of what the asset holds. | | `is_opaque_walker` | Whether a walk of the tree stops at the asset and registers only its primary. | | `plural_dir`, `classify_exts` | Loose files in a folder of this name, or with these extensions, are assets of the type. | | `is_text_default` | Whether the asset's files are text unless stated otherwise. | | `broadcasts_subassets` | Whether assets nested inside an asset of the type are found by their own short name. | | `root` | `true` makes every asset of the type a root, so `~.x` inside one names that asset's own `x`. | | `contract_ref: { field, category }` | A key of the primary file that names another asset the asset is built on. | | `files: { required, optional }` | The files an asset holds (below). | | `allow_unlisted` | `false` reports every file the type does not declare. | | `aliases_from: [{ file, key }]` | Further names an asset answers to, read from its own files. | | `settings:` | Typed per-asset settings (below). | | `inspector:` | The interface people use for the type and its assets (below). | | `preview:` | How an asset is pictured (below). | | `references:` | Names of other assets the type's files carry (below). | | `indexing:` | What search reads for each asset (below). | | `describe:` | How a missing description is generated (below). | ### The files an asset holds Each entry under `files.required` or `files.optional` is `{ path, kind: file | folder, one_of_group?, content? }`. `*` in a path matches within one segment. Entries that share a `one_of_group` are satisfied by any one of them. `content` lists checks on the file's bytes: | Check | Passes when | |---|---| | `non_empty` | the file has content | | `json_field { key, type?, non_empty?, accept? }` | the JSON holds the key (a dotted path) with that shape | | `yaml_field { key, type?, non_empty?, accept? }` | the same for YAML | | `described { keys?, headings?, message? }` | the file says what the asset is (see "Ask your assets to say what they are") | Each check takes a `message`, which is what the author is told when it fails. ### Settings `settings: { values, schema: { type | instance, export? } }` gives every asset typed settings. `values` names the file an asset's values live in; `schema.type` declares one schema for the whole type, and `schema.instance` names a file each asset declares its own in. `asset.create` writes the resolved values, and a write to the values file reaches `onChange` with what changed. ## The human side (`inspector.luau`) A type is used by people through its Inspector, and without one the type is usable only from code. The Inspector is the type's interface for a person: for a procedural graph it is the graph editor, for a kit it is the tracking view of what the kit holds and what is still missing. Writing it is part of writing the type. `inspector: { type, instance? }` in `type.yaml` names the files. `type` is the interface for the type itself and for its assets; `instance` names a file an asset may ship to add its own. Each returns: ```luau return { sections = { { id = "graph", title = "Graph", build = function(ctx) ... end } }, replace = { contents = { ... } }, -- replace a default section by id order = { "graph", "contents" }, -- section order } ``` `build(ctx)` receives the asset and builds the section. A section's `title`, and the text its rows carry, is a string or an `i18n.text` value read from a catalog (`i18n.text("inspectors.mesh.title")`), which follows the editor's language. `asset.create("assetType", ...)` scaffolds a working `inspector.luau` to start from. `asset.validate` on a type that names no inspector, or names one that does not load, reports it. ## Say what your type is for (`about.yaml`) Every type carries an `about.yaml` that says what the type is for, in three plain-language texts: ```yaml intent: "Sets the typeface of the text in your game: UI, labels, signs and 3D lettering." function: "A font, from a TTF, OTF or WOFF file, made available to all of Zero's text, including 3D text." usage: "You choose it by name for your UI or your text, and the text appears in that typeface." ``` - **`intent`** is what the type is for in someone's game, in the words a game maker uses. Up to 800 bytes. - **`function`** is how it works today: what an asset of it is made of and what the engine does with it. Up to 1500 bytes. - **`usage`** is what a person or an agent does with one. Up to 1200 bytes. Write about the type as a whole, not one asset of it, and say what it does now. Agents read these texts to learn when to reach for the type and how; people searching find the type by them. The scaffold starts each text with `[[describe]]` and a note on what to write; a text that still starts that way counts as not written. `services describe` can write them. They show up in `asset.inspect` as `detail.about`, in `assetTypeRef:getAbout()`, at the end of the type's `types/<typename>` guide, and at the top of the type's Inspector. ## Ask your assets to say what they are A type can require each asset to carry a description: a file, written by the author or generated, saying what the asset is and what it is for. Declare it with a `described` check: ```yaml files: required: - path: "README.md" kind: "file" content: - { check: "described", message: "Say what this widget is for and where it goes." } ``` A file that is missing, empty or still has a line starting with `[[describe]]` fails the check, and so does a YAML file whose named `keys` are missing or over their `max_bytes`, or a Markdown file missing a named heading. `asset.validate` names the asset, and a push that carries it is refused with `message`. `services describe` finds such assets and writes their descriptions. `describe:` steers what is generated: ```yaml describe: guidance: "Say what the widget shows, what input it reacts to, and where it fits in a UI." examples: - "<identity of an asset of this type whose description reads well>" ``` An example is an asset of your type whose description is a true, written one, never a placeholder and never the asset being described; with none, leave `examples` empty. A type whose assets the model cannot perceive (a sound, a motion) says so in `guidance`, and the description is drawn only from what the asset's own files state. Start the file unwritten in your `template/`: a heading and one line starting with `[[describe]]`, never example content, which every new asset would carry verbatim. A type whose assets say what they are through their own content (a mesh, a texture) declares no check. ## The type's code (`behavior.luau`) `behavior.luau` returns one table. These are the keys the engine reads from it; anything else on the table is the type's own. ### What the type's assets can do | Key | Shape | What the engine does with it | |---|---|---| | `ref` | `{ [name] = function(self, ...) }` | Every function becomes a method on every asset of the type: `ref:name(...)`. | | `modules` | `{ [name] = require(".x") }` | Code the type's assets reach with `asset.containing(__FILE__).modules.<name>`. | | `events` | an events schema | Events an asset fires. Readers subscribe through `ref.events.<name>:connect(...)`; the type fires them. | | `refShapes` | `{ [method] = function(self) -> (typeExpr, source?) }` | The result type of a `ref` method for one particular asset (below). | | `namePattern` | a Lua pattern | The names `asset.create` accepts for the type's assets. Default `^[A-Za-z][A-Za-z0-9_]*$`. | | `derive` | `{ output, module, compute, fingerprint, matches?, required?, timeout? }` | A file computed from the asset when it is committed; a `required` one holds the commit until it lands. | Some `ref` names mean the same for every type, and the engine calls them: - **`instantiate(self, target?, opts?) -> (root, idMap)`**: puts the asset in a scene. Defining it is what makes the type scene-instantiable. Its return is a contract (below). - **`inspect(self) -> detail`**: what `asset.inspect` reports for the asset beyond the common record (below). - **`preview(self, opts)`**: renders the asset's picture; it wins over the type's `preview:` recipe. - **`previewMaterial(self) -> { material }`**: the material a `surface` preview paints. - **`saveDefinition(self)`**: writes the asset's in-memory edits back to its files in edit mode. Some names are answered for every asset before the type is asked, so a `ref` entry of the same name is never reached: `getSource`, `getBytes`, `getText`, `exists`, `deps`, `canInstantiate`, `canPreview`, `preview` (which calls yours when you define one), `meta`, `runtime`, `events`, `typeRef`, `modules`, and the residency flags `has_backing_asset`, `has_runtime_changes`, `cpu_resident`, `gpu_resident`. ### When the engine calls the type | Hook | Signature | When it runs | |---|---|---| | `onCreate` | `(name, opts) -> { [path] = contents }` | On `asset.create`. Returns the files of the new asset, laid over the type's `template/`. Annotate `opts`: its type is the schema `asset.create` checks the caller's arguments against. A `""` key writes a single loose file. | | `onReplace` | `(dest, files) -> files` | On an `asset.create` over an asset already at `dest`, after `onCreate`, so what the author added can be carried into the replacement. | | `onRegister` | `(self)` | Once per asset, when it first registers: when the world loads, on a live `asset.create`, and when an asset arrives later (installed, pulled, synced). This is what makes an asset take effect the moment it is written. | | `onChange` | `(ref, change)` | On every write to a file inside an asset of the type. `change` is `{ path, asset, type, kind, origin }`, plus `settings` and `settingsChanged` for a write to the settings values file; `kind` is `edited` or `seeded`, `origin` is `local` or `remote`. Filter on `change.path`. Writes to one asset arrive in order, each after the hook for the one before has finished, and the hook may wait on what it reads. A write the hook makes inside its own asset arrives later like any other, so keep the hook convergent. | | `onDependencyChange` | `(ref, change)` | When a module the asset's code requires is re-run, or a name the asset carries starts resolving. `change.kind` is `dependency`. | | `onDelete` | `(ref)` | When an asset of the type leaves the world: deleted, or the world it is in is swapped away. | | `validate` | `(ref) -> { { code, message, severity?, path? } }` | On `asset.validate`, after the `type.yaml` checks, for the type's own rules. `severity` defaults to `error`. Runs on every push, so a type's rules hold at publish. A hook that fails reports `validate.hook_failed`. | ### Settings hooks | Hook | When it runs | |---|---| | `settingsDefaults(name, opts, asked) -> table` | Once per `asset.create`, for values the schema's defaults do not give. | | `settingsCorrections(values, name, opts) -> (corrections?, reasons?)` | On every settings write. A correction to a field the writer named refuses the write, giving the reason. | | `settingsDerivedDefaults(values, explicit, changed)` | On a settings write, for fields derived from others. | | `normalizeSettings(values, stored?)` | On every read and write, to map an earlier spelling of a field to the current one. | | `settingsHealed(values, stored)` | On a read, to repair stored values. | | `settingsSchemaProblem(schema, ref) -> string?` | When an asset's own schema is read; a returned string refuses the schema. | `creationInputs` (`{ [opt] = true | selectorOpt }`) names `asset.create` options that are inputs to the type rather than settings. ### Reloading An edit to `behavior.luau` reaches existing assets with no restart. ## How an asset is pictured (`preview:`) | `kind` | The picture is | The type provides | |---|---|---| | `instantiate` | the asset placed in the preview studio through its `instantiate` | `ref.instantiate` | | `image` | a file the asset holds, fitted to the frame | `source: { files }`, the candidate files in order | | `surface` | the asset painted on a mesh | `mesh`, and `ref.previewMaterial` | | `custom` | whatever `ref.preview` returns | `ref.preview` | ```yaml preview: kind: surface mesh: sphere ``` `angle: [yaw, pitch]` turns the camera. The studio owns the light, the backdrop and the framing, so an asset pictures the same in every world. A type with no `preview:` that defines `instantiate` still answers `ref:preview()`. A picture is rendered when something asks to view it (the editor showing the asset, `ref:preview()`), when previews are generated on request (`assets.generatePreviews`), and when the asset is staged. An edit alone renders nothing. The picture records what it was made from, so a stale one is told from a current one. ## The names your type's assets hold (`references:`) Where your type's own format or API carries the name of another asset, declare it here: ```yaml references: keys: # a top-level key of the type's files that holds a name, or a table of them - { key: "shader", type: "shader" } args: # an argument of a call, counting from 1 - { call: "g:node", position: 2, type: "procNode" } fields: # a field of the options table a call takes - { call: "fx.beam", field: "material", type: "material" } ``` `type` is the category the name resolves in. `asset.declareReferenceKey`, `asset.declareReferenceArg` and `asset.declareReferenceField` declare the same from a script. ## What search reads (`indexing:`) `indexing:` is how assets are found. Search reaches an asset only through what its type's `indexing:` names, and adds nothing of its own. That includes you: an asset indexed badly is one you cannot find later, when you are making something else and need it. A type whose assets are never looked for says `indexing: none`. ```yaml indexing: data: # text, read from the asset's files - role: identity extractor: verbatim source: { file: "README.md" } - role: interface extractor: symbols source: { files: ["init.luau"] } - role: implementation extractor: verbatim source: { files: ["init.luau"] } content: # the picture - role: identity modality: image source: { file: "preview.png" } facets: # what a query filters and re-ranks by file: ".metadata" rigged: { type: bool, from: { components: { contains: SkinnedModel } } } roughness: { type: number, filter: range, from: { file: "mat.yaml", field: "floats.roughness" } } ``` **Roles.** Each `data` and `content` entry has a `role`, and a query matches in two slots: - **`identity`**: what an asset is. For anything you look at, the picture; for anything else, the text that says what it is. - **`capability`**: what it does and how it is made. `interface` (the signatures or shape a caller uses) and `implementation` (the body) both count as capability, and a type with code usually declares both. Ask what a person would recognise an asset of the type by, and what it does, and point each role at the file that says it. For text, that is the asset's description: the file your template starts with a `[[describe]]` block, which the author writes or `services describe` fills in (see "Ask your assets to say what they are"). **`data`.** `extractor: verbatim` embeds a file's text as it is; `symbols` embeds the declared signatures of code. `source` is `{ file }` or `{ files: [...] }`. Never index a file name (`source: { field: name }`): one or two words carry nothing to match. **`content`.** `modality: image` embeds the picture itself, so a text query matches what the asset looks like. A type whose assets are looked at makes the picture its identity. **`facets`.** What a query narrows and re-ranks the matches by. `file` is embedded whole, so keys nobody declared in it are still found. Each further key is computed for every asset and states a value for every one, including `false`: a file can imply "not rigged" but never say it, and a query separates rigged from unrigged only because the unrigged ones say `rigged: false`. A key is `{ type: bool | number | enum, filter?: range, from }`, where `from` is `{ file, field }` (a field of one of the asset's files, dotted for nesting), `{ metadata: key }`, or `{ components: { contains | any_outside } }` (what the asset's entities carry). ## What blocks a push A push checks every asset it carries against its type. These refuse it: - a required file that is missing, a `content` check that fails, a `described` file not written yet; - an error from the type's `validate`. Unlisted files and warnings do not. A `described` file blocks only a push that changes the asset. When a push is refused, the message names each asset and what it lacks. `world.publishBlockers()` and `zm status` read the same list without pushing. ## Typing a result from the asset (`refShapes`) A `ref` method whose result depends on the asset (one entry per child folder, per row of a config, per control a map declares) can only be annotated as `{ [string]: Thing }`, which accepts any key. `refShapes` states the result for each asset instead: a function returning a Luau type expression for that asset, and the module whose types the expression uses. Read the asset; never run it. ```lua -- inputMap.assetType/behavior.luau M.refShapes = { activate = function(self): (string, string) local names = {} for _, control in ipairs(M.ref.controls(self)) do table.insert(names, control.name .. ": Handle") end if #names == 0 then return "", "" end return "{ " .. table.concat(names, ", ") .. " }", "@builtin::modules.zinput.scheme" end, } ``` With it, `map.jump:onPressed(fn)` is checked and `map.noexisting` is reported. A per-asset type applies where the call site names which asset: a component field whose default names it, or an annotation `AssetRef<"inputMap", "<identity>">`. `asset.resolve(name, category)` carries only the category, and a name computed at runtime carries nothing, so calls on those keep the declared return. The type belongs to the call's result: index it there, or bind what you need from it there, and the names stay checked. `require("@builtin::assetTypes.assetType.shared.refShapes").published()` shows what was published: `categories` (each type's method surface) and `returns` (per-asset results by identity, then method). An identity missing from `returns` was never published. Results are recomputed when an asset is written; at most 64 assets of one type are read. ## Putting an asset in a scene (`ref.instantiate`) A caller writes one piece of code against every instantiable type, so what `instantiate` returns is fixed: ```lua local Instantiable = require("@builtin::assetTypes.assetType.shared.instantiable") M.ref = { instantiate = function(self, target, opts) local root = Instantiable.root(self, target, opts) -- compose the asset under `root`, now return Instantiable.result(self, root, idMap) end, } ``` **In.** `target` is the entity the asset lands under, or onto for a hierarchy type; with none, the type spawns a new root. `position`, `rotation` (three numbers in degrees, or a quaternion), `scale`, `name` and `temporary` mean the same for every type: `Instantiable.root` applies them to a root you make, `Instantiable.place` to one you adopt. Document any options of your own in the hook's `--!arg` docs. **Out.** `(root, idMap)`. `root` is the composed root, live when you return: build synchronously, never defer to a component's `awake`. `idMap` maps each original id to the spawned one, so a component that composes the asset again on every load can pass it back in and keep references into the composition. Every call goes through `Instantiable.result`, which refuses a root that is not live and turns a missing `idMap` into `{}`. ## Inspecting an asset (`ref.inspect`) `asset.inspect(ref)` builds a record every asset shares (`identity`, `name`, `guid`, `source`, `typeName`, `typeDefinitionPath`, `scope`, `origin`, `description`, `tags`), then calls `ref.inspect(self)` for the type's own `detail`: ```lua M.ref = { inspect = function(self) -- read the asset's own files, never runtime state: inspect works on an asset -- that has not been compiled, uploaded or registered return { --[[ what makes this asset what it is ]] } end, } ``` Without it, the record is the shared part alone, and an agent inspecting the asset learns nothing of what it is. A hook that raises leaves `detail` empty and sets `record.warning`. ## Discovery - `asset.list("assetType")`: every registered type. - `asset.inspect("<typename>")`: the type, its README and its `about.yaml` texts. - `asset.resolve("<typename>", "assetType")`: the type itself.
▲ 0↑ born
▣
module · born here
❒asset
# material_remap Canonical property/texture-role dictionary used when a material **swaps shaders**. The new shader exposes a different vocabulary than the old one — one shader's `MAIN_TEX` is another's `albedo` is a third's `base_color_texture` — so values would be lost on a naive swap. This module maps any known alias onto a canonical **role** so floats, colors, and texture links carry across the swap to the best of our ability. Consumed by `material.assetType`'s `setShader` ref method (and, transitively, by the `appearance` toolbox's `swapShader`). ## API ```luau local remap = require("modules.material_remap") remap.propertyRole("MAIN_COLOR") -- "base_color" (scalar/color side) remap.textureRole("MAIN_TEX") -- "base_color_texture" (texture side) -- Remap current property values onto the new shader's accepted names. local mapped, carried, dropped = remap.remapProperties(currentProps, shaderRef:getProperties()) -- Canonicalize texture slot names so links bind on the new shader. local texMapped, texCarried = remap.canonicalizeTextures(currentTextures) ``` ## Why two tables `albedo` as a **color** is the base-color factor; `albedo` as a **texture** is the base-color map. `mat.yaml` keeps `colors:` / `floats:` separate from `textures:`, so the caller always knows which side it's remapping. Splitting `PROPERTY_ROLES` from `TEXTURE_ROLES` removes the ambiguity instead of guessing from the value shape. ## Property remap vs texture remap - **Properties** are remapped against the target shader's *real* reflected field names (`shaderRef:getProperties()`, naga reflection). Direct name match wins; otherwise role-to-role. Properties the new shader doesn't expose are dropped. - **Textures** are canonicalized to the engine's builtin on-disk slot convention (`base_color_texture`, `normal_texture`, …) because the engine does not yet surface a target shader's reflected texture-slot list to Luau. Unknown slots pass through unchanged. The alias lists are deliberately broad (glTF / Unity / Unreal / Godot / hand-rolled WGSL conventions). Add new aliases here rather than special-casing a shader at a call site.
▲ 0↑ born
▣
module · born here
❒asset
# material_utils High-level wrappers around the `__material` FFI global. Convenience helpers for the common material-authoring operations: create a named material, apply it to an entity, query / set material properties, and bind textures. Exposed as the `Material` Luau global via `--!global` (auto-injected by the prelude). Material lives ON the Model / SkinnedModel component — there is no standalone `Material` component, because a material only renders where there is a mesh. To apply a material, use `Material.apply()` (which errors if the entity has no model) or set the model's `material` field directly: `entity(id).component.add("Model", { model = "cube", material = "gold" })`. PascalCase aliases (`Material.Create`, `Material.Apply`, etc.) are kept for back-compat with the wider codebase — 88+ call sites across demos, scenes, components, guides, and the engine test suite use the legacy names. The lowercase forms are canonical. ## Exports Canonical (lowercase) surface: - `Material.create(name: string, opts: MaterialOpts?) -> MaterialRef?` — register a named material; returns the AssetRef envelope. - `Material.apply(entityId: string, materialRef: MaterialRefOrName) -> boolean` — set the `material` field on the entity's Model / SkinnedModel. Errors if neither is present. - `Material.exists(name: MaterialRefOrName) -> boolean` — registry predicate. - `Material.getPropertyNames(name: MaterialRefOrName) -> { string }?` — list property names exposed by a material. - `Material.getProperty(name: MaterialRefOrName, prop: string) -> any` — read a property value. - `Material.setProperty(entityId: string, property: string, value: any)` — set a property on the material assigned to an entity's Model / SkinnedModel. - `Material.setTexture(name: MaterialRefOrName, slot: string, textureRef: string) -> boolean` — bind a texture slot. PascalCase back-compat aliases: - `Material.Create(name, opts_or_shader, props?) -> MaterialRef?` — accepts the legacy `(name, shaderString, opts)` 3-arg form OR the canonical `(name, opts)` form. - `Material.Apply` / `Material.Exists` / `Material.GetPropertyNames` / `Material.GetProperty` / `Material.SetTexture` — direct aliases for the lowercase counterparts. - `Material.SetProperty(materialName, property, value)` — writes to the REGISTERED material by name (NOT on a component). Different from lowercase `setProperty`. Types: - `Color = { number } | { r: number, g: number, b: number, a?: number }` - `Textures = { [string]: string }` - `MaterialOpts = { shader?, color?, roughness?, metallic?, emissive?, textures?, [string]: any }` - `MaterialRef = { __ref?, type?, name?, guid? }` - `MaterialRefOrName = MaterialRef | string` ## Usage ```luau local mat = Material.create("gold", { color = { 1, 0.85, 0.2 }, metallic = 1, roughness = 0.15, }) -- entityId must already carry a Model / SkinnedModel (a material only -- renders on a mesh); apply errors otherwise. Material.apply(entityId, mat) -- AssetRef envelope Material.apply(entityId, "gold") -- bare name also works Material.setProperty(entityId, "roughness", 0.3) Material.setTexture("gold", "albedo", "@builtin::textures.gold") ``` ## Notes - `Material.apply` accepts either an AssetRef envelope or a bare name — the model's `material` field auto-wraps strings. - Material is a field on the Model / SkinnedModel component (declared as `material`, an `AssetRef<material>`). There is no standalone Material component — `apply` / `setProperty` route to whichever model is present and error when neither is. - `Material.setProperty` writes the property on the material assigned to the entity's model; `Material.SetProperty` writes on the REGISTERED material by name. They behave differently — keep them straight. - All argument validation raises on bad input rather than silently no-oping, so call sites surface mistakes early.
▲ 0↑ born
▣
module · born here
❒asset
# yaml.module YAML decode + encode for authored engine content. Pure Luau, no engine dependencies — a general parsing library, not data-system plumbing. ```luau local Yaml = require("@builtin::modules.yaml") local doc = Yaml.decode(vfs.read(path)) vfs.write(path, Yaml.encode(doc)) ``` ## Supported subset - Block mappings (`key: value`) and block sequences (`- item`), nested to any depth. - Compact sequence-of-mapping entries (`- path: x` / ` kind: y`). - Flow collections — `{ a: 1, b: 2 }` and `[1, 2, 3]` — single line. - Plain scalars with type inference: `~` / `null` → nil, `true` / `false` → boolean, numeric literals → number, everything else → string. - Single- and double-quoted strings (`''` escapes a literal quote inside a single-quoted string; `\n` `\t` `\r` `\\` `\"` inside a double-quoted one). A quote opens a quoted scalar where a scalar begins — after `key:`, after a `- ` entry marker, or inside a flow collection — so a plain scalar carries an apostrophe as data (`note: the world's rules`). Quoted keys are read in flow mappings. - `#` comments — honored outside quotes, so a `#` inside a quoted string is kept as data. - Literal (`|`) and folded (`>`) block scalars, with a chomping indicator (`-` strips the final newline, `+` keeps every trailing blank line, none keeps one newline) and an indentation indicator (`1`-`9`: the content's indent past the parent's), in either order (`|-`, `>+`, `|2`, `>1-`). A block scalar's content is literal text: quotes (balanced or not), `#`, `key: value` and `---` inside it are data. - An optional leading `---` document marker. ## Loud-error contract Constructs outside the subset above raise instead of misparsing: anchors/aliases (`&`, `*`), tags (`!`), directives (`%`), multi-document streams (a second `---`), a block-scalar header it cannot read (`|x`, `|-+`, `|0`), tab indentation, and inconsistent indentation (both block structure and block-scalar bodies). Every error carries the offending line number (`yaml: line N: ...`), so a bad config points straight at the line to fix. Tab indentation is rejected everywhere — including block-scalar body lines whose leading whitespace contains a tab. A tab after the first non-space character of a line is content and passes through. ## API - `Yaml.decode(text: string): any` — decode a YAML document into a Luau value (table, scalar, or nil for an empty document). Raises on malformed input or an unsupported construct. - `Yaml.decodeWithComments(text: string): (any, boolean)` — decode as `decode` does, and report whether the text carries a comment by the decoder's own rule: a `#` at a line's start or after whitespace, outside a quoted scalar and outside a block scalar. Re-encoding the value drops such comments, so an editor that writes a document back reads this first. - `Yaml.encode(value: table): string` — encode a Luau table as YAML (block style, two-space indent, alphabetically sorted keys). Raises on values YAML can't represent (functions, userdata, non-string mapping keys). A top-level empty table encodes to an empty document, which decodes back to `nil` (the YAML empty-document ambiguity).
▲ 0↑ born
▣
module · born here
❒asset
# material_records The material GPU records this session has released and nothing has filed again. A `.material` asset files its GPU record at its point of use — `matRef:handle()` — and memoises the handle it filed on the ref's runtime, so a second bind of the same material costs a table read where the first cost a parse and an upload. That memo names a record the renderer's registry holds, and `renderer.material.destroy` takes the record away while the asset and its memo stand. The asset is what files the next record, so it has to know which names that applies to. This set is that knowledge: a release puts the key in, filing a record under the key takes it out, and the point of use reads it for the cost of one table index. Written by `renderer.material.destroy` and `renderer.material.create`; read by the `.material` assetType's `handle()`. ## API ```luau local MaterialRecords = require("modules.material_records") -- A point of use holding a memo asks whether the record it names still stands. if MaterialRecords.released[identity] ~= nil then -- The record is gone: file another one, which takes the mark off. end MaterialRecords.noteReleased(key) -- the record under `key` has been released MaterialRecords.noteFiled(key) -- a record stands under `key` again ``` ## Lifetime The set lives in the session store, so it holds for as long as the GPU records it answers for: a VM reload leaves those records standing and leaves this standing with them, and both die with the engine process.
▲ 0↑ born
▣
module · born here
❒asset
# material_schema A shader's declared property vocabulary, and the routing of an authored key onto it. A material's properties belong to its **shader**. The uniform buffer is packed by reflected field name, so a key the shader does not declare is never read by anything: it sits in the material's property table, reads back as though it applied, and contributes nothing to the render. This module is the single place that answers "is this key real, is it a texture slot, or is it neither" — so every path that accepts material properties gives the same answer. Consumed by `material.assetType` (the `.material` asset path) and by `renderer.material.create` (the runtime GPU path). ## API ```luau local schema = require("modules.material_schema") local s = schema.forShader("pbr") -- nil when the shader can't resolve schema.route(s, "base_color", {1,0,0,1}) -- "property", "base_color" schema.route(s, "color", {1,0,0,1}) -- "property", "base_color" (alias) schema.route(s, "base_color_texture", tex) -- "texture", "base_color_texture" schema.route(s, "baseColor", {1,0,0,1}) -- "unknown", "baseColor" schema.declaredNamesList(s) -- "alpha_cutoff, anisotropy, …" schema.undeclaredMessage(name, key, "pbr", s) schema.acceptsSlot(s, "base_color_texture") -- true: the shader declares the slot schema.acceptsSlot(s, "base_color") -- false: a property, not a texture slot schema.declaredSlotsList(s) -- "base_color_texture, emissive_texture, …" schema.undeclaredSlotMessage(name, slot, "pbr", s) schema.isTextureSlotType("texture") -- true schema.isTextureSlotType("texture_array") -- true schema.isTextureSlotType("color") -- false ``` A `properties.yaml` entry of type `texture` or `texture_array` declares a texture slot; every other type except `buffer` declares a property. A texture reaches the bind group only through a slot the shader declares, since the material interface is generated from those slots. `renderer.material.create`, `renderer.material.setTexture` and a material asset's `setTexture` / `writeTexture` refuse any other slot through `acceptsSlot` and report it with `undeclaredSlotMessage`. A schema that holds no names at all (a shader whose vocabulary has not been read yet) accepts every slot. ## Routing order `route` applies the alias table first, then decides by surface: 1. **Alias** — `color` → `base_color`, but only when the shader declares the canonical name and *not* the alias, so a shader that genuinely exposes `color` keeps its own meaning. 2. **Texture** — the schema declares the name as a texture slot, *or* the value is itself a texture (handle / `AssetRef<texture>`). A texture stored as a uniform property reads back via `getProperty` but never reaches the bind group, so the value's own shape decides regardless of the key. 3. **Property** — the schema declares the name as a uniform property. 4. **Unknown** — neither. Nothing reads it; the caller warns with `undeclaredMessage` and drops it. ## When the shader can't be resolved `forShader` returns `nil` for a shader that is not registered yet (a runtime shader still compiling, a name that resolves later). Callers stay permissive in that case rather than reject every key against an empty vocabulary — the check applies where the vocabulary is actually known.
▲ 0↑ born
·
procrecord · born here
❒asset
# material (procRecord) The material record kind: a surface shader, its property values by name, its texture slots by name and, optionally, render state (`blend`, `cull`, `depthWrite`) and a buffer property filled from elements. `material.pbrMat` and `material.shader` answer one, held on one element as `Material = { material = <record> }`. Live, a record becomes the runtime material the `Material` component's `material` field holds. Saved, it is a `.material` asset, and a Texture record in one of its slots is written as a texture beside it. `io.import` of a `.material` asset answers the same element, its record read from the asset.
▲ 0↑ born
▣
module · born here
❒asset
# texture_ref The GPU key a material's texture slot binds by, resolved from whatever form the author wrote it in. The renderer binds a texture slot by **exact GPU-cache key**, and that key is the guid an upload lands under. A reference in any other form — an asset identity (`wall.texture`), a bare name, a `.texture` path, the image path a texture was imported from — names a real texture the cache has never heard of. Bound as written it leaves the slot on the shader's declared fallback: white for a `base_color_texture`, black for a sky panorama. The material then renders as though nothing was bound, and nothing distinguishes that from a texture the author meant to be dark. This module is the single place that answers "what key does this reference bind by", so the same string binds the same texture wherever it is written. Consumed by `material.assetType` (the `.material` asset path), `renderer.material.create`, and `renderer.material.setTexture`. ## API ```luau local TextureRef = require("modules.texture_ref") TextureRef.resolve("wall.texture") -- "9f2c…", "asset" TextureRef.resolve("9f2c…") -- "9f2c…", "asset" (idempotent) TextureRef.resolve("/source/sky/pano.png") -- "f181…", "asset" (→ pano.texture) TextureRef.resolve("color:1,0,0,1") -- unchanged, "procedural" TextureRef.resolve("video_0") -- unchanged, "live" TextureRef.resolve("nothing_here") -- unchanged, "unresolved" TextureRef.isProcedural("default:white") -- true TextureRef.unresolvedMessage(ref, "renderer.material.setTexture") ``` `resolve` also **materialises** the texture (Disk→CPU→GPU via `texRef:handle()`) — the guid only becomes a cache key once the upload has landed. ## Resolution order 1. **Procedural** — `color:` / `default:` / `runtime:`. The GPU texture cache produces these itself, so they pass through untouched. 2. **The reference itself** — a guid, an asset identity, a bare name, or a `.texture` path, resolved through `asset.resolve(ref, "texture")`. 3. **The imported container** — when the reference is a loose raster path (`png` / `jpg` / `jpeg` / `webp`), the sibling `<stem>.texture` the texture importer promotes it into. The importer *removes* the loose original, so the path an author copied out of an import log names a file that no longer exists; this step follows the image to where its texture actually went. 4. **The alternate identity** — a slot's stable identity, passed by the `.material` path so a binding whose guid was orphaned by a delete + recreate still finds the texture the author named. 5. **A resident GPU key** — a live texture with no asset behind it: a video frame (`video_0`), a rasterised text texture, a render target. Binds exactly as written. Anything left is `"unresolved"`. The reference is still returned unchanged — a texture that lands later is picked up by the renderer's own pending retry — but the caller has the outcome and reports it with `unresolvedMessage` instead of letting the slot fall back in silence.
▲ 0↑ born
✦
shader · born here
❒asset
# pbr The engine's standard physically-based material — the full glTF metallic-roughness workflow lit by the shared `@builtin::shaderModules.pbr_shading` model. This is the default surface shader a model uses when its material doesn't specify another, and it is also registered under the legacy alias **`standard`** (the name many materials reference). It is a `surface()` shader: it fills a `PbrSurface` and the engine generates every pipeline entry point and lights it. Every parameter defaults to a neutral value, so a material that sets nothing renders as a clean dielectric; the advanced lobes only cost anything when a material opts into them. ## Properties | Property | Type | Default | Meaning | |---|---|---|---| | `base_color` | color | `[1,1,1,1]` | Albedo tint, multiplied by `base_color_texture` and vertex colour. | | `emissive` | color | `[0,0,0,1]` | Emissive tint, multiplied by `emissive_texture` and `emissive_intensity`. | | `emissive_intensity` | float | `1.0` | HDR multiplier on the emissive output. | | `roughness` | range | `0.5` | Perceptual roughness, multiplied by the green channel of `roughness_metallic_texture`. | | `metallic` | range | `0.0` | Metalness, multiplied by the blue channel of `roughness_metallic_texture`. | | `reflectance` | range | `0.5` | Dielectric reflectance knob (neutral 0.5 → 4% F0). | | `ior` | float | `1.5` | Index of refraction → dielectric F0 and the refraction direction. | | `normal_scale` | float | `1.0` | Strength of the tangent-space `normal_texture`. | | `occlusion_strength` | range | `1.0` | Blend of the `occlusion_texture` (R) into the ambient term. | | `clearcoat` | range | `0.0` | Strength of a second dielectric clearcoat specular lobe. | | `clearcoat_roughness` | range | `0.0` | Roughness of the clearcoat lobe. | | `anisotropy` | float | `0.0` | Anisotropic highlight stretch along the tangent ([-1,1]). | | `sheen_color` | color | `[0,0,0,1]` | Tint of the sheen lobe — the retroreflective rim of velvet, satin and brushed fabric. Black leaves the base untouched. | | `sheen_roughness` | range | `0.3` | Width of the sheen lobe. | | `iridescence` | range | `0.0` | Blend toward the thin-film response, the hue that shifts with view angle. | | `iridescence_thickness` | float | `400.0` | Film thickness in nanometres — which wavelengths cancel and which reinforce. | | `iridescence_ior` | float | `1.3` | Index of refraction of the film. | | `subsurface_color` | color | `[0,0,0,1]` | Tint of the light that entered the surface, scattered beneath it and left again. Black leaves the base untouched. | | `subsurface_radius` | float | `0.5` | How far the diffuse falloff wraps past the terminator, taken per channel against `subsurface_color`. | | `fibre_color` | color | `[0,0,0,1]` | Tint of the second of the two highlights a hair or fur strand gives. Black leaves the base untouched. | | `fibre_specular` | range | `0.35` | Strength of the first strand highlight, in the light's own colour. | | `fibre_shift` | float | `0.06` | How far apart the two strand highlights sit along the fibre. | | `fibre_roughness` | range | `0.1` | Width of the first strand highlight. | | `transmission` | range | `0.0` | Specular transmission — refracts the environment through the surface. | | `thickness` | float | `0.0` | Volume thickness for Beer–Lambert transmission absorption. | | `attenuation_color` | color | `[1,1,1,1]` | Transmission absorption tint. | | `attenuation_distance` | float | large | Beer–Lambert absorption distance. | | `uv_scale` | float2 | `[1,1]` | UV tiling applied before every texture sample. | | `uv_offset` | float2 | `[0,0]` | UV offset applied before every texture sample. | | `alpha_cutoff` | range | `0.0` | Mask threshold — fragments with `alpha <` this are discarded (0 = no cutoff). | | `double_sided` | bool | `false` | Flip the shading normal on back faces. | | `receives_fog` | bool | `true` | Whether the screen-space fog passes (height fog, aerial perspective) reach this surface. `false` leaves an opaque deferred draw at the colour it shaded to, however deep in the medium it stands — see below. | | `instance_color_lane` | float | `-1` | Which of the instance's four shader-data lanes colours it (rgb colour, a coverage). `-1` reads none. See below. | | `instance_emission` | float | `0` | How brightly the lane colour glows where it covers. | ### Emissive authoring The glow output is `emissive × emissive_intensity` (× the `emissive_texture`). The glow **colour** is `emissive`, a vec; the **intensity** over it is `emissive_intensity`, a scalar. So `{ emissive = {0.1, 0.9, 1, 1}, emissive_intensity = 5 }` is a cyan glow at 5×, and it is these two names that `getProperties()` lists and `setProperty` writes. A spelling another engine's convention uses for the same role — `emissive_color`, `emission`, `emissive_tint` — is resolved onto `emissive` when the material is authored, so content carried in from glTF, Unity or Godot reaches the property under the name this shader declares. Where two such spellings meet on one of the two names, the shape of each value says which of them it is: a vec is the colour and a number is the intensity, so `{ emissive_color = {0.2, 0.8, 1, 1}, emissive = 5 }` is the same cyan glow at 5x. Two values of one shape are one property's, and the one written under the name the shader declares applies while the other is named in a warning. A bare positive scalar `emissive` with no colour beside it is the "turn emission on" shorthand and means a white glow at that intensity, so `emissive = 20` on a white material lights up. ### The lobes over the base layer Beyond metallic-roughness, the shading model carries six layers this material declares. Each is gated on its own neutral value, so a material that sets none of them shades as a plain dielectric and each one costs only where it is asked for. | Layer | Turned on by | What it looks like | |---|---|---| | Clearcoat | `clearcoat > 0` | A second dielectric specular lobe on top — car paint, lacquer, a varnished surface. | | Anisotropy | `anisotropy ~= 0` | The highlight stretches along the tangent — brushed metal, a vinyl record. | | Sheen | `sheen_color` above black | A retroreflective rim that brightens toward grazing angles — velvet, satin, dusty cloth. | | Iridescence | `iridescence > 0` | The specular hue shifts with view angle — an oil slick, a soap film, anodised metal, a beetle shell. Thickness picks the colours. | | Subsurface | `subsurface_color` above black | Light wraps past the terminator and glows through thin geometry lit from behind — skin, wax, marble, a leaf. `thickness` gates how much reaches the far side. | | Fibre | `fibre_color` above black | The two offset highlights a strand gives instead of the one a surface gives — hair, fur. Taken around the world tangent as the fibre axis. | All six are evaluated inside the engine's own light loop, once for every light that reaches the surface, so each one is shadowed, attenuated and cone-masked with the base layer it sits over. Each layer, and specular transmission beside them, is a shader feature its gating property switches on (`features:` in `properties.yaml`: `PBR_CLEARCOAT`, `PBR_ANISOTROPY`, `PBR_SHEEN`, `PBR_IRIDESCENCE`, `PBR_SUBSURFACE`, `PBR_FIBRE`, `PBR_TRANSMISSION`; the per-instance colour below is `PBR_INSTANCE_COLOR`). A material that sets the property away from its neutral value draws a program holding that layer; one that leaves every layer at rest draws a program holding none of them, so the default material pays only for the metallic-roughness model it shades as. Setting a property with `renderer.material.setProperty` moves the material between the two programs, and `renderer.shaderVariants()` lists the ones a scene has asked for. An oil-slicked wet surface is `iridescence = 1`, an `iridescence_thickness` around 300-500 nm and a low `roughness` over a dark `base_color`. Skin is a warm `subsurface_color` with a `subsurface_radius` near 0.5. Velvet is a `sheen_color` at the fabric's own hue over a dark base. ### Standing outside the fog `receives_fog = 0` declares that the screen-space fog passes — `heightFog` and `aerialPerspective` in `@builtin::systems.atmosphere` — leave this surface at the colour it shaded to. The declaration travels to those passes as a per-pixel surface flag written into the alpha of the G-buffer normal (`@builtin::shaderModules.surface_flags`). Only the deferred G-buffer fragment entry writes that channel, so the declaration reaches the fog from an **opaque** draw on the **deferred** path. A draw the renderer sends through the forward fragment entry — every draw on the forward path, and the transparent phase on either path — writes no G-buffer channel to carry it, and its pixels take the fog like any other. ### Per-instance colour `instance_color_lane` names one of the four shader-data lanes every drawn instance carries (`renderer.instanceData.set` for an entity, the `instanceDataBuffer` of `renderer.mesh.drawInstanced` for a population). The lane's `rgb` is this instance's colour and its `a` is how much of it covers the material's own base colour and emission, 0 none through 1 all, so one material draws every member of a structure, a crowd or a population in a colour of its own: a stress map, a heat map, damage tints, team colours, a selection highlight. A lane never written reads zero and leaves the material's own look. ```luau local mat = renderer.material.create({ shader = "@builtin::shaders.pbr", properties = { instance_color_lane = 2, roughness = 0.6 } }, "beams") beam.component.add("Model", { model = "cube", material = mat }) -- the handle renderer.instanceData.set(beam, 2, 1, 0.2, 0, 1) -- this beam orange-red ``` The colour replaces the base colour before lighting, so the surface still shades and the `albedo` capture pass reads the lane colour. `instance_emission` adds the lane colour as emission where it covers. Lanes 0 and 1 carry a baked lightmap's rect and layer, so a lit material takes lane 2 or 3. The read is the `PBR_INSTANCE_COLOR` feature, so a material that leaves `instance_color_lane` at `-1` draws a program without it. `@builtin::materials.instance_color` is this material ready made, reading lane 2. A write is local to the engine that makes it and replicates nothing, which is what makes it cheap enough to recolour hundreds of members every frame; `Model.tint` is the synced tint every participant sees. ## Textures (glTF metallic-roughness set) | Slot | Default | Channels | |---|---|---| | `base_color_texture` | white | RGBA albedo (sRGB). | | `roughness_metallic_texture` | white | G = roughness, B = metallic (glTF packing). | | `emissive_texture` | white | RGB emissive (sRGB). | | `normal_texture` | flat-normal | Tangent-space normal map. | | `occlusion_texture` | white | R = ambient occlusion. | A program samples the maps its material binds and no other. Each slot is a shader feature switched on by the material binding a texture there (`PBR_BASE_COLOR_MAP`, `PBR_ROUGHNESS_METALLIC_MAP`, `PBR_NORMAL_MAP`, `PBR_EMISSIVE_MAP`, `PBR_OCCLUSION_MAP`): a slot left unbound, or bound to its own default (`default:white`, `default:normal`), reads as the value that default stands for, times the slot's factor, with no texture sample, and an unbound normal map leaves the geometric normal exactly as it is. A solid-colour material takes no texture sample at all. A material binding one image as both `roughness_metallic_texture` and `occlusion_texture` (glTF's packed occlusion-roughness-metallic image) draws `PBR_OCCLUSION_IN_ROUGHNESS_METALLIC`, which reads occlusion from the R of the metallic-roughness texel and samples the image once. Because the engine holds the full `PbrSurface`, the capture tool's debug passes (albedo / roughness / metallic / AO / emissive / world-normal / shadow / depth / motion) all read real material data.
▲ 0↑ born
▣
module · born here
❒asset
# assetType runtime The machinery that reads a `<typename>.assetType/behavior.luau` and turns its declarations into live behaviour. A `behavior.luau` is a table of declarations — `ref` methods, `modules` shared code, an `events` schema, a `namePattern`, `refShapes`, and the `onCreate` / `onRegister` / `onChange` / `onDelete` / `validate` / `settingsDefaults` / `settingsCorrections` hooks. None of it runs itself. This is the code that runs it, and it lives here because reading a type's declarations is the **assetType type's own behaviour** — the same way `material.assetType` owns what a `.material` does. ## Sub-modules | Module | Reads | Responsibility | |---|---|---| | `ref.module` | `ref`, `modules` | Builds every `AssetRef` envelope, attaches the shared metatable, and dispatches per-type methods and shared modules onto it. Also owns edit-mode write-behind persistence. | | `create.module` | `onCreate`, `namePattern`, `validate` | Backs `asset.create`: resolves the type, checks the name against its pattern, runs `onCreate` (or clones `template/`), and writes the instance. `validate.module` beside it checks a creation `opts` table against the type's `createSchema`. Before running `onCreate`, resolves the type's settings chain (below) and hands the result to the hook as `opts.settings`. | | `settings.module` | `settings`, `settingsDefaults`, `settingsCorrections` | A type's declared settings schema and where its values live (`type.yaml`'s `settings:` block). `Settings.resolveForCreate` layers the schema's own defaults, the type's own `settingsDefaults(name, opts, asked)` hook (a DEFAULT the schema can't express — a name-derived convention, a fact read off a payload the caller handed it, a value following a field `asked` shows a higher layer naming; any later layer overrides it), the Preset Manager, an importer's settings, the caller's `settings` table, then the type's own `settingsCorrections(values, name, opts)` hook (a CROSS-FIELD CONSTRAINT the schema can't express, applied last over the fully merged values). A correction over a default/preset/importer value lands silently; a correction that would override what the caller's own `settings` table explicitly asked for refuses the creation instead, naming the field and why. Neither hook is ever handed a table to mutate; each returns what it wants changed (`settingsCorrections` may also return a `{ [field]: reason }` table for that refusal message). `Settings.cloneValues` deep-copies a values table — `create.module` hands `onCreate` a copy, never the table it stamps. `Settings.valuesOf` / `writeValues` read and write an asset's own values file. | | `typeYaml.module` | `type.yaml` | The folder a type lives in and its parsed `type.yaml`, decoded once per content version of the file. `settings.module` and `inspector.module` read their blocks through it. `about` / `aboutAt` read a type's `about.yaml` (`intent`, `function`, `usage`), leaving out any key that is empty or still starts with `[[describe]]`; `aboutRows` and `aboutMarkdown` lay the texts out for the Inspector and the `types/<name>` guide. | | `inspector.module` | `type.yaml`'s `inspector:` block | Which inspector a type declares for its assets (`inspector: { type: ... }` or `{ instance: ... }`), and the declaration that file returns — the sections it adds, the generic ones it replaces, and their order — or the problem that kept it from loading. | | `onRegister.module` | `onRegister` | Fires an instance's once-only registration hook — on arrival, on world load, and for `@builtin` library instances. | | `changeDispatch.module` | `onChange`, `onDelete`, `refShapes` | Routes a VFS source write or a folder delete to the enclosing typed asset's type hooks. | | `refShapes.module` | `refShapes`, `ref` | Publishes what every `AssetRef<category>` answers to, so a member read on an asset-typed value is checked against that category's real surface. | | `events.module` | `events` | The per-asset event runtime behind `ref.events`. | | `instantiable.module` | `ref.instantiate` | The instantiation contract an asset type opts into: `root` stands the root entity, `place` applies the base placement opts to one the type adopted, and `result` shapes the `(root, idMap)` every `instantiate` returns. Also registers the `sceneInstantiable` field-constraint validator. | | `declaration.module` | `type.yaml` | The type's decoded declaration, read once and held until a write inside an `.assetType` folder; what every question about a type as a whole reads. | | `previewRecipe.module` | `type.yaml` `preview:` | How an instance's `preview.png` is produced: which of the four recipes (`instantiate`, `image`, `surface`, `custom`) the type declares, and what that recipe needs. | ## Reaching it ```luau local rt = require("@builtin::assetTypes.assetType.shared") rt.ref.loadTypeBehavior("material") ``` Fields resolve lazily. The prelude requires the sub-modules directly, in dependency order (`ref`, then `changeDispatch`, `onRegister.install()`, `refShapes.install()`) — a table that required all six on load would take that ordering away from it.
▲ 0↑ born
backing path · materials/error_test.material

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported on this asset or on the parts this page shows. Parts it leaves out are not counted here.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.