3D engine that AI agents drive
Add a build modifier that reveals faces over time (#704)
Nguyen Xuan Anbaf1178ee5fc
diff --git a/changes/704.md b/changes/704.mdnew file mode 100644index 00000000..8cf2d716--- /dev/null+++ b/changes/704.md@@ -0,0 +1 @@+- Add a `build` mesh modifier that reveals faces over `start` and `length` frames in index, seeded random or axis order, with `reverse` (#704).diff --git a/changes/704.size.md b/changes/704.size.mdnew file mode 100644index 00000000..68893257--- /dev/null+++ b/changes/704.size.md@@ -0,0 +1,3 @@+- scene:agent-scene: build is a new modeling capability (face-by-face reveal for construction shots) and the lead approves its small growth.+- scene:agent-scene+lazy: the same build modifier, loaded with the mesh engine.+- goal:agent-scene: new modeling capability approved by the lead; the bundle grows 170 bytes gzip.diff --git a/docs/mesh.md b/docs/mesh.mdindex d6974e9d..4d577027 100644--- a/docs/mesh.md+++ b/docs/mesh.md@@ -202,7 +202,7 @@ These three (and `bevel`, below) work as edits and as stack nodes:### Modifier stack-A recipe mesh may carry `stack`, a list of `mirror`, `array`, `solidify`, `bevel`, `subdivide`, `uv_unwrap`, `set_position`, `displace`, `decimate`, `remesh`, `weld`, `triangulate`, `edge_split`, `smooth`, `simple_deform`, `cast`, `screw`, `wireframe`, `skin`, `lattice`, `curve`, `hook`, `wave`, `weighted_normal` and `smooth_by_angle` nodes (up to 16) evaluated after the+A recipe mesh may carry `stack`, a list of `mirror`, `array`, `solidify`, `bevel`, `subdivide`, `uv_unwrap`, `set_position`, `displace`, `decimate`, `remesh`, `weld`, `triangulate`, `edge_split`, `smooth`, `simple_deform`, `cast`, `screw`, `wireframe`, `skin`, `lattice`, `curve`, `hook`, `wave`, `build`, `weighted_normal` and `smooth_by_angle` nodes (up to 16) evaluated after theedits without changing them, as Blender's modifier stack. Every prefix (the edit result, then each node) is cachedby its recipe text in a least-recently-used cache bounded at 64 entries and 64 MiB, so changing a late node reusesthe earlier work. Results list one entry per node with `cached: true` when reused. `meshCacheStats()` reports hits@@ -225,7 +225,7 @@ Normals stay those of the base mesh. Test: `tests/mesh-shape-keys.test.js`.### Whole-mesh modifiers-`weld`, `triangulate`, `edge_split`, `smooth`, `simple_deform`, `cast`, `screw`, `wireframe`, `skin`, `lattice`, `curve`, `hook`, `wave`, `bounding_box`, `convex_hull`, `ocean`, `weighted_normal` and `smooth_by_angle` take no selection and no name, and work as edits or stack nodes. Their fields and defaults are plain data in `MESH_MODIFIER_NOTES` (`src/agent-scene-capabilities.js`), which `scene_capabilities` returns as `meshModifiers`; the code is in `src/mesh-modifiers.js` and `src/mesh-restructure.js`.+`weld`, `triangulate`, `edge_split`, `smooth`, `simple_deform`, `cast`, `screw`, `wireframe`, `skin`, `lattice`, `curve`, `hook`, `wave`, `bounding_box`, `convex_hull`, `ocean`, `build`, `weighted_normal` and `smooth_by_angle` take no selection and no name, and work as edits or stack nodes. Their fields and defaults are plain data in `MESH_MODIFIER_NOTES` (`src/agent-scene-capabilities.js`), which `scene_capabilities` returns as `meshModifiers`; the code is in `src/mesh-modifiers.js` and `src/mesh-restructure.js`.| op | fields | does || --- | --- | --- |@@ -246,6 +246,7 @@ Normals stay those of the base mesh. Test: `tests/mesh-shape-keys.test.js`.| `smooth_by_angle` | `angle` (30), `ignoreSharp` (false) | Marks edges bending more than the angle sharp and the others smooth, over the geometry `smoothAngle`; sharp edges made by hand, and the 12 of a box, stay sharp unless `ignoreSharp` is set. || `bounding_box` | none | Replaces the mesh with the axis-aligned box around all its vertices: 8 vertices and 6 quads. Tags and attributes are dropped. || `convex_hull` | none | Replaces the mesh with its convex hull, outward triangles on the extreme vertices only, from at most 8192 vertices. A mesh whose vertices lie on one line or in one plane has no hull and is refused. Tags and attributes are dropped. |+| `build` | `order` (index, random or axis), `seed` (0, random only), `axis` (y, axis only), `frame` (0), `start` (0), `length` (60 frames, above 0), `reverse` (false) | Shows the first faces in that order: none before `start`, all from `start + length`, linear between; `reverse` unbuilds. Unused vertices drop, tags and corner attributes follow their faces, and while no face shows the mesh is one zero-area triangle. Same fields and frame give the same bytes on every seek. Works on imported meshes. || `ocean` | `axis` (y, the up axis), `windSpeed` (10 m/s, above 0 to 60), `direction` (0 degrees from +x toward +z), `choppiness` (1, 0 to 4), `size` (100 m, 1 to 10000), `seed` (0), `time` (0 s), `resolution` (8, 1 to 16) | A seeded sea like Blender's Ocean modifier, without the FFT: a sum of travelling waves on a lattice of wave vectors with a Phillips spectrum for the wind, so the surface repeats every `size` metres and the same seed and time give identical vertices. Waves lift the up axis; choppiness pulls vertices toward the crests along the other two. The squeeze of that move is written as the vertex group `foam` (0 flat, 1 folded). Waves cost (2 x resolution + 1)^2 - 1 per vertex, capped at 50 million evaluations. A box base has few vertices across a flat face (bevel 0 has none inside it), so run `subdivide_edges` with `cuts` first, or the waves have nothing to move. For an open sea: delete every face but the top, `subdivide_edges` with 16 cuts, `subdivide` 4 levels (about 74,000 vertices), scale the sheet to hundreds of metres, then `ocean` with a `size` of 50 (smaller than the wind's longest wave, so the sea has short chop), and a `vertex_color` field that mixes deep blue to white by `{ "attr": "group", "name": "foam" }`. |`triangulate` and `edge_split` check their output size before building it, against the same vertex and face limits as the other edits. Each op has cases in `tests/fixtures/blender/cases.json` and matches Blender 5.2 with no listed difference. `screw` and `wireframe` have cases in the same fixtures (the volume of the open screw strips differs by winding, listed in `differences.json`); `wave` matches Blender on two cases; `skin`, `lattice`, `curve` and `hook` are not compared with Blender, because each needs a second object there. The two normal modifiers are tested by their own properties, because the Blender comparison does not measure normals. Not yet: `shrinkwrap` and `scatter_on_surface` as stack nodes (`instances` already scatters), and cast shapes other than the sphere.diff --git a/docs/parity.md b/docs/parity.mdindex 57af54eb..a199dcb1 100644--- a/docs/parity.md+++ b/docs/parity.md@@ -73,7 +73,7 @@ To move to a new Blender release, run `node scripts/parity-manual-snapshot.mjs`.| Modeling > Modifiers > Generate > Array (Legacy) Modifier | out of scope | The Array Modifier row replaces it. | | || Modeling > Modifiers > Generate > Bevel Modifier | done | Stack node and edit, with segments, profile and overlap clamp, on edges only. | [mesh-bevel](../tests/mesh-bevel.test.js), [Blender results](../tests/fixtures/blender/golden.json) | || Modeling > Modifiers > Generate > Boolean Modifier | partial | Manifold boolean as an edit. It is not a stack node. | [mesh-boolean](../tests/mesh-boolean.test.js), [Blender results](../tests/fixtures/blender/golden.json) | |-| Modeling > Modifiers > Generate > Build Modifier | missing | No equivalent. | | |+| Modeling > Modifiers > Generate > Build Modifier | partial | `build` edit and stack node: faces appear over `start` and `length` frames in index, seeded random or along-axis order, with `reverse`. Works on recipe and imported meshes. No order by field, and no `frame` link to the film clock (pass the frame). Not compared against Blender output. | [mesh-build](../tests/mesh-build-modifier.test.js) | #704 || Modeling > Modifiers > Generate > Curve to Tube Modifier | partial | `tube` and `curve` are geometry types, and `curve` has a taper and custom profile. Neither is a stack node. | [curve-text](../tests/curve-text.test.js), [Blender comparison](../tests/blender-curve-text.test.js) | #45 || Modeling > Modifiers > Generate > Decimate Modifier | partial | Collapse mode as `decimate` with a ratio, keeping open boundaries and tag borders; `generateMeshLods`, `generateGeometryLods` and `generateAssetLods` make levels with a measured error. Unsubdivide and planar modes, vertex-group weighting and symmetry are missing. Compared with Blender on 4 shared fixtures by volume, area and Hausdorff distance. | [blender golden](../tests/blender-golden.test.js), [decimate](../tests/mesh-decimate.test.js) | #40 || Modeling > Modifiers > Generate > Edge Split Modifier | done | `edge_split` edit and stack node: vertices split along edges bending more than `angle`. Edges marked sharp by hand do not exist in recipes. | [mesh-modifiers](../tests/mesh-modifiers.test.js), [Blender results](../tests/fixtures/blender/golden.json) | |diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 4945350b..d8e956be 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -157,6 +157,7 @@ export const MESH_MODIFIER_NOTES = Object.freeze({smooth_by_angle: 'edges bending over angle 30 (0-180) become sharp, others smooth, over smoothAngle; ignoreSharp true also clears hand-made sharp edges.',bounding_box: 'becomes its axis-aligned box.',convex_hull: 'becomes its convex hull, up to 8192 vertices.',+ build: 'shows faces one by one as frame runs from start 0 over length 60 frames (frame 0; give the current frame, e.g. from your film clock): order index (default), random (seed 0) or axis (axis y, lowest centroid first); reverse true unbuilds. Unused vertices drop; while none shows, one zero-area triangle stays.',ocean: 'seeded sea: lifts axis (y) by waves of windSpeed 10 m/s (0-60) toward direction 0 deg, size 100 m (repeats), seed 0, time 0 s, resolution 8 (1-16); choppiness 1 (0-4) pulls points to crests. Writes group foam.',});diff --git a/src/mesh-build-modifier.js b/src/mesh-build-modifier.jsnew file mode 100644index 00000000..38a8b9f2--- /dev/null+++ b/src/mesh-build-modifier.js@@ -0,0 +1,91 @@+import { seededRandom } from './mesh-fields.js';+import { faceCentroids } from './mesh-normals.js';+import { registerModifierNormalizer, registerModifierRunner } from './mesh-modifiers.js';+import { MeshBuilder } from './mesh-stack.js';+import { editBoolean, editField } from './mesh-edit-field.js';++// Build modifier, as Blender's Build: the faces of the mesh appear one by one over a run of frames. `frame` is the frame to+// show, `start` and `length` give the run, and `order` says which face comes next: by index, by a seeded shuffle or along+// an axis (lowest centroid first). `reverse` plays the run backwards, so the mesh unbuilds. The order depends only on the+// mesh and the fields, so every frame, seek and run gives the same vertices. Vertices no visible face uses are dropped.+// A mesh cannot be empty, so while no face shows the mesh is one zero-area triangle at the first vertex, which draws nothing.++export const BUILD_ORDERS = Object.freeze(['index', 'random', 'axis']);+export const MAX_BUILD_FRAME = 1e6;+export const MAX_BUILD_SEED = 0x7fffffff;+const AXIS_INDEX = Object.freeze({ x: 0, y: 1, z: 2 });+const RANDOM_CHANNEL = 71;++function faceBuildOrder(mesh, { order, axis, seed }) {+ const faces = Array.from({ length: mesh.faceCount }, (unused, face) => face);+ if (order === 'index') return faces;+ const keys = new Float64Array(mesh.faceCount);+ if (order === 'random') {+ for (const face of faces) keys[face] = seededRandom(face, RANDOM_CHANNEL, seed);+ } else {+ const centroids = faceCentroids(mesh);+ for (const face of faces) keys[face] = centroids[face * 3 + AXIS_INDEX[axis]];+ }+ return faces.sort((first, second) => keys[first] - keys[second] || first - second);+}++/** How many faces show at `frame`: none before `start`, all from `start + length` on, flipped when `reverse`. */+export function visibleBuildFaces(faceCount, { frame, start, length, reverse }) {+ const progress = Math.min(1, Math.max(0, (frame - start) / length));+ return Math.floor((reverse ? 1 - progress : progress) * faceCount + 1e-9);+}++function hiddenMesh(mesh, builder) {+ const [x, y, z] = mesh.positions;+ builder.addFace([builder.addVertex(x, y, z), builder.addVertex(x, y, z), builder.addVertex(x, y, z)]);+ return builder.build();+}++export function buildMesh(mesh, edit) {+ const visibleCount = visibleBuildFaces(mesh.faceCount, edit);+ if (visibleCount >= mesh.faceCount) return mesh;+ const builder = new MeshBuilder(mesh);+ if (visibleCount === 0) return hiddenMesh(mesh, builder);+ const newVertex = new Map();+ for (const face of faceBuildOrder(mesh, edit).slice(0, visibleCount).sort((first, second) => first - second)) {+ const corners = [];+ for (let corner = mesh.faceOffsets[face]; corner < mesh.faceOffsets[face + 1]; corner++) corners.push(corner);+ const vertices = corners.map(corner => {+ const vertex = mesh.cornerVertices[corner];+ if (!newVertex.has(vertex)) {+ newVertex.set(vertex, builder.addVertex(mesh.positions[vertex * 3], mesh.positions[vertex * 3 + 1], mesh.positions[vertex * 3 + 2]));+ }+ return newVertex.get(vertex);+ });+ builder.addFace(vertices, { sourceFace: face, sourceCorners: corners, sourceEdges: corners.map(corner => mesh.cornerEdges[corner]) });+ }+ return builder.build();+}++function normalizeBuild(edit, normalized, index, { finiteNumber, integerInRange }) {+ normalized.order = edit.order ?? 'index';+ if (!BUILD_ORDERS.includes(normalized.order)) {+ throw editField(index, 'order', edit.order, `one of ${BUILD_ORDERS.join(', ')}, such as "random" with a seed`);+ }+ normalized.frame = edit.frame === undefined ? 0 : finiteNumber(edit.frame, index, 'frame', { minimum: -MAX_BUILD_FRAME, maximum: MAX_BUILD_FRAME });+ normalized.start = edit.start === undefined ? 0 : finiteNumber(edit.start, index, 'start', { minimum: -MAX_BUILD_FRAME, maximum: MAX_BUILD_FRAME });+ normalized.length = edit.length === undefined ? 60 : finiteNumber(edit.length, index, 'length', { minimum: 0, maximum: MAX_BUILD_FRAME, exclusiveMinimum: true });+ normalized.reverse = editBoolean(edit.reverse, index, 'reverse') ?? false;+ if (normalized.order === 'random') {+ normalized.seed = edit.seed === undefined ? 0 : integerInRange(edit.seed, index, 'seed', 0, MAX_BUILD_SEED);+ } else if (edit.seed !== undefined) {+ throw editField(index, 'seed', edit.seed, 'left out, because only order "random" uses a seed');+ }+ if (normalized.order === 'axis') {+ normalized.axis = edit.axis ?? 'y';+ if (!Object.hasOwn(AXIS_INDEX, normalized.axis)) throw editField(index, 'axis', edit.axis, 'one of "x", "y", "z"');+ } else if (edit.axis !== undefined) {+ throw editField(index, 'axis', edit.axis, 'left out, because only order "axis" uses an axis');+ }+}++registerModifierNormalizer('build', normalizeBuild);+registerModifierRunner('build', (mesh, edit) => {+ const built = buildMesh(mesh, edit);+ return { mesh: built, result: { visibleFaces: built === mesh ? mesh.faceCount : visibleBuildFaces(mesh.faceCount, edit), totalFaces: mesh.faceCount } };+});diff --git a/src/mesh-operations.js b/src/mesh-operations.jsindex 4b2fc752..65c6264c 100644--- a/src/mesh-operations.js+++ b/src/mesh-operations.js@@ -23,6 +23,7 @@ export const MODIFIER_OPERATIONS = /* @__PURE__ */ Object.freeze({smooth_by_angle: { fields: ['angle', 'ignoreSharp'], tags: [] },bounding_box: { fields: [], tags: [] },convex_hull: { fields: [], tags: [] },+ build: { fields: ['order', 'axis', 'seed', 'frame', 'start', 'length', 'reverse'], tags: [] },ocean: { fields: ['axis', 'windSpeed', 'direction', 'choppiness', 'size', 'seed', 'time', 'resolution'], tags: [] },});diff --git a/src/mesh-recipe.js b/src/mesh-recipe.jsindex de084009..6761588f 100644--- a/src/mesh-recipe.js+++ b/src/mesh-recipe.js@@ -28,6 +28,7 @@ import './mesh-field-surfaces.js';import './field-rotation.js';import './mesh-hull-modifiers.js';import './mesh-ocean-modifier.js';+import './mesh-build-modifier.js';import { remeshMesh, remeshGridSize, MAX_REMESH_RESOLUTION } from './mesh-remesh.js';import {MESH_EDIT_OPERATIONS, MAX_MESH_EDITS, STACK_OPERATIONS, MAX_STACK_NODES, SCULPT_STROKE_TYPES, MAX_SCULPT_STROKES, SHRINKWRAP_MODES,diff --git a/tests/mesh-build-modifier.test.js b/tests/mesh-build-modifier.test.jsnew file mode 100644index 00000000..99a10f9c--- /dev/null+++ b/tests/mesh-build-modifier.test.js@@ -0,0 +1,113 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { createMeshData, applyMeshEdits, evaluateMeshStack } from '../src/mesh.js';+import { faceNormals } from '../src/mesh-normals.js';+import { visibleBuildFaces } from '../src/mesh-build-modifier.js';+import { MESH_MODIFIER_NOTES } from '../src/agent-scene-capabilities.js';++// A strip of 10 quads along x, one unit wide, each quad tagged "odd" or not and given a corner attribute.+function strip() {+ const quads = 10;+ const positions = new Float32Array((quads + 1) * 2 * 3);+ for (let column = 0; column <= quads; column++) {+ positions.set([column, 0, 0], column * 6);+ positions.set([column, 1, 0], column * 6 + 3);+ }+ const faceOffsets = new Uint32Array(quads + 1);+ const cornerVertices = new Uint32Array(quads * 4);+ for (let quad = 0; quad < quads; quad++) {+ faceOffsets[quad + 1] = (quad + 1) * 4;+ cornerVertices.set([quad * 2, quad * 2 + 2, quad * 2 + 3, quad * 2 + 1], quad * 4);+ }+ const odd = new Uint8Array(quads);+ for (let quad = 1; quad < quads; quad += 2) odd[quad] = 1;+ const cornerValue = Float32Array.from({ length: quads * 4 }, (unused, corner) => corner);+ return createMeshData({+ positions, faceOffsets, cornerVertices,+ attributes: { face: { 'tag:odd': { data: odd, size: 1 } }, corner: { marker: { data: cornerValue, size: 1 } } },+ });+}++function build(frame, overrides = {}) {+ return applyMeshEdits(strip(), [{ op: 'build', start: 10, length: 50, frame, ...overrides }]).mesh;+}++function bytes(mesh) {+ return Buffer.concat([mesh.positions, mesh.faceOffsets, mesh.cornerVertices].map(array => Buffer.from(array.buffer, array.byteOffset, array.byteLength)));+}++test('faces appear in index order between start and start + length', () => {+ assert.equal(build(0).faceCount, 1);+ assert.equal(build(10).faceCount, 1);+ assert.equal(build(15).faceCount, 1);+ assert.equal(build(35).faceCount, 5);+ assert.equal(build(60).faceCount, 10);+ assert.equal(build(999).faceCount, 10);+ const half = build(35);+ const xs = Array.from({ length: half.vertexCount }, (unused, vertex) => half.positions[vertex * 3]);+ assert.equal(Math.max(...xs), 5);+ assert.equal(half.vertexCount, 12);+});++test('a build with no face showing is one zero-area triangle with finite normals', () => {+ const empty = build(0);+ assert.equal(empty.faceCount, 1);+ assert.equal(empty.vertexCount, 3);+ assert.ok(faceNormals(empty).normals.every(Number.isFinite));+});++test('the same frame gives the same bytes on every run and after seeking back', () => {+ const frames = [5, 20, 35, 50, 60, 35, 20];+ for (const order of ['index', 'random', 'axis']) {+ const first = frames.map(frame => bytes(build(frame, { order })));+ const second = frames.map(frame => bytes(build(frame, { order })));+ first.forEach((buffer, position) => assert.ok(buffer.equals(second[position]), `${order} at ${frames[position]}`));+ assert.ok(first[2].equals(first[5]), `${order} frame 35 matches after seeking`);+ assert.ok(first[1].equals(first[6]), `${order} frame 20 matches after seeking`);+ }+});++test('random order is seeded and grows the same set of faces step by step', () => {+ const faceXs = mesh => new Set(Array.from({ length: mesh.faceCount }, (unused, face) => mesh.positions[mesh.cornerVertices[mesh.faceOffsets[face]] * 3]));+ const seeded = build(35, { order: 'random', seed: 3 });+ const other = build(35, { order: 'random', seed: 4 });+ assert.equal(seeded.faceCount, 5);+ assert.notDeepEqual(Array.from(faceXs(seeded)), Array.from(faceXs(other)));+ const earlier = faceXs(build(25, { order: 'random', seed: 3 }));+ for (const x of earlier) assert.ok(faceXs(seeded).has(x), 'a face never disappears while building');+});++test('axis order starts at the lowest centroid and tags and corner attributes follow their faces', () => {+ const mesh = applyMeshEdits(strip(), [{ op: 'build', order: 'axis', axis: 'x', start: 0, length: 10, frame: 3 }]).mesh;+ assert.equal(mesh.faceCount, 3);+ assert.deepEqual(Array.from(mesh.attributes.face['tag:odd'].data), [0, 1, 0]);+ assert.deepEqual(Array.from(mesh.attributes.corner.marker.data), Array.from({ length: 12 }, (unused, corner) => corner));+});++test('reverse unbuilds and mirrors the count', () => {+ assert.equal(build(0, { reverse: true }).faceCount, 10);+ assert.equal(build(35, { reverse: true }).faceCount, 5);+ assert.equal(build(60, { reverse: true }).faceCount, 1);+ assert.equal(visibleBuildFaces(7, { frame: 1, start: 0, length: 3, reverse: false }), 2);+});++test('it works as a stack node', () => {+ const evaluated = evaluateMeshStack(strip(), [{ op: 'build', start: 0, length: 10, frame: 4 }]);+ assert.equal(evaluated.mesh.faceCount, 4);+});++test('a wrong field names the field and what to pass', () => {+ const run = edit => applyMeshEdits(strip(), [{ op: 'build', ...edit }]);+ assert.throws(() => run({ order: 'spiral' }), /edits\[0\]\.order.*index, random, axis/);+ assert.throws(() => run({ length: 0 }), /edits\[0\]\.length/);+ assert.throws(() => run({ frame: Infinity }), /edits\[0\]\.frame/);+ assert.throws(() => run({ seed: 1 }), /edits\[0\]\.seed.*random/);+ assert.throws(() => run({ order: 'random', seed: 1.5 }), /edits\[0\]\.seed/);+ assert.throws(() => run({ axis: 'x' }), /edits\[0\]\.axis.*axis/);+ assert.throws(() => run({ order: 'axis', axis: 'w' }), /edits\[0\]\.axis/);+ assert.throws(() => run({ reverse: 'yes' }), /edits\[0\]\.reverse/);+});++test('the capability note describes the fields', () => {+ assert.match(MESH_MODIFIER_NOTES.build, /order/);+});