Log inGet started
✦
shader · drop-in viewer
asset⌬ shadershaderprimary: shader.wgsl·originates fromworld 07158574-5…

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 th…

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

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

PropertyTypeDefaultMeaning
base_colorcolor[1,1,1,1]Albedo tint, multiplied by base_color_texture and vertex colour.
emissivecolor[0,0,0,1]Emissive tint, multiplied by emissive_texture and emissive_intensity.
emissive_intensityfloat1.0HDR multiplier on the emissive output.
roughnessrange0.5Perceptual roughness, multiplied by the green channel of roughness_metallic_texture.
metallicrange0.0Metalness, multiplied by the blue channel of roughness_metallic_texture.
reflectancerange0.5Dielectric reflectance knob (neutral 0.5 → 4% F0).
iorfloat1.5Index of refraction → dielectric F0 and the refraction direction.
normal_scalefloat1.0Strength of the tangent-space normal_texture.
occlusion_strengthrange1.0Blend of the occlusion_texture (R) into the ambient term.
clearcoatrange0.0Strength of a second dielectric clearcoat specular lobe.
clearcoat_roughnessrange0.0Roughness of the clearcoat lobe.
anisotropyfloat0.0Anisotropic highlight stretch along the tangent ([-1,1]).
sheen_colorcolor[0,0,0,1]Tint of the sheen lobe — the retroreflective rim of velvet, satin and brushed fabric. Black leaves the base untouched.
sheen_roughnessrange0.3Width of the sheen lobe.
iridescencerange0.0Blend toward the thin-film response, the hue that shifts with view angle.
iridescence_thicknessfloat400.0Film thickness in nanometres — which wavelengths cancel and which reinforce.
iridescence_iorfloat1.3Index of refraction of the film.
subsurface_colorcolor[0,0,0,1]Tint of the light that entered the surface, scattered beneath it and left again. Black leaves the base untouched.
subsurface_radiusfloat0.5How far the diffuse falloff wraps past the terminator, taken per channel against subsurface_color.
fibre_colorcolor[0,0,0,1]Tint of the second of the two highlights a hair or fur strand gives. Black leaves the base untouched.
fibre_specularrange0.35Strength of the first strand highlight, in the light's own colour.
fibre_shiftfloat0.06How far apart the two strand highlights sit along the fibre.
fibre_roughnessrange0.1Width of the first strand highlight.
transmissionrange0.0Specular transmission — refracts the environment through the surface.
thicknessfloat0.0Volume thickness for Beer–Lambert transmission absorption.
attenuation_colorcolor[1,1,1,1]Transmission absorption tint.
attenuation_distancefloatlargeBeer–Lambert absorption distance.
uv_scalefloat2[1,1]UV tiling applied before every texture sample.
uv_offsetfloat2[0,0]UV offset applied before every texture sample.
alpha_cutoffrange0.0Mask threshold — fragments with alpha < this are discarded (0 = no cutoff).
double_sidedboolfalseFlip the shading normal on back faces.
receives_fogbooltrueWhether 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_lanefloat-1Which of the instance's four shader-data lanes colours it (rgb colour, a coverage). -1 reads none. See below.
instance_emissionfloat0How 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.

LayerTurned on byWhat it looks like
Clearcoatclearcoat > 0A second dielectric specular lobe on top — car paint, lacquer, a varnished surface.
Anisotropyanisotropy ~= 0The highlight stretches along the tangent — brushed metal, a vinyl record.
Sheensheen_color above blackA retroreflective rim that brightens toward grazing angles — velvet, satin, dusty cloth.
Iridescenceiridescence > 0The specular hue shifts with view angle — an oil slick, a soap film, anodised metal, a beetle shell. Thickness picks the colours.
Subsurfacesubsurface_color above blackLight 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.
Fibrefibre_color above blackThe 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.

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)

SlotDefaultChannels
base_color_texturewhiteRGBA albedo (sRGB).
roughness_metallic_texturewhiteG = roughness, B = metallic (glTF packing).
emissive_texturewhiteRGB emissive (sRGB).
normal_textureflat-normalTangent-space normal map.
occlusion_texturewhiteR = 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.

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.

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.

117+items
·
shadermodule · born here
❒asset
# parallax Parallax occlusion for any lit surface shader: relief from a height map, drawn on a flat face. The view ray is marched into the height field in tangent space and every map the surface samples is read where the ray met the relief, so raised parts stand in front of low ones as the view moves. A shorter march toward the sun gives the relief its own shadow. ## Which way the height map runs One convention for the module and both built-in shaders that carry it: the map's R channel is **height, white highest** (raised parts white, gaps and grooves black). A map authored the other way, **depth, white deepest**, is read by switching `height_map_is_depth` on, with no need to invert the image: | Where | The switch | Default | |---|---|---| | this module | `ZeroParallax.height_map_is_depth` | `false` (height, white highest) | | `pbr` material | `height_map_is_depth` property | `false` (height, white highest) | | `pbr_parallax_occlusion` material | `height_map_is_depth` property | `true` (depth, white deepest: the maps made for it, `parallax_bricks` among them, are depth maps) | A relief that reads inside out (stones sunk into the mortar, carving standing proud) is a map read the wrong way: flip `height_map_is_depth`. ```wgsl #include "@builtin::shaderModules.parallax" fn surface(input: FragmentData) -> PbrSurface { let relief = zero_parallax(0.06, 32.0); // depth in UV units, most steps let hit = zero_parallax_march(input, height_texture, height_texture_sampler, input.uv, relief); var s = zero_pbr_default_surface(input); s.albedo = textureSampleGrad(base_color_texture, base_color_texture_sampler, hit.uv, hit.ddx, hit.ddy).rgb; // ... every other map at hit.uv the same way ... // The relief's self-shadow, folded into the sun the shading lights with. s.sun_visibility = zero_parallax_sun_visibility(input, s, height_texture, height_texture_sampler, hit, relief); return s; } ``` A `fragment()` shader that lights itself does the same and returns `zero_pbr_shade(input, s)`. ## `ZeroParallax` | Field | Meaning | |---|---| | `depth` | How deep the relief reaches, in UV units: the furthest the march moves a UV. 0 draws the flat face. | | `max_steps` | The view march's steps at a grazing view; straight down takes 40% of them, the self-shadow half. | | `fade_start`, `fade_end` | World distance from the camera over which the relief flattens; past `fade_end` no march runs. | | `height_map_is_depth` | `false` (the default): R is height, white highest. `true`: R is depth below the top, white deepest. | `zero_parallax(depth, max_steps)` fills the rest: fading over 20 to 40 world units, reading a height map. ## What it costs and where - The view march runs only where the relief is nearer than `fade_end`, and its step count falls as the view turns toward the face. - The relief flattens toward a grazing view, so the silhouette of a curved surface (a trunk, a column) keeps its shape. - The self-shadow march runs only on a fragment the sun lights: `zero_pbr_sun_visibility` states the sun's share first, and a fragment the sun does not reach, that faces away from it, or that its shadow maps hold in full shadow takes no self-shadow sample. - Maps are read with `textureSampleGrad` through `hit.ddx` / `hit.ddy`, the derivatives of the face's own UV with the frame's texture bias, so the jumps the march makes at the relief's edges choose no coarser mip and the picture holds still under temporal anti-aliasing. ## What the relief is The fragment stage draws it: the depth the surface writes and the shadow it casts are those of the flat face, and the relief offsets the UV inside the face rather than past its edges. A UV that tiles keeps every tile: the march reads the height map with the sampler's own wrap. `zero_parallax_march` takes the derivatives of the UV it is given, so it is called from uniform control flow, where an implicit-derivative `textureSample` may be. The built-in `pbr` shader carries it as a feature (`parallax_depth_scale` > 0 with `height_texture`), and `pbr_parallax_occlusion` is built on it; each states the map's direction with its `height_map_is_depth` property. The rendering guide's relief section (`guides { path = "topics/rendering-geometry" }`) places it among the engine's other geometry techniques.
▲ 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
·
assettype · born here
❒asset
# Shader module (asset type) A `.shaderModule` is a block of WGSL that other shaders **include** rather than copy — a lighting model, a set of colour-space helpers, one package's shared prelude. It declares no entry point and is never dispatched or drawn on its own account; it exists to be expanded into the shaders that name it. ## Folder shape ``` <name>.shaderModule/ module.wgsl # the WGSL — helpers, structs, constants (required) README.md # what THIS module provides (required) .metadata # tags and free-form fields (required) ``` Each file carries a committed `.meta` sidecar pinning its stable guid, and the folder carries one of its own. ## Including one A shader names a module by identity, and the identity is what records the dependency — so a shader that is packed, pulled or published carries the modules it includes with it: ```wgsl #include "~.colour" // a module under the same `~.` #include "@builtin::shaderModules.pbr_shading" // one from the builtin library ``` A missing module is a hard error at compile: a shader that names an interface which no longer exists fails loudly rather than compiling against a stale copy. Each module is expanded at most once per shader, so two shaders that both include the same module — or a module that includes another — produce one copy, not a duplicate-definition error. ## Writing one Write only what other shaders need in scope: functions, structs, constants. A module may reference a binding its includers declare, which is how a package's prelude can read that package's uniform block. ```wgsl const LUMA: vec3<f32> = vec3<f32>(0.2126, 0.7152, 0.0722); fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> { let lo = c / 12.92; let hi = pow(max(c + vec3<f32>(0.055), vec3<f32>(0.0)) / 1.055, vec3<f32>(2.4)); return select(hi, lo, c <= vec3<f32>(0.04045)); } ``` ## Answering to another name A module declares extra names it answers to with `@alias` lines in the header of `module.wgsl`: ```wgsl // @alias: colour_helpers // @alias: @mypack::shaderModules.colour ``` Each becomes an alias on the asset, so the name resolves everywhere an identity does: `asset.resolve`, an `#include`, and the publish gate alike. Only the header is read — the scan stops at the first line that is not a comment, so a directive cannot hide in the module body. A name another asset already holds is refused and reported, since an alias extends the identity namespace rather than taking a name out of another asset's hands. ## Registration & hot reload Writing `module.wgsl` registers the module under every name the asset answers to — its guid, its identity, and any alias — so a shader includes it by whichever name it holds. Saving re-registers it and the shaders that include it recompile, with no world reload. ## Discovery - `asset.list("shaderModule")` — every registered module. - `moduleRef:getSource()` — the module's WGSL. ## Related types - `.shader` — render-domain shaders (surface, sky, post-process, screen). - `.computeShader` — compute programs. ## In the Inspector Selecting a shader module opens its **Module** section: how many lines it holds, the aliases a shader `#include`s it by, and an opener for `module.wgsl`.
▲ 0↑ born
◐
material · born here
❒asset
# postReference_focusBars Four rows of bar pairs, 8 pairs across the top row and doubling on each row below: the focus chart a depth-of-field reading is taken off. Drawn unlit by `@builtin::shaders.referenceChart`, so a picture of it is measured against the light its properties state. Part of the post-verification reference scenes (`@builtin::scenes.postReference.*`); `@builtin::modules.postMetrics` reads them.
▲ 0↑ born
◐
material · born here
❒asset
# postReference_skyRamp A sky-blue ramp of light from 0.02 to 0.6 across: a clear sky's gradient. Drawn unlit by `@builtin::shaders.referenceChart`, so a picture of it is measured against the light its properties state. Part of the post-verification reference scenes (`@builtin::scenes.postReference.*`); `@builtin::modules.postMetrics` reads them.
▲ 0↑ born
❒
package · born here
❒asset
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Chrome A polished chrome surface built on the `pbr` shader — fully metallic (`metallic: 1.0`) with a bright near-white base colour (`0.95, 0.95, 0.97`) and very low roughness (`0.05`) for mirror-sharp reflections. Opaque, back-face culled, instanced, with the `_METALLICSPECGLOSSMAP` keyword enabled. ## Inputs - `colors.base_color` (`0.95, 0.95, 0.97, 1.0`) — bright, faintly cool chrome tint. - `floats.metallic` (`1.0`) — fully metallic. - `floats.roughness` (`0.05`) — near-mirror sharpness. - `textures.base_color_texture` (`default:white`): the white base texture the colour multiplies against, so the surface renders `base_color` alone.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Snow Particle A soft, cold-white flake surface for falling-snow particle effects — a near-white base colour (`0.95, 0.97, 1.0`) with a cool blue-grey emissive glow (`0.25, 0.3, 0.4`) so flakes stay faintly visible in shadow. Transparent, double-sided (`cull: none`), and drawn in the transparent queue (`3000`). Built on `@builtin::shaders.snow_material`. ## Inputs - `colors.base_color` — the cold-white flake tint. - `colors.emissive` (`0.25, 0.3, 0.4`) — cool self-illumination that keeps flakes readable in dark scenes. - `floats.roughness` (`0.8`) — matte, non-glossy flakes. - `floats.metallic` (`0.0`) — fully dielectric.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Gold Polished gold — a fully metallic PBR surface with a warm yellow base colour (`1.0, 0.84, 0.0`) and low roughness (`0.25`) for bright, sharp reflections. Built on `@builtin::shaders.pbr`. ## Inputs - `colors.base_color` — the gold tint. - `floats.metallic` (`1.0`) — fully metallic. - `floats.roughness` (`0.25`) — sharpness of the reflection; raise for a brushed look.
▲ 0↑ born
◐
material · born here
❒asset
# Checkerboard A procedural checkerboard pattern rendered by `@builtin::shaders.checkerboard`, alternating a red base colour (`1.0, 0.2, 0.2`) with a blue emissive colour (`0.2, 0.2, 1.0`). Opaque and non-metallic (`metallic 0.0`) at mid roughness (`0.5`) — useful as a UV / scale test surface. ## Inputs - `colors.base_color` — the red square colour. - `colors.dark_color` — the blue square colour. - `floats.roughness` (`0.5`) — diffuse spread on the lit squares. - `floats.metallic` (`0.0`) — dielectric surface.
▲ 0↑ born
◐
material · born here
❒asset
# Custom Textured A textured opaque surface built on `@builtin::shaders.custom_material`, sampling the `array_texture` builtin over a warm peach base colour (`1.0, 0.8, 0.6`). Non-metallic (`metallic 0.0`) at mid roughness (`0.5`) — a worked example of pairing a custom shader with an array texture. ## Inputs - `textures.base_color_texture` (`@builtin/textures/array_texture`) — the sampled array texture. - `colors.base_color`: the warm peach colour the texture is multiplied by. - `floats.roughness` (`0.5`) — diffuse spread. - `floats.metallic` (`0.0`) — dielectric surface.
▲ 0↑ born
◐
material · born here
❒asset
# Sky Procedural A fully procedural atmospheric sky with a day/night cycle, built on `@builtin::shaders.procedural_sky`. Renders with no culling and no depth write behind all geometry (queue `1000`), computing gradient, sun, moon and stars analytically from its parameters — no texture required. ## Inputs - `properties.zenith_color` / `horizon_color` / `ground_color` — the atmospheric gradient from overhead (`0.1, 0.3, 0.6`) through the horizon (`0.5, 0.7, 1.0`) to the ground (`0.3, 0.25, 0.2`). - `properties.sun_intensity` (`20`) / `sun_size` (`0.02`) — brightness and disc size of the sun. - `properties.turbidity` (`4`) — atmospheric haze / scattering density. - `properties.stars_intensity` (`1`) / `moon_size` (`0.03`) — night-sky star brightness and moon disc size.
▲ 0↑ born
◐
material · born here
❒asset
# Sky Cubemap A cubemap sky/environment background built on `@builtin::shaders.cubemap_sky`. Renders with no culling and no depth write behind all geometry (queue `1000`), sampling the built-in `Ryfjallet_cubemap` with adjustable rotation and exposure. ## Inputs - `textures.sky_texture` — the cubemap sampled as the sky (`Ryfjallet_cubemap`). - `floats.rotation` (`0.0`) — yaw rotation of the sky around the vertical axis. - `floats.exposure` (`1.0`) — brightness multiplier applied to the sampled colour.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Default Unlit A flat, unlit surface that renders its base colour directly with no lighting response, built on the `unlit` shader. Uses a white base colour (`1.0, 1.0, 1.0`) over the `default:white` texture with `emissive` (`1.0`) for full brightness — the go-to default for UI, gizmos, and debug geometry that must stay legible regardless of scene lighting. ## Inputs - `colors.base_color` — the flat colour shown directly. - `textures.base_color_texture` (`default:white`) — the white base texture the colour multiplies against. - `floats.emissive` (`1.0`) — full, lighting-independent brightness.
▲ 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
❒
bundle · born here
❒asset
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Instance Color A lit white surface that every instance wearing it colours from its own shader-data lane 2, built on `@builtin::shaders.pbr` with `instance_color_lane = 2`. One material draws hundreds of members in hundreds of colours, and a colour that changes every frame costs one `renderer.instanceData.set` per member: a stress map over a bridge, a heat map, a damage flash, team colours, a selection highlight, a gauge. ```luau local LANE = 2 for i, id in members do local load = loads[i] -- 0 relaxed .. 1 at its limit renderer.instanceData.set(id, LANE, load, 1 - load, 0, 1) -- green to red, fully covered end ``` The lane's `rgb` is the colour and its `a` is how much of it covers the base colour and the emission, 0 none through 1 all; an instance whose lane was never written reads zero and draws plain white. The colour replaces the base colour before lighting, so the member still shades, casts its highlights and shows the lane colour in the `albedo` capture pass. Set `instance_emission` above 0 for a colour that glows where it covers. `renderer.mesh.drawInstanced` reads the same lane from its `instanceDataBuffer`, so a GPU-filled population colours each copy the same way. The writes are local to the engine that makes them and replicate nothing; `Model.tint` is the synced form of a tint, for a colour every participant must see. ## Inputs - `floats.instance_color_lane` (`2`): the lane read; lanes 0 and 1 carry a baked lightmap's rect and layer. - `floats.instance_emission` (`0`): how brightly the lane colour glows. - `colors.base_color` (white), `floats.roughness` (`0.5`), `floats.metallic` (`0`): the surface under the lane colour.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Emissive White A bright white light-emitting PBR surface built on the `pbr` shader with the `_EMISSION` keyword enabled. A white base colour (`1.0, 1.0, 1.0`) paired with a strong `emissive` (`20.0`) makes it glow and drive bloom — well suited to light fixtures, emitters, and glowing accents. Non-metallic (`metallic 0.0`) at mid roughness (`0.5`). ## Inputs - `floats.emissive` (`20.0`) — high emission strength that produces the glow. - `keywords: _EMISSION` — enables the emissive path in the PBR shader. - `colors.base_color` — the white surface and emission colour. - `floats.roughness` (`0.5`) — diffuse spread on the lit surface.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Water An animated water surface with a deep blue base colour (`0.1, 0.3, 0.8`) and low roughness (`0.2`) for glossy, reflective highlights, driven by a scrolling normal map for wave detail. Opaque, back-face culled, instanced, in the opaque queue (`2000`). Built on `@builtin::shaders.water_material`, sampling `@builtin/textures/water_normals`. ## Inputs - `colors.base_color` (`0.1, 0.3, 0.8`) — the water body colour. - `floats.roughness` (`0.2`) — low roughness for sharp specular reflections. - `floats.metallic` (`0.0`) — dielectric surface. - `textures.normal_texture` — the wave normal map (`@builtin/textures/water_normals`).
▲ 0↑ born
◐
material · born here
❒asset
# postReference_chrome A polished metal: its highlight of a bright light is a sub-pixel specular, the firefly a bloom and a temporal resolve are read on in the post-verification reference scenes.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Grass blades Swaying grass for a blade mesh, built on `@builtin::shaders.grass_material` with the same green as `@builtin::materials.grass` (`0.22, 0.62, 0.16`) and `sway` at `1.0`. The shader bends each vertex along its blade in proportion to `uv.y²`, so this material belongs on a mesh whose `uv.y` runs 0 at a blade's root to 1 at its tip — a merged field of blades, each a cross of two tapered quads. It inherits the Rust-side render defaults (opaque, back-face culled, queue `2000`) so its pipeline matches the library variant compiled at startup. ## Inputs - `colors.base_color` (`0.22, 0.62, 0.16, 1.0`) — the grass green tint. - `floats.sway` (`1.0`) — the full blade bend. `@builtin::materials.grass` leaves it at the shader's default of `0` for a ground surface.
▲ 0↑ born
◐
material · born here
❒asset
# Text Default The default surface for Text3D — a white base colour (`1.0, 1.0, 1.0`) drawn with alpha blending and no depth write so glyphs composite cleanly over the scene. Transparent, double-sided (`cull: none`), `depth_write: false`, in the transparent queue (`3000`). Built on the `pbr` shader. ## Inputs - `colors.base_color` (`1.0, 1.0, 1.0`) — the glyph colour. - `render.depth_write` (`false`) — glyphs blend without occluding each other. - `render.cull` (`none`) — text is visible from both sides. - `floats.roughness` (`0.5`) / `floats.metallic` (`0.0`) — dielectric defaults.
▲ 0↑ born
◐
material · born here
❒asset
# Grid Background A procedural background/reference-grid surface built on `@builtin::shaders.grid_bg`. It draws grid lines over a black base colour (`0.0, 0.0, 0.0`) with full roughness (`1.0`) and no metallic response, rendered opaque with culling disabled (`cull: none`) and instancing enabled so it can back many objects at once. ## Inputs - `colors.base_color` (`0.0, 0.0, 0.0, 1.0`) — black backdrop behind the grid lines. - `floats.roughness` (`1.0`) — fully diffuse, no highlights. - `render.cull` (`none`) — visible from both faces. - `render.instancing` (`true`) — supports instanced draws.
▲ 0↑ born
◐
material · born here
❒asset
# Standard Default The baseline PBR surface — a neutral white base colour (`1.0, 1.0, 1.0`), half roughness (`0.5`), non-metallic (`0.0`), wired with the full standard texture set (base colour, normal, roughness-metallic, emissive, occlusion) and the `_NORMALMAP` / `_OCCLUSIONMAP` keywords enabled. Opaque, back-face culled, instanced, in the opaque queue (`2000`). Built on `@builtin::shaders.pbr`. This is the starting point most materials copy and retint. ## Inputs - `colors.base_color` (`1.0, 1.0, 1.0`) — the albedo tint over the base colour texture. - `floats.roughness` (`0.5`) / `floats.metallic` (`0.0`) — dielectric, mid-gloss default. - `floats.normal_strength` (`1.0`) / `floats.ao_strength` (`1.0`) — normal-map and occlusion intensity. - `textures.normal_texture` / `textures.roughness_metallic_texture` / `textures.occlusion_texture` — the PBR map slots, seeded with neutral defaults.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# postReference_grey18 A lit 18% grey (middle grey) surface, rough and dielectric: what a light of known intensity is read off in the post-verification reference scenes.
▲ 0↑ born
◐
material · born here
❒asset
# Parallax Cube (Flat) A brick surface built on `@builtin::shaders.pbr_parallax_occlusion` with `parallax_depth_scale = 0`, so the ray-march is bypassed and the shared brick textures render as plain textured PBR (rough `0.7`, non-metallic, white base colour). Opaque, back-face culled, queue `2000`. Pair it with `parallax_cube` to A/B the parallax effect from a fixed viewpoint. ## Inputs - `floats.parallax_depth_scale` (`0.0`) — disables the occlusion ray-march, flattening the surface. - `floats.roughness` (`0.7`) — matte brick finish. - `floats.normal_scale` (`1.0`) — strength of the normal map. - `textures.height_texture` — the brick height map (unused while depth scale is `0`).
▲ 0↑ born
◐
material · born here
❒asset
# postReference_siemensStar A Siemens star of 36 spokes, 0.9 on 0.02: the spokes narrow below a pixel toward the centre, where a temporal resolve aliases. Drawn unlit by `@builtin::shaders.referenceChart`, so a picture of it is measured against the light its properties state. Part of the post-verification reference scenes (`@builtin::scenes.postReference.*`); `@builtin::modules.postMetrics` reads them.
▲ 0↑ born
◐
material · born here
❒asset
# Skybox An unlit cubemap skybox rendered from the inside of the mesh, built on `@builtin::shaders.cubemap_unlit`. Uses front-face culling and no depth write so it draws behind all scene geometry (queue `1000`), sampling the built-in `Ryfjallet_cubemap` environment. ## Inputs - `textures.base_color_texture` — the cubemap sampled as the background (`Ryfjallet_cubemap`). - `floats.reflect_mode` (`0.0`) — samples the cube directly as a background rather than as a reflection. - `colors.base_color` (`1.0, 1.0, 1.0`) — tint applied to the sampled cubemap.
▲ 0↑ born
◐
material · born here
❒asset
# postReference_greyWedge The grey wedge: one column per whole stop from -10 to +10, each middle grey (0.18) at that exposure. Drawn unlit by `@builtin::shaders.referenceChart`, so a picture of it is measured against the light its properties state. Part of the post-verification reference scenes (`@builtin::scenes.postReference.*`); `@builtin::modules.postMetrics` reads them.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Checkerboard White A static white/grey checkerboard rendered by `@builtin::shaders.checkerboard`, alternating a white base colour (`1.0, 1.0, 1.0`) with a dark grey check colour (`0.3, 0.3, 0.3`). Animation is disabled (`animation_speed 0.0`), giving a fixed, neutral grid — ideal as a level-design blockout or scale-reference floor. Opaque, non-metallic (`metallic 0.0`) at mid roughness (`0.5`). ## Inputs - `colors.base_color` — the white square colour. - `colors.check_color` — the dark grey square colour. - `floats.animation_speed` (`0.0`) — held at zero for a static pattern. - `floats.roughness` (`0.5`) — diffuse spread on the squares.
▲ 0↑ born
◐
material · born here
❒asset
# postReference_white A flat unlit white of 0.8 light: the thin geometry of the temporal reference scene (wires, a fence, a fan's blades) drawn against the dark, so every pixel it touches stands out from its neighbours. Drawn by `@builtin::shaders.referenceChart`. Part of the post-verification reference scenes (`@builtin::scenes.postReference.*`); `@builtin::modules.postMetrics` reads them.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# parallax_cube Brick wall material using `@builtin::shaders.pbr_parallax_occlusion` with the parallax march enabled (`parallax_depth_scale = 0.08`, 48 ray-march layers). Pair with `parallax_cube_flat` for a same-textures, no-POM A/B comparison. ## Shader `@builtin::shaders.pbr_parallax_occlusion` — see that shader's README for the full parameter list. ## Textures All from `@builtin::textures.parallax_bricks` (height/normal derived from three.js's MIT-licensed `brick_bump` + `brick_diffuse`): - `base_color_texture` → `bricks_albedo` - `normal_texture` → `bricks_normal` - `roughness_metallic_texture` → `bricks_roughness` - `occlusion_texture` → `bricks_ao` - `height_texture` → `bricks_height` ## Usage ```luau Material.Apply(entityId, "parallax_cube") -- Override at runtime: Material.SetProperty("parallax_cube", "parallax_depth_scale", 0.12) ``` Pair it with `parallax_cube_flat` (same textures, `parallax_depth_scale = 0`) to compare the ray-marched surface against a flat-mapped baseline. ## Notes - `Material.SetProperty` mutations are global — every entity using `parallax_cube` sees the change. If you need per-entity variation, derive a new material name and override the property there. - Use under any standard camera (forward path). The deferred path is not yet POM-aware; materials applied to a deferred camera will render as plain textured PBR.
▲ 0↑ born
◐
material · born here
❒asset
# Neon A glowing cyan neon surface built on `@builtin::shaders.pbr` with emission enabled. It pairs a bright cyan-blue base colour (`0.2, 0.8, 1.0`) with a matching emissive colour driven hard by `emissive: 5.0`, so it reads as a self-lit light source. Low roughness (`0.2`), non-metallic, opaque, instanced, with the `_EMISSION` keyword enabled. ## Inputs - `colors.emissive` (`0.2, 0.8, 1.0, 1.0`) — cyan glow colour. - `floats.emissive_intensity` (`5.0`) — strong emissive intensity (feeds bloom). - `colors.base_color` (`0.2, 0.8, 1.0, 1.0`) — matching cyan base tint. - `floats.roughness` (`0.2`) — glossy surface under direct light.
▲ 0↑ born
❒
package · born here
❒asset
# oceans A sea and the ground under it, as one package: the wave simulation, the surface that renders it, the seabed it is seen through, and the answer to "how high is the water here" that gameplay needs to float things on it. ```lua local Ocean = require("@builtin::systems.oceans.modules.ocean") Ocean.create({ preset = "gale" }) ``` That is a whole ocean — waves out to the horizon, foam on the breaking crests, a seabed below, and a surface that follows whoever is looking at it. To float something on it: ```lua local ocean = Ocean.forEntity(oceanEntityId) boat.position = { x, ocean:sampleHeight(x, z), z } ``` It is a building block. The sun the water glitters under, the ambient its foam sits in and the sky it reflects all come from the scene, through the same directional light and reflection probes every other material in the engine reads — so an ocean drops into a world that already has lighting instead of bringing a second set, and changing the scene's light changes the water with it. ## What it does The simulation is **spectral**: instead of animating individual waves, it builds the sea's energy across every wavelength and direction from an oceanographic spectrum, then inverse-transforms that into a height field. A real sea is what comes out — wind speed alone decides wave height, and it rises with wind the way a fully developed sea does, following the Pierson–Moskowitz law. It runs in **cascades** — independent wave fields over different patch sizes, each band-limited to its own range of wavelengths. A tile of roughly two kilometres carries the long waves and one of a few hundred metres the short ones; they sum into a surface with detail at every scale, and because the bands are disjoint no wavelength is synthesised twice. Above them a **Gerstner bank** adds the swell analytically, which no cascade can hold: a wave longer than its own patch has nowhere to live, and swell arrives from a distant storm on its own heading anyway. **Foam** is not painted on. It comes from the Jacobian of the wave displacement: where the surface folds over itself, the wave is breaking. Whitecaps appear where and when the geometry actually breaks, accumulate into a persistent world-space field, and streak behind the crest as they decay. **Colour and transparency are the same mechanism.** Per-channel Beer–Lambert extinction over the distance light travelled through water gives both — red dies within a metre, blue survives tens. That is why shallow water over sand reads turquoise and the open sea reads near-black blue without switching materials. **The seabed** is one noise field read twice: scaled it is the terrain's relief, unscaled it picks between sand and rock, so outcrops stand on the high ground and sand fills the hollows. The sun's caustic web moves over both, bent by the horizontal displacement of the water directly above it. Bodies land on it: the pass that raises the ground writes the same field out as a height patch that travels with the viewer, so what a body stands on is what the frame drew. Nothing here ships an image. Every map the surface and the seabed sample — the foam patterns, the sand, the rock, the caustics — is grown on the GPU at startup. ## The pieces | Asset | What it is | |---|---| | `components/Ocean` | Puts a sea on an entity. Its fields are the sea state; the simulation is rebuilt from them, so an ocean survives a scene reload. | | `modules/ocean` | The substrate: `attach`, `create`, `forEntity`, `sampleHeight`, `sampleDisplacement`. | | `components/Buoyancy` | Floats a rigid body on any water, inside the physics step. Its fields are the hull: how dense it is, how quickly it settles, and what displaces water (its colliders, a stated box or what it draws). | | `modules/buoyancy` | The float: `attach`, `forEntity`, `list`, `clear`, `submergedFraction`, `restingY`. | | `modules/oceanPresets` | Nine named sea states, from `calmClear` through `gale`. | | `modules/oceanQuality` | The four tiers — how finely a sea is resolved, as distinct from what sea it is. | | `modules/oceanClipmap` | The camera-following ring geometry both the surface and the seabed are built on. | | `modules/oceanFloor` | The seabed: terrain, ground materials, caustics and the ground physics collides with. | | `modules/oceanScene` | The seam between the scene capture and the materials that sample it. | | `shaders/oceanSurface` | The water: cascade normals, absorption, exact dielectric Fresnel, subsurface scattering, sun glitter, foam, and the view from below. | | `shaders/oceanFloor` | The seabed: sand and rock blended by terrain noise, under a caustic web. | | `materials/oceanWater`, `materials/oceanSeabed` | The default looks. | | `renderFeatures/oceanScene` | Copies the frame's colour and depth so the surface can refract what is behind it and measure its own water column. | | `computeShaders/ocean_*` | The ten-stage GPU pipeline. | ## Wind is the control Significant wave height goes as the **square** of wind speed, so that one field does most of the work: | Wind | Sea | Wave height | |---|---|---| | 3 m/s | glassy, a mirror | ~0.2 m | | 11 m/s | working sea, occasional whitecap | ~2.5 m | | 24 m/s | gale, breaking and streaked | ~12 m | Everything else shapes character rather than size: `choppiness` pinches crests into peaks, `standingWaveRatio` runs waves both ways instead of only downwind, `jonswapGamma` sharpens a fetch-limited sea, and the foam layers decide how readily a breaking crest whitens and how long it streaks. Read `documentation/oceans.guide` for the full walkthrough, including the seabed, buoyancy, reflections and what each tier costs.
▲ 0↑ born
◐
material · born here
❒asset
# postReference_checker A checker of 64 cells across, 0.8 on 0.03: the high-frequency background a fast object crosses. Drawn unlit by `@builtin::shaders.referenceChart`, so a picture of it is measured against the light its properties state. Part of the post-verification reference scenes (`@builtin::scenes.postReference.*`); `@builtin::modules.postMetrics` reads them.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# postReference_colorChecker The 24 patches of the ColorChecker Classic, each its published sRGB value read as linear reflectance. Drawn unlit by `@builtin::shaders.referenceChart`, so a picture of it is measured against the light its properties state. Part of the post-verification reference scenes (`@builtin::scenes.postReference.*`); `@builtin::modules.postMetrics` reads them.
▲ 0↑ born
❒
package · born here
❒asset
▲ 0↑ born
❒
package · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# 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.
▲ 0↑ born
◐
material · born here
❒asset
# Animated Color An opaque, back-culled surface whose colour animates over time, driven by `@builtin::shaders.animate_shader`. Starts from a white base colour (`1.0, 1.0, 1.0`) with an `emissive` of `1.0` so the shifting colour reads brightly, at mid roughness (`0.5`) and fully non-metallic (`metallic 0.0`). ## Inputs - `colors.base_color` — the starting colour the animation modulates. - `floats.emissive` (`1.0`) — self-illumination strength of the animated colour. - `floats.roughness` (`0.5`) — matte diffuse spread. - `floats.metallic` (`0.0`) — dielectric, non-metallic surface.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
❒
bundle · born here
❒asset
# Error Text A 3D "ERROR" text model used as the visible fallback when an asset fails to load — spawned in place of missing geometry so a broken reference is obvious in-scene instead of silently invisible. Decomposed from `ERRORText.fbx` into this bundle (mesh + material + texture + entity template). ## Composition - Root `error_text` → `Sketchfab_model` → the `ERRORText.fbx` node hierarchy. - Carries the extruded "ERROR" letter mesh, its material, and texture as private subassets. ## Usage Spawned automatically by the engine as the placeholder for an unresolved asset; can also be spawned directly to test the fallback path.
▲ 0↑ born
◐
material · born here
❒asset
# Plastic White A clean white plastic — a non-metallic PBR surface with a pure white base colour (`1.0, 1.0, 1.0`) and mid roughness (`0.5`) for a soft dielectric sheen. Built on `@builtin::shaders.pbr`. Opaque, back-face culled, queue `2000`. ## Inputs - `colors.base_color` (`1.0, 1.0, 1.0`) — the white plastic tint. - `floats.roughness` (`0.5`) — soft, semi-glossy highlight. - `floats.metallic` (`0.0`) — dielectric (non-metal) response. - `floats.emissive` (`0.0`) — no self-illumination.
▲ 0↑ born
◐
material · born here
❒asset
# postReference_darkRamp A ramp of light from 0 at the left edge to 0.1 at the right: the dark gradient an undithered 8-bit display path bands on. Drawn unlit by `@builtin::shaders.referenceChart`, so a picture of it is measured against the light its properties state. Part of the post-verification reference scenes (`@builtin::scenes.postReference.*`); `@builtin::modules.postMetrics` reads them.
▲ 0↑ born
◐
material · born here
❒asset
# Lit Checkerboard A static, lit checkerboard surface built on `@builtin::shaders.lit_checkerboard` — the default ground material for newly seeded worlds. It uses a neutral light-grey base colour (`0.85, 0.85, 0.85`) with a grey emissive tint (`0.35, 0.35, 0.35`) so the pattern stays readable in dim scenes, high roughness (`0.7`), no metallic, opaque, and instanced. ## Inputs - `colors.base_color` (`0.85, 0.85, 0.85, 1.0`) — neutral grey checker palette. - `colors.dark_color` (`0.35, 0.35, 0.35, 1.0`) — the dark square colour, close enough to the base that the pattern stays readable in low light. - `floats.roughness` (`0.7`) — mostly diffuse surface. - `render.instancing` (`true`) — supports instanced draws.
▲ 0↑ born
◐
material · born here
❒asset
# Decal Default The default material a `DecalProjector` stamps when none is assigned. A flat cyan tint (`0.05, 0.95, 1.0`) on `@builtin::shaders.pbr`. Assign a material with a `base_color_texture` to project a texture; the projector samples the material's base colour at the box-local XY of every surface inside its projection box.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Sky Equirectangular An equirectangular panorama sky/environment background built on `@builtin::shaders.equirect_sky`. Renders with no culling and no depth write behind all geometry (queue `1000`), with adjustable rotation and exposure. Assign an equirectangular image to `sky_texture` (via `material.setTexture` or a Skybox) to display a panorama. ## Inputs - `textures.sky_texture` — the equirectangular panorama image to sample. Falls back to black, so a sky with nothing assigned reads as night rather than as an error. Assign a `.texture` by guid, identity, name, or path: ```luau renderer.material.setTexture("@builtin::materials.sky_equirect", "sky_texture", "my_panorama.texture") ``` An image dropped into `/zero/source` imports into a sibling `<stem>.texture` container and the loose file is removed, so reference the container (or its identity) rather than the original image path. - `floats.rotation` (`0.0`) — yaw rotation of the panorama around the vertical axis. - `floats.exposure` (`1.0`) — brightness multiplier applied to the sampled colour.
▲ 0↑ born
◐
material · born here
❒asset
# error_marker The material of the ERROR sign a Model or SkinnedModel shows in place of a mesh that failed to resolve, to become GPU-resident, or to pose. It draws the `error_marker` shader's magenta checker.
▲ 0↑ born
◐
material · born here
❒asset
# Instance Color Unlit An unlit white surface that every instance wearing it colours from its own shader-data lane 2, built on the `unlit` shader with `instance_color_lane = 2`. It draws exactly the picture `Model.tint` gives an unlit surface for the same colour and blend, at the cost of one `renderer.instanceData.set` per member and with nothing replicated, so it is the material for flat per-instance colour that changes every frame: a heat map, a stress readout, indicator lights. ```luau renderer.instanceData.set(id, 2, 1, 0, 0, 1) -- this member red, fully covered renderer.instanceData.set(id, 2, 1, 0, 0, 0) -- back to the material's white ``` The lane's `rgb` is the colour and its `a` is how much of it covers the material's own colour, 0 none through 1 all; a lane never written reads zero and leaves it white. Set `instance_emission` above 0 to add the colour again on top, scaled, for a colour that blooms. ## Inputs - `floats.instance_color_lane` (`2`): the lane read. - `floats.instance_emission` (`0`): how much of the lane colour is added on top where it covers. - `colors.base_color` (white) over `textures.base_color_texture` (`default:white`): the colour under the lane colour.
▲ 0↑ born
◐
material · born here
❒asset
# Brushed Metal A brushed metallic surface built on the `pbr` shader — fully metallic (`metallic: 1.0`) with a neutral grey base colour (`0.6, 0.6, 0.6`) and moderate roughness (`0.3`) that softens reflections into the muted sheen of brushed steel or aluminium. Opaque, back-face culled, instanced, with the `_METALLICSPECGLOSSMAP` keyword enabled. ## Inputs - `colors.base_color` (`0.6, 0.6, 0.6, 1.0`) — neutral metal grey. - `floats.metallic` (`1.0`) — fully metallic. - `floats.roughness` (`0.3`) — softened, brushed reflections. - `textures.base_color_texture` (`default:white`): the white base texture the colour multiplies against, so the surface renders `base_color` alone.
▲ 0↑ born
◐
material · born here
❒asset
# postReference_emitter A flat emitter answering with 16 times the display's white: the source a bloom reading is taken around. Drawn unlit by `@builtin::shaders.referenceChart`, so a picture of it is measured against the light its properties state. Part of the post-verification reference scenes (`@builtin::scenes.postReference.*`); `@builtin::modules.postMetrics` reads them.
▲ 0↑ born
◐
material · born here
❒asset
# Sky Solid A flat solid-colour background built on `@builtin::shaders.solid_sky`. Renders with no culling and no depth write behind all geometry (queue `1000`), filling the sky with a single dark-grey colour (`0.2, 0.2, 0.2`) at unit exposure. ## Inputs - `colors.solid_color` (`0.2, 0.2, 0.2`) — the flat fill colour of the background. - `floats.exposure` (`1.0`) — brightness multiplier applied to the fill colour.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Grass A soft green ground surface built on `@builtin::shaders.grass_material`, with a natural green base colour (`0.22, 0.62, 0.16`), high roughness (`0.75`) for a diffuse, non-shiny look, and no metallic or emissive contribution. It inherits the Rust-side render defaults (opaque, back-face culled, queue `2000`) so its pipeline matches the library variant compiled at startup. It leaves the shader's `sway` at its default of `0`, so it shades whatever geometry it is applied to and leaves every vertex where the mesh puts it; `@builtin::materials.grass_blades` is the same green on a blade mesh that bends. ## Inputs - `colors.base_color` (`0.22, 0.62, 0.16, 1.0`) — the grass green tint. - `floats.roughness` (`0.75`) — matte, diffuse surface. - `floats.metallic` (`0.0`) / `floats.emissive` (`0.0`) — non-metallic, non-glowing.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Cubemap Env A chrome-ball environment surface that samples a cubemap for mirror-like reflections, built on `@builtin::shaders.cubemap_unlit`. `reflect_mode` (`1.0`) selects the reflection path, and the `Ryfjallet_cubemap` builtin texture supplies the environment. Opaque, with a white base colour (`1.0, 1.0, 1.0`) so the cubemap colours pass through untinted. ## Inputs - `textures.base_color_texture` (`@builtin/textures/Ryfjallet_cubemap`) — the environment cubemap that is reflected. - `floats.reflect_mode` (`1.0`) — selects the reflection sampling mode. - `colors.base_color` — white tint that leaves the reflected colours unchanged.
▲ 0↑ born
◐
material · born here
❒asset
# Solid Line A flat, opaque line surface with a bright green base colour (`0.0, 1.0, 0.5`) for drawing gizmos, paths, and debug geometry. Opaque, back-face culled, instanced, and rendered in the opaque queue (`2000`). Built on `@builtin::shaders.line_material`. ## Inputs - `colors.base_color` (`0.0, 1.0, 0.5`) — the line colour. - `floats.roughness` (`0.5`) — surface roughness. - `floats.emissive` (`0.0`) — no self-illumination. - `render.instancing` (`true`) — many lines draw in a single instanced batch.
▲ 0↑ born
◐
material · born here
❒asset
# Glass Clear glass — a smooth, transparent PBR surface with a faint blue tint (`0.9, 0.95, 1.0`) and low alpha (`0.3`). Rendered in the transparent queue with backface culling off (`cull: none`) so both faces of thin geometry show. Built on `@builtin::shaders.pbr`. ## Inputs - `colors.base_color` — tint and opacity (the alpha channel drives how much shows through). - `floats.roughness` (`0.0`) — perfectly smooth; raise for frosted glass.
▲ 0↑ born
❒
bundle · born here
❒asset
▲ 0↑ born
◐
material · born here
❒asset
# Default The neutral fallback surface — a plain white, non-metallic PBR material with mid roughness (`0.5`), sampling the built-in white texture. This is what an object renders as when no material is assigned. Built on `@builtin::shaders.pbr`. ## Inputs - `colors.base_color` — the flat tint (white by default). - `floats.roughness` (`0.5`) / `floats.metallic` (`0.0`) — a neutral matte dielectric. - `textures.base_color_texture` — the built-in `default:white` texture.
▲ 0↑ born
◐
material · born here
❒asset
# Triplanar Checker A checkerboard surface projected triplanarly, so the pattern stays uniform across arbitrary geometry with no UVs and no stretching. Neutral white base colour (`1.0, 1.0, 1.0`), half roughness (`0.5`), non-metallic, with a projection sharpness of `4.0` controlling how tightly the three axis projections blend at edges. Opaque, back-face culled, instanced, in the opaque queue (`2000`). Built on `@builtin::shaders.triplanar`, sampling `@builtin/textures/array_texture`. ## Inputs - `floats.triplanar_sharpness` (`4.0`) — blend tightness between the X/Y/Z projections. - `colors.base_color` (`1.0, 1.0, 1.0`) — tint over the projected texture. - `textures.base_color_texture` — the projected checker source (`@builtin/textures/array_texture`). - `floats.roughness` (`0.5`) / `floats.metallic` (`0.0`) — dielectric, mid-gloss default.
▲ 0↑ born
▣
module · born here
❒asset
# shader_includes Module Resolves the `#include` lines of a WGSL source against the asset system, so a shader includes a `.shaderModule` by every name form `require` and `asset.resolve` accept. ## Purpose A shader names a module the way any content names any asset — a guid, an identity, a package-relative `~.tail`, a `.relative.tail`, an `@root::` or `@builtin::` path. The engine's include expansion is a flat key lookup, so a relative form means nothing on its own: `~.tail` is a different module depending on which package asked for it. This module closes that gap in the one place that knows both — the including asset, which holds its own VFS path. Every literal is resolved against that path and rewritten to the module's guid before the source reaches the compiler, so a relative include resolves exactly where a relative `require` would. The rewrite applies to the source handed to the compiler. What the author wrote stays on disk, which is what the reference extractor records, with its line, when the file is written. ## Usage An assetType canonicalizes its own WGSL, passing the asset's path as the base the relative literals expand against: ```luau local ShaderIncludes = require("modules.shader_includes") local wgsl = ShaderIncludes.canonicalize(vfs.read(path .. "/shader.wgsl"), path) ``` Given `path` inside a package, both of these reach the compiler as the same guid-keyed include: ```wgsl #include "~.ssr_common" #include "@builtin::systems.reflections.ssr_common" ``` A literal that resolves to no asset is left as it was written, so a framework name — `zero::surface` and its siblings, which are registry keys rather than assets — reaches the expander untouched. Source carrying no `#include`, or given no base path, is returned unchanged.
▲ 0↑ born
❒
package · born here
❒asset
# deprecatedParticles (deprecated) > **Deprecated.** This belongs to the earlier particle substrate. It stays loadable by identity and guid for content that already uses it; nothing new should use it, and search does not offer it. Particles are procgen sim nodes (`sim.spawn`, `sim.particles`, `sim.shader`) played through an effect: use `@builtin::assetTypes.effect`. The package holds the GPU particle engine module (`engine`), the `deprecatedParticles` module over it, the `DeprecatedParticleEmitter` and `DeprecatedSimpleParticleEmitter` components, the shaders, compute shaders and materials they draw with, and a demo scene. The package's `.metadata` carries the deprecation marker, so every asset inside is deprecated.
▲ 0↑ born
◐
material · born here
❒asset
# Plastic Red A glossy red plastic — a non-metallic PBR surface with a saturated red base colour (`0.8, 0.1, 0.1`) and mid roughness (`0.5`) for a soft dielectric sheen. Built on `@builtin::shaders.pbr`. Opaque, back-face culled, queue `2000`. ## Inputs - `colors.base_color` (`0.8, 0.1, 0.1`) — the red plastic tint. - `floats.roughness` (`0.5`) — soft, semi-glossy highlight. - `floats.metallic` (`0.0`) — dielectric (non-metal) response. - `floats.emissive` (`0.0`) — no self-illumination.
▲ 0↑ born
◐
material · born here
❒asset
# Cel Shaded A stylised, toon-shaded opaque surface built on `@builtin::shaders.extended_material`, with a warm red-orange base colour (`0.9, 0.3, 0.2`). The sun's light is cut into flat bands that multiply the base colour, so every band renders the hue of `base_color` and only its brightness steps; ambient light lifts the side facing away from the sun in the same hue. High roughness (`0.8`) keeps the surface matte: its specular term stays below the first band, so each lit band is one flat colour. ## Inputs - `colors.base_color`: the surface colour every band renders in, multiplied by `base_color_texture`. - `floats.roughness` (`0.8`): the size and strength of the specular highlight, which is banded with the rest of the sun's light; 0 is a small bright highlight. At four bands, a roughness of 0.5 or more keeps the highlight below the first band, so none shows. - `floats.quantize_steps` (`4`): the number of bands the sun's light is cut into; 0 shades smoothly. - `textures.base_color_texture`: an optional surface texture, drawn multiplied by `base_color`. Unset, it is white, and the surface renders `base_color` alone.
▲ 0↑ born
✦
shader · born here
❒asset
# eye.shader An eye: an iris refracting behind a clear cornea. The iris sample is displaced by refracting the view ray at the cornea and walking it `iris_depth` inward, so the iris slides as the viewing angle changes. The cornea itself is the engine's clearcoat lobe, which keeps one continuous specular highlight across the iris and the sclera. `iris_radius`, `pupil_radius` and `limbus_softness` shape the disc; `iris_texture` is sampled in the refracted frame, `sclera_texture` in the surface's own UVs.
▲ 0↑ born
✦
shader · born here
❒asset
# billboard Camera-facing billboard shader for textured quads — labels, sprites, and 3D text. All four corners of the quad sit at the same anchor, so the vertex's world position is the anchor under any entity or parent transform. Each corner carries its in-plane offset in the vertex colour; the vertex stage offsets the corner in world space facing whichever camera renders the pass, so the quad is visible and correctly framed from the main viewport, an offscreen capture, and a render-texture camera alike. Because the offset is applied in world space before projection, the quad keeps real extent and stays drawn when the anchor leaves the frustum. The horizontal axis stays world-level, so it tracks a pitching camera without rolling. The world size lives in the per-corner offset (resizing rebuilds the vertex colours), so there are no size material properties, and the mesh declares its own render bounds so frustum culling keeps it. The fragment mirrors `unlit`: `base_color * base_color_texture` with masked-transparency cutoff.
▲ 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
·
assettype · born here
❒asset
# Shader (asset type) A shader is a WGSL program that runs on the GPU. Materials reference shaders and supply property values; renderable entities reference materials, not shaders directly. This README is the canonical reference for writing **every** kind of shader — it covers all domains, the surface authoring contract, the material property schema, the engine library functions you can call, and how a shader registers and compiles. > New to how shaders, materials, meshes, and textures relate as assets and live > GPU resources? Read `core/resource-model` first. ## Folder shape A `.shader` is a folder asset: ``` <name>.shader/ shader.wgsl # the WGSL body (required) properties.yaml # the material property schema (optional; surface shaders) README.md # a one-paragraph description of THIS shader (required) .metadata # asset metadata ``` Each file carries a committed `.meta` sidecar pinning its stable guid. The identity is `<name>` (the `.shader` suffix strips). A shader's material properties are exactly the ones its `properties.yaml` declares: a shader with no `properties.yaml` declares none, and the engine reads no property from the WGSL body. A `.wgsl` file standing on its own, outside a `.shader` folder, is WGSL source rather than a shader: a material draws with the `.shader` folder that holds it as `shader.wgsl`. Materials and other assets reference a shader by **AssetRef** (a typed, guid-backed handle), never by a raw string. ## Domains The first line of `shader.wgsl` declares the domain: ```wgsl // @domain: surface ``` | Domain | What it is | You write | |---|---|---| | `surface` | A material on a mesh (the common case). | `fragment()` (+ optional `vertex()`/`vertex_clip()`). The engine generates everything else. | | `post-process` | A full-screen pass over the rendered frame, in the space it declares (bloom, vignette, grade). | `fragment(in: PostInput) -> vec4` only. The engine generates the fullscreen `vs_main`/`fs_main` and the group(1) interface from `properties.yaml`. | | `screen` | A standalone full-screen visual (UI background, procedural). | `fragment(in: ScreenInput) -> vec4` only. The engine generates the fullscreen `vs_main`/`fs_main` and the group(1) interface from `properties.yaml`. | | `sky` | The sky background (a fullscreen material). | `fragment(in: SkyInput) -> vec4` only. The engine generates the fullscreen `vs_main`/`fs_main` and the group(1) interface from `properties.yaml`. | | `compute` | GPU data processing, no rasterization. | An `@compute @workgroup_size(...)` entry over storage buffers; you write the `@group/@binding` lines yourself. For compute work, the `.computeShader` assetType (see below) generates them for you. | `// @domain:` resolves the names above and `postprocess` / `screenspace` / `ui` as further spellings of `post-process` and `screen`. A body carrying no `@domain:` line is `surface`. `shaderRef:domain()` answers the domain a body declares, a further spelling as the domain it names. Any other name is refused where the shader registers, with an error naming the spellings that resolve, so a shader reaches the renderer only under a domain the compiler scaffolds. Particles are drawn and simulated through these domains like anything else: the particle package's `particle_sprite` and `particle_mesh` are `surface` shaders, and its simulation, culling and sorting steps are `.computeShader` assets. ## Texture coordinate space A shader that samples a texture through a coordinate it builds itself declares which space that coordinate lives in, on a line beside `@domain:`: ```wgsl // @domain: surface // @uv_space: world ``` | Value | The coordinate | A material's `uv_scale` means | |---|---|---| | `mesh` (the default) | The mesh's own UV attribute, `input.uv`. | How many times the texture repeats across a surface. | | `world` | The fragment's world position, as a triplanar projection samples. | How many times the texture repeats per world unit, so a larger surface carries more. | Texture residency reads the declaration to work out how finely a frame samples each texture: a material laying eight copies of its texture across a surface samples each copy at an eighth of the surface's size, and the mip level that serves it is three levels coarser than the surface's own footprint implies. Leaving the line out puts the shader in mesh space, which is what sampling `input.uv` is. `renderer.textureStreaming().textures` reads back the span each texture was measured at and the level that span asked for. **Compute shaders have their own assetType.** A `.computeShader/` folder gives compute the same zero-scaffolding contract surface/sky/post/screen get: you write only `@compute fn main` (+ helper fns/structs, **no `@group/@binding` lines**) and declare bindings in a sibling `bindings.yaml` (storage buffers, textures, samplers, storage textures, plus a `params:` uniform); the engine generates the `@group(0)/@binding(N)` declarations. Dispatch it through a resolved reference (`asset.resolve("name", "computeShader"):dispatch(...)`). See the `.computeShader` assetType README and `man compute`. **Surface**, **sky**, **post-process**, and **screen** shaders all get engine-generated scaffolding — you write only `fragment()` and declare properties in `properties.yaml`; the engine generates the entry points and the group(1) material interface. (Each domain's `fragment` takes a domain-specific input instead of `FragmentData`: `SkyInput`, `PostInput`, or `ScreenInput` — see "Sky shaders" and "Post-process & screen shaders" below.) Compute shaders get the same treatment via the separate `.computeShader` assetType (write only `@compute fn main`, declare bindings in `bindings.yaml`). The `compute` domain here writes its own entry points directly — see `man compute`. ## Surface shaders A surface shader writes **only** the parts that are unique to it. The engine owns all the scaffolding — the vertex stage, every render-mode entry point (`vs_main` / `fs_forward` / `fs_gbuffer`), group(0) (camera, transforms, lights, shadows, and the material rows), and the material interface generated from `properties.yaml` (`material` and your texture slots). Adding a render path never touches your shader. Inside `fragment()` you have access to exactly four things — nothing is hidden: 1. **`input: FragmentData`** — the interpolated per-fragment surface data the engine hands you: world position, world normal, uv, view direction, vertex colour, and more. Every field is in the `FragmentData` table below. 2. **`material.*` and your textures** — the material inputs **you** declare in `properties.yaml`. The mapping is mechanical: a scalar property named `foo` becomes `material.foo`; a texture property named `bar` becomes `bar` (the texture) and `bar_sampler` (its sampler). `material` has **exactly** the fields your `properties.yaml` declares and no others — to add an input, add a property. List what a shader exposes with `shaderRef:getProperties()` or `asset.inspect("<name>")`. 3. **Engine state** — the scene's camera, lights, time, and shadows that the renderer binds for every surface shader. `uniforms.*` (sun direction/colour, ambient, `camera_pos`, `time`) and the punctual lights (`zero_point_light(i)`) are always in scope; the shadow functions come from `#include "@builtin::shaderModules.shadows"`. This is how you light a surface **without** the prebuilt PBR — see "Engine state" and "Writing your own shading" below. 4. **Library functions** you `#include` (see "Library includes"). A shader and its property schema go together. The two files below are a complete surface shader: `properties.yaml` — declares the material inputs: ```yaml properties: - { name: base_color, type: color, default: [1, 1, 1, 1] } - { name: roughness, type: float, default: 0.5, min: 0, max: 1 } - { name: metallic, type: float, default: 0.0, min: 0, max: 1 } - { name: base_color_texture, type: texture, default: white } ``` `shader.wgsl`; those declarations are read as `material.base_color`, `material.roughness`, `material.metallic`, and the `base_color_texture` / `base_color_texture_sampler` pair: ```wgsl // @domain: surface #include "@builtin::shaderModules.pbr_shading" // the PBR helpers — see "Library includes" fn fragment(input: FragmentData) -> vec4<f32> { var s = zero_pbr_default_surface(input); s.albedo = material.base_color.rgb * textureSample(base_color_texture, base_color_texture_sampler, input.uv).rgb; s.perceptual_roughness = material.roughness; s.metallic = material.metallic; return vec4<f32>(zero_pbr_shade(input, s), material.base_color.a); } ``` `fragment()` returns the final colour. The engine forces no lighting model on you — flat, toon, PS1, dithered, or PBR are all just different `fragment()` bodies. Calling `zero_pbr_shade` is opt-in. ### The two surface bodies, and what each gives up A surface shader exposes one of two entry points, and which one decides how much of the shader the engine can see: | Body | The engine gets | PBR debug passes read | |---|---|---| | `fn fragment(input: FragmentData) -> vec4<f32>` | the finished pixel, and the `PbrSurface` too when the body hands one to `zero_pbr_shade` | the real channel where a surface was handed over; magenta, the "no data here" marker, where the body shades by its own math | | `fn surface(input: FragmentData) -> PbrSurface` | the surface (albedo, roughness, metallic, emissive, normal, occlusion), which the engine then lights | the real channel | Both are first-class: `fragment()` is what you want when the shader owns its own look, `surface()` when you want engine lighting. `capture { pass = "albedo" }` (and `roughness` / `metallic` / `ao` / `emissive`) answers about your material for either body wherever the engine has the surface — writing the same `PbrSurface` behind `surface()` or behind `fragment()` + `zero_pbr_shade` gives one answer per channel. A body that lights itself by its own math draws those channels magenta. `pbr.shader` exposes `surface()`. `capture { pass = "normal" }` is a geometry read rather than a material one, so it answers for every shader: the normal of the surface where one was handed over, and the interpolated normal of the triangle where none was. It is the same normal the frame's normal buffer carries, which is what a screen-space pass reading `@scene.normal` sees. `shaderRef:shadingModel()` reports which one a shader ended up with — `"engine-lit"` for `surface()`, `"self-shading"` for `fragment()`. ### Optional vertex hooks ```wgsl // Displace geometry in OBJECT space. Runs on skinned meshes too (it sees the // already-skinned, morph-applied local position). Return the modified vertex. // The `v` parameter is immutable (WGSL function params are), so copy it into a // `var` first and modify that. fn vertex(v: VertexData) -> VertexData { var out = v; out.position += out.normal * sin(out.time) * 0.1; return out; } // Post-transform vertex hook (runs AFTER the engine's world/skin/projection). Two // things you can do here, separately or together: // * move `clip_position` — vertex jitter, PS1 snapping, render-resolution lowering; // * write `color` — PER-VERTEX (Gouraud) shading: light the vertex from its // world_normal + the light context and the engine forwards the result into the // interpolated `vertex_color` the fragment reads. fn vertex_clip(v: ClipVertex) -> ClipVertex { var out = v; // Gouraud: Lambert sun + ambient, evaluated once per vertex (flat-banded shading). let n_dot_l = max(dot(v.world_normal, -normalize(v.light_direction)), 0.0); let lit = v.ambient_color * v.ambient_intensity + v.light_color * v.light_intensity * n_dot_l; out.color = vec4<f32>(v.color.rgb * lit, v.color.a); out.clip_position = round(out.clip_position * 80.0) / 80.0; // PS1 snap return out; } ``` #### Geometry built per instance: grass, kelp, hair cards, debris `vertex()` knows which vertex of which instance it places: `VertexData.vertex_index` is the vertex's index in its mesh and `VertexData.instance_id` the instance's slot, whose lanes `zero_object_data(v.instance_id, lane)` reads. A hook can therefore build its geometry rather than displace it: a strip mesh drawn thousands of times by `renderer.mesh.drawInstanced`, each copy shaped, sized and bent from the lanes of its `instanceDataBuffer`, becomes a field of grass blades, kelp fronds or hair cards that sway with `v.time`. Being a surface shader, it is lit, shadowed (it casts the shape the hook built), motion-vectored and fogged like the rest of the scene. The rendering-instance-data guide (`guides { path = "topics/rendering-instance-data" }`) has a worked blade field; a render feature's raster pass (`types/rasterShader`) is the hand-written alternative, a vertex and fragment program with its own pipeline. #### Declaring how far a hook moves geometry: `vertexBoundsDilation` Static geometry is culled per cluster against its bounds as authored. A hook that moves vertices — wind sway, an outline hull, a vertex wave — can move them outside those bounds, and the cull then drops clusters whose displaced triangles are still on screen. Declare the farthest the hook moves any vertex, in world units, as a `vertexBoundsDilation` float property, with a default that covers the shader's own properties across their ranges: ```yaml properties: - { name: sway, type: float, default: 0.5, min: 0, max: 4 } # 0.4 x sway, at sway's largest value. - { name: vertexBoundsDilation, type: float, default: 1.6, min: 0, max: 100 } ``` Each material sets its own value — a material that sways less can set less, one moved farther sets more — and a material that sets none takes the default. The cull adds the material's value to every bound in its frustum and occlusion tests (not to the level-of-detail cut). A shader with a hook and no `vertexBoundsDilation` property is named once in the engine log when it compiles; its geometry is culled against its undisplaced bounds. ### Structs the engine passes you `FragmentData` (input to `fragment()`): | Field | Type | Meaning | |---|---|---| | `world_position` | `vec3<f32>` | fragment world-space position | | `world_normal` | `vec3<f32>` | interpolated geometric normal (normalized) | | `world_tangent` | `vec4<f32>` | xyz = world tangent, w = handedness (mikktspace) | | `uv` | `vec2<f32>` | primary texture coordinates (perspective-correct) | | `affine_uv` | `vec2<f32>` | the same UVs interpolated **without** perspective correction — the PS1 texture "swim". Always available; sample with it instead of `uv` for affine texture mapping | | `vertex_color` | `vec4<f32>` | interpolated per-vertex colour (white if unset; carries per-vertex lighting if `vertex_clip()` wrote it — see Gouraud below) | | `view_position` | `vec3<f32>` | camera world position | | `view_direction` | `vec3<f32>` | normalized world-space direction the camera sees this point from: toward the camera's position under a perspective projection, against its forward axis (the same for every point) under an orthographic one | | `light_direction` | `vec3<f32>` | directional (sun) travel direction, unit length; surface→sun is `-light_direction`. Where no sun reaches the camera it points straight down | | `light_color` | `vec3<f32>` | sun colour | | `light_intensity` | `f32` | sun intensity; 0 where no sun reaches the camera | | `ambient_color` | `vec3<f32>` | ambient colour | | `ambient_intensity` | `f32` | ambient intensity as it reaches this pixel: the scene's ambient occlusion is already in it (times `ambient_visibility`), so a crease darkens under the ambient with no work in the shader | | `ambient_visibility` | `f32` | the share of the light of its surroundings that reaches this pixel: 1 minus the scene's ambient occlusion here, 1 where nothing occludes it. Multiply it into any light of the surroundings you gather yourself (a sky colour, a reflection-probe or environment sample); `ambient_intensity` already carries it. `zero_scene_bent_normal(input.frag_coord.xy, n)` names the direction the open part of the hemisphere faces, `n` where no pass wrote one | | `frag_coord` | `vec4<f32>` | framebuffer pixel coords (xy) + depth (z) — for screen-space dither | | `receives_shadows` | `f32` | per-instance: > 0.5 if this surface receives shadows | | `material_index` | `u32` | per-instance: the index standing for the material this surface draws with — the number `renderer.materialIdentity()` maps to a name | | `shader_data` | `array<vec4<f32>, 4>` | per-instance: this entity's own four `vec4` lanes — its `ecs.ShaderData` component's `lane0`..`lane3`, or what `renderer.instanceData.set` put in them (zero until something does). A procedural graph's elements set them through the `data0`..`data3` attributes | | `front_facing` | `bool` | true for front faces (double-sided shading) | | `time` | `f32` | gameplay seconds: advances with the world at `engine.timeScale` and stands still while gameplay is paused (edit mode starts paused), so an effect slows and stops with the world | `shader_data` is the per-instance channel, and it is what lets ONE material serve many entities that differ in a value — a dissolve at its own progress per subject, a hit flash at its own age, a fill level per instance. The alternative is a material per entity, which is a separate pipeline binding and a separate row in the material table for every one of them. ```wgsl const DISSOLVE_LANE: u32 = 0u; fn fragment(input: FragmentData) -> vec4<f32> { let progress = input.shader_data[DISSOLVE_LANE].x; ... } ``` ```lua -- one material on twenty entities, each at its own progress renderer.instanceData.set(subject, 0, progress) renderer.instanceData.clear(subject) -- back to zero lanes ``` The engine attaches no meaning to a lane: a shader and whatever writes it agree what each one carries. Name the indices in the module that writes them. `renderer.instanceData.laneCount()` is how many there are. The same lanes reach a hardware-instanced population through `renderer.mesh.drawInstanced`'s `instanceDataBuffer`, on slots no entity owns. `VertexData` (in/out of `vertex()`): `position` (object-local, model-scale + morph applied), `normal`, `uv`, `color`, `time`, and which vertex of which instance it is: `instance_id` (`u32`, the instance's slot — `zero_object_data(v.instance_id, lane)` reads the lanes the fragment gets as `shader_data`) and `vertex_index` (`u32`, the vertex's index in its mesh). Both hold the same values in the colour pass, the depth views, every shadow page and the previous-frame evaluation, so geometry a hook builds from them — a blade placed and bent by its instance's lanes, a strip shaped by its vertex's index — lands in the same place in each. The rendering-instance-data guide has a worked blade field. `ClipVertex` (in/out of `vertex_clip()`) — the post-transform vertex. Read context: `clip_position`, `world_position`, `world_normal`, `uv`, `view_position`, `view_direction`, `light_direction`, `light_color`, `light_intensity`, `ambient_color`, `ambient_intensity`, `time`, `view_proj` (the view-projection of the frame being evaluated), and where the vertex stands on its instance: `local_position` (its position in the mesh, after `vertex()` and before the instance's world transform), `object_origin` (the world position of the instance's origin), `object_scale` (the world length of the instance's x, y and z axes) and `object_axes` (`mat3x3<f32>`, the world direction of those axes, unit length) — what a camera-facing card, a shard grown about its own base, or anything placed per instance is built from. **Writable:** `clip_position` (snap / jitter) and `color` (write a lit colour here for per-vertex Gouraud shading; the engine forwards it to the interpolated `vertex_color` — left untouched, the mesh's own vertex colour passes through). `vertex()` and `vertex_clip()` run in the vertex stage, which reads the frame uniforms (`uniforms.*`, and the `ClipVertex` members built from them), the scene buffer (`zero_object_data`, `zero_object_visuals`, the node transforms), the material interface and a `read` buffer property. The point, spot and area lights (`zero_point_light`, `zero_punctual_projection`), the shadow maps, the environment and light probes, the feature textures, the scene depth, colour and reflection copies and a `@group(2)` buffer the shader declares `read_write` are visible to the fragment stage alone: read them in `fragment()` or `surface()`. A shader whose vertex hook reaches one fails to compile, and the error names the stage, the binding and the calls that reach it. ### Each hook runs twice: this frame and the one before it A vertex hook decides where the surface IS, so it also decides where the surface WAS. The engine runs every hook a shader declares a second time, over the same vertex standing one frame back — the previous-frame position stream, with `time` = the clock that frame was drawn at and (for `vertex_clip()`) `view_proj` = the view-projection it was drawn with. The motion vector the renderer publishes is taken between the two results, so a displacement that moves with time reports the velocity of the displaced surface, and a displacement that does not move reports the motion of the transform alone because the identical offset appears on both evaluations and cancels. What that asks of a hook: - **Take the frame from the argument.** `v.time` is the clock of the evaluation being run; `uniforms.time` is always this frame's. A displacement built on `uniforms.time` is identical on both evaluations, so its motion vector cancels to exactly zero. The same holds for `v.view_proj` against `uniforms.view_proj`: a clip hook that rebuilds its position from world space through `uniforms.view_proj` reprojects the previous frame with this frame's camera, and reports no camera motion at all. The wind helpers come in both shapes for this reason — `zero_wind_sway_at_time(world_pos, stiffness, v.time)` inside a hook, `zero_wind_sway(world_pos, stiffness)` outside one. - **Anchor a wrap to `uniforms.time`.** A displacement that jumps discontinuously — a falling drop that restarts at the top, a looping offset — differences its jump as velocity on whichever frame it wraps. Compute the wrap COUNT from `uniforms.time` and the position within the cycle from `v.time`, and both evaluations share the same cycle, so the surface reports the speed it fell at. `@builtin::shaders.rain_material` and `snow_material` do exactly that. The per-vertex attributes (`world_normal`, `uv`, `color`) and the lighting and camera-position context are this frame's on both evaluations, so a hook that displaces along its normal reports the motion of the transform plus this frame's displacement. ## Engine state — point lights & shadows The common lighting state — the sun (`input.light_direction` / `light_color` / `light_intensity`), the ambient (`input.ambient_color` / `ambient_intensity`), the camera (`input.view_position` / `view_direction`), and `input.time` — is already on `FragmentData`, so most shaders never touch the raw engine state. The one thing not on `FragmentData` is the punctual-light array (its length varies), which is always in scope. A scene can hold up to 1024 lights, so a fragment walks the ones the light grid lists where it stands, which hold every light that can reach it: | Expression | Type | Meaning | |---|---|---| | `zero_lights_near(world_pos)` | `ZeroLightsNear` | the lights that can reach a fragment at `world_pos`; `.count` of them | | `zero_light_near(near, k)` | `u32` | the index of the `k`th of them, for `zero_point_light` | | `uniforms.point_light_count` | `u32` | number of lights the frame shades under, every one of them | | `zero_point_light(i)` | `PointLightData` | one point or spot light (fields below) | | `zero_punctual_projection(i)` | `PunctualProjection` | a spot or area light's projection: `view_proj`, the frustum its cookie and shadow are placed by, and `cookie_layer` | `PointLightData`: `position`, `radius`, `color`, `intensity`, `direction`, `cone_outer_cos`, `cone_inner_cos`, `kind` (0 = point, 1 = spot). Shadows come from `#include "@builtin::shaderModules.shadows"`: - `compute_directional_shadow_factor(world_pos, normal, light_dir) -> f32` — 1.0 lit, 0.0 fully shadowed. - `compute_spot_shadow_factor(...)` / `compute_point_shadow_factor(...)` / `compute_area_shadow_factor(...)` — one shadow shape each. - `compute_punctual_shadow_factor(light_index, world_pos, normal) -> f32` — the row's own shape, read off its `kind`, for a loop that walks the punctual lights and does not want the switch. - `zshadow_light_reach(light_index, world_pos, normal, object_channels) -> f32` — how much direct light that row puts on a surface on those light channels: the channel mask, falloff, cone or rect orientation, and the cosine, times intensity. Zero exactly where the light contributes nothing. ## Writing your own shading The engine forces no lighting model — `zero_pbr_shade` is just one option. You can light a surface yourself from the state above. Here is a complete custom-lit (Lambert diffuse) surface with no PBR: ```wgsl // @domain: surface #include "@builtin::shaderModules.shadows" // exposes compute_directional_shadow_factor fn fragment(input: FragmentData) -> vec4<f32> { let n = normalize(input.world_normal); let albedo = material.base_color.rgb; // Directional (sun) light: Lambert N·L, attenuated by its shadow. let sun = normalize(-input.light_direction); // surface -> sun let sun_shadow = compute_directional_shadow_factor(input.world_position, n, input.light_direction); var lit = input.light_color * input.light_intensity * max(dot(n, sun), 0.0) * sun_shadow; // Point + spot lights: the ones that can reach this fragment. let near = zero_lights_near(input.world_position); for (var k = 0u; k < near.count; k = k + 1u) { let pl = zero_point_light(zero_light_near(near, k)); let to_light = pl.position - input.world_position; let dist = length(to_light); let l = to_light / max(dist, 1e-4); let atten = max(1.0 - dist / max(pl.radius, 1e-4), 0.0); lit += pl.color * pl.intensity * max(dot(n, l), 0.0) * atten; } // Ambient fill, with the scene's ambient occlusion already in it. lit += input.ambient_color * input.ambient_intensity; return vec4<f32>(albedo * lit, material.base_color.a); } ``` - **Unlit:** skip the lights and return your colour directly. - **Toon / PS1 / custom:** start from the loop above and band, quantize, or warp it however you like. - **PBR:** build a `PbrSurface` and call `zero_pbr_shade` (see "Library includes") instead of writing the BRDF by hand. ## Material properties — `properties.yaml` A surface shader declares its material properties in a sibling `properties.yaml`. The engine GENERATES the entire group(1) interface from it — the uniform struct (`material.<name>`) plus a texture/sampler pair per declared texture. You write no `@group`/`@binding` lines. ```yaml properties: - { name: base_color, type: color, default: [1, 1, 1, 1] } - { name: roughness, type: float, default: 0.5, min: 0, max: 1 } - { name: metallic, type: float, default: 0.0, min: 0, max: 1 } - { name: emissive, type: color, default: [0, 0, 0, 1] } - { name: base_color_texture, type: texture, default: white } - { name: normal_texture, type: texture, default: flat_normal } ``` | `type` | WGSL field type | Notes | |---|---|---| | `float` | `f32` | optional `min`/`max` for editor sliders | | `float2`/`float3`/`float4` | `vec2/3/4<f32>` | | | `color` | `vec4<f32>` | linear RGB colour and alpha, default is `[r,g,b,a]`; the shader reads it as written | | `int` | `i32` | | | `bool` | `u32` | | | `texture` | `texture_2d<f32>` + `sampler` | `default:` is a built-in texture name (`white`, `black`, `flat_normal`) | A `color` holds linear RGB, the space lighting is computed in, the way `base_color` multiplies a colour texture's linear sample. A colour picked from a picture or written as a hex code is sRGB, and written as it is it reads paler and less saturated than picked: convert it first, `color.toLinear(assert(color.hex("#ff8800")))` (`{ r, g, b, a }`: `#ff8800` is `{ r = 1, g = 0.246, b = 0, a = 1 }`), and write that. In the shader you read scalars as `material.<name>` and sample textures as `textureSample(<name>, <name>_sampler, uv)`. A texture slot with no bound texture samples its default, so a shader can always sample — no presence flag needed. `vertex()` reads the same material interface, so a height or deformation map drives displacement from the slot it was bound to. A vertex stage has no implicit derivatives, so sample it at an explicit mip there: `textureSampleLevel(<name>, <name>_sampler, uv, 0.0)`. ## Sky shaders A `// @domain: sky` shader draws the sky as a fullscreen pass. You write **only** `fn fragment(in: SkyInput) -> vec4<f32>` — the colour along the view ray for each pixel — and declare tunables in `properties.yaml` exactly like a surface shader (read as `material.<name>`, textures via `textureSample(<name>, <name>_sampler, uv)`). The engine generates the fullscreen `vs_main`/`fs_main`, the group(1) interface, and reconstructs the world-space ray; there is no separate sky renderer — a sky material runs through the same material pipeline, just on a fullscreen triangle. A sky pipeline binds group(0) and the group(1) interface alone, so a sky that reads a `buffer` property or any other `@group(2)` binding fails to compile, and the error names the binding and the calls that reach it. `SkyInput` (the only argument) carries: | Field | Type | Meaning | |---|---|---| | `ray_dir` | `vec3<f32>` | normalized world-space ray through this pixel | | `ndc` | `vec2<f32>` | screen position in NDC `[-1, 1]` | | `sun_direction` | `vec3<f32>` | unit vector TOWARD the sun (from the directional light) | | `camera_pos` | `vec3<f32>` | world-space camera position | | `time` | `f32` | gameplay seconds: advances with the world at `engine.timeScale` and stands still while gameplay is paused (edit mode starts paused), so an effect slows and stops with the world | | `constants` | `SkyConstants` | what the shader's `sky_constants()` returned for this draw (zeros when it declares none) | ```wgsl // @domain: sky fn fragment(in: SkyInput) -> vec4<f32> { let up = max(in.ray_dir.y, 0.0); let col = mix(material.horizon_color.rgb, material.zenith_color.rgb, up); return vec4<f32>(col * material.exposure, 1.0); } ``` Day/night comes from `sun_direction.y` (the directional light's elevation), so a sky shader never needs a time-of-day uniform — orient the light and the sky follows. The builtin sky shaders (`procedural_sky`, `solid_sky`, `cubemap_sky`, `equirect_sky`) are all authored this way; author a custom sky material and point a `Skybox` component at it. `fragment()` runs once for every pixel of the view and every texel of each environment-capture face. A value that holds for the whole draw (a colour mixed from the material and the sun's elevation, a `cos` of an angular size, an exponent derived from a property) goes in an optional `fn sky_constants(in: SkyConstantsInput) -> SkyConstants`, which the generated vertex stage evaluates once per draw. `fragment()` reads its result as `in.constants`. `SkyConstantsInput` carries `sun_direction`, `camera_pos` and `time` (the same values `SkyInput` holds), `sky_constants()` reads the material as `material.<name>` like `fragment()`, and `SkyConstants` is eight `vec4<f32>` slots, `v0` to `v7`, packed however the sky likes: ```wgsl // @domain: sky fn sky_constants(in: SkyConstantsInput) -> SkyConstants { let day = clamp(in.sun_direction.y * 2.0, 0.0, 1.0); var c: SkyConstants; c.v0 = vec4<f32>(mix(vec3<f32>(0.02), material.zenith_color.rgb, day), day); c.v1 = vec4<f32>(mix(vec3<f32>(0.01), material.horizon_color.rgb, day), 0.0); return c; } fn fragment(in: SkyInput) -> vec4<f32> { let up = max(in.ray_dir.y, 0.0); return vec4<f32>(mix(in.constants.v1.rgb, in.constants.v0.rgb, up), 1.0); } ``` A branch on an `in.constants` value is taken or skipped by every pixel of the draw together, so a term that only contributes some of the time (stars at night) costs nothing while it is off. The vertex stage has no implicit derivatives, so a texture read in `sky_constants()` is `textureSampleLevel`. ## Post-process & screen shaders `// @domain: post-process` and `// @domain: screen` shaders are authored exactly like surface and sky — you write **only** `fn fragment(in: PostInput) -> vec4<f32>` (post) or `fn fragment(in: ScreenInput) -> vec4<f32>` (screen) and declare tunables in `properties.yaml` (read as `material.<name>`, textures via `textureSample(<name>, <name>_sampler, uv)`). The engine generates the fullscreen `vs_main`/`fs_main` and the group(1) material interface. **There are no `uniforms.params[i]` slots** — that convention is retired; every input is a named property. A **post-process** shader's `properties.yaml` carries one further, top-level key beside `properties:` — `space`, either `light` (the default) or `display`: ```yaml space: display properties: - { name: amount, type: float, default: 1.0, min: 0, max: 1 } ``` `light` is the scene's linear radiance — what every surface, the sky and every `afterLighting` feature write, unbounded above 1.0. `display` is the code values the `__display__` pass leaves behind after applying exposure and its tone curve — the 0-1 range a colourist's tool and a dithered or quantized effect expect. `postprocess.add`'s `opts.space` overrides what the asset declares for one registration. The chain converts at both ends of an effect that runs on a segment in the other space, so a light-space vignette still darkens a frame graded after `__display__`, and a lookup table built from a `.cube` export always sees the code values it was authored against, wherever the chain runs it. `space` also decides which layer a registration that names none lands on: a `light` shader grades `scene`, the segment holding the scene's own light, and a `display` shader grades `display`, the picture after `__display__` and before the UI lands on it. So `postprocess.add("glow", asset.resolve("~.shaders.bloom", "shader"))` thresholds highlights that still stand above 1.0, and a lookup table registered the same way reads the code values it was built for and leaves every screen in the colours it declares. `opts.layer` names one explicitly — `"all"`, after the UI, is what an effect that must grade the interface says. A post-process shader may also declare the post stage of the frame it runs in, `stage:` — `optics` (the `scene` layer), `display` (the `display` layer) or `ui` (the `all` layer); `renderer.post.stages()` lists every stage with the colour space and resolution its picture is held in. A registration takes the declared stage unless `opts.stage` or `opts.layer` names another seam, and a stage the frame does not have, or one only render features run in, is refused naming the stages there are: ```yaml space: display stage: display properties: - { name: amount, type: float, default: 1.0, min: 0, max: 1 } ``` A **post-process** shader's `properties.yaml` carries a further, optional top-level key — `passes:`, the pass list the frame draws through, in order: ```yaml space: light passes: - { name: bright, entry: bright, scale: 0.5, inputs: [scene] } - { name: down1, entry: downsample, scale: 0.25, inputs: [bright] } - { name: up0, entry: upsample, scale: 0.5, inputs: [down1, bright] } - { name: composite, entry: composite, inputs: [scene, up0] } ``` Every pass's entry — `fn <entry>(in: PostInput) -> vec4<f32>` — lives in the one `shader.wgsl` the assetType recompiles on. `scale` is the fraction of the view a pass draws at; the LAST pass takes none, since it draws at the view's size and writes the chain's output. `inputs` names what a pass reads — `"scene"`, the chain's input for this effect, or the name of an EARLIER pass — and `inputs[0]` is what `zero_sample_scene(uv)` reads inside that pass's body; every input, `inputs[0]` included, is also reachable by index through `zero_pass_input(i, uv)` and `zero_pass_input_size(i)`, below. The one place the two reads of `inputs[0]` disagree: in an effect whose declared space differs from the segment it draws on, `zero_sample_scene` converts a `scene` input into that space while `zero_pass_input(0, uv)` hands back the segment's own, unconverted value. A shader declaring no `passes:` is one pass whose entry is `fragment`, and its generated WGSL is byte-identical to what it is without the key. A pass that is not the last writes a scratch target the effect owns — in the space the shader declared, view-sized times its own `scale` — allocated on the first draw and replaced whenever the size changes. `engine.params`, below, carries the drawing pass's own index, its scale, and its first input's texel size, so one shader body serves every level of a chain built this way. The worked example is the bloom: `@builtin::shaders.post.bloom` declares twelve passes — a threshold pass, five downsamples, five tent upsamples and a composite — out of four entries, since the five downsamples share one and the five upsamples share another, each level reading the one below it through `zero_pass_input` and telling itself apart by `engine.params`. Its own README walks the declaration. A declaration is refused at compile time — reported through `compileStatus()`, `postprocess.add`'s second return value, or a live effect's `status()[i].error` — for: an entry `passes:` names that `shader.wgsl` does not define; an input naming a later pass, or naming neither `scene` nor an earlier pass; a `scale` outside `(0, 1]`; a `scale` declared on the last pass; a `buffer` property (group(2) carries the pass inputs); or a shader whose group(0) plus declared texture slots plus widest pass's inputs ask for more than the 16 FRAGMENT sampled textures one shader stage has. A **post-process** shader runs as a full-screen pass over the already-rendered frame. Its `fragment` argument and framework helpers: `PostInput`: | Field | Type | Meaning | |---|---|---| | `frag_coord` | `vec4<f32>` | framebuffer pixel coords (`@builtin(position)`) | | `uv` | `vec2<f32>` | screen UV, `(0,0)` top-left … `(1,1)` bottom-right | Framework helpers (always in scope — no include needed): | Call | Returns | Meaning | |---|---|---| | `zero_sample_scene(uv)` | `vec4<f32>` | the rendered scene colour at `uv`, converted into the space this effect declared (`zero_scene_light` is the same call, for content that reads it by that name) | | `zero_scene_depth(uv: vec2<f32>)` | `f32` | scene depth at `uv` — a screen UV here, where the surface domain's `zero::scene_depth` module takes a pixel coordinate under the same name (exact texel — an R32Float copy). Reversed: 1.0 is the near plane, 0.0 the far plane and empty sky, so a nearer surface reads GREATER and `d > 0.0` means "a surface was drawn here" | | `zero_linear_depth_through(d, near, far, engine.view_proj)` | `f32` | that sample as a distance in metres along the camera's view axis, under a perspective or an orthographic camera — the one inversion of the reversed range (`zero_linear_depth(d, near, far)` is its perspective case alone) | | `zero_scene_motion(uv)` | `vec2<f32>` | per-pixel screen-space motion vector at `uv` | | `zero_pass_input(i, uv)` | `vec4<f32>` | the pass's declared input `i`, at `uv`. Input 0 is what `zero_sample_scene` reads | | `zero_pass_input_size(i)` | `vec2<f32>` | that input's size in texels, so one entry serves every level of a chain | | `zero_display_exposure()` | `f32` | the exposure in force: the gain `__display__` multiplies the scene's light by before its curve, the value this frame's display pass draws with (1 where the chain carries none). Light times it is light in the units the picture shows it at, so a threshold judged against `light * zero_display_exposure()` picks the same highlights at every exposure | Engine data uniform `engine` (a `PostEngineData`): | Field | Type | Meaning | |---|---|---| | `resolution` | `vec4<f32>` | `x`=width, `y`=height, `z`=1/width, `w`=1/height | | `time` | `vec4<f32>` | `x`=elapsed seconds, `y`=dt, `z`=frame index | | `view_proj` | `mat4x4<f32>` | this frame's view-projection | | `prev_view_proj` | `mat4x4<f32>` | last frame's view-projection (motion) | | `inv_view_proj` | `mat4x4<f32>` | inverse view-projection (world-space reconstruction) | | `params` | `vec4<f32>` | `x`=this pass's own index, `y`=the scale it draws at, `zw`=1/size of its first input — for a pass the post-process chain draws. A pass a `renderFeature` fragment pass draws carries that feature's `spec.params` here instead; a shader declaring `passes:` is always drawn by the chain, so the two never meet in one shader. | | `exposure` | `vec4<f32>` | `x`=the exposure in force (what `zero_display_exposure()` reads) | The engine fills all of it **per render target**. A registered effect runs over the live viewport's frame AND over every offscreen one — a `capture` from a world-space station or orbiting an entity, a capture of a named camera, a render-to-texture camera — and in each of those, `view_proj`, `prev_view_proj` and `inv_view_proj` are the camera THAT render was drawn from, while `resolution` is that target's own pixel size. So a pass reconstructing world space from `zero_scene_depth(uv)` reconstructs against the station and lens the capture asked for, and an offscreen frame is a picture of the effect as it stands at that station. (A render feature's passes reach an offscreen render the same way, against the same camera — the `renderFeature` assetType README carries that half, including `@frame.camera`, its own per-target camera input.) An offscreen render keeps no view history of its own, so `prev_view_proj` there holds that same matrix rather than the frame before it, and a pass taking camera motion from the two reads none. On the viewport the pair is a frame apart, so camera motion is the one reading a capture answers differently from the screen. `postProcessing = false` on a capture is the one control that takes the chain off the frame it returns; it names the camera property the ephemeral capture camera is built with, so it scopes to that one capture. What a capture opts out of is the registered effects; `__display__` still runs on it, so the exposure and tone curve that turn the scene's light into a picture are on what a capture returns. A diagnostic capture (`albedo`, `normal`, `motion_vectors`, …) bypasses `__display__` itself, since a channel like that is a reading of the scene rather than a graded picture of it. The environment-cube capture bypasses it too, and for the same reason: a probe face carries radiance into the cube array, and `__display__` would fit that radiance to a display's code values — a picture of it rather than the value the PBR indirect term multiplies into its lighting. A complete post-process effect — a vignette via `fragment()` + `properties.yaml`: `properties.yaml`: ```yaml properties: - { name: intensity, type: float, default: 0.5, min: 0, max: 1 } - { name: radius, type: float, default: 0.75, min: 0, max: 1 } - { name: softness, type: float, default: 0.45, min: 0, max: 1 } ``` `shader.wgsl`: ```wgsl // @domain: post-process fn fragment(in: PostInput) -> vec4<f32> { let color = zero_sample_scene(in.uv); let intensity = max(material.intensity, 0.01); let radius = max(material.radius, 0.01); let softness = max(material.softness, 0.01); let center = in.uv - vec2<f32>(0.5); let dist = length(center); let vignette = smoothstep(radius, radius - softness, dist); let darkened = color.rgb * mix(vec3<f32>(1.0), vec3<f32>(vignette), intensity); return vec4<f32>(darkened, color.a); } ``` The asset above **defines** the effect. It enters the frame when something registers it: ```luau postprocess.add("vignette", asset.resolve("~.shaders.vignette", "shader"), { priority = 200 }) ``` The registration names no layer, so the effect grades the layer its `space` belongs to: this vignette reads light, so it runs on `scene`, over the picture before the UI reaches it. Registering it is the one step that makes it render, so a world's chain holds exactly the passes its content asked for. Editing the shader body afterwards recompiles every effect registered from it, in place — the pass keeps its enabled state, priority, layer, tuned property values and bound textures, and draws the new pixels on the next frame. `postprocess.remove(name)` takes it back out of the chain and leaves the asset alone. Drive the named properties at runtime with `postprocess.setProperty(name, prop, value)` and bind texture properties with `postprocess.setTexture(name, prop, path)` (both keyed by the **property name**, never a slot index — see the post-process section of `man shaders` / the `postprocess.*` API). Read them back with `postprocess.describe(name)`: it carries the chain state `postprocess.status()` lists for that effect, the `properties` schema it was registered with, and the `values` each of those properties currently holds. Before the effect exists, `shaderRef:getProperties()` on the asset names the same schema, so what a pass takes is answerable either side of the registration. A **screen** shader is a standalone full-screen visual (UI background, procedural pattern). `ScreenInput` mirrors `PostInput` (`frag_coord` + `uv`); there is no scene to sample, so it has no `zero_sample_scene` helpers. Its `engine` uniform is a `ScreenEngineData`: | Field | Type | Meaning | |---|---|---| | `time` | `f32` | gameplay seconds: advances with the world at `engine.timeScale` and stands still while gameplay is paused (edit mode starts paused), so an effect slows and stops with the world | | `scroll` | `f32` | UI scroll offset | | `resolution` | `vec2<f32>` | render-target size in pixels | | `mouse` | `vec2<f32>` | mouse position | | `velocity` | `f32` | scroll velocity | ```wgsl // @domain: screen fn fragment(in: ScreenInput) -> vec4<f32> { let t = engine.time * 0.5; let col = vec3<f32>( sin(in.uv.x * 3.14159 + t) * 0.5 + 0.5, sin(in.uv.y * 3.14159 + t * 0.7) * 0.5 + 0.5, material.brightness ); return vec4<f32>(col, 1.0); } ``` ## Library includes A library module is a **`.shaderModule` asset**: it only EXPOSES functions and structs and does nothing on its own (exactly like a Unity `.cginc`). You must call what you include. Include one by its identity, the same string you would hand `asset.resolve`: | Include | Exposes | |---|---| | `@builtin::shaderModules.pbr_shading` | `struct PbrSurface { albedo, normal (world), metallic, perceptual_roughness, emissive, occlusion }`; `zero_pbr_default_surface(FragmentData) -> PbrSurface`; `zero_pbr_shade(FragmentData, PbrSurface) -> vec3<f32>` (the full forward PBR lighting); `zero_pbr_indirect_visibility(FragmentData, PbrSurface) -> ZpbrIndirectVisibility` (the share of the surroundings' light each indirect lobe takes from the scene's ambient occlusion: `diffuse` with the light a crease bounces back, `specular` from the open cone around the bent normal); `zero_pbr_shade_with_visibility(FragmentData, PbrSurface, ZpbrIndirectVisibility) -> vec3<f32>` (the same lighting with that share stated by the caller) | | `@builtin::shaderModules.shadows` | `compute_directional_shadow_factor(...)`, `compute_spot_shadow_factor(...)`, `compute_point_shadow_factor(...)`, `compute_area_shadow_factor(...)`, `compute_punctual_shadow_factor(...)`, `zshadow_light_reach(...)`; each light's `_with_kernel` form takes a shared `ZShadowKernel` (`zshadow_kernel()`) so several lookups of one fragment derive its filter rotation once | | `@builtin::shaderModules.engine_bindings` | the group(0) declarations (camera, transforms, lights, shadow maps) — surface shaders get this implicitly; include it directly only for advanced raw access | | `@builtin::shaderModules.shadow_bias` | `zshadow_offset_receiver(...)`, `zshadow_directional_depth_bias(...)` and the rest of the bias math, as pure functions | | `@builtin::shaderModules.texturing` | `ztex_stochastic(...)` (tile without a visible repeat grid), `ztex_blend_normals(...)` (reoriented normal blending) | | `@builtin::shaderModules.depth` | `zero_linear_depth_through(depth, near, far, view_proj)` — the one reading of a stored depth, for the projection the view-projection states; `zero_linear_depth` and `zero_linear_depth_orthographic` are its two cases | | `@builtin::shaderModules.ambient_light` (`zero::ambient_light`) | `zpbr_surroundings_irradiance(world_pos, n, flat_ambient)` (the diffuse light the surroundings hand a surface with normal `n`: the flat ambient, the captured sky and reflection probes, and the baked light-probe volumes, as the PBR model reads it) and `zpbr_surroundings_in_scatter(world_pos, flat_ambient)` (that light averaged over every direction: what a participating medium scatters). A compute pass binds `environment_map`, `environment_sampler` and `zero_environment` to `@scene.environment`, `@scene.environmentSampler` and `@scene.reflectionProbes` | | `@builtin::shaderModules.gbuffer_material` (`zero::gbuffer_material`) | `struct ZeroGbufferMaterial { base_color, metallic, perceptual_roughness }`; `zero_gbuffer_unpack_material(texel: vec4<u32>) -> ZeroGbufferMaterial`; `zero_gbuffer_material(t: texture_2d<u32>, coord: vec2<i32>) -> ZeroGbufferMaterial`, `zero_gbuffer_base_color`/`zero_gbuffer_metallic`/`zero_gbuffer_roughness(t, coord)` — the one unpacking of `@scene.material`'s `Rgba8Uint` texel into what a surface reflects | | `zero::scene_depth` | `zero_scene_depth(px: vec2<f32>)`, `zero_scene_depth_uv(uv: vec2<f32>)`, `zero_scene_depth_texel(px: vec2<i32>)`, `zero_scene_depth_size()`, `zero_scene_depth_is_sky(d: f32)`, `zero_scene_world_position(px: vec2<f32>)`, `zero_scene_world_normal(px: vec2<f32>)`, `zero_scene_depth_fade(px: vec2<f32>, world_position: vec3<f32>, fade_distance: f32)` — every `px` is a pixel coordinate in two components, so a surface fragment passes `input.frag_coord.xy`, not the `vec4<f32>` `FragmentData.frag_coord` holds. The depth already drawn UNDER a surface fragment, and the world position and geometric normal of the surface standing there. What a decal projector box, a soft particle, a forcefield or water intersection foam shades against. Surface domain; the depth belongs to the view being drawn | | `zero::scene_color` | `zero_scene_color(px: vec2<f32>)`, `zero_scene_color_uv(uv: vec2<f32>)`, `zero_scene_color_texel(px: vec2<i32>)`, `zero_scene_color_size()`, `zero_scene_color_refract(px: vec2<f32>, offset_px: vec2<f32>)`, `zero_scene_color_refract_uv(px: vec2<f32>, offset_fraction: vec2<f32>)` — every `px` is a pixel coordinate in two components, so a surface fragment passes `input.frag_coord.xy`, not the `vec4<f32>` `FragmentData.frag_coord` holds. The scene colour already composed BEHIND a surface fragment, and the displaced read that bends it. What heat haze, a refraction shockwave, a cloaking or shield warp, glass and ice shade with. Surface domain; the colour belongs to the view being drawn, and is the lit opaque scene as it stood immediately before the transparent pass — so a `blend`-queue surface reads this frame's, an opaque one reads the previous frame's, and two overlapping blended surfaces both read the same picture and do not bend each other | | `zero::projection` | `zero_projection_is_orthographic(view_proj: mat4x4<f32>) -> bool`, `zero_projection_parallel_ray(view_proj: mat4x4<f32>) -> vec3<f32>`, `zero_projection_view_direction(view_proj: mat4x4<f32>, camera_position: vec3<f32>, world_position: vec3<f32>) -> vec3<f32>`: what a view-projection states about how it projects: whether it is orthographic, the direction an orthographic one sees along (pointing back toward the camera), and the direction a camera sees a world point from under either projection, the value `FragmentData.view_direction` holds. Pure math with no bindings, so a surface, post-process or compute shader passes the view-projection it holds (`uniforms.view_proj`, `engine.view_proj`, or a uniform of its own) | `asset.list("shaderModule")` enumerates the `.shaderModule` assets in this engine, builtin and world-authored alike, and each one's README says what it exposes. Those are the `@builtin::shaderModules.*` rows above; a module you write is included exactly the same way, by its own identity or by the `~.name` form. The `zero::`-named rows come from the renderer itself. Their WGSL is baked into the engine binary and registered under those names before any asset exists, so they answer an `#include` in every engine and appear in no asset index. A shader that includes one records no dependency on it: the engine reading the shader is the engine that already holds the module. Two spellings reach the same `.shaderModule`: a module's declared alias answers as well as its identity, so a shader written against `zero::pbr` compiles and pins the asset that name resolves to. Prefer the identity: it says which asset travels with the content. Whichever punctuation an include is written with — `#include "name"`, `#include 'name'` or `#include <name>` — names the same module and records the same dependency. The engine's own scaffolding — `zero::surface`, `zero::sky`, `zero::post`, `zero::screen` — is injected by the compiler around the matching domain and is never written by hand. The surface framework puts `safe_normalize`, `mat3_from_mat4` and `apply_normal_map(FragmentData, tangent_normal)` in scope for every surface shader. ## Shader features — compile-time variants A **property** is runtime uniform data (a colour, a float, a texture): set per material, read as `material.<name>`, no recompile. A **feature** decides which code is in the program at all. Use a property when the value changes at runtime, a feature when it changes what the shader is. Declare features in `properties.yaml`, alongside the properties: ```yaml properties: - { name: base_color, type: color, default: [1, 1, 1, 1] } features: - { name: PARALLAX, default: false, description: silhouette parallax march } - { name: DETAIL, default: true, description: detail-normal overlay } ``` Guard the code each feature owns with `#ifdef`: ```wgsl fn surface(input: FragmentData) -> PbrSurface { var s = zero_pbr_default_surface(input); #ifdef PARALLAX s.normal = parallax_normal(input); // absent when PARALLAX is off #else s.normal = input.world_normal; #endif return s; } ``` `#ifdef` / `#ifndef` / `#else` / `#endif`, one per line, and they nest. The directives resolve before the WGSL reaches the compiler, so the program holds exactly the lines its feature set selected and every other line is an empty one, which keeps a compiler message on the line number the file shows. An unbalanced block is a compile error naming its line. A material is what chooses a feature set, so `features:` shapes the shaders a material draws with — the surface, sky and screen-space domains. A material names the features it wants in its `mat.yaml`: ```yaml name: worn_rock shader: "@builtin::shaders.pbr_layered" features: PARALLAX: true # on, over the shader's default DETAIL: false # off, against the shader's default ``` or through `asset.create`: ```lua asset.create("material", "worn_rock", { shader = "@builtin::shaders.pbr_layered", features = { PARALLAX = true, DETAIL = false }, }) ``` ### A property that switches a feature on A feature can also be switched on by a material's property values. List the properties under the feature's `properties:`, and the feature is on for every material whose value for one of them stands away from that property's declared default: ```yaml properties: - { name: clearcoat, type: range, default: 0.0, min: 0, max: 1 } features: - { name: CLEARCOAT, properties: [clearcoat], description: the coat lobe } ``` ```wgsl #ifdef CLEARCOAT s.clearcoat = material.clearcoat; #endif ``` A material at `clearcoat: 0` draws a program holding none of the coat's code; one that sets `clearcoat: 0.6`, in its `mat.yaml`, through `asset.create` or with `renderer.material.setProperty`, draws the `CLEARCOAT` variant, and setting it back to 0 returns it to the base program. The property stays a runtime value the program reads; the feature decides only whether the code reading it is there. This is how a shader with costly optional parts keeps every material that leaves them at rest on the cheap program without each material having to name a feature. A material naming the feature off under `features:` keeps it off whatever the property holds. Write the guarded code so that, with the feature off, the shader computes what it would with the property at its default: the material sees one look either way, and pays for the part only where it shows. Each distinct set of switched-on features is a program to compile the first time a material reaches it. A material keeps the programs its values switched it onto compiled while it lives, so a property crossing back and forth reuses them; when the shader's variant budget is spent, the ones no material draws with are given back first. A `properties:` entry is a value property (`float`, `range`, `int`, `bool`, `color`, `float2` to `float4`) the shader declares; one naming no declared property, or a texture or buffer, is refused by name. ### A texture that switches a feature A feature can be switched by the textures a material binds. `textures:` lists texture slots, and the feature is on for every material binding a texture in one of them other than the slot's declared default; `shared_texture:` lists two or more slots, and the feature is on for every material binding one and the same texture in all of them. This is how a shader samples only the maps a material binds: ```yaml properties: - { name: base_color_texture, type: texture, default: white } - { name: rm_texture, type: texture, default: white } - { name: ao_texture, type: texture, default: white } features: - { name: BASE_MAP, default: true, textures: [base_color_texture], description: the base colour map } - { name: AO_MAP, default: true, textures: [ao_texture], description: the occlusion map } - { name: PACKED_AO, shared_texture: [rm_texture, ao_texture], description: occlusion read from the rm map } ``` ```wgsl var base_texel = vec4<f32>(1.0); // what the white default stands for #ifdef BASE_MAP base_texel = textureSample(base_color_texture, base_color_texture_sampler, uv); #endif ``` A switched feature, by value or by texture, is decided by what the material holds: on where one of its switches holds, off where none does, and a material naming the feature under `features:` decides it over the switch. A map feature declared `default: true` keeps the shader's own default configuration sampling every map, so a material whose feature set the variant budget has no room for still draws its maps. A `textures:` or `shared_texture:` entry naming no declared texture slot, and a `shared_texture:` listing one slot, are refused by name. The engine compiles one program per feature set its materials ask for, named `<shader>#<features>`. Materials sharing a set share that program. A feature the shader does not declare selects nothing, so a stray name cannot make the engine compile anything, and the compile names both halves of a mismatch: a guard on a name `features:` does not declare, and a declared name no guard tests. **Permutations are the cost.** A shader with n features can express 2^n programs, each its own compile and pipeline. One shader holds at most 32 variants; a material asking for a set past that draws with the shader's default features and the engine logs which shader ran out. Read what a scene is spending: ```lua for _, s in renderer.shaderVariants() do print(s.shader, #s.variants, "of", s.budget) print(renderer.variantSource(s.base.program)) -- what it ships as for _, v in s.variants do print(v.program, renderer.variantSource(v.program)) -- what one asked for end end ``` A shader registers under every key it answers to — its identity, its guid, each alias — and each key is a row. A variant lands on the row for the key the material named, which for authored content is the guid, so take a program name from the report rather than composing one. ## Materials reference shaders A `.material` applies a shader to entities. Its `mat.yaml` references the shader by its identity string and supplies property values: ```yaml name: my_material shader: "@builtin::shaders.pbr" render: blend: alphaBlend cull: back depth_write: false properties: roughness: 0.5 base_color: [1.0, 1.0, 1.0, 1.0] textures: base_color_texture: { ref: "default:white" } ``` `shader:` is a plain identity string, and a colour is an array. A key's value is the rest of its line, so every value above stands alone on one. ### The render block Render behaviour (the blend equation, alpha cutout, which faces are drawn) lives in the `render:` block and drives the pipeline, not the fragment. These are the keys that reach the pipeline from both authoring routes, and the values each one takes: | Key | Values | Sets | |-----|--------|------| | `blend` | `opaque` `transparent` `alpha` `alphaBlend` `additive` `add` `cutout` `alphaCutout` `premultiplied` `premultipliedAlpha` `multiply` | the equation the fragment composites with | | `cull` | `back` `front` `none` `off` `disabled` | which faces the rasterizer keeps | | `depth_write` | `true` `false` | whether the draw writes depth | | `depth_compare` | `less` `lessEqual` `lequal` `equal` `greater` `greaterEqual` `gequal` `always` `never` | the test a fragment's depth passes | | `topology` | `triangleList` `lineList` `lines` `line` | what consecutive vertices assemble into | | `queue` | a whole number: `2000` opaque, `3000` transparent, `4000` overlay | the draw order of the material; a number inside a queue orders within it | `blend` is also spelled `type`, and the two name one key. Its equations, over the fragment the shader returned (`src`) and the value already in the target (`dst`): `opaque` is `src`; `transparent`, `alpha` and `alphaBlend` are `src * src.a + dst * (1 - src.a)`; `additive` and `add` are `src + dst`, the mode a glow, a light shaft or a spark card is written for; `premultiplied` and `premultipliedAlpha` are `src + dst * (1 - src.a)`, taking a source that already carries its own coverage; `multiply` is `src * dst`, which is how a soot, grime or shadow card darkens what stands behind it. `cutout` and `alphaCutout` keep the fragment or discard it on its alpha and go on writing depth. The same block is what `asset.create`'s `render` argument takes, key for key and value for value, so one material named in Luau and the same material standing on disk ask for their pipeline with the same words. `depth_write` is the one key whose value takes the shape of its route: the word `false` on a `mat.yaml` line, the boolean `false` in the Luau table. ```lua asset.create("material", "heat_plume", { shader = "@builtin::shaders.pbr", render = { blend = "alphaBlend", cull = "none", depth_write = false }, }) ``` Where a value outside a key's set is reported is what the two routes differ on. `asset.create` refuses the call on any of these keys and names the set it measured the value against, or for `queue`, that it takes a number. A `mat.yaml` standing on disk registers either way, each key falling back to a value of its own: `blend` to `opaque`, `cull` to `back`, `depth_write` to `true`, `depth_compare` to `less`, `topology` to `triangleList` and `queue` to `2000`. The engine log carries the blend fallback, naming the value and the set it was measured against, so a `mat.yaml` value is worth putting through `asset.create` once — that is where every key answers with its set. ## Registration & hot reload A `.shader` is compiled by the asset system, not by the renderer: writing `shader.wgsl` or `properties.yaml` fires the `.shader` assetType's `onChange`, which compiles it: the body + the property schema are read, the group(1) interface and (for surface) every render-mode entry point are generated, `#include`s are expanded, the result is **validated**, and the shader is registered. Validation happens at this compile step — the whole point of "compile". A shader with invalid WGSL (an unknown field, a type mismatch, an undefined function) **fails to compile** with the real reason — readable directly from Luau via `shaderRef:compileStatus()` (`{ status = "compiled" | "failed" | "pending", error?, pending? }`), and also in the author log and `asset.inspect`; it is **not** registered. This fires on create and on every edit, so saving a `.wgsl` recompiles with no world reload; the change is visible on the next frame. Compilation is async, so a `compileStatus()` of `"pending"` immediatel
▲ -1↑ born
backing path · shaders/pbr.shader

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.