Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add a fracture-node recipe operation and fragment geometry type (#979)

Nguyen Xuan Anab328d644d21
diff --git a/changes/979-recipe.md b/changes/979-recipe.md
new file mode 100644
index 00000000..df438451
--- /dev/null
+++ b/changes/979-recipe.md
@@ -0,0 +1 @@
+- `scene_apply` takes a `fracture-node` operation that breaks a convex node into 2 to 64 glued Voronoi pieces with physics bodies and breakable joints (#979)
diff --git a/changes/979-recipe.size.md b/changes/979-recipe.size.md
new file mode 100644
index 00000000..9f089b94
--- /dev/null
+++ b/changes/979-recipe.size.md
@@ -0,0 +1,4 @@
+- entry:agent-scene: the fragment geometry type and the fracture-node dispatch, a few hundred bytes gzip; the fracture code itself loads on demand
+- scene:agent-scene+lazy: the new on-demand fracture module (recipe operation, piece cache) and the fracture code it pulls in
+- goal:agent-scene: an agent can only fracture a part without writing code through a recipe operation, which needs these paths
+- tool:scene_capabilities: the physics topic text for fracture-node and the fragment geometry type
diff --git a/docs/physics.md b/docs/physics.md
index a795885d..7cad003e 100644
--- a/docs/physics.md
+++ b/docs/physics.md
@@ -380,7 +380,7 @@ Recipe joints also accept `spring` (`restLength`, `stiffness`, `damping`), `moto
Defaults are `box` for dynamic bodies and sensors, `trimesh` for fixed ones.
`layer` (0 to 15) and `collidesWith` replace raw bit masks.
A node cannot have both a physics body and a motion `translation` or `rotation` track.
-Limits: 64 bodies, 64 joints, 10 seconds, 60 steps a second, so at most 601 frames.
+Limits: 128 bodies, 512 joints, 10 seconds, 60 steps a second, so at most 601 frames.
The bake runs once, when the scene is created or the section changes, and is reused while the section and the geometry stay the same.
After that the scene treats physics like motion: `sampleMotion(time)` and the MCP `motionTime` read the recording, so a seek back gives the same matrices. A time past `duration` holds the last pose, and `null` restores the authored pose.
@@ -410,7 +410,33 @@ const parts = fragmentPhysics(fracture, { translation: [0, 2, 0], strength: 20,
`fragmentPhysics` turns that into bodies, convex hull colliders and one fixed joint per neighbouring pair, each with `breakImpulse: strength`. A fixed joint takes `breakImpulse` (N s, above 0): in the bake the joint is removed on the first step in which either of its bodies takes a contact impulse (contact force times the timestep) at or above it. A body resting under its own weight takes about `mass * 9.81 / 60`, so a strength above that holds a structure up and a ball or a falling slab below it breaks the glue. All the joints of a hit fragment that are weaker than the hit break together; the rest of the structure stays glued. `recording.jointBreaks` lists `{ frame, joint, impulse }`. Recipes take `breakImpulse` on a fixed `physics.joints` entry, and `scene_inspect` reports `jointBreaks`.
-Not yet: reaching `fractureMesh` from a recipe or the MCP tool without writing the fragments out as nodes, clusters that break as one, and breaking in the live runtime (glue joints there never break).
+### Fracture from a recipe or the MCP tool
+
+`scene_apply` (and `apply` on a scene) takes a `fracture-node` operation, so an agent breaks a part without code:
+
+```json
+[
+ { "type": "set-physics", "physics": { "duration": 2, "bodies": [
+ { "node": "floor", "type": "fixed", "shape": "box" },
+ { "node": "ball", "shape": "ball", "density": 400, "velocity": [0, 0.5, -14] } ] } },
+ { "type": "fracture-node", "node": "wall", "seed": 7, "cells": 24, "strength": 5, "impact": [0, 0, 0.2], "impactRadius": 0.5 }
+]
+```
+
+| Field | Meaning |
+| --- | --- |
+| `node` | A root mesh node with a convex geometry (a box, cylinder, sphere or convex mesh of at most 2048 triangles), no children and no motion track. |
+| `cells` | 2 to 64 pieces. |
+| `strength` | Glue strength in N s, above 0: a piece hit harder than this in one 1/60 s step loses its glue (see `breakImpulse`). |
+| `seed`, `impact`, `impactRadius` | As for `fractureMesh`; `impact` is in the node's geometry space, before the node scale. |
+| `density`, `friction` | Optional, passed to every piece body (density default 1). |
+
+The operation replaces the node by `cells` nodes named `<node>-frag-<i>` with the same transform and material, adds one `fragment` geometry per piece, one dynamic `convex` body per piece to `physics`, and one fixed joint `<node>-glue-<a>-<b>` per neighbouring pair with `breakImpulse: strength`. Without a physics section it creates one of 3 seconds. Set the ball, floor and duration first in a `set-physics` in the same batch (it replaces the section, so a later `set-physics` drops the pieces). 128 bodies and 512 joints are the limits; a part that needs more glue joints is rejected with a message to use fewer cells.
+
+A `fragment` geometry is `{ id, type: "fragment", source, index, cells, seed, impact?, impactRadius? }`: piece `index` of the fracture of the geometry `source`, in its local space. The same recipe gives the same bytes, and the cache key includes the source geometry, so editing the source regenerates every piece. Fragments are not nested: `source` must not be a fragment.
+`scene_inspect` lists the broken glue as `physics.jointBreaks` with the time of each break. The inside faces are material slot 1 of the geometry (`fractureMesh` returns the group ranges); recipe nodes carry one material, so pieces show it on both sides.
+
+Not yet: clusters that break as one, and breaking in the live runtime (glue joints there never break).
## Recipe ragdoll
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 09fc0923..9bf1bfef 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -492,6 +492,7 @@ const geometry = z.discriminatedUnion('type', [
z.strictObject({ id: identifier, type: z.literal('icoSphere'), subdivisions: detail(0, 7) }),
z.strictObject({ id: identifier, type: z.literal('circle'), segments, innerRadius: finite.optional() }).describe('Unit disc facing +Z; innerRadius makes a ring.'),
z.strictObject({ id: identifier, type: z.literal('line'), from: vector3, to: vector3, radius: finite.optional(), radialSegments: detail(3, 128) }),
+ z.strictObject({ id: identifier, type: z.literal('fragment'), source: identifier, index: z.number().int().min(0).max(63), cells: z.number().int().min(2).max(64), seed: detail(0, 4294967295), impact: vector3.optional(), impactRadius: positive.optional() }).describe('Piece of a fractured geometry; made by fracture-node.'),
z.strictObject({ id: identifier, type: z.literal('mesh'), base: z.discriminatedUnion('type', primitiveGeometries(false)).describe('Starting shape, converted to welded quads with axis face tags.'), edits: recipeMeshEdits.optional().describe('Replayable edit log, applied in order. Each item has the shape of one mesh_edit edit; read that tool for every op and field.'), stack: recipeMeshStack.optional().describe('Non-destructive modifier stack evaluated after the edits. Each item has the shape of one mesh_stack node; read that tool for the ops.'), smoothAngle: bounded(0, 180).optional().describe('Edges bending more than this many degrees render hard. Defaults to 30.'), shapeKeys: recipeMeshEdits.optional().describe('Named morph targets, at most 16: { name, offsets | edits, value }. See scene_capabilities meshShapeKeys.') }),
]);
// No description: this field repeats in every motion track schema. A wrong name fails with every valid form, and docs/agent-motion.md lists them.
@@ -734,6 +735,10 @@ const otherOperations = [
z.strictObject({ type: z.literal('set-camera'), ...cameraFields }),
z.strictObject({ type: z.literal('set-motion'), motion: recipeMotionReference.nullable() }),
z.strictObject({ type: z.literal('bake-motion'), nodes: z.array(identifier).min(1).max(32), start: nonnegative.optional(), end: nonnegative.optional(), step: positive.optional(), tolerance: z.record(z.string(), z.number()).optional() }),
+ z.strictObject({
+ type: z.literal('fracture-node'), node: identifier, cells: z.number().int().min(2).max(64), strength: positive,
+ seed: detail(0, 4294967295), impact: vector3.optional(), impactRadius: positive.optional(), density: positive.optional(), friction: nonnegative.optional(),
+ }).describe('Break a convex root node into glued physics pieces. Fields: scene_capabilities physics.'),
z.strictObject({ type: z.literal('set-armatures'), armatures: armaturesReference.nullable() }),
z.strictObject({ type: z.literal('set-physics'), physics: z.record(z.string(), z.unknown()).nullable().describe('Same object as recipe.physics in scene_create.') }),
z.strictObject({ type: z.literal('set-cloth'), cloth: z.record(z.string(), z.unknown()).nullable() }),
diff --git a/src/agent-apply-report.js b/src/agent-apply-report.js
index afd67c14..a55aec2c 100644
--- a/src/agent-apply-report.js
+++ b/src/agent-apply-report.js
@@ -108,6 +108,9 @@ function describeOperation(working, operation, maxText) {
else working[name] = structuredClone(next);
return { changed: operation[name] === null ? `cleared ${name}` : `set ${name}` };
}
+ if (type === 'fracture-node') {
+ return { changed: `fractured ${operation.node} into ${operation.cells} pieces with glue` };
+ }
if (type === 'bake-motion') {
return { changed: `baked ${shortList(operation.nodes ?? [], maxText)} to keys` };
}
diff --git a/src/agent-fracture.js b/src/agent-fracture.js
new file mode 100644
index 00000000..75fad357
--- /dev/null
+++ b/src/agent-fracture.js
@@ -0,0 +1,145 @@
+import { invalidField } from './field-error.js';
+import { knownKeys } from './motion-validation.js';
+import { fractureMesh, MAX_FRACTURE_CELLS, MIN_FRACTURE_CELLS } from './fracture.js';
+import { AGENT_SCENE_CAPABILITIES } from './agent-scene-capabilities.js';
+
+// Recipe side of fracture: the `fragment` geometry type (one Voronoi piece of a source geometry) and the
+// `fracture-node` operation that swaps a node for its pieces, bodies and breakable glue.
+
+const DEFAULT_PHYSICS_DURATION = 3;
+const FRACTURE_CACHE_SIZE = 4;
+const UNSUPPORTED_NODE_FIELDS = ['instances', 'asset', 'vegetation', 'relations'];
+const FRACTURE_NODE_FIELDS = ['type', 'node', 'cells', 'strength', 'seed', 'impact', 'impactRadius', 'density', 'friction'];
+
+const fractureCache = new Map();
+
+/** The fracture of one source and option set, kept for the few most recent so the pieces of a part share one computation. */
+function cachedFracture(key, compute) {
+ if (fractureCache.has(key)) return fractureCache.get(key);
+ const fracture = compute();
+ fractureCache.set(key, fracture);
+ if (fractureCache.size > FRACTURE_CACHE_SIZE) fractureCache.delete(fractureCache.keys().next().value);
+ return fracture;
+}
+
+function fractureOptions(definition) {
+ return { seed: definition.seed ?? 1, cells: definition.cells, impact: definition.impact, impactRadius: definition.impactRadius };
+}
+
+/**
+ * Render geometry of piece `definition.index`, in the source geometry's local space.
+ * `sourceSignature` is the cache identity of the source record, so editing the source changes the pieces.
+ */
+export function fragmentGeometry(definition, sourceSignature, generateSource) {
+ const options = fractureOptions(definition);
+ const key = JSON.stringify([sourceSignature, options.seed, options.cells, options.impact ?? null, options.impactRadius ?? null]);
+ const fracture = cachedFracture(key, () => fractureMesh(generateSource(), options));
+ const fragment = fracture.fragments[definition.index];
+ return {
+ positions: fragment.positions.slice(),
+ normals: fragment.normals.slice(),
+ indices: fragment.indices.slice(),
+ };
+}
+
+function validatedOperation(operation) {
+ knownKeys(operation, FRACTURE_NODE_FIELDS, 'operation');
+ if (typeof operation.node !== 'string') {
+ throw invalidField('node', operation.node, 'the ID of a node to fracture, such as "wall"', TypeError);
+ }
+ if (!Number.isInteger(operation.cells) || operation.cells < MIN_FRACTURE_CELLS || operation.cells > MAX_FRACTURE_CELLS) {
+ throw invalidField('cells', operation.cells, `a whole number of pieces from ${MIN_FRACTURE_CELLS} to ${MAX_FRACTURE_CELLS}, such as 24`);
+ }
+ if (!(Number.isFinite(operation.strength) && operation.strength > 0)) {
+ throw invalidField('strength', operation.strength, 'the glue strength as an impulse above 0 in N s, such as 5; a body hit by more than this in one 1/60 s step breaks its glue');
+ }
+ for (const field of ['density', 'friction']) {
+ if (operation[field] !== undefined && !(Number.isFinite(operation[field]) && operation[field] > 0)) {
+ throw invalidField(field, operation[field], `a number above 0, such as ${field === 'density' ? 1 : 0.6}`);
+ }
+ }
+ return operation;
+}
+
+function fracturableNode(candidate, nodeId) {
+ const node = candidate.nodes.find(entry => entry.id === nodeId);
+ if (!node) {
+ throw invalidField('node', nodeId, `the ID of an existing node, one of ${candidate.nodes.slice(0, 8).map(entry => entry.id).join(', ') || 'none yet'}`);
+ }
+ if (node.geometry === undefined) {
+ throw invalidField('node', nodeId, 'a node with a geometry to break; pick a mesh node such as "wall"');
+ }
+ const unsupported = UNSUPPORTED_NODE_FIELDS.find(field => node[field] !== undefined);
+ if (unsupported) {
+ throw invalidField('node', nodeId, `a plain mesh node; ${nodeId} uses ${unsupported}, so fracture a node without it`);
+ }
+ if (node.parent !== null && node.parent !== undefined) {
+ throw invalidField('node', nodeId, 'a root node, with no parent, since every piece is a physics body; reparent it first with set-node');
+ }
+ if (candidate.nodes.some(entry => entry.parent === nodeId)) {
+ throw invalidField('node', nodeId, 'a node without children; move the children to another parent with set-node first');
+ }
+ if ((candidate.motion?.tracks ?? []).some(track => track.id === nodeId)) {
+ throw invalidField('node', nodeId, 'a node without motion tracks; the pieces are moved by physics, so remove its tracks first');
+ }
+ return node;
+}
+
+function claimPieceIds(candidate, nodeId, cells) {
+ const ids = Array.from({ length: cells }, (_, index) => `${nodeId}-frag-${index}`);
+ const taken = ids.find(id => candidate.nodes.some(entry => entry.id === id) || candidate.geometries.some(entry => entry.id === id));
+ if (taken) {
+ throw invalidField('node', nodeId, `a node whose piece IDs are free; ${taken} already exists, so rename it or remove it first`);
+ }
+ return ids;
+}
+
+function physicsWithRoom(candidate, bodiesNeeded, jointsNeeded) {
+ const physics = candidate.physics ?? { duration: DEFAULT_PHYSICS_DURATION, bodies: [] };
+ const { maxBodies, maxJoints } = AGENT_SCENE_CAPABILITIES.physics.limits;
+ const bodyCount = physics.bodies.length + bodiesNeeded;
+ const jointCount = (physics.joints?.length ?? 0) + jointsNeeded;
+ if (bodyCount > maxBodies) {
+ throw invalidField('cells', bodiesNeeded, `at most ${maxBodies - physics.bodies.length} pieces, since physics holds ${maxBodies} bodies and ${physics.bodies.length} are in use; use fewer cells`);
+ }
+ if (jointCount > maxJoints) {
+ throw invalidField('cells', bodiesNeeded, `fewer pieces: ${jointsNeeded} glue joints would pass the ${maxJoints} joints physics holds (${physics.joints?.length ?? 0} in use); use fewer cells`);
+ }
+ return physics;
+}
+
+/**
+ * The fracture-node operation. Replaces `operation.node` by `cells` piece nodes with the same transform and material,
+ * adds a convex dynamic body per piece and one fixed joint with `breakImpulse: strength` per neighbouring pair. Set a
+ * physics section with the ball and floor first (set-physics replaces the section), or let this create one of 3 seconds.
+ */
+export function fractureNode(candidate, rawOperation, generateSource) {
+ const operation = validatedOperation(rawOperation);
+ const node = fracturableNode(candidate, operation.node);
+ const definition = { seed: operation.seed ?? 1, cells: operation.cells, impact: operation.impact, impactRadius: operation.impactRadius };
+ const fracture = fractureMesh(generateSource(node.geometry), fractureOptions(definition));
+ const ids = claimPieceIds(candidate, node.id, operation.cells);
+ const physics = physicsWithRoom(candidate, operation.cells, fracture.glue.length);
+ const scale = node.scale ?? [1, 1, 1];
+ const { id: removedId, geometry: sourceGeometry, ...shared } = node;
+ const pieces = ids.map(id => ({ ...structuredClone(shared), id, geometry: id }));
+ candidate.geometries.push(...ids.map((id, index) => ({
+ id, type: 'fragment', source: sourceGeometry, index, cells: operation.cells, seed: definition.seed,
+ ...(operation.impact === undefined ? {} : { impact: operation.impact }),
+ ...(operation.impactRadius === undefined ? {} : { impactRadius: operation.impactRadius }),
+ })));
+ const position = candidate.nodes.findIndex(entry => entry.id === removedId);
+ candidate.nodes.splice(position, 1, ...pieces);
+ physics.bodies.push(...ids.map(id => ({
+ node: id, type: 'dynamic', shape: 'convex', density: operation.density ?? 1,
+ ...(operation.friction === undefined ? {} : { friction: operation.friction }),
+ })));
+ physics.joints = [...(physics.joints ?? []), ...fracture.glue.map(({ a, b, anchor }) => {
+ const scaledAnchor = anchor.map((value, axis) => value * scale[axis]);
+ return {
+ name: `${removedId}-glue-${a}-${b}`, type: 'fixed', bodyA: ids[a], bodyB: ids[b],
+ anchorA: scaledAnchor, anchorB: scaledAnchor, breakImpulse: operation.strength,
+ };
+ })];
+ candidate.physics = physics;
+}
diff --git a/src/agent-physics.js b/src/agent-physics.js
index 8292cc85..90f8caf2 100644
--- a/src/agent-physics.js
+++ b/src/agent-physics.js
@@ -4,14 +4,14 @@ import { restWorldMatrix, boneTails, boneNodeId } from './rig.js';
import { createRagdoll, ragdollPatches, ragdollReport } from './ragdoll.js';
import { bakePhysicsScene, loadPhysicsEngine, physicsEngineLoaded, setPhysicsModuleLoader } from './physics.js';
import { normalizeForceFields } from './force-fields.js';
+import { AGENT_SCENE_CAPABILITIES } from './agent-scene-capabilities.js';
export { loadPhysicsEngine, physicsEngineLoaded, setPhysicsModuleLoader };
export { needsPhysics } from './agent-scene-modules.js';
const FRAMES_PER_SECOND = 60;
const MAX_DURATION_SECONDS = 10;
-const MAX_BODIES = 64;
-const MAX_JOINTS = 64;
+const { maxBodies: MAX_BODIES, maxJoints: MAX_JOINTS } = AGENT_SCENE_CAPABILITIES.physics.limits;
const MAX_LAYER = 15;
const MAX_TRIMESH_TRIANGLES = 20000;
const MAX_HULL_POINTS = 2048;
diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.js
index ef6b1239..018631a0 100644
--- a/src/agent-scene-capabilities.js
+++ b/src/agent-scene-capabilities.js
@@ -198,7 +198,7 @@ export const MESH_BOOLEAN_NOTES = Object.freeze({
export const AGENT_SCENE_CAPABILITIES = Object.freeze({
format: '67js.scene', schemaVersion: 1,
- geometryTypes: Object.freeze(['box', 'cylinder', 'sphere', 'cone', 'icoSphere', 'torus', 'lathe', 'extrude', 'tube', 'curve', 'sdf', 'text', 'grid', 'plane', 'circle', 'line', 'terrain', 'mesh']),
+ geometryTypes: Object.freeze(['box', 'cylinder', 'sphere', 'cone', 'icoSphere', 'torus', 'lathe', 'extrude', 'tube', 'curve', 'sdf', 'text', 'grid', 'plane', 'circle', 'line', 'terrain', 'mesh', 'fragment']),
camera: 'eye, target, up, near, far, then fov (vertical degrees) or focalLength (mm, with sensorWidth mm, 36; not both). projection orthographic with orthoScale (view height in m, default 4). shift [x, y] moves the frame by a fraction of its size. fStop (0.7-64) turns on depth of field focused on target; 1.4 or lower is full blur; effects.depthOfField.blur must stay 0. Orthographic/shifted cameras use the rasterizer.',
terrain: 'One mesh, x and z from -size/2 to size/2, hills about y = 0. size 40 m (1-2000), resolution 64 cells (2-256), seed 1, amplitude 1 m (0-200), holes up to 16 of {center:[x,z],radius}, no surface inside; radius a few cells or more.',
placedAssets: 'Node field asset:{id,materials?,clip?,drive?} turns a group node into a catalog GLB (id from asset_catalog). Its transform places it. materials:[{name,color,metallic,roughness,opacity,emission,emissiveColor}] override source materials by name. clip:{index,start=0,speed=1,loop=true} plays that clip from scene time start; set-motion tracks move the node and scene time seeks the clip. drive:{path | legs, cruiseSpeed | speed, wheels, lights} drives a car along a path in the placement frame (docs/vehicle.md). Max 512 placements, 16 assets, 16 animated.',
@@ -227,7 +227,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({
operations: Object.freeze([
'set-node', 'set-material', 'set-camera', 'add-node', 'remove-node',
'add-geometry', 'remove-geometry', 'add-material', 'remove-material',
- 'set-environment', 'set-effects', 'set-shadow', 'set-motion', 'set-armatures', 'set-physics', 'set-cloth', 'set-timeline', 'set-particles', 'set-bake', 'set-post-passes', 'set-game', 'edit-mesh', 'set-mesh-stack', 'bake-motion',
+ 'set-environment', 'set-effects', 'set-shadow', 'set-motion', 'set-armatures', 'set-physics', 'set-cloth', 'set-timeline', 'set-particles', 'set-bake', 'set-post-passes', 'set-game', 'edit-mesh', 'set-mesh-stack', 'bake-motion', 'fracture-node',
]),
materialTags: Object.freeze(['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass', 'water']),
// A flat water sheet; the largest sets the level. A bed d metres down keeps exp(-absorption * d) per channel (RGB per metre).
@@ -308,9 +308,9 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({
shapes: Object.freeze(['box', 'ball', 'capsule', 'convex', 'trimesh']),
jointTypes: Object.freeze(['spherical', 'revolute', 'prismatic', 'fixed']),
sensors: true, collisionLayers: 16,
- breakableJoints: 'fixed joint breakImpulse (N s): breaks when a body takes a contact impulse (force x 1/60 s) over it in one step; scene_inspect lists jointBreaks. fractureMesh in src/fracture.js makes glued fragments (docs/physics.md).',
+ breakableJoints: 'fixed joint breakImpulse (N s): breaks when a body takes a contact impulse (force x 1/60 s) over it in one step; scene_inspect lists jointBreaks. scene_apply fracture-node { node, cells 2-64, strength N s, seed 1, impact [x,y,z] in geometry space, impactRadius, density 1, friction }: replaces a convex root node by cells nodes NAME-frag-i (fragment geometries) with convex bodies and one breakable fixed joint NAME-glue-a-b per neighbour pair; send it after the set-physics that holds the floor, ball and duration (set-physics replaces the section). docs/physics.md.',
ragdoll: 'physics.ragdoll {armature}: limp capsule per bone; needs a floor',
- limits: Object.freeze({ maxBodies: 64, maxJoints: 64, maxDuration: 10, framesPerSecond: 60, maxTrimeshTriangles: 20000, maxHullPoints: 2048 }),
+ limits: Object.freeze({ maxBodies: 128, maxJoints: 512, maxDuration: 10, framesPerSecond: 60, maxTrimeshTriangles: 20000, maxHullPoints: 2048 }),
}),
// Recipe cloth: a position-based solver (no peer dependency) records any root mesh node as a deformable sheet.
cloth: Object.freeze({
diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.js
index a2e9971a..b36b8ab3 100644
--- a/src/agent-scene-modules.js
+++ b/src/agent-scene-modules.js
@@ -11,6 +11,7 @@ const MODULE_LOADERS = {
motionBake: () => import('./agent-motion-bake.js'),
drive: () => import('./agent-drive.js'),
physics: () => import('./agent-physics.js'),
+ fracture: () => import('./agent-fracture.js'),
cloth: () => import('./agent-cloth.js'),
particles: () => import('./agent-particles.js'),
bake: () => import('./agent-bake.js'),
@@ -55,7 +56,8 @@ const MODULE_MARKERS = {
motion: ['"motion":{', '"bake-motion"'],
motionBake: ['"bake-motion"'],
drive: ['"drive":{'],
- physics: ['"physics":{'],
+ physics: ['"physics":{', '"fracture-node"'],
+ fracture: ['"type":"fragment"', '"fracture-node"'],
cloth: ['"cloth":{'],
particles: ['"particles":{'],
bake: ['"bake":{'],
@@ -103,7 +105,8 @@ export function needsMeshBooleans(value) {
/** True when a recipe or an operation list carries a physics section, so the host loads the solver first. */
export function needsPhysics(value) {
- return JSON.stringify(value ?? null).includes('"physics":{');
+ const text = JSON.stringify(value ?? null);
+ return text.includes('"physics":{') || text.includes('"fracture-node"');
}
/** Names of the on-demand modules a recipe, or a list of edit operations, needs. */
diff --git a/src/agent-scene.js b/src/agent-scene.js
index 0eee6301..aa53f19f 100644
--- a/src/agent-scene.js
+++ b/src/agent-scene.js
@@ -464,6 +464,7 @@ const GEOMETRY_FIELDS = {
text: ['text', 'size', 'depth', 'font', 'align', 'curveSegments'],
mesh: ['base', 'edits', 'stack', 'smoothAngle', 'shapeKeys'],
terrain: ['size', 'resolution', 'seed', 'amplitude', 'holes'],
+ fragment: ['source', 'seed', 'cells', 'index', 'impact', 'impactRadius'],
};
// A line is a two-point curve; both ends must be finite and apart.
@@ -494,7 +495,7 @@ function geometryEstimate(value, scope = PENDING_CUTTER_SCOPE) {
return input.length;
}
for (const field of GEOMETRY_FIELDS[value.type]) {
- if (value[field] !== undefined && !['profile', 'contour', 'holes', 'path', 'closed', 'base', 'edits', 'stack', 'shapeKeys', 'points', 'taper', 'text', 'font', 'align', 'from', 'to', 'shape', 'splines', 'kind', 'weights', 'order', 'knots', 'knotMode', 'trim', 'grow', 'root'].includes(field)) {
+ if (value[field] !== undefined && !['profile', 'contour', 'holes', 'path', 'closed', 'base', 'edits', 'stack', 'shapeKeys', 'points', 'taper', 'text', 'font', 'align', 'from', 'to', 'shape', 'splines', 'kind', 'weights', 'order', 'knots', 'knotMode', 'trim', 'grow', 'root', 'source', 'impact'].includes(field)) {
finite(value[field], field);
}
}
@@ -564,6 +565,8 @@ function geometryEstimate(value, scope = PENDING_CUTTER_SCOPE) {
const beveled = (value.bevel ?? 0) > 0 || (value.bevelThickness ?? value.bevel ?? 0) > 0;
return 6 * (count + holes.length * 2 - 2) + 6 * count * (detail('steps', 1, 1, 256) + (beveled ? detail('bevelSegments', 3, 1, 32) * 2 : 0));
}
+ case 'fragment':
+ return fragmentEstimate(value, scope);
case 'mesh': {
const base = value.base;
if (!base || typeof base !== 'object' || Array.isArray(base) || base.type === 'mesh' || Object.hasOwn(base, 'id')) {
@@ -593,6 +596,27 @@ function geometryEstimate(value, scope = PENDING_CUTTER_SCOPE) {
}
}
+// One Voronoi piece of the geometry named by `source`. Its size is only bounded by the source, so it is checked against maxVertices once built.
+function fragmentEstimate(value, scope) {
+ if (typeof value.source !== 'string') {
+ throw invalidField('source', value.source, 'the ID of a convex geometry in geometries, such as "wall"', TypeError);
+ }
+ const cells = integer(value.cells, 2, 64, 'cells');
+ integer(value.index, 0, cells - 1, 'index');
+ integer(value.seed ?? 1, 0, 4294967295, 'seed');
+ if (value.impact !== undefined) vector(value.impact, 3, 'impact');
+ if (value.impactRadius !== undefined && !(value.impactRadius > 0)) {
+ throw invalidField('impactRadius', value.impactRadius, 'a distance above 0 in the source local space, such as 0.5');
+ }
+ if (!scope.definitions) return 16 * cells;
+ const source = scope.definitions.get(value.source);
+ if (!source || source.type === 'fragment') {
+ const reason = source ? 'a geometry that is not itself a fragment' : `the ID of a geometry in geometries, one of ${[...scope.definitions.keys()].slice(0, 8).join(', ') || 'none yet'}`;
+ throw invalidField(`geometries.${value.id}.source`, value.source, reason);
+ }
+ return geometryEstimate(source, { definitions: scope.definitions, chain: [] }) + 16 * cells;
+}
+
function hasInstancedNodes(nodes) {
return !Array.isArray(nodes) || nodes.some(node => node && typeof node === 'object' && Object.hasOwn(node, 'instances'));
}
@@ -660,6 +684,11 @@ function checkedCutterDependencies(meshDefinition, definitions) {
/** Cache identity of a geometry record: its own fields plus the cutter geometries it depends on. */
function geometrySignature(definition, definitions) {
+ if (definition.type === 'fragment') {
+ // The pieces depend on the source record, so editing the source changes the key. Estimating first rejects a missing or fragment source.
+ geometryEstimate(definition, { definitions, chain: [] });
+ return `${JSON.stringify(definition)}|source|${geometrySignature(definitions.get(definition.source), definitions)}`;
+ }
const dependencies = definition.type === 'mesh' ? checkedCutterDependencies(definition, definitions) : '';
return dependencies ? `${JSON.stringify(definition)}|cutters|${dependencies}` : JSON.stringify(definition);
}
@@ -713,6 +742,12 @@ function generateGeometry(value, maxVertices, scope) {
return agentSceneModule('text').text(value.text, { ...value, maxVertices });
case 'terrain':
return agentSceneModule('terrain').generateTerrainGeometry(value, maxVertices);
+ case 'fragment': {
+ if (!scope) throw invalidField('type', 'fragment', 'a geometry inside a recipe, where its source geometry is found by ID');
+ const source = scope.definitions.get(value.source);
+ return agentSceneModule('fracture').fragmentGeometry(value, geometrySignature(source, scope.definitions),
+ () => generateGeometry(source, maxVertices, { definitions: scope.definitions, chain: [] }));
+ }
case 'mesh': {
const cutterScope = meshCutterScope(value, scope);
const dependencies = scope ? checkedCutterDependencies(value, scope.definitions) : '';
@@ -732,6 +767,17 @@ function generateGeometry(value, maxVertices, scope) {
}
}
+/** Render geometry of a candidate recipe's geometry by ID, for an operation that needs the real mesh (fracture-node). */
+function generateOperationGeometry(candidate, geometryId, limits) {
+ const definitions = geometryDefinitions(candidate.geometries);
+ const definition = definitions.get(geometryId);
+ if (!definition) {
+ throw invalidField('node', geometryId, `a node whose geometry exists; add the geometry ${geometryId} first`);
+ }
+ geometryEstimate(definition, { definitions, chain: [] });
+ return generateGeometry(definition, Math.min(limits.maxVertices, 1_000_000), { definitions, chain: [] });
+}
+
function compile(recipe, geometries, localBounds, limits) {
const materials = new Map(recipe.materials.map(material => [material.id, material]));
const graph = createSceneGraph(recipe.nodes.map(node => {
@@ -1442,7 +1488,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {
const geometry = Object.freeze(generateGeometry(plan.definition, Math.min(limits.maxVertices, 1_000_000), { definitions: definitionsById, chain: [] }));
const geometryBytes = Object.values(geometry).reduce((total, array) => total + array.byteLength, 0);
const vertices = geometry.positions.length / 3;
- if (plan.definition.type === 'mesh') {
+ if (plan.definition.type === 'mesh' || plan.definition.type === 'fragment') {
// Edits can grow a mesh past its estimate. Undo history never blocks an edit, so release the oldest revisions before refusing.
while (revisionHistory.length > 0 && residentStats.vertices + pendingVertices - plan.estimatedVertices + vertices > limits.maxVertices) {
revisionHistory.shift();
@@ -1450,6 +1496,9 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {
residentStats = geometryStats(ownedGeometryRecords());
}
if (residentStats.vertices + pendingVertices - plan.estimatedVertices + vertices > limits.maxVertices) {
+ if (plan.definition.type === 'fragment') {
+ throw invalidField(`geometries.${plan.definition.id}`, `${vertices} render vertices`, 'pieces that fit maxVertices across the scene; use fewer cells or a coarser source geometry');
+ }
throw new RangeError(`Mesh ${plan.definition.id} has ${vertices} render vertices after its edits, which exceeds maxVertices across the scene. Reduce detail or edits.`);
}
} else if (vertices > plan.estimatedVertices || geometryBytes > plan.estimatedVertices * (56 + TERRAIN_SKY_VISIBILITY_BYTES)) {
@@ -1909,6 +1958,12 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {
agentSceneModule('motionBake').bakeMotion(candidate, operation, motionBakeSource(state));
continue;
}
+ if (operation.type === 'fracture-node') {
+ const { id: fracturedId } = candidate.nodes.find(node => node.id === operation.node) ?? {};
+ agentSceneModule('fracture').fractureNode(candidate, operation, geometryId => generateOperationGeometry(candidate, geometryId, limits));
+ if (fracturedId !== undefined) removedNodes.add(fracturedId);
+ continue;
+ }
if (operation.type === 'edit-mesh') {
knownKeys(operation, ['type', 'geometry', 'edits', 'replace'], 'operation');
const target = meshGeometryTarget(candidate, operation, type => `Add a mesh geometry with base: { type: '${type}', ... } to edit it.`);
diff --git a/tests/actionable-errors-scene-core.test.js b/tests/actionable-errors-scene-core.test.js
index 00d428c5..fce9457d 100644
--- a/tests/actionable-errors-scene-core.test.js
+++ b/tests/actionable-errors-scene-core.test.js
@@ -36,7 +36,7 @@ const RECIPE_CASES = [
['a camera takes fov or focalLength, never both', recipe => { recipe.camera = { fov: 40, focalLength: 50 }; }, RangeError, /^camera\.focalLength: got 50; expected only one of fov \(degrees\) or focalLength \(millimetres with sensorWidth\), such as fov 45; remove the other\.$/],
['a missing material names the choices', recipe => { recipe.nodes[0].material = 'ghost'; }, RangeError, /^nodes\.body\.material: got "ghost"; expected one of plain\.$/],
['a duplicate ID names the collection', recipe => { recipe.nodes[1].id = 'body'; }, RangeError, /^nodes\[1\]\.id: got "body"; expected an ID no other nodes entry uses; rename one, or remove the other\.$/],
- ['a geometry type outside the list names the list', recipe => { recipe.geometries[0].type = 'blob'; }, TypeError, /^geometries\[0\]\.type: got "blob"; expected one of box, cylinder.*terrain\.$/],
+ ['a geometry type outside the list names the list', recipe => { recipe.geometries[0].type = 'blob'; }, TypeError, /^geometries\[0\]\.type: got "blob"; expected one of box, cylinder.*terrain, fragment.$/],
['a point list gives the range and an example', recipe => { recipe.geometries.push({ id: 'ring', type: 'lathe', profile: [[1, 0]] }); }, RangeError, /^geometries\[2\]\.profile: got "1 points"; expected a list of 2 to 4096 points of 2 numbers, such as \[\[0,0\],\[1,1\]\]\.$/],
['a wrong schema version gives the expected value', recipe => { recipe.schemaVersion = 2; }, RangeError, /^schemaVersion: got 2; expected 1\.$/],
// src/agent-terrain.js
diff --git a/tests/fracture-recipe.test.js b/tests/fracture-recipe.test.js
new file mode 100644
index 00000000..5308c4ef
--- /dev/null
+++ b/tests/fracture-recipe.test.js
@@ -0,0 +1,107 @@
+import './support/load-agent-scene-modules.mjs';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { createAgentScene, loadPhysicsEngine, needsPhysics } from '../src/agent-scene.js';
+import { AGENT_SCENE_CAPABILITIES } from '../src/agent-scene-capabilities.js';
+
+await loadPhysicsEngine();
+
+function wallRecipe() {
+ return {
+ format: '67js.scene', schemaVersion: 1,
+ geometries: [{ id: 'slab', type: 'box', bevel: 0 }, { id: 'ball', type: 'sphere' }],
+ materials: [{ id: 'brick', color: [0.6, 0.3, 0.2] }],
+ nodes: [
+ { id: 'floor', geometry: 'slab', material: 'brick', translation: [0, -0.25, 0], scale: [8, 0.5, 8] },
+ { id: 'wall', geometry: 'slab', material: 'brick', translation: [0, 1, 0], scale: [3, 2, 0.4] },
+ { id: 'ball', geometry: 'ball', material: 'brick', translation: [0, 1, 5], scale: [0.5, 0.5, 0.5] },
+ ],
+ };
+}
+
+function operations({ shoot, strength = 5, cells = 16, extra = {} }) {
+ return [
+ {
+ type: 'set-physics',
+ physics: {
+ duration: 2,
+ bodies: [
+ { node: 'floor', type: 'fixed', shape: 'box' },
+ { node: 'ball', shape: 'ball', density: 400, ...(shoot ? { velocity: [0, 0.5, -14] } : {}) },
+ ],
+ },
+ },
+ { type: 'fracture-node', node: 'wall', seed: 7, cells, strength, ...extra },
+ ];
+}
+
+function applyOperations(scene, list) {
+ return scene.apply(list, { expectedRevision: scene.inspect({}).revision });
+}
+
+function fracturedScene(settings) {
+ const scene = createAgentScene(wallRecipe());
+ applyOperations(scene, operations(settings));
+ return scene;
+}
+
+function geometryDigest(scene) {
+ const hash = createHash('sha256');
+ for (const part of scene.parts) {
+ const { positions, indices } = part.geometry;
+ hash.update(Buffer.from(positions.buffer, positions.byteOffset, positions.byteLength));
+ hash.update(Buffer.from(indices.buffer, indices.byteOffset, indices.byteLength));
+ }
+ return hash.digest('hex');
+}
+
+test('fracture-node swaps a node for glued piece nodes with bodies, deterministically', () => {
+ const first = fracturedScene({ shoot: false });
+ const second = fracturedScene({ shoot: false });
+ const recipe = first.exportRecipe();
+ const pieces = recipe.nodes.filter(node => node.id.startsWith('wall-frag-'));
+ assert.equal(pieces.length, 16);
+ assert.equal(recipe.nodes.some(node => node.id === 'wall'), false);
+ assert.ok(pieces.every(node => node.material === 'brick' && node.scale[0] === 3 && node.translation[1] === 1));
+ assert.equal(recipe.physics.bodies.filter(body => body.shape === 'convex').length, 16);
+ assert.ok(recipe.physics.joints.length >= 15, `${recipe.physics.joints.length} glue joints`);
+ assert.ok(recipe.physics.joints.every(joint => joint.type === 'fixed' && joint.breakImpulse === 5));
+ assert.deepEqual(second.exportRecipe(), recipe);
+ assert.equal(geometryDigest(first), geometryDigest(second));
+ assert.equal(needsPhysics([{ type: 'fracture-node', node: 'wall', cells: 8, strength: 5 }]), true);
+ assert.ok(AGENT_SCENE_CAPABILITIES.operations.includes('fracture-node'));
+});
+
+test('editing the source geometry changes the pieces', () => {
+ const scene = fracturedScene({ shoot: false });
+ const before = geometryDigest(scene);
+ applyOperations(scene, [{ type: 'remove-geometry', id: 'slab' }, { type: 'add-geometry', geometry: { id: 'slab', type: 'box', bevel: 0.2 } }]);
+ assert.notEqual(geometryDigest(scene), before);
+});
+
+test('a resting wall keeps all its glue and a ball fired at it breaks some', () => {
+ const resting = fracturedScene({ shoot: false });
+ resting.sampleMotion(2);
+ assert.equal(resting.inspect({}).physics.jointBreaks, undefined);
+
+ const hit = fracturedScene({ shoot: true });
+ hit.sampleMotion(2);
+ const breaks = hit.inspect({}).physics.jointBreaks;
+ assert.ok(breaks.length > 0, 'the ball breaks glue');
+ assert.ok(breaks.every(entry => entry.joint.startsWith('wall-glue-') && entry.impulse >= 5));
+ const total = hit.exportRecipe().physics.joints.length;
+ assert.ok(breaks.length < total, `${breaks.length} of ${total} joints break, the rest of the wall holds`);
+});
+
+test('an impact point and radius reach the pieces and bad input says what to pass', () => {
+ const scene = fracturedScene({ shoot: false, cells: 24, extra: { impact: [0, 0, 0.2], impactRadius: 0.3 } });
+ const piece = scene.exportRecipe().geometries.find(geometry => geometry.id === 'wall-frag-0');
+ assert.deepEqual(piece.impact, [0, 0, 0.2]);
+ const base = createAgentScene(wallRecipe());
+ assert.throws(() => applyOperations(base, operations({ cells: 1 })), /cells: got 1; expected a whole number of pieces from 2 to 64/);
+ assert.throws(() => applyOperations(base, operations({ cells: 65 })), /cells/);
+ assert.throws(() => applyOperations(base, operations({ strength: 0 })), /strength: got 0; expected the glue strength/);
+ assert.throws(() => applyOperations(base, [{ type: 'fracture-node', node: 'nope', cells: 4, strength: 5 }]), /node: got "nope"; expected the ID of an existing node/);
+ assert.throws(() => applyOperations(base, [{ type: 'fracture-node', node: 'wall', cells: 4, strength: 5, extra: 1 }]), /extra/);
+});