Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Document line art and set the size and tool cost budgets (#285)

Nguyen Xuan An44b9ec5f0862
diff --git a/bench/size/budgets.json b/bench/size/budgets.json
index 459b421b..4191f5e2 100644
--- a/bench/size/budgets.json
+++ b/bench/size/budgets.json
@@ -6,7 +6,7 @@
"agent-scene": 100000
},
"budgets": {
- "entry:core": 88890,
+ "entry:core": 88936,
"entry:model": 14400,
"entry:nature": 13200,
"entry:motion": 15260,
@@ -34,22 +34,23 @@
"entry:ground-bounce": 9460,
"entry:path-tracer": 15960,
"entry:texture-set": 900,
- "entry:agent-scene": 80770,
- "entry:agent-scene+lazy": 263350,
- "entry:agent-asset": 112170,
- "entry:agent-asset+lazy": 274720,
+ "entry:agent-scene": 81036,
+ "entry:agent-scene+lazy": 269152,
+ "entry:agent-asset": 112387,
+ "entry:agent-asset+lazy": 280473,
"entry:hdri": 3300,
"entry:camera-effects": 8600,
"entry:water-reflection": 26580,
"entry:render-passes": 1700,
+ "entry:line-art": 23974,
"entry:gaussian-splats": 11023,
"entry:material-layer-shaders": 21400,
"entry:light-linking": 19720,
"entry:cascaded-shadows": 28530,
- "scene:lit-box": 65870,
- "scene:gltf-box": 90150,
- "scene:gltf-box+lazy": 93480,
- "scene:agent-scene": 109670,
- "scene:agent-scene+lazy": 292250
+ "scene:lit-box": 65920,
+ "scene:gltf-box": 90200,
+ "scene:gltf-box+lazy": 93527,
+ "scene:agent-scene": 109939,
+ "scene:agent-scene+lazy": 298059
}
}
diff --git a/bench/tool-cost-budgets.json b/bench/tool-cost-budgets.json
index 0ff57b3c..29494144 100644
--- a/bench/tool-cost-budgets.json
+++ b/bench/tool-cost-budgets.json
@@ -1,16 +1,16 @@
{
- "measured": "2026-10-31, from scripts/measure-tool-cost.mjs; raised by 800 total and 150 for scene_apply for branch and labels fields (no new tool); raised by 650 total and 80 for scene_apply for clip layers, bone masks and retargeting through MCP; raised by 20 for scene_create and 20 for the scene_capabilities result after merging the expression language with the material graph; was 373388 schema bytes before shared IDs and recipe references; trimmed after the render-passes merge: material graph, depth of field, motion blur and passes details moved to scene_capabilities, budgets set to the measured value plus 0.5% (total 188267, scene_capabilities result 5167); raised by 95 for scene_apply and 690 for the scene_capabilities result for node relations; curve and text geometry entries shortened to a pointer at scene_capabilities curveText, budgets set to the measured value plus 0.5% (total 189468, scene_capabilities result 6399); then six modifier ops (weld, triangulate, edge_split, smooth, simple_deform, cast) added as one compact schema entry with details in scene_capabilities meshModifiers, entry and mesh_stack description shortened: total 190382 (budget unchanged at 190420), mesh_edit 34216 (budget 34220), scene_capabilities result 7042 (budget 7050); mesh_stack 11682 (budget 11690); after merging imported mesh topology with the modifier ops: raised the total to 190480 (measured 190471), mesh_edit to 34300 (measured 34293) and the scene_capabilities result to 7520 (measured 7512) for imported mesh edits; then cloth (recipe cloth, set-cloth, grid geometry) added with the total unchanged at 190480 (measured 189159): physics descriptions shortened and set-physics now takes the same record reference as set-motion, scene_create raised to 62150 and scene_apply lowered to 44130, scene_capabilities result raised to 8190 (measured 8176) for the cloth details; then particles and hair (recipe `particles`, set-particles) added with the total unchanged at 190480 (measured 189642, scene_create raised to 62350 and scene_apply to 44370 for the recipe particles reference and set-particles): the section is one record reference described in scene_capabilities, so the scene_capabilities result rose to 9570 (measured 9523) for the particle and hair fields; after merging the film timeline (recipe timeline, set-timeline) with particles: total 190719 (budget 190730), scene_create 62464, scene_apply 44620, scene_capabilities result 9902; then the path tracer renderer setting (drop z.int bounds, integers still checked by the job validator): total raised to 190830 (measured 190818); after merging the render limits and light bake with the path tracer: measured total 190013, scene_create raised to 62680 (measured 62667), scene_apply to 44860 (measured 44852) and the scene_capabilities result to 10620 (measured 10613) for the bake section and job size limits; then material layers anisotropy and iridescence (issue #51): the 16 layer fields take one short line each in the schema and their ranges and notes moved to scene_capabilities scene.materialLayers, so the scene_capabilities result rose to 12230 (measured 12168); then the worker bake limit added workerMaxSeconds to the bake limits (result 13361, budget raised to 13370); then the sculpt and shrinkwrap mesh edits (issue #47) with the total unchanged at 190830 (measured 190612): the face rule and tag prefix descriptions shortened (the face rule text repeats in every select field), so mesh_edit rose to 33980 (measured 33960) and mesh_stack fell to 11030 (measured 11014), and the scene_capabilities result rose to 13350 (measured 13338) for the meshSculpt notes; then recipe light links and shadow cascades (issue #52): environment fields added to the shared environment schema with the total unchanged at 190830 (measured 190507) by shortening its descriptions, and the scene_capabilities result raised to 13870 (measured 13865) for lightLinking and shadowCascades; then the nine remaining modifiers (issue #42: screw, skin, wireframe, lattice, curve, hook, wave, weighted_normal, smooth_by_angle) added their notes to meshModifiers and a free modifier record replaced the modifier schema entry, so the schemas shrank and the scene_capabilities result rose to 15900 (measured 15814); path query of scene_inspect (issue #64): one record field of 205 bytes in the scene_inspect schema (total 190732, within its budget) and the navigation notes in scene_capabilities, so the result rose to 14500 (measured 14494); reflection probes (issue #55): the bake.probes line, and the scene_capabilities result raised to 16600 (measured 16541) after merging with main; volumeFog shadowAmbient (issue #165): scene_create raised to 62945 (measured 62940) and scene_apply to 45040 (measured 45037); keyframe easing (issue #286): one easing string field in each of the motion track schemas, scene_create raised to 63450 (measured 63444) and the total to 191000 (measured 190994); glTF import line gltfImport (issue #280): the scene_capabilities result raised to 16701 (measured 16681)",
- "schemaTotalBytes": 191040,
+ "measured": "2026-10-31, from scripts/measure-tool-cost.mjs; raised by 800 total and 150 for scene_apply for branch and labels fields (no new tool); raised by 650 total and 80 for scene_apply for clip layers, bone masks and retargeting through MCP; raised by 20 for scene_create and 20 for the scene_capabilities result after merging the expression language with the material graph; was 373388 schema bytes before shared IDs and recipe references; trimmed after the render-passes merge: material graph, depth of field, motion blur and passes details moved to scene_capabilities, budgets set to the measured value plus 0.5% (total 188267, scene_capabilities result 5167); raised by 95 for scene_apply and 690 for the scene_capabilities result for node relations; curve and text geometry entries shortened to a pointer at scene_capabilities curveText, budgets set to the measured value plus 0.5% (total 189468, scene_capabilities result 6399); then six modifier ops (weld, triangulate, edge_split, smooth, simple_deform, cast) added as one compact schema entry with details in scene_capabilities meshModifiers, entry and mesh_stack description shortened: total 190382 (budget unchanged at 190420), mesh_edit 34216 (budget 34220), scene_capabilities result 7042 (budget 7050); mesh_stack 11682 (budget 11690); after merging imported mesh topology with the modifier ops: raised the total to 190480 (measured 190471), mesh_edit to 34300 (measured 34293) and the scene_capabilities result to 7520 (measured 7512) for imported mesh edits; then cloth (recipe cloth, set-cloth, grid geometry) added with the total unchanged at 190480 (measured 189159): physics descriptions shortened and set-physics now takes the same record reference as set-motion, scene_create raised to 62150 and scene_apply lowered to 44130, scene_capabilities result raised to 8190 (measured 8176) for the cloth details; then particles and hair (recipe `particles`, set-particles) added with the total unchanged at 190480 (measured 189642, scene_create raised to 62350 and scene_apply to 44370 for the recipe particles reference and set-particles): the section is one record reference described in scene_capabilities, so the scene_capabilities result rose to 9570 (measured 9523) for the particle and hair fields; after merging the film timeline (recipe timeline, set-timeline) with particles: total 190719 (budget 190730), scene_create 62464, scene_apply 44620, scene_capabilities result 9902; then the path tracer renderer setting (drop z.int bounds, integers still checked by the job validator): total raised to 190830 (measured 190818); after merging the render limits and light bake with the path tracer: measured total 190013, scene_create raised to 62680 (measured 62667), scene_apply to 44860 (measured 44852) and the scene_capabilities result to 10620 (measured 10613) for the bake section and job size limits; then material layers anisotropy and iridescence (issue #51): the 16 layer fields take one short line each in the schema and their ranges and notes moved to scene_capabilities scene.materialLayers, so the scene_capabilities result rose to 12230 (measured 12168); then the worker bake limit added workerMaxSeconds to the bake limits (result 13361, budget raised to 13370); then the sculpt and shrinkwrap mesh edits (issue #47) with the total unchanged at 190830 (measured 190612): the face rule and tag prefix descriptions shortened (the face rule text repeats in every select field), so mesh_edit rose to 33980 (measured 33960) and mesh_stack fell to 11030 (measured 11014), and the scene_capabilities result rose to 13350 (measured 13338) for the meshSculpt notes; then recipe light links and shadow cascades (issue #52): environment fields added to the shared environment schema with the total unchanged at 190830 (measured 190507) by shortening its descriptions, and the scene_capabilities result raised to 13870 (measured 13865) for lightLinking and shadowCascades; then the nine remaining modifiers (issue #42: screw, skin, wireframe, lattice, curve, hook, wave, weighted_normal, smooth_by_angle) added their notes to meshModifiers and a free modifier record replaced the modifier schema entry, so the schemas shrank and the scene_capabilities result rose to 15900 (measured 15814); path query of scene_inspect (issue #64): one record field of 205 bytes in the scene_inspect schema (total 190732, within its budget) and the navigation notes in scene_capabilities, so the result rose to 14500 (measured 14494); reflection probes (issue #55): the bake.probes line, and the scene_capabilities result raised to 16600 (measured 16541) after merging with main; volumeFog shadowAmbient (issue #165): scene_create raised to 62945 (measured 62940) and scene_apply to 45040 (measured 45037); keyframe easing (issue #286): one easing string field in each of the motion track schemas, scene_create raised to 63450 (measured 63444) and the total to 191000 (measured 190994); glTF import line gltfImport (issue #280): the scene_capabilities result raised to 16701 (measured 16681); outlines and toon light (issue #285): environment.lines is one free record and material toon one short line, total 192150 (measured 192127), scene_create 63800 (measured 63778), scene_apply 45480 (measured 45463), scene_create_asset 19500 (measured 19480), and the scene_capabilities result 17060 (measured 17038) for the lineArt entry",
+ "schemaTotalBytes": 192150,
"schemaToolBytes": {
- "scene_create": 63450,
- "scene_apply": 45040,
+ "scene_create": 63800,
+ "scene_apply": 45480,
"mesh_edit": 33980,
- "scene_create_asset": 19310,
+ "scene_create_asset": 19500,
"mesh_stack": 11030
},
"schemaOtherToolBytes": 4000,
"resultBytes": {
- "scene_capabilities": 16701,
+ "scene_capabilities": 17060,
"scene_create": 1400,
"scene_inspect": 1400,
"mesh_inspect": 1200,
diff --git a/changes/285.md b/changes/285.md
new file mode 100644
index 00000000..491d8f61
--- /dev/null
+++ b/changes/285.md
@@ -0,0 +1 @@
+- Add outlines, toon light and polylines (part of #285). `environment.lines: {}` draws outlines of fixed pixel width at silhouettes, part boundaries, creases and depth jumps from the object ID, normal and depth guides. `lines.polylines` draws screen-width lines in the world, and `toon` on a material (or `lines.toon`) bands the light. A recipe turns it on with one `set-environment` edit through MCP, and `scene_capabilities` reports `lineArt`. The code is the new addon `@codepawlhq/67js/addons/line-art`, loaded only by recipes that use it, and a scene without `lines` draws as before. Guide: `docs/line-art.md`.
diff --git a/docs/agent-look.md b/docs/agent-look.md
index 80167f3d..aa254bbf 100644
--- a/docs/agent-look.md
+++ b/docs/agent-look.md
@@ -177,6 +177,16 @@ Range values between zero and `0.001` reject.
The existing directional shadow map remains the source of shadows.
Point lights can illuminate through opaque walls.
+## Outlines and toon light
+
+`environment.lines` draws outlines, an optional banded light and screen-width polylines. One edit turns it on:
+
+```json
+{ "type": "set-environment", "environment": { "lines": { "width": 2, "toon": 3 } } }
+```
+
+`"lines": null` turns it off. A material can also set `toon` (0 to 8) for its own bands. The fields, limits and costs are in [line art](line-art.md). `scene_capabilities` reports `lineArt` and the `toon` layer field.
+
## Volume fog
Active volume fog requires an opaque renderer with `{ hdr: true, depth: true }` and negotiated HDR support.
diff --git a/docs/line-art.md b/docs/line-art.md
new file mode 100644
index 00000000..07f6d4f2
--- /dev/null
+++ b/docs/line-art.md
@@ -0,0 +1,58 @@
+# Outlines, toon light and lines
+
+Diagrams, cutaways and toon films need lines and a banded shade. One recipe edit turns them on:
+
+```json
+{ "environment": { "lines": { "width": 2 } } }
+```
+
+That draws a dark outline at silhouettes, part boundaries, creases and depth jumps. Add `"toon": 3` to `lines` to band the light of every material into three steps, or `"toon": 4` on one material. Remove the field (or set `"lines": null` in `set-environment`) and the scene renders as before.
+
+## Fields of `environment.lines`
+
+| Field | Default | What it does |
+| --- | --- | --- |
+| `width` | 1.5 | Line width in output pixels, 0.25 to 16. Fractions draw a fainter line. |
+| `color` | `[0.02, 0.02, 0.02]` | Linear RGB of the line, 0 to 4. The colour is drawn before tone mapping, so a bright line reads a little darker than written. |
+| `boundaries` | `true` | A line where the object ID changes: silhouettes and the edge between two parts. |
+| `creaseAngle` | 35 | Degrees. A line where the surface normal turns by more than this between neighbouring pixels. 0 turns creases off. |
+| `depthJump` | 0.08 | A line where one surface sits in front of another of the same part. Relative step of the inverse depth. 0 turns it off. |
+| `toon` | 0 | Light steps for every material that sets no `toon` of its own, 0 to 8. 0 leaves the smooth light. |
+| `polylines` | none | Lines drawn in the world with a screen width, see below. |
+
+The width is in pixels of the output, so a 480 pixel preview and a 1920 pixel render carry lines of the same thickness. A scene that wants the same look at every size should scale `width` with the image height itself.
+
+## Toon light
+
+`toon` on a material (also a layer field, 0 to 8, 0 off) steps the cosine of each light that reaches it. The sun, a point light and a spot light each make their own bands, and the edge between two bands is 0.02 of the light range wide. Shadows keep their own softness, and the sky light that fills the dark side is not banded. A material with `toon` set wins over `lines.toon`.
+
+## Polylines
+
+```json
+{ "environment": { "lines": { "polylines": [
+ { "points": [[0.2, 1.0, 0.6], [0.2, 1.8, 0.6], [-1.2, 1.8, 0.6]], "color": [0.8, 0.1, 0.1], "width": 3, "depthTest": false }
+] } } }
+```
+
+Each polyline has 2 to 256 `points` (`closed: true` joins the last to the first), and its own `color`, `width` and `depthTest` (default `true`: the scene hides what lies behind a surface). Use `depthTest: false` for leader lines and annotations that stay in front. At most 64 polylines and 4,096 segments per recipe. Ends and joins are round.
+
+## Limits
+
+- Outlines and polylines draw only for a frame that carries `lines`. They read the opaque and cutout geometry only (like render passes), so blended and translucent parts get no outline.
+- An outline costs two extra draws of the opaque geometry (the object ID and normal passes) plus one full-screen pass. Frames without lines cost nothing.
+- Outlines need `depth: true` on the renderer and `installRenderPasses` first. A render job writes the pass files without lines.
+- Creases are found from the picture, not from the mesh: a bevel wider than a few pixels turns its normal slowly and draws no line. Lower `creaseAngle` or use a sharper edge.
+- Through the MCP server, `scene_create` and `set-environment` take `environment.lines`, and a material takes `toon`. `scene_capabilities` reports both.
+
+## Code
+
+```js
+import { Renderer67 } from '@codepawlhq/67js';
+import { installRenderPasses } from '@codepawlhq/67js/addons/render-passes';
+import { installLineArt, resolveLineArt } from '@codepawlhq/67js/addons/line-art';
+
+const renderer = installLineArt(installRenderPasses(new Renderer67(canvas, parts, { depth: true, hdr: true })));
+renderer.render({ ...camera, lines: resolveLineArt({ width: 2, toon: 3 }) });
+```
+
+A recipe host loads the code with `await loadAgentSceneModules(recipe)`. The preview and render jobs install it themselves.
diff --git a/docs/mcp.md b/docs/mcp.md
index f491a851..a1b82ff3 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -175,6 +175,8 @@ The recipe also accepts [authored lighting, fog, effects and shadow coverage](ag
Use `set-environment`, `set-effects` and `set-shadow` with nested partial records to adjust the look.
Nested `volumeFog` and `bloom` fields merge. `pointLights` replaces the complete list.
+`environment.lines` turns on outlines, toon light and polylines, and `lines: null` removes them. A material takes `toon` for its own light steps. The code loads only for a recipe that uses either. See [line art](line-art.md).
+
The preview allocates depth support at creation so enabling fog does not recreate render targets.
Active volume fog requires HDR support. Unsupported previews reject that edit before committing.
diff --git a/docs/parity.md b/docs/parity.md
index a003da04..4b5d06cf 100644
--- a/docs/parity.md
+++ b/docs/parity.md
@@ -197,7 +197,7 @@ To move to a new Blender release, run `node scripts/parity-manual-snapshot.mjs`.
| Rendering > Materials > Assignment | done | A node names one material. | [agent-scene](../tests/agent-scene.test.js) | |
| Rendering > Materials > Preview | out of scope | Interface for a person. Agents use `scene_look`. | | |
| Rendering > Materials > Settings | partial | Opaque and blend in recipes, and mask on imported assets, with double-sided support. | [gltf-extensions](../tests/gltf-extensions.test.js) | #51 |
-| Rendering > Materials > Line Art | missing | No line rendering. | | |
+| Rendering > Materials > Line Art | partial | `toon` on a material bands the light. Outlines come from screen-space guides (object ID, normal, depth) at a fixed pixel width. Line Art modifier options (occlusion levels, intersections, chaining, hatching) do not exist. Not yet compared with a Blender Line Art render. | [line-art](../tests/line-art.test.js), [guide](line-art.md) | |
| Rendering > Materials > Legacy Textures | out of scope | Blender keeps these for old files. | | |
| Rendering > Shader Nodes > Input | partial | `uv` coordinates only. There is no object, geometry, camera or light-path input. | [material-graph](../tests/material-graph.test.js) | #50 |
| Rendering > Shader Nodes > Output | partial | A graph makes base colour, roughness, metallic, emission and height. It is baked to textures on the CPU, so it can not react to light, view or position. The `brick-graph` reference scene scores 0.2269 against Cycles; its `brick-flat` control (the graph's average colour, no maps) is the baseline it is compared with, and a bump of 0 would score 0.2065, so the bump is stronger than Blender's, not weaker. | [material-graph](../tests/material-graph.test.js), [brick-graph scene](../bench/reference/scenes.js) | #50 |
@@ -208,7 +208,7 @@ To move to a new Blender release, run `node scripts/parity-manual-snapshot.mjs`.
| Rendering > Shader Nodes > Utilities | partial | Maths on numbers and vectors: add, sub, mul, div, min, max, pow, abs, floor, fract, sqrt, clamp and smoothstep. There is no vector maths, mapping, map range or separate and combine nodes. | [material-graph](../tests/material-graph.test.js) | #50 |
| Rendering > Shader Nodes > Group | missing | No node graph. | | #50 |
| Rendering > Color Management | partial | ACES tone mapping and grading. There is no choice of color space or display. | [effects](../tests/effects.test.js) | |
-| Rendering > Freestyle | missing | No line rendering. | | |
+| Rendering > Freestyle | partial | `environment.lines` draws silhouette, boundary and crease lines in screen space, and `polylines` draws screen-width lines in the world. There are no line sets, styles or strokes along curves. | [line-art](../tests/line-art.test.js), [guide](line-art.md) | |
| Rendering > View Layers & Passes | partial | Render jobs write albedo, normal, emission, depth and object ID passes as PNG files. There are no view layers, no cryptomatte and no lighting passes (diffuse, glossy, shadow). | [render-passes](../tests/render-passes.test.js) | #54 |
| Rendering > Render Output > Output Properties | partial | PNG and MP4, frame rate, duration (to 60 s) and size, and a CPU or NVENC encoder. There is no stereo or metadata. | [agent-render-jobs](../tests/agent-render-jobs.test.js) | #60 |
| Rendering > Render Output > Audio Rendering | partial | A video job mixes one local WAV, MP3, OGG or FLAC file with an offset and reports measured sync. No several tracks, mixing, gain or generated sound. | [film-timeline](../tests/film-timeline.test.js), `npm run smoke:film-timeline` | #60 |