Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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.json
index 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": true
diff --git a/skills/build-67js-scene/references/errors-and-recovery.md b/skills/build-67js-scene/references/errors-and-recovery.md
index 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.md
index 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-clou
looks, `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 = off
multiple scattering; `multiScatter`, `multiExtinction` and `multiAnisotropy` (0 to 1, default 0.5 each) shape them and
act 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`).