3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Audit the scene skill for 0.21.0: fix stale claims, add this release's features (#1979)
Nguyen Xuan An2bca5bc290e1
diff --git a/bench/agent-modeling/suite.mjs b/bench/agent-modeling/suite.mjsindex 71005eca..6c1bf0e6 100644--- a/bench/agent-modeling/suite.mjs+++ b/bench/agent-modeling/suite.mjs@@ -69,6 +69,8 @@ export const KIND_REFERENCES = {export const TOPIC_REFERENCES = {placedAssets: ['game.md'],motionIk: ['film-and-animation.md'],+ explosion: ['effects-and-feedback.md'],+ askUser: ['effects-and-feedback.md'],};// Reference files no bench task loads, each with the reason. A new file under references/ must be reachable from a kind or listed here.diff --git a/changes/1979.md b/changes/1979.mdnew file mode 100644index 00000000..87ef7de7--- /dev/null+++ b/changes/1979.md@@ -0,0 +1 @@+- Audit the scene skill for 0.21.0: fix stale claims (motion duration range, emissiveColor tracks, ask-user wording), add explosion, retro, vehicle damage, pins and lasso, review page, splat palette and turntable how-tos in a new effects-and-feedback reference, and steer agents to the asset catalog, `scene_capabilities` and `scene_look` before guessing, boxing real objects or rendering (#1979).diff --git a/skills/build-crucible-scene/SKILL.md b/skills/build-crucible-scene/SKILL.mdindex 5624ae19..8bd569f8 100644--- a/skills/build-crucible-scene/SKILL.md+++ b/skills/build-crucible-scene/SKILL.md@@ -1,6 +1,6 @@---name: build-crucible-scene-description: Build, light, film and refine 3D scenes through the Crucible MCP server (npm package @codepawlhq/crucible). Use when an agent has the scene_* tools and must model parts, set materials, lights, HDRI, color looks, fog, lens and depth of field, animate a camera, lights, sun, sky and effects, bake light, fix z-fighting or recover from a tool error. Also for "làm cảnh Crucible", "dựng cảnh 3D bằng Crucible", "model bị răng cưa", "ánh sáng cảnh Crucible", "đổ bóng", "sương mù Crucible", "camera Crucible". Image and video export is the render-crucible-media skill.+description: Build, light, film and refine 3D scenes through the Crucible MCP server (npm package @codepawlhq/crucible). Use when an agent has the scene_* tools and must model parts, set materials, lights, HDRI, color looks, fog, lens and depth of field, animate a camera, lights, sun, sky and effects, bake light, fix z-fighting or recover from a tool error. Also for "làm cảnh Crucible", "dựng cảnh 3D bằng Crucible", "model bị răng cưa", "ánh sáng cảnh Crucible", "đổ bóng", "sương mù Crucible", "camera Crucible". Explosions, the PS1 retro look, vehicle dents and asking the person with pins or a lasso are covered too. Image and video export is the render-crucible-media skill.license: MIT---@@ -15,20 +15,21 @@ Start the server with `npx --package @codepawlhq/crucible crucible-mcp --backend1. `scene_capabilities`: with no arguments it returns a short index of features, limits and topic names. Pass`topic` (one name or a list of up to 8) for the field list of a feature (`environment`, `materialFields`, `geometries`, `meshEdit.bevel`,`motion`) or `examples.scene_apply` for a complete call of a hard tool. Tool schemas list only common fields, so read the topic before a feature you have not used.+ Ask for every topic you need in one list call, not one call per topic.In a list, a wrong name does not fail the call: the valid topics answer and the wrong ones come back in `unknown` with suggestions.2. `scene_create` with a `recipe`: `{ "format": "crucible.scene", "schemaVersion": 1, "geometries": [], "materials": [], "nodes": [] }`plus optional `camera`, `environment`, `effects`, `shadow`, `motion`, `bake`, `timeline`.3. `scene_inspect`: node IDs, bounds, `diagnostics`, current `revision`.4. `scene_look`: the PNG. Add `labels: true` to match node names to the image. Judge the image, not the lint.+ Never submit a render job for a scene you have not looked at (`scene_look`, or `scene_review` for several angles).5. `scene_apply` with the current `expectedRevision` and a small `operations` batch. A stale revision fails whole.6. `scene_checkpoint` before a risky batch, `scene_restore` to undo, `scene_release_checkpoint` after. Without a checkpoint, `scene_restore` with `revision` goes back to one of the last 4 earlier revisions.7. `scene_export_recipe` keeps the result. `scene_dispose` a scene you finished with.Beside the loop: `mesh_inspect`, `mesh_edit` and `mesh_stack` edit polygon meshes (see the modeling row below), and-`scene_walkmap` returns a grid of walkable and blocked cells for placing characters and paths. `scene_ask_user`, where the-server lists it, opens the view for the person to pin notes on: use it when a change is hard to put in words. In an MCP Apps-host the view opens in the chat and the call returns `outcome: "pending"` at once. For a person on a phone, `scene_export_web`-with `review: true` writes a page to host. Pass the text of the file it saves to `scene_ask_user` as `reviewFile` to read the marks. Each export reads once.+`scene_walkmap` returns a grid of walkable and blocked cells for placing characters and paths. `scene_ask_user` lets the person+pin notes (or lasso a region) on the view when a change is hard to put in words; `scene_export_web` with `review: true` does the+same on a phone. Shared materials, lassos and `reviewFile` are in `effects-and-feedback.md`.`sessionId` may be left out: the last used scene is meant. With two scenes open, pass it on every call. The server keeps 4 scenes and closes the least recently used (`evictedSessions` in the create result), and 16 checkpoints per scene, oldest first (`evictedCheckpointIds`).Variants: `scene_apply` with a `branch` name, compare in one `scene_review` (a `branch` per shot), keep one with `scene_restore`.@@ -42,6 +43,7 @@ Variants: `scene_apply` with a `branch` name, compare in one `scene_review` (a `| 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` |+| Explosion, `material.retro`, vehicle damage, pins and lasso from the person, review page, splat palette | `${CLAUDE_SKILL_DIR}/references/effects-and-feedback.md` || A playable game: animate a placed, retargeted character (idle, walk, run), web export | `${CLAUDE_SKILL_DIR}/references/game.md` || Polygon modeling: extrude, inset, bevel, booleans, mirror, array | `${CLAUDE_SKILL_DIR}/references/mesh-modeling.md` || Scene code against the npm library, not MCP | `${CLAUDE_SKILL_DIR}/references/scene-contract.md` |@@ -56,6 +58,11 @@ Variants: `scene_apply` with a `branch` name, compare in one `scene_review` (a `radius, not the diameter. A 6-segment cylinder has flats on Z (1.732 x scale apart) and corners on X.- Stack parts from numbers: write each part's bottom and top Y first, adding the Y of the surface it stands on (a height "abovethe slab" is measured from the slab's top, not from Y = 0). After building, compare `scene_inspect` bounds with the task's numbers.+- A real-world object (vehicle, tree, furniture, character, prop): look in `scene_asset_catalog` first and place the GLB with the `asset`+ node field. Build it from primitives or a mesh recipe only when the catalog has nothing usable, and say what you searched for.+ Do not stack boxes and cylinders for something that exists as a model.+- Never guess a field or a range: read the `scene_capabilities` topic for it first. Do not set `environment.ground: false` or hand-frame a+ camera for a skinned GLB: since #1976 the auto-frame and the floor use its posed bounds.- Reuse one geometry ID for repeated parts and move them with node transforms.- To place a part by a face height ("upper surface at 0.5"), use `relations: [{ "kind": "level", "at": "top", "y": 0.5 }]` (`bottom` or `center` too) instead of adding half the thickness to a centre; Y is where that face lands, in world metres.- Put parts against each other with node `relations` (`attach`, `gap`, `flush`, `align`, `centered`) so one `set-node`@@ -79,6 +86,6 @@ Variants: `scene_apply` with a `branch` name, compare in one `scene_review` (a `## FinishDeliver the recipe, one `scene_look` image and any limit you hit. Say what you measured (counts, bounds, seconds)-apart from what you judged by eye. Do not claim Blender parity or general speed over three.js.+apart from what you judged by eye. Do not claim Blender parity or general speed over three.js. Build scenes with these tools, not with a bare three.js script.Changes, including unreleased and breaking ones: `https://crucible.codepawl.com/changelog.json`.A Crucible bug: `gh issue create -R codepawl/crucible` with the steps, the recipe and a still; no local paths.diff --git a/skills/build-crucible-scene/references/effects-and-feedback.md b/skills/build-crucible-scene/references/effects-and-feedback.mdnew file mode 100644index 00000000..8e4c583d--- /dev/null+++ b/skills/build-crucible-scene/references/effects-and-feedback.md@@ -0,0 +1,96 @@+# Effects and feedback: explosions, retro look, vehicle damage, asking the person++<!-- skill-navigation:start -->+This is the [effects and feedback](#effects-and-feedback-explosions-retro-look-vehicle-damage-asking-the-person) reference. Read the section for the task:+[Explosion](#explosion), [Retro look](#retro-look), [Vehicle damage](#vehicle-damage), [Ask the person with pins and lasso](#ask-the-person-with-pins-and-lasso),+[Review page for a phone](#review-page-for-a-phone) or [Splat palette and dither](#splat-palette-and-dither). Field ranges are always in `scene_capabilities`.+<!-- skill-navigation:end -->++Calls follow the conventions in `look.md`. `tests/skill-examples.test.js` applies every `operations` block, so they stay valid.++## Explosion++One `add-explosion` writes the whole blast: flash, ring, a gas-sim fire and smoke volume, bloom, sparks, dust, rubble, a scorch+decal and a camera shake, all as ordinary recipe sections whose IDs start with the blast `id`. Do not build the six systems by hand.+Read `scene_capabilities` topic `explosion` first (`size` 0.5 to 100 m, `fuel` `dry` or `oily`, `sparks`, `motionBlur`).++```json+{ "expectedRevision": 1, "operations": [+ { "type": "add-explosion", "id": "blast", "center": [0, 0, 0], "size": 6, "start": 0.5, "seed": 7, "fuel": "oily", "shake": 0.4 }+] }+```++- A scene holds one grid volume and 4 particle systems; the blast uses one volume and 3 systems, so a second blast or your own grid volume fails.+- `debris: { "node": "crate" }` breaks a convex mesh into 12 thrown pieces; send `set-physics` with a fixed floor first.+- The fire grid is baked from the name when the server applies the batch (about 4 s the first time for a fuel and seed). No file is needed.+- `bakeGasSim` and `bakeGasSimToGrids` (`docs/volumetric.md`) are library functions, not MCP tools. Over MCP the gas sim comes only through `add-explosion`.++## Retro look++`retro` on a material gives the PlayStation 1 look in raster renders: `vertexSnap: [width, height]` (whole numbers 16 to 4096) snaps+vertices to a screen grid so they jitter with the camera, and `affineUV: true` makes textures swim on large triangles. Set either or both.+The path tracer ignores it and shadows come from the unsnapped mesh. The topic is `materialRetro`.++```json+{ "expectedRevision": 2, "operations": [+ { "type": "set-material", "id": "paint", "retro": { "vertexSnap": [160, 120], "affineUV": true } }+] }+```+++## Vehicle damage++Reachable over MCP (`scene_capabilities` topic `vehicleDamage`, `docs/vehicle.md`): a `dented` geometry, which pushes `source` in around+each impact (`impacts` 1 to 8 of `{ point, direction, impulse }` in N s; `stiffness` 2000, `maxDepth` 0.25 m, `radius` 0.4 m by default),+and a part that tears off as a physics body on a `fixed` joint with `breakImpulse`. A dent keeps the vertex count and the source cannot+be a fragment or another dent.++```json+{ "expectedRevision": 3, "operations": [+ { "type": "add-geometry", "geometry": { "id": "body-dented", "type": "dented", "source": "cube", "stiffness": 40000, "maxDepth": 0.3, "radius": 0.5,+ "impacts": [ { "point": [0, 0.5, 0.5], "direction": [0, 0, -1], "impulse": 9000 } ] } },+ { "type": "set-node", "id": "body", "geometry": "body-dented" }+] }+```++Not reachable over MCP: `detachedPartFlight` (a loose part's flight in a kinematic drive, `part.size` the box extents so no corner+crosses the wall) and `hingedDoorSwing`. They are library helpers of `@codepawlhq/crucible/addons/vehicle`; no `scene_apply`+operation calls them, so do not write one. Read `docs/vehicle.md` only when you write scene code.++## Ask the person with pins and lasso++`scene_ask_user` is for a change the person cannot put in words ("warmer here", "this bit"), not for facts you can inspect. It+opens the current view in their browser (in an MCP Apps host, inline in the chat, answering `outcome: "pending"` at once). They+pin up to 16 points with a note each. A mark returns `partId`, `point`, `normal`, `note`, `distance`, `material` and `view.camera`.++- A pin or lasso carrying `materialSharedWith` (part IDs, at most 8; `materialSharedWithMore` counts the rest) means other parts use+ that material, so changing it changes them too. Give the part its own material first, then edit that one:++```json+{ "expectedRevision": 4, "operations": [+ { "type": "add-material", "material": { "id": "paint-warm", "color": [0.4, 0.6, 0.8] } },+ { "type": "set-node", "id": "lid", "material": "paint-warm" },+ { "type": "set-material", "id": "paint-warm", "color": [0.8, 0.55, 0.4] }+] }+```++- A mark with `kind: "lasso"` is an outline: apply the note to every entry of its `parts` (`partId`, `coverage`, `material`, most+ covered first). A part with `edge: true` (coverage under 0.15) only grazes the outline: skip it when the note does not fit.+ Only the browser view makes lassos; the inline chat view and the review page take pins only.+- `outcome` `cancelled` or `timeout` returns no marks: ask in plain text. Edits made while they mark change `revision`; the result warns.+- `scene_ask_user` has no `motionTime` field: marks are not made at a film time yet (issue #922). For a film moment, `scene_look` with+ `motionTime` and ask in words, or ask on the base pose.++## Review page for a phone++`scene_export_web` with `review: true` (needs `--jobs`, no game) writes `index.html` and `frame.png` under `<jobs>/exports/`. Host+the folder or send it. The reviewer taps to pin and presses Save file or Copy. Pass the text of that file (at most 16 KiB) to+`scene_ask_user` as `reviewFile`: the marks come back with the same fields as a local call, without the PNG. Each export is read once, and+the server remembers the camera of the last 8 exports, so export again after a second read or a restart.++## Splat palette and dither++Library code, not a recipe field: `createGaussianSplats(data, { alphaCut: 0.5, palette: ['#1b1b2f', '#c8553d', '#ffd166'], dither: 'bayer4' })`+from `@codepawlhq/crucible/addons/gaussian-splats`. `palette` is 2 to 256 colours (hex strings or `[r, g, b]` of 0 to 1) and needs+`alphaCut`; `dither` is `none`, `bayer4` or `bayer8`. Only opaque splat pixels snap. There is no outline option on splats yet, so do not+promise one (`docs/gaussian-splats.md`).diff --git a/skills/build-crucible-scene/references/film-and-animation.md b/skills/build-crucible-scene/references/film-and-animation.mdindex f246a676..921bdb9e 100644--- a/skills/build-crucible-scene/references/film-and-animation.md+++ b/skills/build-crucible-scene/references/film-and-animation.md@@ -3,7 +3,7 @@<!-- skill-navigation:start -->This is the [Film and animation: motion tracks, shots, timeline](#film-and-animation-motion-tracks-shots-timeline) reference. Read [Motion record](#motion-record) before any track.Then read what the film needs: [Animated lights, sun, sky and effects](#animated-lights-sun-sky-and-effects), [Shots and cuts](#shots-and-cuts) or-[Character and imported motion](#character-and-imported-motion). Read [Before a film goes out](#before-a-film-goes-out) completely before the first export.+[Character and imported motion](#character-and-imported-motion) or [Seamless turntable](#seamless-turntable). Read [Before a film goes out](#before-a-film-goes-out) completely before the first export.<!-- skill-navigation:end -->Calls follow the conventions in `look.md`. `tests/skill-examples.test.js` applies every block, so they stay valid.@@ -12,11 +12,11 @@ Everything here is deterministic: a seek to a time gives the same pixels as play## Motion record-`set-motion` takes one complete record `{ duration, loop, tracks }`, or `null` to clear it. A track has `kind`, an+`set-motion` takes one complete record `{ duration, loop, tracks }` (`duration` 0.1 to 30 s), or `null` to clear it. A track has `kind`, an`id` (omitted for `camera`, `sun`, `environment`, `effects`), a `property`, optional `interpolation`(`LINEAR`, `STEP`, `SMOOTH`, `CUBICSPLINE`) and `keyframes` of `{ time, value }` (optional per-key `easing`).Properties: node `translation`, `rotation` (XYZW quaternion), `scale`, `visible` (1 or 0); material `color`,-`emission`, `roughness`, `metallic`; camera `eye`, `target`, `fov`, `roll`. Every referenced ID must exist after the+`emissiveColor`, `emission`, `roughness`, `metallic`; camera `eye`, `target`, `fov`, `roll`. Every referenced ID must exist after thebatch. Nonlooping motion must cover every sampled time.Tool `scene_apply` (a camera push-in plus a spinning part; node `lid` exists):@@ -95,6 +95,15 @@ Rigs, `motion.ik`, constraints, drivers, clip layers on an imported asset and mo`scene_capabilities`. Read `scene_inspect` (`motionIk`, `rig`, `animations`) after every change and fix its warningsbefore you finish.+## Seamless turntable++One turn that repeats with no hitch: rotation keys every 45 degrees with `interpolation: "LINEAR"` (rotation keys blend with a+quaternion slerp that takes the short way, so keep neighbouring keys well under 180 degrees apart; 9 keys, the last at 360, give+constant speed), motion `duration` equal to the turn, `loop: true`, and a video job of the same `duration`. Video frame n samples the+clock at n / fps, so the last frame stops one step short of the full turn and a repeated clip has no doubled frame. Check cropping on+the union of the object's bounds over frames sampled through the whole turn (`scene_review` with several `motionTime`), not one still:+the widest angle is rarely frame 0.+## Before a film goes outA metro film once shipped all of these as "texture glitches". Check each one in the preview:diff --git a/skills/build-crucible-scene/references/look.md b/skills/build-crucible-scene/references/look.mdindex 57a8b400..49cb3fd5 100644--- a/skills/build-crucible-scene/references/look.md+++ b/skills/build-crucible-scene/references/look.md@@ -27,6 +27,12 @@ Tool `scene_apply`:`world: true` makes the sky the background too.+Flat dark backdrop for one object (item card, turntable): video has no alpha, so put an emissive `box` card about 1.5 m behind the+target, square to the camera, with `color` black, the tint in `emissiveColor` and `emission` above 0. A setup such as `studio` still+lights that card through its environment light, so set `environmentIntensity` near 0.02 (range 0 to 100) and the emissive alone sets+its colour. Set overall brightness with `effects.exposure` (0.01 to 16), then measure a corner pixel of a `scene_look` against the+target hex and scale `emission`.+Time of day comes from the sun alone: `"sky": { "type": "physical", "preset": "golden-hour" }` (also `sunset`, `blue-hour`) sets sun elevation and azimuth, and the key, sky and haze follow from one atmosphere, so a low sun reads warm with no grading. Put `sunElevation` or `sunRotation` beside a preset to move the sun; a preset starts the sky again, so earlier sky fields are dropped.## HDRI from the catalogdiff --git a/tests/skill-examples.test.js b/tests/skill-examples.test.jsindex 2169347e..67e088f6 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'];+const referenceNames = ['look', 'light', 'camera', 'film-and-animation', 'effects-and-feedback'];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')));