Skip to content

3D engine that AI agents drive

Add materials and particles references to the scene skill (#2247)

Nguyen Xuan An51e600774214
diff --git a/bench/agent-modeling/suite.mjs b/bench/agent-modeling/suite.mjs
index 6c1bf0e6..eeed01ee 100644
--- a/bench/agent-modeling/suite.mjs
+++ b/bench/agent-modeling/suite.mjs
@@ -58,7 +58,7 @@ export const KIND_REFERENCES = {
modeling: ['mesh-modeling.md', 'errors-and-recovery.md'],
revision: ['mesh-modeling.md', 'errors-and-recovery.md'],
scene: ['mesh-modeling.md', 'errors-and-recovery.md'],
- look: ['look.md', 'errors-and-recovery.md'],
+ look: ['look.md', 'materials.md', 'errors-and-recovery.md'],
light: ['light.md', 'errors-and-recovery.md'],
camera: ['camera.md', 'errors-and-recovery.md'],
animation: ['film-and-animation.md', 'errors-and-recovery.md'],
@@ -70,6 +70,8 @@ export const TOPIC_REFERENCES = {
placedAssets: ['game.md'],
motionIk: ['film-and-animation.md'],
explosion: ['effects-and-feedback.md'],
+ particles: ['particles-and-vfx.md'],
+ localVolumes: ['particles-and-vfx.md'],
askUser: ['effects-and-feedback.md'],
};
diff --git a/changes/2247.md b/changes/2247.md
new file mode 100644
index 00000000..d769c248
--- /dev/null
+++ b/changes/2247.md
@@ -0,0 +1 @@
+- The scene skill has two new references, `materials.md` (colour, patterns, glass, water, shader hooks) and `particles-and-vfx.md` (caps, spray, dust, sparks, sea foam, fog and beams), so agents stop rediscovering their limits by trial (#2247).
diff --git a/skills/build-crucible-scene/SKILL.md b/skills/build-crucible-scene/SKILL.md
index 8bd569f8..d442b641 100644
--- a/skills/build-crucible-scene/SKILL.md
+++ b/skills/build-crucible-scene/SKILL.md
@@ -40,6 +40,8 @@ Variants: `scene_apply` with a `branch` name, compare in one `scene_review` (a `
|---|---|
| Sky, HDRI, `.cube` look, tone mapping, fog, exposure, bloom, AO, outlines | `${CLAUDE_SKILL_DIR}/references/look.md` |
| Sun, point, spot and area lights, caps, baked bounce light, flush faces | `${CLAUDE_SKILL_DIR}/references/light.md` |
+| Colour, patterns, glass, clearcoat, water tags, shader hooks, judging a surface | `${CLAUDE_SKILL_DIR}/references/materials.md` |
+| Spray, dust, sparks, sea foam, particle caps, fog and beams | `${CLAUDE_SKILL_DIR}/references/particles-and-vfx.md` |
| Lens, focal length, depth of field, shift, orthographic | `${CLAUDE_SKILL_DIR}/references/camera.md` |
| Motion tracks (camera, nodes, lights, sun, sky, effects), shots, timeline | `${CLAUDE_SKILL_DIR}/references/film-and-animation.md` |
| A call failed, a diagnostic appeared, the picture is wrong | `${CLAUDE_SKILL_DIR}/references/errors-and-recovery.md` |
diff --git a/skills/build-crucible-scene/references/materials.md b/skills/build-crucible-scene/references/materials.md
new file mode 100644
index 00000000..ed58d1b9
--- /dev/null
+++ b/skills/build-crucible-scene/references/materials.md
@@ -0,0 +1,166 @@
+# Materials: colour, patterns, glass, water, shader hooks
+
+<!-- skill-navigation:start -->
+This is the [Materials: colour, patterns, glass, water, shader hooks](#materials-colour-patterns-glass-water-shader-hooks) reference. Read [Colour and values](#colour-and-values) and [Patterns](#patterns) before texturing a part.
+Then read the task's section: [Glass, coat, sheen and wax](#glass-coat-sheen-and-wax), [Water and sea](#water-and-sea), [Shader hooks](#shader-hooks),
+[Editing materials and imports](#editing-materials-and-imports) or [Judge a surface](#judge-a-surface).
+<!-- skill-navigation:end -->
+
+Calls follow the conventions in `look.md`. `tests/skill-examples.test.js` applies every block, so they stay valid.
+Field lists and ranges: `scene_capabilities` topics `materialFields`, `materialLayers`, `pattern`, `materialSnippet`.
+
+## Colour and values
+
+| Field | Range | Note |
+|---|---|---|
+| `color` | each channel 0 to 1, linear | Hue only; brightness comes from light. |
+| `metallic`, `roughness` | 0 to 1 | The renderer keeps a roughness floor of 0.075. |
+| `emission` | 0 or more | A multiplier. `emissiveColor` is its own linear RGB, each channel 0 or more. |
+| `opacity` | 0 to 1 | Below 1 on an opaque material turns it into `blend`. |
+| `alphaMode` | `opaque`, `blend`, `add` | `add` adds its light to what is behind it (sparks, beams); a recipe has no `mask` mode. |
+| `doubleSided` | `true` or `false` | Thin sheets, leaves, cards. |
+
+Starting values, then judge with `scene_look`:
+
+| Kind | `color` | `metallic` | `roughness` |
+|---|---|---|---|
+| Rough stone, plaster | mid grey, or white under a pattern | 0 | 0.85 to 1 |
+| Painted wall, car paint | the hue | 0 | 0.3 to 0.6 (add `clearcoat` for a gloss) |
+| Bare metal | light grey or the metal tint | 1 | 0.2 to 0.5 |
+| Rubber, cloth | dark | 0 | 0.9 |
+| Lamp, screen | the hue | 0 | any, with `emission` 2 to 8 |
+
+Metal is 0 or 1 in practice; use a value between only for a worn edge. A `metallic` above 0 no longer fails `scene_apply` with
+"Light bake takes at most 200000 triangles" (#2202 is fixed): no bake runs unless the recipe asks for one.
+
+## Patterns
+
+Colour multiplies the pattern's own colours. A dark `color` on a dark stone pattern renders near black, so keep
+`color: [1, 1, 1]` on a patterned material and change the look through the pattern's `colors`. Roughness and metallic
+also multiply the pattern's maps: `roughness: 1` keeps the pattern's own roughness.
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-material", "material": { "id": "rock", "color": [1, 1, 1], "roughness": 1,
+ "pattern": { "type": "stone", "size": 1.5, "count": 4, "bump": 1.2, "seed": 7 } } },
+ { "type": "set-node", "id": "body", "material": "rock" }
+] }
+```
+
+- `type`: `noise`, `wood`, `planks`, `bricks`, `tiles`, `marble`, `stone`, `concrete`, `metal`, `rust`, `fabric`, or `graph` (your own node graph; see `scene_capabilities` `materialGraph`).
+- `size` is metres per repeat (0.01 to 100), so the grain keeps its real size on any node scale. `count` (1 to 64) is rings, planks, bricks or cells per repeat. `bump` is relief, 0 to 4. `seed` varies it.
+- `axis` (`x`, `y`, `z`, default `y`) is the object axis wood, planks and brushed metal run along. `mapping` is `box` (default, no UVs needed) or `uv`.
+- `colors` is two linear RGB colours, darker first. Only `bricks` takes a third (the mortar); a third colour on any other type fails with "Material pattern colors must be two linear RGB colours ... (three for bricks ...)".
+- `resolution` is 256, 512 (default, about 4 MiB a pattern) or 1024.
+- A scene holds at most 16 different patterns. Two materials with identical pattern JSON count once, so reuse one pattern and tint it with `color`.
+- A pattern needs the `surface` tag. On any other tag (`water`, `liquid`, `foam`, `unlit`, `foliage`, `grass`) it fails; keep the `surface` tag or remove the pattern.
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-material", "material": { "id": "wall", "color": [1, 1, 1], "roughness": 0.95,
+ "pattern": { "type": "bricks", "colors": [[0.33, 0.1, 0.06], [0.52, 0.2, 0.12], [0.45, 0.42, 0.38]], "count": 6, "size": 1.2 } } },
+ { "type": "set-node", "id": "body", "material": "wall" }
+] }
+```
+
+## Glass, coat, sheen and wax
+
+Layer fields and ranges (`scene_capabilities` `materialLayers`): `clearcoat` 0 to 1, `clearcoatRoughness` 0 to 1, `transmission` 0 to 1,
+`thickness` 0 to 1000 m, `ior` 1 to 2.5, `specular` 0 to 4, `sheenColor` and `attenuationColor` 0 to 1 per channel, `sheenRoughness` 0 to 1,
+`anisotropy` 0 to 1, `iridescence` 0 to 1, `attenuationDistance` above 0.
+
+- Glass: `transmission: 1` with a nonzero `thickness`. With `thickness: 0` the view is not bent. Leave `opacity: 1` and `alphaMode: "opaque"`: a transmitting material that is also blended does not refract, and `scene_inspect` says so (`transmission-blended`).
+- Transmission needs the `surface` or `liquid` tag. It ignores `anisotropy` and `iridescence`, and `thickness`, `attenuationColor` and `attenuationDistance` do nothing while `transmission` is 0. A window pane also takes `rayVisibility: 'glass'` (see `SKILL.md`).
+- `clearcoat`, `sheenColor`, `specular`, `specularColor`, `anisotropy` and `iridescence` apply only to the `surface` and `liquid` tags; other tags raise an `ignored-material-field` diagnostic.
+- `subsurface` (skin, wax, leaves): `weight` 0 to 1, `radius` [r, g, b] 0 to 100, `scale` 0 to 10 metres per radius unit, `color` 0 to 1. Surface tag, rasterizer only.
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-material", "material": { "id": "glass", "color": [1, 1, 1], "roughness": 0.05, "transmission": 1, "thickness": 0.04, "ior": 1.5,
+ "attenuationColor": [0.8, 0.95, 0.9], "attenuationDistance": 2 } },
+ { "type": "add-material", "material": { "id": "lacquer", "color": [0.6, 0.05, 0.04], "roughness": 0.4, "clearcoat": 1, "clearcoatRoughness": 0.05 } },
+ { "type": "add-material", "material": { "id": "wax", "color": [0.9, 0.8, 0.6], "roughness": 0.5,
+ "subsurface": { "weight": 0.6, "radius": [1, 0.4, 0.2], "scale": 0.05, "color": [0.9, 0.7, 0.5] } } },
+ { "type": "set-node", "id": "body", "material": "glass" },
+ { "type": "set-node", "id": "lid", "material": "lacquer" }
+] }
+```
+
+## Water and sea
+
+Tags (`tag` on `add-material`): `surface` (default), `unlit`, `liquid`, `foam`, `foliage`, `grass`, `water`. A `water` material takes
+`waterPreset` (`lake`, `sea`, `river`), `absorption` (RGB per metre, 0 to 20), `turbidity` (0 clear to 1 murky) and an optional `waterRamp`;
+an `opacity` under 1 shows the bed. The sea itself is an `ocean` mesh edit; it writes the `foam` vertex group.
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-material", "material": { "id": "sea", "tag": "water", "waterPreset": "sea", "color": [0.1, 0.3, 0.45], "roughness": 0.1, "opacity": 0.9 } },
+ { "type": "add-geometry", "geometry": { "id": "sea", "type": "mesh", "base": { "type": "box", "bevel": 0 },
+ "edits": [ { "op": "subdivide", "levels": 4 }, { "op": "ocean", "windSpeed": 8, "choppiness": 1, "size": 20, "seed": 3 } ] } },
+ { "type": "add-node", "node": { "id": "water", "geometry": "sea", "material": "sea", "scale": [20, 1, 20] } }
+] }
+```
+
+`windSpeed` (0 to 60 m/s) only shapes the waves: no force pushes a prop along. Props ride the wave height through
+`physics.ocean` and `float`; a boat adds `float.boat` thrust and a `wake` (docs/physics.md "Floating on the ocean"). A small prop on a
+`windSpeed` 12 sea bobs hard, so lower `windSpeed` or add float points. Foam, spray and wake drive particles: see `particles-and-vfx.md`.
+
+## Shader hooks
+
+`snippet` is a GLSL ES 3.00 function that changes colour and alpha per fragment, or discards it. Rasterizer only; at most 4096 bytes of
+code, 16 uniforms, no `#` lines, counted loops only. The engine declares your `uniforms`; do not redeclare them. Inputs: `color`, `alpha`,
+`uv`, `worldPosition`. `discard` removes the fragment in every alpha mode and also removes its shadow; a lowered `alpha` fades a `blend` or `add`
+part (an opaque part has nothing to fade). `snippet: null` clears it. A compile error comes back as `renderError` with snippet line numbers.
+
+A wet band that darkens the lower half metre of a wall:
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-material", "material": { "id": "wet", "color": [0.7, 0.68, 0.64], "roughness": 0.9,
+ "snippet": { "fragment": "void materialHook(inout vec3 color, inout float alpha, vec2 uv, vec3 worldPosition) {\n float wet = 1.0 - smoothstep(bandTop - 0.2, bandTop, worldPosition.y);\n color *= 1.0 - 0.55 * wet;\n}", "uniforms": { "bandTop": 0.5 } } } },
+ { "type": "set-node", "id": "body", "material": "wet" }
+] }
+```
+
+A dissolve cuts stripes with `discard`; a soft beam shell fades `alpha` along height on an additive material:
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-material", "material": { "id": "dissolve", "color": [0.8, 0.5, 0.3], "doubleSided": true,
+ "snippet": { "fragment": "void materialHook(inout vec3 color, inout float alpha, vec2 uv, vec3 worldPosition) {\n if (fract(worldPosition.y * 9.0 + worldPosition.x * 3.0) < cut) discard;\n}", "uniforms": { "cut": 0.35 } } } },
+ { "type": "add-material", "material": { "id": "beam", "tag": "unlit", "color": [1, 0.9, 0.7], "alphaMode": "add", "opacity": 0.25, "doubleSided": true,
+ "snippet": { "fragment": "void materialHook(inout vec3 color, inout float alpha, vec2 uv, vec3 worldPosition) {\n alpha *= smoothstep(lowY, highY, worldPosition.y);\n}", "uniforms": { "lowY": 0.0, "highY": 3.0 } } } },
+ { "type": "set-node", "id": "body", "material": "dissolve" },
+ { "type": "set-node", "id": "lid", "material": "beam" }
+] }
+```
+
+A single cone seen from the side shows a hard silhouette. Stack two or three shells of growing radius with falling `opacity` and
+fade each along the beam. Point and spot lights also scatter in `volumeFog` (up to 8 lights, no shadows); see `particles-and-vfx.md` for fog limits.
+
+## Editing materials and imports
+
+- `set-material` takes colour, `metallic`, `roughness`, `emission`, `emissiveColor`, `opacity`, `alphaMode`, `doubleSided`, `pattern`, `map`, `subsurface`, `snippet`, water fields and the layer fields. It rejects `tag` (the error lists the fields it takes). To change a tag, `add-material` a new one and `set-node` onto it.
+- A textured import (GLB placement): the `asset.materials` override multiplies its `color` into the texture, it does not replace the texture. To recolour, tint with `color` (a dark texture stays dark), or flatten with `asset.flatten.color`, which paints every material of the placement one colour and drops the textures; a named override still wins.
+- Faces that lie flush flicker: `decal: true` on the top node or `depthLayer` 1 to 4 (see `light.md`). Do not add them for near-flush faces; the renderer ranks those itself.
+
+## Judge a surface
+
+Light a material neutrally before judging it. `environment.setup: "overcast"` is a grey sky with no coloured panel, so hue and roughness
+read honestly. `studio` has three light panels and shows gloss and metal reflections. Then turn the key light: a surface that
+looks right under one light and flat or noisy under another is wrong. Apply two variants as branches and compare them in one
+`scene_review` with a `branch` per shot (a variant is one `set-environment` that rotates `lightDirection` by 90 degrees about up):
+
+```json
+{ "expectedRevision": 1, "branch": "key-a", "operations": [
+ { "type": "set-environment", "environment": { "setup": "overcast", "lightDirection": [-3, 6, 4] } }
+] }
+```
+
+```json
+{ "expectedRevision": 1, "branch": "key-b", "operations": [
+ { "type": "set-environment", "environment": { "setup": "overcast", "lightDirection": [4, 6, 3] } }
+] }
+```
+
+Both blocks are `scene_apply` arguments. Then `scene_review` with `shots: [{ "branch": "key-a" }, { "branch": "key-b" }]`, and keep one with `scene_restore` and its `branch`.
diff --git a/skills/build-crucible-scene/references/particles-and-vfx.md b/skills/build-crucible-scene/references/particles-and-vfx.md
new file mode 100644
index 00000000..a5e22037
--- /dev/null
+++ b/skills/build-crucible-scene/references/particles-and-vfx.md
@@ -0,0 +1,149 @@
+# Particles and VFX: spray, dust, sparks, sea foam, fog and beams
+
+<!-- skill-navigation:start -->
+This is the [Particles and VFX](#particles-and-vfx-spray-dust-sparks-sea-foam-fog-and-beams) reference. Read [Caps](#caps) and [Nothing shows](#nothing-shows) before the first system.
+Then read the task's section: [Spray, dust and sparks](#spray-dust-and-sparks), [Check a system](#check-a-system), [Sea spray, foam and wake](#sea-spray-foam-and-wake),
+[Fog and beams](#fog-and-beams) or [Not built yet](#not-built-yet).
+<!-- skill-navigation:end -->
+
+Calls follow the conventions in `look.md`. `tests/skill-examples.test.js` applies every block, so they stay valid.
+Field list: `scene_capabilities` topic `particles`. Full contract: `docs/physics.md` "Recipe particles and hair".
+The values below are starting points that validate; none was tuned by eye, so judge each with `scene_look` at a `motionTime` inside the burst.
+
+## Caps
+
+| Limit | Value |
+|---|---|
+| Systems in `particles.systems` | 4 |
+| `count` per system | 1 to 2000 |
+| Particles in all systems together (emitter and hair; sparks count apart) | 4000 |
+| Vertices drawn in total | 100000 |
+| `type: "sparks"` count, all spark systems together | 4096 |
+| `lifetime` | 0.01 to 60 s (sparks 0.05 to 5 s) |
+
+A system draws its node's geometry once per particle, so the vertex cap is the one you hit first. A default `box` is 1176 vertices, a default
+`sphere` 2665 and a default `plane` 289; the error names the vertices per particle. Use `box` with `bevel: 0` (24 vertices) or a `plane`
+with `segments: 1` (4 vertices, a card). `scene_inspect` returns `particles.systems[].verticesPerParticle`, `maxAlive` and `endsAt`.
+
+Emission: `count` is how many are born in all. With `rate` (births per second) they are spread over `count / rate` seconds; without it, all are born at time 0 in
+one burst. `start` (alias `delay`) is the time of the first birth. `stop` is an absolute time in seconds, not a length after `start`: it must be above
+`start` and at most 3600, so `{ "start": 1.6, "stop": 0.4 }` fails with "expected a time in seconds after the start (1.6), such as 3.6". Nothing is born at or after `stop`;
+particles already born finish their life.
+
+A box emitter takes `halfExtents`, not `radius`. Crucible no longer writes a `radius` into a box emitter, and a stored `radius: 0.5` on a box is dropped, so later batches apply (#2203). `sphere` and `disc` take `radius`.
+
+`set-particles` may name a node added in an earlier batch (#2204); the node and the system can be in one batch or two. A system replaces its node's own geometry with the
+particles, so use a node made for it, and give the emitter place through `emitter.position`: the node's `translation`, `rotation` and `scale` are ignored (`scene_inspect` warns with `particle-node-transform-ignored`).
+
+## Nothing shows
+
+A system can validate and draw nothing. Check these before changing values:
+
+1. The time. A system with `start: 1.6` has no particle at the default `scene_look` time; pass `motionTime` between `start` and `endsAt` from the report.
+2. The card. A `plane` faces +Z and keeps its facing (there is no camera-facing billboard), so seen from the side it is edge-on. Set `doubleSided: true` on the material and `orient: "random"` on the system, or use a `box` or low-poly sphere.
+3. `scale: "grow"` starts every particle at size 0 and reaches full size at death; `"shrink"` does the reverse. A short life with `grow` is mostly tiny.
+4. `alpha` and `color` become vertex colours and `alpha` multiplies the colour, so a particle fades toward black and never becomes see-through. On an `alphaMode: "add"` material black adds nothing, so the fade works; on an opaque or `blend` one the particle turns black against the background.
+5. Size. `size` is the scale of the node's geometry in metres: a unit `plane` with `size` 0.002 is 2 mm.
+
+## Spray, dust and sparks
+
+Spray is many small cards, born in a short window, flung up and pulled back by gravity and `drag`:
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-geometry", "geometry": { "id": "card", "type": "plane", "segments": 1 } },
+ { "type": "add-material", "material": { "id": "mist", "tag": "unlit", "color": [0.9, 0.95, 1], "alphaMode": "add", "opacity": 0.5, "doubleSided": true } },
+ { "type": "add-node", "node": { "id": "spray", "geometry": "card", "material": "mist" } },
+ { "type": "set-particles", "particles": { "systems": [
+ { "node": "spray", "seed": 11, "count": 700, "rate": 1800, "start": 0.5, "stop": 1.5, "lifetime": [0.5, 1.1],
+ "speed": [2, 5], "spread": 40, "size": [0.04, 0.11], "drag": 0.8, "orient": "random", "scale": "shrink",
+ "emitter": { "shape": "sphere", "position": [0, 0.4, 0], "radius": 0.3 } }
+ ] } }
+] }
+```
+
+Dust drifts: low speed, long life, high drag, and a gentle lift through the section `gravity` (default `[0, -9.81, 0]`). The section's `wind` moves
+emitter particles only where `drag` is above 0.
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-geometry", "geometry": { "id": "speck", "type": "box", "bevel": 0 } },
+ { "type": "add-material", "material": { "id": "dust", "tag": "unlit", "color": [0.7, 0.62, 0.5], "alphaMode": "add", "opacity": 0.35 } },
+ { "type": "add-node", "node": { "id": "dust", "geometry": "speck", "material": "dust" } },
+ { "type": "set-particles", "particles": { "gravity": [0, 0.05, 0], "wind": [0.4, 0, 0], "systems": [
+ { "node": "dust", "seed": 5, "count": 400, "rate": 80, "lifetime": [2, 4], "speed": [0.1, 0.6], "spread": 180, "size": [0.02, 0.06],
+ "drag": 1.5, "alpha": [1, 0], "emitter": { "shape": "box", "position": [0, 0.5, 0], "halfExtents": [1.5, 0.4, 1.5] } }
+ ] } }
+] }
+```
+
+Sparks are a third kind: `type: "sparks"` with `preset: "explosion"` throws bright cooling streaks. Its node needs a material with `tag: "unlit"` and `color: [1, 1, 1]`;
+any other tag is refused with a message that says so. `floor` stops them on the ground, `bounce` (0 to 1) bounces them, `temperature` is `[start, end]` kelvin with start at or above end.
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-geometry", "geometry": { "id": "spark", "type": "box" } },
+ { "type": "add-material", "material": { "id": "spark", "tag": "unlit", "color": [1, 1, 1] } },
+ { "type": "add-node", "node": { "id": "sparks", "geometry": "spark", "material": "spark" } },
+ { "type": "set-particles", "particles": { "systems": [
+ { "type": "sparks", "preset": "explosion", "node": "sparks", "position": [0, 0.5, 0], "seed": 1758, "count": 400, "floor": 0 }
+ ] } }
+] }
+```
+
+Other fields: `instances` (up to 8 nodes, one drawn per particle), `color` `[[r, g, b] birth, [r, g, b] death]`, `colliders` (up to 8 static nodes), `bounce`, `friction`, `spin`, force `fields`.
+A system with `colliders`, `bounce` or force fields is stepped at 1/120 s, so a seek back costs the particle's age in steps.
+
+## Check a system
+
+`scene_inspect` returns the `particles` report: per system the particle count, `verticesPerParticle`, `maxAlive` (the most alive at once) and `endsAt` (when the last one dies). Read it before the picture:
+a `maxAlive` of 3 for a spray means `rate` is too low or the window too short. Seeking is exact: the same `motionTime` gives the same particles, in any order, and raising `count` keeps the earlier ones.
+Sample a burst with `scene_review` shots at different `motionTime` values (for example just after `start`, at the middle, near `endsAt`).
+
+## Sea spray, foam and wake
+
+An `ocean` mesh edit writes a `foam` vertex group. With `spray: true` it also writes a `spray` group (where the surface rises) and a `spray` velocity vector. A system takes droplets from the strong crests:
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "add-geometry", "geometry": { "id": "sea", "type": "mesh", "base": { "type": "box", "bevel": 0 },
+ "edits": [ { "op": "subdivide", "levels": 4 }, { "op": "ocean", "windSpeed": 12, "choppiness": 2, "size": 2, "resolution": 4, "time": 1.5, "seed": 3, "spray": true } ] } },
+ { "type": "add-geometry", "geometry": { "id": "speck", "type": "box", "bevel": 0 } },
+ { "type": "add-material", "material": { "id": "water", "color": [0.1, 0.3, 0.5] } },
+ { "type": "add-material", "material": { "id": "foam", "color": [0.9, 0.95, 1] } },
+ { "type": "add-node", "node": { "id": "surface", "geometry": "sea", "material": "water" } },
+ { "type": "add-node", "node": { "id": "droplet", "geometry": "speck", "material": "foam" } },
+ { "type": "set-particles", "particles": { "systems": [
+ { "node": "droplet", "count": 400, "speed": [0, 1], "lifetime": [0.6, 1.4], "size": 0.05, "scale": "shrink",
+ "emitter": { "shape": "mesh", "mesh": "surface", "from": "vertices", "group": "spray", "groupThreshold": 0.3, "velocityFrom": "spray", "velocityScale": 2 } }
+ ] } }
+] }
+```
+
+- `mesh` names the node, not the geometry. The droplets read the mesh after its `edits`; a sea that carries floating bodies keeps its `ocean` op in the geometry `stack` instead (`physics.ocean.geometry`).
+- Spray exists only where the foam folds: `choppiness` 0 sprays nowhere. A sea with no spray at its `time` refuses the scene with "no weight in vertex group spray": raise `windSpeed` or `choppiness`, lower `groupThreshold`, or change `time`.
+- A sea moved by an `oceanTime` geometry track is followed: each droplet leaves the crests of the sea at its birth time.
+- The edit's `wake: { points: [[x, z, strength, width]], height }` draws a trail you place; `physics` `float.boat.wake` fills it from a moving hull. Floating props ride the wave height; ocean `windSpeed` pushes nothing.
+
+## Fog and beams
+
+`environment.volumeFog` is one box: `density` 0 to 10, `steps` 8 to 48, `minimum` and `maximum` within 100000, `anisotropy` -0.9 to 0.9, `noiseAmount` 0 to 1, `drift` in units per second.
+Point and spot lights scatter in it (at most 8, points first, no shadows, no light linking), and so does the sun. Up to 8 `localVolumes` (box, sphere, mesh part, grid) add smoke puffs or a glow in one place with no fog box.
+
+```json
+{ "expectedRevision": 1, "operations": [
+ { "type": "set-environment", "environment": {
+ "spotLights": [ { "position": [0, 4, 0], "direction": [0, -1, 0], "angle": 0.35, "penumbra": 0.6, "intensity": 400, "color": [1, 0.9, 0.7] } ],
+ "volumeFog": { "density": 0.05, "minimum": [-6, 0, -6], "maximum": [6, 5, 6], "anisotropy": 0.5, "noiseAmount": 0.3 }
+ } }
+] }
+```
+
+- Open bug #2205: `scene_look` can fail with "WebGL render failed with error 1282" for a volume fog that combines `noiseAmount`, `drift`, `heightFalloff` and `color` on a physical sky, and the culprit field is not isolated. Add the fog fields one at a time with `scene_look` between, and keep the last set that renders.
+- A visible beam is a cone part, not a fog effect: give it an `alphaMode: "add"` material with a low `opacity`, stack two or three shells of growing radius, and fade each along its length with a `snippet` (see `materials.md`, "Shader hooks"). One shell shows a hard silhouette from the side.
+
+## Not built yet
+
+- Smoke and fire simulation inside the MCP tools. `add-explosion` bakes a blast (flash, fire and smoke grid, sparks, dust, rubble; see `effects-and-feedback.md`). For a puff, use emitter particles with `scale: "grow"` or a noisy `localVolumes` sphere with `emission`.
+- Particles that follow a moving node: the emitter stays where `emitter.position` puts it in world space. Collision between particles, collision with a moving node and hair collision are not built either.
+- A camera-facing billboard particle and per-vertex alpha (a fade is a darkening; use `alphaMode: "add"`).
diff --git a/tests/skill-examples.test.js b/tests/skill-examples.test.js
index 67e088f6..404117a6 100644
--- a/tests/skill-examples.test.js
+++ b/tests/skill-examples.test.js
@@ -11,7 +11,7 @@ import {
// The build-crucible-scene skill teaches agents the scene_apply tool by example. Every json block in these references that
// carries an `operations` list must keep applying to a fresh scene, so an API change fails here instead of misleading an agent.
-const referenceNames = ['look', 'light', 'camera', 'film-and-animation', 'effects-and-feedback'];
+const referenceNames = ['look', 'light', 'camera', 'film-and-animation', 'effects-and-feedback', 'materials', 'particles-and-vfx'];
const shippedFile = (name, extension) => readFile(new URL(`../assets/looks/${name}.${extension}`, import.meta.url));
for (const name of BUNDLED_ENVIRONMENT_NAMES) registerCatalogEnvironment(name, parseRadianceHdr(await shippedFile(name, 'hdr')));