3D engine that AI agents drive
Weight mesh particle emitters by a vertex group, so sparks come off a painted rim
Nguyen Xuan An3c3865da6122
diff --git a/changes/695.group.size.md b/changes/695.group.size.mdnew file mode 100644index 00000000..d270f558--- /dev/null+++ b/changes/695.group.size.md@@ -0,0 +1,5 @@+- scene:agent-scene: vertex group weighting for mesh particle emitters is a simulation capability the lead approved; 17 bytes gzip in the core bundle (capabilities text)+- scene:agent-scene+lazy: group weighted surface and vertex emission cost 319 bytes gzip in the lazy particles path+- goal:agent-scene: the 17 bytes are the capabilities text that tells an agent about the group field; the code loads lazily+- entry:agent-scene: +17 bytes gzip is the capabilities text for the emitter group field+- entry:agent-scene+lazy: +310 bytes gzip is the weighted sampler, which loads only with particlesdiff --git a/changes/695.md b/changes/695.mdindex 4b333364..02f9be53 100644--- a/changes/695.md+++ b/changes/695.md@@ -1 +1,2 @@- Particle emitters take points from a mesh surface (weighted by area), its vertices or its closed volume, push them along the normal, and draw each particle as one of up to 8 listed nodes with a random or surface-aligned rotation (#695)+- Mesh particle emitters take a vertex group (`emitter.group`) that weights surface and vertex emission, so sparks come off a painted rim (#695)diff --git a/docs/parity.md b/docs/parity.mdindex b50ddf54..81a3a177 100644--- a/docs/parity.md+++ b/docs/parity.md@@ -118,7 +118,7 @@ To move to a new Blender release, run `node scripts/parity-manual-snapshot.mjs`.| Modeling > Modifiers > Physics > Fluid Modifier | partial | `addons/spume` plays back a liquid baked outside the browser. Decision (#63): no browser liquid solver, see docs/physics.md "Decision". | [spume](../tests/spume.test.js) | #63 || Modeling > Modifiers > Physics > Ocean Modifier | partial | `ocean` edit and stack node: seeded Phillips-spectrum sea (wind speed, direction, size, seed, time), choppiness and a `foam` vertex group from the folding of the surface. Same seed and time give identical vertices (CPU, no FFT, a lattice of up to 33 x 33 wave vectors). No spray, no baked cache, no GPU path, no depth or damping, no repeat count and no foam or spray bake. Not compared against Blender output. | [mesh-ocean](../tests/mesh-ocean.test.js) | #599 || Modeling > Modifiers > Physics > Particle Instance Modifier | partial | An emitter system draws its node's mesh once per particle, or one of up to 8 listed nodes picked at random, with a random starting rotation or the +Y axis turned onto the emitting surface normal. No collection, no weighted pick, no scale or rotation from the instanced node and no moving source. | [particles](../tests/particles.test.js) | #63 |-| Modeling > Modifiers > Physics > Particle System Modifier | partial | Recipe `particles`: seeded emitters (point, box, sphere, disc, and a mesh's surface weighted by area, its vertices or its closed volume, with an initial speed along the normal) with gravity, drag, wind, a floor and size over life, and hair strands from a surface. A seek is a closed-form evaluation, so it repeats exactly. Force fields (`fields`), collision with chosen static meshes and the floor with bounce and friction, spin, color and alpha over life (a fade to black; no per-vertex alpha), no children or hair dynamics, and no comparison against Blender was run. See docs/physics.md. | [particles](../tests/particles.test.js) | #63 |+| Modeling > Modifiers > Physics > Particle System Modifier | partial | Recipe `particles`: seeded emitters (point, box, sphere, disc, and a mesh's surface weighted by area, its vertices or its closed volume, optionally weighted by a vertex group, with an initial speed along the normal) with gravity, drag, wind, a floor and size over life, and hair strands from a surface. A seek is a closed-form evaluation, so it repeats exactly. Force fields (`fields`), collision with chosen static meshes and the floor with bounce and friction, spin, color and alpha over life (a fade to black; no per-vertex alpha), no children or hair dynamics, and no comparison against Blender was run. See docs/physics.md. | [particles](../tests/particles.test.js) | #63 || Modeling > Modifiers > Physics > Soft Body Modifier | missing | Not built: a closed mesh needs volume or shape-matching constraints, closed-mesh input checks and a recipe field with schema and capability text, which was not measured to fit the 1.5 KB gzip limit. | | #62 || Modeling > Modifiers > Geometry Nodes Modifier | partial | Bounded JSON field expressions drive `set_position`, `displace`, a `field` selection rule and `instances` (including curve points by count or length, fillet and `realize`); they are one language, `src/expression.js`, with motion drivers. There is no node graph, no loops, no custom node groups, and no volume nodes. | [src/mesh-fields.js](../src/mesh-fields.js), [tests/mesh-fields.test.js](../tests/mesh-fields.test.js), [tests/blender-golden.test.js](../tests/blender-golden.test.js), [pillar-court task](../bench/agent-modeling/tasks.mjs) | #43, #698 || Modeling > Geometry Nodes | partial | Fields over attributes, noise and math (position, normal, index, tags), Set Position, Instance on Points (grid, scatter, surface, curve, with Poisson spacing, density, variants, rotation and scale fields) and Displace. Noise is not Blender's noise function, and there is no Blender comparison for instancing. Issue #43 chose bounded JSON expressions and not a visual editor. | [src/mesh-fields.js](../src/mesh-fields.js), [tests/mesh-fields.test.js](../tests/mesh-fields.test.js), [tests/blender-golden.test.js](../tests/blender-golden.test.js) | #43 |diff --git a/docs/physics.md b/docs/physics.mdindex 6e98197d..e206e1d1 100644--- a/docs/physics.md+++ b/docs/physics.md@@ -560,7 +560,7 @@ A recipe `particles` section holds up to 4 systems (`src/particles.js`, `src/hai- Both kinds replace their node's part at each sampled time, so the renderer sees a topology change. `npm run smoke:agent-particles` seeks sparks and hair through the MCP preview, repeats the PNG bytes after a seek back and checks that a second session renders the same bytes.- `scene_inspect` returns a `particles` report: per emitter the particle count, vertices per particle, `maxAlive` and `endsAt`; per hair system the strands, segments and vertices per strand.- Collision (#614): `colliders` lists up to 8 static root nodes (4096 triangles in total, read only); particles bounce off their triangles and the floor plane with `bounce` (0 to 1; 0 sticks where it lands; 0.3 with colliders, 0 on a floor alone) and `friction` (0 to 1, 0.5): Coulomb friction removes friction times the normal impulse from the speed along the surface, so a slider slows and stops, and spin is damped by each contact. A particle on a collider, a force field or a bounce is stepped at 1/120 s from its birth with the path tested against the triangles, so a fast particle cannot tunnel through a thin mesh. A bounce slower than 0.4 m/s is zeroed (no micro-bounces), so the particle slides, and a slow slider settles. `spin` (deg/s, a number or [min, max]) turns each particle about a seeded axis until it settles. `color` ([r,g,b] at birth, [r,g,b] at death) and `alpha` (a number or [birth, death]) become vertex colours; the renderer has no per-vertex alpha, so alpha multiplies the colour: a particle fades toward black, which reads as a fade on a dark background but does not become see-through. Whole steps are remembered per particle, so playback costs one frame of steps and a seek back replays from birth, with the same bytes. Measured with 2000 particles of 60 s bouncing on a box: a seek to the end took about 0.5 s and playback about 3.5 ms a frame; most particles settle early, a particle under a field that never settles costs its whole age at every seek back.-- A mesh emitter (`emitter: { "shape": "mesh", "mesh": "wall", "from": "surface" }`) takes the points from another root node's mesh in its world position, so debris can come off a wall or petals off a tree. `from` is `surface` (a point on a triangle, weighted by area), `vertices` (one of the mesh vertices) or `volume` (a point inside a closed mesh, found by testing random points in its bounds; an open mesh is rejected). `normalSpeed` adds a speed along the surface normal on top of `direction`, `spread` and `speed` (set `speed` to 0 for a pure push along the normal). The mesh is read once at its transform when the scene is built, so a moving source is not followed; it may have at most 8192 triangles. `emitter.position` offsets the points. The same seed gives the same points, and raising `count` keeps the earlier ones.+- A mesh emitter (`emitter: { "shape": "mesh", "mesh": "wall", "from": "surface" }`) takes the points from another root node's mesh in its world position, so debris can come off a wall or petals off a tree. `from` is `surface` (a point on a triangle, weighted by area), `vertices` (one of the mesh vertices) or `volume` (a point inside a closed mesh, found by testing random points in its bounds; an open mesh is rejected). `group` names a vertex group of the mesh (made with a `vertex_group` mesh edit) and weights the points by it: `surface` weighs each triangle by its area times the mean weight of its corners, `vertices` picks by weight, so sparks come off a painted edge or rim; a missing group is an error listing the groups the mesh has, and `volume` takes no group. `normalSpeed` adds a speed along the surface normal on top of `direction`, `spread` and `speed` (set `speed` to 0 for a pure push along the normal). The mesh is read once at its transform when the scene is built, so a moving source is not followed; it may have at most 8192 triangles. `emitter.position` offsets the points. The same seed gives the same points, and raising `count` keeps the earlier ones.- `instances` is a list of up to 8 root node IDs whose geometry a particle takes, one drawn at random for each particle (leaves picked from three meshes). Leave it out to repeat the system node. `orient` is `none` (the default; only `spin` turns a particle), `random` (a random starting rotation) or `normal` (the instance's +Y axis turned onto the surface normal; needs a mesh emitter with `from` of `surface` or `vertices`). Instances share the one material of the system node, and the vertex limit is counted with the largest instance for every particle.- Not included: collision between particles, collision with a moving node, particles that follow a moving node, hair collision, combing, clumping, children, hair on a skinned surface, UVs on hair (so textured materials do not apply) and fur shading.- Measured on the dev machine: creating a scene with 4000 box particles (96000 vertices) takes about 57 ms, and each seek takes 8 to 15 ms; the test bounds a seek at 150 ms.diff --git a/src/agent-particles.js b/src/agent-particles.jsindex 0e183dd4..e783a91d 100644--- a/src/agent-particles.js+++ b/src/agent-particles.js@@ -11,7 +11,7 @@ const PARTICLES_FIELDS = ['gravity', 'wind', 'fields', 'systems'];const SYSTEM_TYPES = ['emitter', 'hair'];const EMITTER_SYSTEM_FIELDS = ['type', 'node', 'seed', 'count', 'rate', 'lifetime', 'speed', 'direction', 'spread', 'emitter', 'size', 'scale', 'drag', 'floor', 'bounce', 'friction', 'colliders', 'spin', 'color', 'alpha', 'instances', 'orient'];const HAIR_FIELDS = ['type', 'node', 'surface', 'seed', 'count', 'length', 'segments', 'width', 'droop', 'lean', 'sway', 'swayRate'];-const EMITTER_FIELDS = ['shape', 'position', 'halfExtents', 'radius', 'mesh', 'from', 'normalSpeed'];+const EMITTER_FIELDS = ['shape', 'position', 'halfExtents', 'radius', 'mesh', 'from', 'group', 'normalSpeed'];const EMITTER_SHAPES = ['point', 'box', 'sphere', 'disc', 'mesh'];const ORIENT_MODES = ['none', 'random', 'normal'];const SCALE_MODES = ['constant', 'shrink', 'grow'];@@ -45,6 +45,15 @@ function normalizeMeshEmitter(input, emitter, context, path) {}emitter.mesh = input.mesh;emitter.from = from;+ if (input.group !== undefined) {+ if (typeof input.group !== 'string' || !input.group) {+ throw invalidField(`${path}.group`, input.group, 'the name of a vertex group on the emitter mesh, such as "edge"');+ }+ if (from === 'volume') {+ throw invalidField(`${path}.group`, input.group, `left out, because a vertex group weighs ${path}.from "surface" or "vertices", not "volume"`);+ }+ emitter.group = input.group;+ }if (input.normalSpeed !== undefined) {emitter.normalSpeed = finiteNumber(input.normalSpeed, `${path}.normalSpeed`, -1000, 1000);}@@ -65,7 +74,7 @@ function normalizeEmitter(input, context, path) {if (shape === 'mesh') {normalizeMeshEmitter(input, emitter, context, path);} else {- for (const field of ['mesh', 'from', 'normalSpeed']) {+ for (const field of ['mesh', 'from', 'group', 'normalSpeed']) {if (input[field] !== undefined) throw invalidField(`${path}.${field}`, input[field], `left out unless ${path}.shape is "mesh"`);}}@@ -323,15 +332,27 @@ function collisionSurfaceOf(system, nodes, geometries) {return surface;}+// The emitter group's weight per render vertex. A name the mesh lacks is an error that lists the groups it has.+function vertexGroupOf(emitter, geometry) {+ const weights = geometry.vertexGroups?.[emitter.group];+ if (!weights) {+ const known = Object.keys(geometry.vertexGroups ?? {});+ throw invalidField('particles.systems[].emitter.group', emitter.group, `a vertex group of node ${emitter.mesh} (known groups: ${known.join(', ') || 'none'}); make one with a vertex_group mesh edit`);+ }+ return weights;+}+function meshSourceOf(system, nodes, geometries) {const emitter = system.emitter;if (emitter.shape !== 'mesh') return emitter;const sourceNode = nodes.get(emitter.mesh);const geometry = geometries.get(sourceNode.geometry);const world = surfaceInWorld(geometry, nodeMatrix(sourceNode));- const source = createMeshSource(world.positions, world.normals, geometry.indices, emitter.from);+ const weights = emitter.group ? vertexGroupOf(emitter, geometry) : null;+ const source = createMeshSource(world.positions, world.normals, geometry.indices, emitter.from, weights);if (!source) {- throw invalidField(`particles.systems[].emitter.mesh`, emitter.mesh, `a node whose mesh has triangles with some area, because emitter.from is "${emitter.from}"`);+ const groupNote = emitter.group ? ` and some weight in vertex group "${emitter.group}"` : '';+ throw invalidField(`particles.systems[].emitter.mesh`, emitter.mesh, `a node whose mesh has triangles with some area${groupNote}, because emitter.from is "${emitter.from}"`);}if (source.triangleCount > PARTICLE_LIMITS.maxEmitterTriangles) {throw invalidField('particles.systems[].emitter.mesh', `${source.triangleCount} triangles on node ${emitter.mesh}`, `a mesh with at most ${PARTICLE_LIMITS.maxEmitterTriangles} triangles, such as a simpler proxy mesh`);diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 646b005a..d5b571e2 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -304,7 +304,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({}),// Recipe particles: closed-form from seeded launch values, so any time is computed directly and a seek never replays.particles: Object.freeze({- emitter: 'System node geometry is the particle shape; its transform does not move them. Fields (defaults): node, seed (1), count (100), rate (per second; omit: burst at 0), lifetime, speed, size (number or [min, max]; 1, 1, 0.05), direction ([0,1,0]), spread (cone degrees, 30), emitter { shape point|box|sphere|disc|mesh, position, halfExtents, radius; mesh: mesh node, from surface (area weighted)|vertices|volume (closed mesh), normalSpeed m/s along the normal }, instances [node ids, up to 8: each particle draws one], orient none|random|normal (mesh surface or vertices), scale constant|shrink|grow, drag (1/s, 0), floor (world y they land on).',+ emitter: 'System node geometry is the particle shape; its transform does not move them. Fields (defaults): node, seed (1), count (100), rate (per second; omit: burst at 0), lifetime, speed, size (number or [min, max]; 1, 1, 0.05), direction ([0,1,0]), spread (cone degrees, 30), emitter { shape point|box|sphere|disc|mesh, position, halfExtents, radius; mesh: mesh node, group (vertex group weighting surface or vertices), from surface (area weighted)|vertices|volume (closed mesh), normalSpeed m/s along the normal }, instances [node ids, up to 8: each particle draws one], orient none|random|normal (mesh surface or vertices), scale constant|shrink|grow, drag (1/s, 0), floor (world y they land on).',hair: 'type hair grows strands from a read-only root surface node into node (its own geometry is ignored). Fields (defaults): surface, seed, count, length (m, number or [min, max], 0.1), segments (1-8, 4), width (m, 0.004), droop (0.5), lean (0.2), sway (tip travel m, off), swayRate (Hz, 0.5). Tapering tubes, no UVs.',sectionFields: 'systems, gravity ([0,-9.81,0]), wind (m/s; moves emitter particles only with drag > 0, and sets the hair sway direction), fields (also cloth; wind, turbulence, vortex, drag, magnet: docs/physics.md)',collision: 'colliders [node ids], bounce 0-1 (0.3 with colliders), friction 0-1 (0.5), spin deg/s, color [[r,g,b] birth, [r,g,b] death], alpha [birth, death].',diff --git a/src/particle-emitter-mesh.js b/src/particle-emitter-mesh.jsindex 377fa07d..fd69cbdd 100644--- a/src/particle-emitter-mesh.js+++ b/src/particle-emitter-mesh.js@@ -1,4 +1,5 @@// A mesh as a particle emitter: points on its surface (weighted by triangle area), at its vertices, or inside its volume.+// A vertex group (one weight per vertex) narrows the surface and vertex modes to where the group is painted.// Every sample draws from the particle's own generator, so the same seed gives the same points.export const EMITTER_MESH_MODES = Object.freeze(['surface', 'vertices', 'volume']);@@ -28,7 +29,7 @@ function dotProduct(first, second) {return first[0] * second[0] + first[1] * second[1] + first[2] * second[2];}-function trianglesOf(positions, indices) {+function trianglesOf(positions, indices, weights) {const triangles = [];for (let offset = 0; offset + 2 < indices.length; offset += 3) {const a = corner(positions, indices[offset]);@@ -36,7 +37,8 @@ function trianglesOf(positions, indices) {const c = corner(positions, indices[offset + 2]);const faceVector = crossProduct(subtract(b, a), subtract(c, a));const doubleArea = Math.hypot(faceVector[0], faceVector[1], faceVector[2]);- triangles.push({ a, b, c, doubleArea, normal: doubleArea > 0 ? faceVector.map(component => component / doubleArea) : [0, 1, 0] });+ const groupWeight = weights ? (weights[indices[offset]] + weights[indices[offset + 1]] + weights[indices[offset + 2]]) / 3 : 1;+ triangles.push({ a, b, c, doubleArea, emitWeight: doubleArea * groupWeight, normal: doubleArea > 0 ? faceVector.map(component => component / doubleArea) : [0, 1, 0] });}return triangles;}@@ -45,7 +47,7 @@ function surfaceSampler(triangles) {const cumulative = [];let total = 0;for (const triangle of triangles) {- total += triangle.doubleArea;+ total += triangle.emitWeight;cumulative.push(total);}if (!(total > 0)) return null;@@ -112,23 +114,38 @@ function volumeSampler(triangles, positions) {};}-function vertexSampler(positions, normals) {+function vertexSampler(positions, normals, weights) {const vertexCount = positions.length / 3;+ const cumulative = [];+ let total = 0;+ for (let vertex = 0; vertex < vertexCount; vertex++) {+ total += weights ? weights[vertex] : 1;+ cumulative.push(total);+ }+ if (!(total > 0)) return null;return random => {- const vertex = Math.min(Math.floor(random() * vertexCount), vertexCount - 1);- return { point: corner(positions, vertex), normal: corner(normals, vertex) };+ const target = random() * total;+ let low = 0;+ let high = vertexCount - 1;+ while (low < high) {+ const middle = (low + high) >> 1;+ if (cumulative[middle] <= target) low = middle + 1;+ else high = middle;+ }+ return { point: corner(positions, low), normal: corner(normals, low) };};}/*** Build a sampler over a mesh already in world space. `sample(random)` returns `{ point, normal }`; the normal is null- * for a volume. Returns null when the mesh cannot supply the mode (no area, or no triangles).+ * for a volume. `weights` is an optional vertex group (one weight per vertex) for the surface and vertices modes. Returns+ * null when the mesh cannot supply the mode (no area, no triangles, or a group that weighs nothing).*/-export function createMeshSource(positions, normals, indices, mode) {- const triangles = trianglesOf(positions, indices);+export function createMeshSource(positions, normals, indices, mode, weights = null) {+ const triangles = trianglesOf(positions, indices, weights);if (!triangles.length) return null;let sampler = null;- if (mode === 'vertices') sampler = vertexSampler(positions, normals);+ if (mode === 'vertices') sampler = vertexSampler(positions, normals, weights);else if (mode === 'volume') sampler = volumeSampler(triangles, positions);else sampler = surfaceSampler(triangles);if (!sampler) return null;diff --git a/tests/particle-emitter-mesh.test.js b/tests/particle-emitter-mesh.test.jsindex efdc597f..6d3063a9 100644--- a/tests/particle-emitter-mesh.test.js+++ b/tests/particle-emitter-mesh.test.js@@ -159,3 +159,50 @@ test('bad emitter input names the field and what to pass', () => {failure({ instances: Array(9).fill('leaf') }, /instances/);failure({ emitter: { shape: 'mesh', mesh: 'leaf', from: 'volume' } }, /closed mesh/);});++// A wall whose top row of vertices is painted into the vertex group "rim".+function rimWallRecipe(system) {+ const base = recipe(system);+ base.geometries.push({+ id: 'rimmed', type: 'mesh', base: { type: 'box', bevel: 0 },+ edits: [{ op: 'vertex_group', name: 'rim', select: { tag: 'top' }, weight: 1 }],+ });+ base.nodes.push({ id: 'rimwall', geometry: 'rimmed', material: 'paint', translation: WALL_CENTER, scale: [WALL_SCALE, WALL_SCALE, WALL_SCALE] });+ return base;+}++function rimCentres(system) {+ const scene = createAgentScene(rimWallRecipe(system));+ scene.sampleMotion(0);+ return particleCentres(sparksGeometry(scene), 24);+}++test('a vertex group keeps sparks on the painted rim, from vertices and from the surface', () => {+ const topHeight = WALL_CENTER[1] + WALL_SCALE * 0.5;+ const fromVertices = rimCentres({ emitter: { shape: 'mesh', mesh: 'rimwall', from: 'vertices', group: 'rim' } });+ assert.equal(fromVertices.length, 80);+ for (const centre of fromVertices) assert.ok(Math.abs(centre[1] - topHeight) < TOLERANCE, `y ${centre[1]}`);+ // Surface triangles weigh area times the mean group weight: the unpainted bottom face gets none and the top face the most.+ const bottomHeight = WALL_CENTER[1] - WALL_SCALE * 0.5;+ const onTop = centres => centres.filter(centre => Math.abs(centre[1] - topHeight) < TOLERANCE).length;+ const fromSurface = rimCentres({ emitter: { shape: 'mesh', mesh: 'rimwall', group: 'rim' }, count: 400 });+ const ungrouped = rimCentres({ emitter: { shape: 'mesh', mesh: 'rimwall' }, count: 400 });+ assert.ok(fromSurface.every(centre => centre[1] > bottomHeight + TOLERANCE), 'no spark on the unpainted bottom face');+ assert.ok(onTop(fromSurface) > onTop(ungrouped) * 1.8, `${onTop(fromSurface)} on top against ${onTop(ungrouped)} without a group`);+});++test('sparks from a group and leaves picked from 3 meshes work in one scene, with the same bytes each run', () => {+ const build = () => {+ const scene = createAgentScene(rimWallRecipe({ emitter: { shape: 'mesh', mesh: 'rimwall', group: 'rim' }, instances: ['sparks', 'leaf', 'thorn'], count: 40, size: 0.1 }));+ scene.sampleMotion(0.5);+ return Array.from(sparksGeometry(scene).positions);+ };+ assert.deepEqual(build(), build());+});++test('a vertex group that is missing, nameless or aimed at a volume names the field and what to pass', () => {+ const failure = (emitter, pattern) => assert.throws(() => createAgentScene(rimWallRecipe({ emitter: { shape: 'mesh', mesh: 'rimwall', ...emitter } })), pattern);+ failure({ group: 'hem' }, /emitter\.group[\s\S]*known groups: rim/);+ failure({ group: '' }, /emitter\.group[\s\S]*name of a vertex group/);+ failure({ group: 'rim', from: 'volume' }, /emitter\.group[\s\S]*"surface" or "vertices"/);+});