3D engine that AI agents drive
Point the scene skill at scene_capabilities topics
Nguyen Xuan Aneaa69942bbd0
diff --git a/changes/skills-capability-topics.md b/changes/skills-capability-topics.mdnew file mode 100644index 00000000..951a65f6--- /dev/null+++ b/changes/skills-capability-topics.md@@ -0,0 +1 @@+The scene skill points agents at the scene_capabilities topics for field detail, drops the notes for the fixed fog schema (#661) and packaged catalog (#664) gaps, and its HDRI, look and fog eval checks the shipped names and 3 scatter octaves again.diff --git a/skills/build-67js-scene/SKILL.md b/skills/build-67js-scene/SKILL.mdindex c4d2569c..ad42993a 100644--- a/skills/build-67js-scene/SKILL.md+++ b/skills/build-67js-scene/SKILL.md@@ -12,8 +12,9 @@ Start the server with `npx --package @codepawlhq/67js 67js-mcp --backend gpu --a## Loop-1. `scene_capabilities`: features, limits and field detail. Read it before a feature you have not used; it is the- source for every field list, so this skill names fields and does not copy them.+1. `scene_capabilities`: with no arguments it returns a short index of features, limits and topic names. Pass+ `topic` for the field list of one feature (`environment`, `materialFields`, `geometries`, `meshEdit.bevel`,+ `motion`). Tool schemas list only common fields, so read the topic before a feature you have not used.2. `scene_create` with a `recipe`: `{ "format": "67js.scene", "schemaVersion": 1, "geometries": [], "materials": [], "nodes": [] }`plus optional `camera`, `environment`, `effects`, `shadow`, `motion`, `bake`, `timeline`.3. `scene_inspect`: node IDs, bounds, `diagnostics`, current `revision`.diff --git a/skills/build-67js-scene/evals/hdri-look-and-fog.json b/skills/build-67js-scene/evals/hdri-look-and-fog.jsonindex 14d1b6b9..5655b602 100644--- a/skills/build-67js-scene/evals/hdri-look-and-fog.json+++ b/skills/build-67js-scene/evals/hdri-look-and-fog.json@@ -3,30 +3,20 @@"skills": ["build-67js-scene"],- "prompt": "Using the 67js MCP tools and the build-67js-scene skill: make a small outdoor-style scene (a ground slab and a sphere). Light it with a catalog HDRI as the visible sky if one works (otherwise a light setup), apply a color look, and add volume fog with multiple scattering if the tools allow it (otherwise plain volume fog). Look at it, then finish by calling scene_export_recipe. If a call fails, do not loop: use the closest thing that works.",- "expected": "The agent called scene_asset_catalog and ends with a recipe that has a sky (environment.hdri or a setup), a color look, volume fog with density above 0, and a scene_look after the last edit. Strict target once issues 661 and 664 are fixed: hdri sky-clouds, look teal-orange, volumeFog.scatterOctaves 3.",+ "prompt": "Using the 67js MCP tools and the build-67js-scene skill: make a small outdoor-style scene (a ground slab and a sphere). Use the shipped HDRI sky-clouds as the visible sky, the shipped teal-orange color look, and volume fog with 3 scatter octaves. Look at it, then finish by calling scene_export_recipe.",+ "expected": "The agent ends with a recipe that has hdri sky-clouds, look teal-orange, volumeFog.scatterOctaves 3 with density above 0, and a scene_look after the last edit.","checks": [{- "label": "scene_asset_catalog called",- "toolCalled": "scene_asset_catalog"+ "label": "sky is sky-clouds",+ "path": "environment.hdri",+ "op": "equals",+ "value": "sky-clouds"},{- "label": "a sky is chosen",- "anyOf": [- {- "path": "environment.hdri",- "op": "exists"- },- {- "path": "environment.setup",- "op": "exists"- }- ]- },- {- "label": "a color look is set",+ "label": "look is teal-orange","path": "environment.look",- "op": "exists"+ "op": "equals",+ "value": "teal-orange"},{"label": "volume fog is on",@@ -34,6 +24,12 @@"op": "gt","value": 0},+ {+ "label": "three scatter octaves",+ "path": "environment.volumeFog.scatterOctaves",+ "op": "equals",+ "value": 3+ },{"label": "scene_look after the last edit","lookAfterLastEdit": truediff --git a/skills/build-67js-scene/references/errors-and-recovery.md b/skills/build-67js-scene/references/errors-and-recovery.mdindex 400ad088..f3fa1c15 100644--- a/skills/build-67js-scene/references/errors-and-recovery.md+++ b/skills/build-67js-scene/references/errors-and-recovery.md@@ -10,15 +10,13 @@ Every tool error names what failed and what to do next, so read the message befo| `expectedRevision must match the current revision.` | Another call changed the scene, or you used an old number. | `scene_inspect`, take its `revision`, resend the same batch. || `Camera fStop drives depth of field; set effects.depthOfField.blur to 0 or remove fStop.` | Both depth of field controls are on. | Keep one: `fStop` on the camera, or `effects.depthOfField.blur`. See `camera.md`. || `Give a camera fov or a focalLength, not both.` | Both lens fields in one command. | Send only one; `focalLength` replaces `fov`. |-| `Unrecognized keys: "scatterOctaves", "multiScatter"` on `volumeFog` | The MCP schema does not accept the opt-in scattering fields yet (#661). | Do not retry; use `density`, `anisotropy`, `noiseAmount`; see `look.md`. |-| `The URL must be of scheme file` on `hdri` or `look` | A shipped catalog name fails in the packaged server (#664). | Use a catalog ID, a `setup` or a built-in look (`warm`, `cool`, `contrast`, `faded`). || `bake.gridFog needs bake.irradianceGrid.` | `gridFog` alone. | Add `irradianceGrid: true`. See `light.md`. || `Shot <name> reads motion up to N s but the motion lasts M s.` | A timeline longer than a non-looping motion. | Lengthen the motion, set `loop: true` or a shot `motionStart`. || A light list error naming a cap | More than 16 point, 8 spot or 7 area lights. | Merge or remove lights; each list replaces the old one. || `environment.hdri must be one of ... or the 64-character ID ...` | A made-up name, path or URL. | `scene_asset_catalog`, copy a listed name or ID. || `No scene is active` | Nothing created yet, or disposed. | `scene_create`. || Result has `renderSucceeded: false` and `renderError` | The edit committed, the draw failed (bad pass, lost context). | `scene_export_recipe` to keep it, fix the cause named in `renderError`, then `scene_look`. |-| An unknown field is rejected before dispatch | A typo or a field of another recipe section. | Fix the name; `scene_capabilities` lists valid fields. |+| An unknown field is rejected before dispatch | A typo or a field of another recipe section. | Fix the name; `scene_capabilities` with the section as `topic` lists valid fields. |## Diagnostics in `scene_inspect`diff --git a/skills/build-67js-scene/references/look.md b/skills/build-67js-scene/references/look.mdindex bb01c151..475f2d1b 100644--- a/skills/build-67js-scene/references/look.md+++ b/skills/build-67js-scene/references/look.md@@ -26,9 +26,6 @@ Call `scene_asset_catalog` (no arguments). It lists two shipped HDRIs, `sky-cloulooks, `teal-orange` and `noir`, and every `.hdr` (kind `environment`) and `.cube` (kind `look`) file in the server's`--assets` folder as a 64-character ID. A recipe names an entry and never carries a path or URL. For a bigger HDRI,tell the user to put a 1k or 2k `.hdr` (4 MiB at most) in the assets folder and restart the server for its ID.-Known gap (issue #664): in the packaged server a shipped name (`sky-clouds`, `teal-orange`) can fail with "The URL must be of-scheme file". Do not retry it: use a catalog ID from `--assets`, or fall back to `setup` (`studio`, `sunset`) and the-built-in looks below, and say which one you used.Tool `scene_apply`:@@ -79,11 +76,12 @@ Multiple scattering is opt in. `scatterOctaves` (integer 1 to 4, default 1 = offmultiple scattering; `multiScatter`, `multiExtinction` and `multiAnisotropy` (0 to 1, default 0.5 each) shape them andact only above 1 octave. Each octave costs three extra density taps per step, so start at 2.-Known gap (issues #661 and #664): the MCP tool schema refuses these fields today. `scene_create` and `scene_apply`-return "Unrecognized keys: scatterOctaves, multiScatter" for `volumeFog`, so multiple scattering is not reachable over-MCP yet; the library (`createAgentScene`) accepts them. Do not retry: build the fog from `density`, `anisotropy`,-`noiseAmount` and `heightFalloff`, and tell the user the opt-in scattering needs the schema fix. Check-`scene_capabilities` once in a while, since the fix removes this note.+```json+{ "type": "set-environment", "environment": { "volumeFog": { "density": 0.04, "scatterOctaves": 3, "multiScatter": 0.5 } } }+```++`keyTransmittance` and `surfaceTransmittance` are also opt in. `scene_capabilities` with `topic: "environment"` lists+every `volumeFog` field and its range.Point lights do not scatter in volume fog; the sun does. A sunlit closed room with fog uses `bake.gridFog`(see `light.md`). Animate density with an `environment` track `volumeFogDensity` (see `film-and-animation.md`).