3D engine that AI agents drive
Recorded rigid-body physics
This optional addon uses Rapier 3D to bake collisions and joint motion into a timeline.
Scene playback can seek forward or backward without changing the simulation.
The main renderer does not need Rapier for playback.
Available from version 0.4.0.
The library build exports it through crucible/addons/physics when using the npm alias.
Rapier is an optional peer dependency and remains outside the core and library archive.
npm install @dimforge/[email protected]
Use a package-aware development server such as Vite to resolve the solver import.
import { createPhysicsScene, planPhysicsScene } from 'crucible/addons/physics';
const definition = {
gravity: [0, -9.81, 0],
bodies: [
{ name: 'floor', type: 'fixed', translation: [0, -0.5, 0] },
{ name: 'box', type: 'dynamic', translation: [0, 3, 0] },
],
colliders: [
{ name: 'floor', body: 'floor', shape: 'cuboid', halfExtents: [5, 0.5, 5] },
{ name: 'box', body: 'box', shape: 'cuboid', halfExtents: [0.5, 0.5, 0.5], mass: 1 },
],
events: [{ tick: 120, body: 'box', impulse: [2, 4, 0] }],
};
const options = { frameCount: 601, timestep: 1 / 60, maxMemoryBytes: 64 * 1024 * 1024 };
const plan = planPhysicsScene(definition, options);
const physics = await createPhysicsScene(definition, options);
const bindings = physics.bindParts([{ body: 'box', part: boxPart }]);
const updatedParts = [boxPart];
function applyAnimation(time) {
bindings.apply(time);
renderer.updateParts(updatedParts);
}
applyAnimation(5);
applyAnimation(1); // A backward seek produces the same recorded pose.
physics.dispose();
boxPart is an existing Crucible part with a retained Float32Array(16) matrix.
The binding replaces its world translation and rotation while keeping its scale and matrix identity.
The physics body origin must match the visual part origin.
Multiple visual parts can bind to one body when they share that origin.
Visual offsets need separate parts or body definitions.
Definition
Names must be nonempty and unique within each body, collider, or joint list. References use body names. Arrays follow their declared creation order. Unknown properties fail validation instead of changing the simulation silently. Inputs are copied before asynchronous initialization.
Bodies use dynamic, fixed, or kinematic types.
The default type is dynamic.
Each body accepts translation and rotation in world space.
Rotation uses a unit quaternion [x, y, z, w].
Dynamic bodies also accept linearVelocity, angularVelocity, linearDamping, angularDamping, and boolean ccd.
Every dynamic body needs at least one collider.
Colliders attach to a named body through body.
Their translation and rotation are relative to that body.
Multiple colliders form a compound body.
Collider scales come from their dimensions, independently of visual part scales.
| Shape | Required dimensions |
|---|---|
ball |
Positive radius. |
cuboid |
Three positive halfExtents. |
capsule |
Positive radius and halfHeight for its cylindrical segment along local Y. |
cylinder |
Positive radius and halfHeight along local Y. |
cone |
Positive radius and halfHeight along local Y, apex at +halfHeight. |
Each collider accepts either positive mass or positive density.
The default density is 1.
Rapier computes the center of mass and angular inertia from these collider properties.
The default friction is 0.5 and the default restitution is 0.
Restitution must stay between zero and one.
Joints connect bodyA and bodyB at local anchorA and anchorB points.
The default anchors are [0, 0, 0].
Connected bodies do not collide unless contactsEnabled is true.
| Joint type | Additional fields |
|---|---|
spherical |
None. The joint permits relative rotation. |
revolute |
Required unit axis expressed in both bodies' local frames. Optional limits and motor. |
prismatic |
Required unit axis expressed in both bodies' local frames. Optional limits and motor. |
fixed |
Optional unit frameA and frameB quaternions, both default to identity, and optional breakImpulse (see Fracture and breakable glue). |
spring |
restLength (default 0), positive stiffness and nonnegative damping (default 0). |
An articulated ragdoll is a graph of dynamic bodies, colliders, and joints.
This example connects two capsule bodies named upperArm and forearm.
Their initial translations and rotations must place these anchors together.
definition.joints = [{
name: 'elbow', type: 'revolute',
bodyA: 'upperArm', bodyB: 'forearm',
anchorA: [0, -0.5, 0], anchorB: [0, 0.5, 0],
axis: [0, 0, 1], contactsEnabled: false,
}];
Joint limits and motors
Revolute joints permit one relative rotation, and prismatic joints permit one relative translation along their axis.
Their optional limits: [minimum, maximum] restrict that coordinate.
Revolute coordinates use radians. Prismatic coordinates use scene distance units.
Both endpoints must remain strictly increasing after Float32 rounding.
Position motor targets must stay inside the rounded limits. Velocity targets can push against a limit, which the solver enforces.
The prismatic coordinate is the signed distance between the world anchors, projected onto the first body's world axis. Its initial anchors must align along that axis, and its body orientations must match. Controlled revolute joints require initially coincident anchors and matching world axes. Their initial relative twist angle must fit the limits. Initial coordinate membership uses the Float32-rounded coordinate, matching the solver's numeric precision. Uncontrolled revolute joints retain their existing initialization behavior.
At an exact half-turn, +Math.PI and -Math.PI describe the same orientation.
Limit validation uses whichever endpoint the range permits, while nearby excluded angles still fail.
Exact half-turn quaternion antipodes use a canonical sign before baking so their solver trajectories agree.
definition.joints = [{
name: 'slider', type: 'prismatic',
bodyA: 'base', bodyB: 'carriage', axis: [1, 0, 0],
limits: [-1, 1],
motor: { mode: 'position', target: 0.5, stiffness: 40, damping: 8, maxForce: 10 },
}];
Motors use complete serializable snapshots with the fields below.
The addon fixes their Rapier model to ForceBased and requires a positive force cap.
An active motor needs at least one directly attached dynamic body.
| Mode | Required fields | Behavior |
|---|---|---|
position |
target, positive stiffness, nonnegative damping, positive maxForce |
Drives toward the relative coordinate with zero target velocity. |
velocity |
target, positive damping, positive maxForce |
Drives toward the relative speed without a position target. stiffness is unsupported. |
For revolute motors, target uses radians or radians per second, and maxForce caps torque.
For prismatic motors, target uses distance or distance per second, and maxForce caps force.
Motor response depends on mass, inertia, contacts and the force cap. Targets are not prescribed poses.
motor: null disables actuation by zeroing the gains and force cap.
It retains momentum and joint constraints instead of holding the current pose.
Disabling an already disabled motor is a valid no-op.
Spherical and fixed joints reject these single-coordinate limits and motor fields, including motor: null.
Rapier 0.21.0 exposes per-axis spherical motor methods, but this addon does not yet define their multi-axis data contract.
Its spherical binding does not expose the single-coordinate limit methods used here.
Tick events
Events run before their tick's integration step.
Frame zero records the initial pose.
Tick zero events affect frame one.
The final valid tick is frameCount - 2.
Events run in ascending tick order, preserving declaration order within each tick.
An impulse event targets a dynamic body.
The default event type is impulse.
Its impulse and torqueImpulse vectors use world space.
An optional world point applies the linear impulse away from the center of mass.
At least one impulse vector is required.
definition.events = [
{ tick: 0, body: 'forearm', torqueImpulse: [0, 0, 0.2] },
{ tick: 60, body: 'upperArm', impulse: [1, 2, 0], point: [0, 1, 0] },
];
A kinematicPose event targets a position-based kinematic body.
Its optional translation and rotation define the next world pose.
At least one field is required.
Rapier computes velocity from this target, so a moving kinematic collider can push dynamic bodies.
An unchanged target holds its previous position.
definition.events = [
{ tick: 0, type: 'kinematicPose', body: 'platform', translation: [0, 1, 0] },
];
A jointMotor event replaces the complete motor snapshot of a named revolute or prismatic joint.
Its fields are tick, type, joint and motor. Body impulse and pose fields are unsupported.
The replacement persists until another motor event, and both attached bodies wake when the event runs.
Same-tick snapshots preserve declaration order, so the final snapshot controls that tick's integration.
definition.events = [
{ tick: 60, type: 'jointMotor', joint: 'slider', motor: { mode: 'position', target: -0.5, stiffness: 40, damping: 8, maxForce: 10 } },
{ tick: 120, type: 'jointMotor', joint: 'slider', motor: null },
];
Motor events obey the same tick range and before-integration timing as impulses. Initial motors, limits and nested event snapshots are copied before awaiting WASM initialization. Recorded sampling never changes motor state or reruns the solver.
Sampling and bindings
physics.sample(time, out) returns packed poses in physics.bodyNames order.
Each body occupies seven Float32 values [x, y, z, qx, qy, qz, qw].
physics.bodyIndex(name) returns that body's index.
The output must have exactly bodyNames.length * 7 values.
Omitting out allocates a new array.
Supplying a retained output avoids allocations during playback.
const pose = new Float32Array(physics.bodyNames.length * 7);
physics.sample(1.25, pose);
const boxOffset = physics.bodyIndex('box') * 7;
const boxHeight = pose[boxOffset + 1];
Sampling clamps finite times to [0, physics.duration].
Translations use linear interpolation.
Quaternions use normalized interpolation along the shortest arc.
Times at recorded ticks return their stored poses.
Interpolated poses do not run collision detection and can show small penetrations between frames.
A smaller timestep reduces these interpolation artifacts.
Bindings retain their sample buffer and transformation scratch matrices.
Their apply(time) method allocates no arrays during playback.
Bindings validate every target before updating any matrix.
Replacing a target matrix fails before any target changes.
Distinct matrix views must also occupy nonoverlapping byte ranges in their shared buffer.
Affine matrices with independent nonzero scales are supported. Shear and perspective matrices fail validation. Reflections use a negative X scale with the same handedness as the original matrix.
Limits and disposal
frameCount defaults to 601 and includes frame zero.
timestep defaults to 1 / 60 seconds, rounded to Float32.
The maximum timestep is one second.
solverIterations defaults to 8 and accepts integers from 1 through 128.
duration equals (frameCount - 1) * timestep.
Long timelines require larger frame limits and memory budgets.
| Option | Default | Maximum configurable value |
|---|---|---|
maxBodies |
256 |
4096 |
maxColliders |
1024 |
8192 |
maxJoints |
512 |
8192 |
maxEvents |
10000 |
100000 |
maxFrames |
3601 |
1000000 |
maxMemoryBytes |
134217728 |
2147483647 |
planPhysicsScene validates the full definition without loading Rapier or allocating its world.
Its frozen result contains exact timelineBytes and an estimated solverReserveBytes.
The reservation accounts for body, collider, joint, and potential contact counts.
estimatedPeakBytes must fit maxMemoryBytes before WASM initialization and timeline allocation.
The reservation is not a hard measurement or cap on Rapier's WASM heap.
Shared WASM initialization, JavaScript metadata, caller outputs, and visual bindings are outside this estimate.
Numbers must remain finite in Float32. Positive dimensions, mass, density, and timestep must remain positive after rounding. Collider volume and inertia scales must also remain finite and positive.
Effective collider masses and conservative minimum inertia estimates must remain normal Float32 values, at least 2 ** -126.
Their reciprocals and the timestep reciprocal must remain finite and positive.
This restriction prevents Rapier from treating very small masses or inertias as zero.
The minimum inertia estimate uses 0.1 * mass * smallestExtent ** 2 for each collider.
Compound bodies add these lower bounds.
Gravity, initial velocities, and impulse vectors must have finite Float32 squared norms. Preflight also bounds accumulated velocity from gravity and declared impulses. Angular bounds include torque impulses and off-center impulses divided by the minimum inertia estimate. Lever-arm estimates include initial positions, collider offsets, and conservative travel over the whole recording. These estimates ignore damping and contact resistance, so they can reject otherwise usable configurations.
Joint controls also have explicit public bounds after Float32 rounding.
Revolute limits and position targets stay within [-Math.fround(Math.PI), Math.fround(Math.PI)].
Prismatic limits and position targets stay within [-1e6, 1e6].
Motor speed targets stay within [-1e4, 1e4], gains cannot exceed 1e6, and force caps cannot exceed 1e8.
Nonzero targets and damping must not round to zero.
Preflight checks motor force and step-impulse squared norms, gain products with the timestep, and nonzero target-driven impulse estimates. Positive squared estimates must remain normal Float32 values, so extremely weak controls can fail validation. It aggregates peak force caps across connected joint components for the complete recording duration. Every dynamic body in such a component receives conservative linear and angular acceleration bounds from those forces and torques. Anchor lengths and collider offsets bound motor torque and the corresponding linear motion. The resulting acceleration, speed and position estimates must remain within their validated Float32 ranges.
These bounds deliberately ignore motor disable intervals, joint limits, damping and contact resistance. They can reject long recordings or unusual mass and inertia ratios that can otherwise simulate successfully. They preserve the existing mass and inertia checks and include motor-induced motion instead of checking authored targets alone.
Kinematic translation changes divided by the timestep must have finite Float32 squared norms.
Kinematic rotation targets require a finite squared bound of (Math.PI / timestep) ** 2.
Same-tick translation targets use the previous integrated translation for these checks.
These checks cover declared motion, without guaranteeing bounds on every force from contact or constraint solving.
Rapier's internal motion limits can also change finite extreme velocities. The preflight checks prevent known overflow cases. They do not promise preservation of arbitrarily large authored speeds.
Large translations can lose small movements through Float32 rounding.
For example, 16777217 becomes 16777216.
Nonfinite solver outputs fail the bake and release the world.
The bake also validates actual linear and angular velocity squared norms at every recorded frame.
Every completed or failed bake frees the Rapier world and its contained solver resources.
physics.dispose() releases the recorded timeline reference and is safe to call repeatedly.
Sampling, binding creation, body lookup, and existing bindings fail after disposal.
Caller-owned arrays and part matrices remain available.
The shared Rapier module and its reusable WASM memory remain initialized.
JavaScript and WASM allocators can retain freed capacity for reuse.
Design and boundaries
Two API shapes were considered. One exposed a mutable solver world with delta-time callbacks. The selected shape accepts a serializable body graph and explicit tick events, then records a bounded timeline. This shape makes film seeks independent of playback order and keeps solver state out of render callbacks.
Two motor control shapes were considered.
A live scene.joint(name).setMotor(...) API exposes mutable solver state and callbacks during playback.
The selected shape adds complete joint motor snapshots to the existing serializable definitions and tick events.
This preserves pre-async validation, deterministic bake order and arbitrary recorded seeks after the solver world is freed.
The addon supports rigid-body contacts, compound colliders, impulses, kinematics, articulated graphs, and single-coordinate joint limits and motors. It does not implement spherical multi-axis controls, or live solver editing. It does not bind physics directly to skeletal bones or generate a humanoid skeleton. Those features need additional public contracts. Creating a scene bakes synchronously after asynchronous WASM initialization and can block the main thread. A worker integration can move that bake off the render thread.
Mesh colliders, sensors and masks
A collider takes shape: 'convexHull' with points (flat xyz, at most maxHullPoints, default 2048) or shape: 'trimesh' with vertices and indices (at most maxColliderTriangles triangles across the scene, default 20000).
Counts are checked before any typed array is allocated, and indices must point at a vertex.
A trimesh needs a fixed or kinematic body, because it encloses no volume to take a mass from.
Use a convex hull for a dynamic body; its true mass comes from the hull, and the bounding box only sizes the safety checks.
sensor: true makes a collider report overlaps without pushing anything.
groups and mask are 16-bit integers. Two colliders touch only when each one's groups shares a bit with the other's mask.
Both default to 0xffff.
The recorded scene lists what happened:
contactEvents:{ frame, kind: 'contact' | 'sensor', started, colliderA, colliderB }in step order, with indices intocolliderNames.contactEventsTruncatedis true pastmaxContactEvents(default 4096).restFrames: per body, the frame from which it stays under 0.02 m/s and 0.05 rad/s until the end, or-1while it still moves.
bakePhysicsScene is the synchronous twin of createPhysicsScene. Await loadPhysicsEngine() once, then bake without awaiting.
setPhysicsModuleLoader replaces how Rapier is imported, for a host that serves it from a URL, as the MCP preview does.
Recipe physics
A scene recipe takes a physics section, and set-physics edits it (null clears it):
"physics": {
"duration": 3,
"gravity": [0, -9.81, 0],
"bodies": [
{ "node": "tray", "type": "fixed", "shape": "trimesh" },
{ "node": "ball-1", "shape": "ball", "restitution": 0.3, "layer": 1, "collidesWith": [0] }
],
"joints": [{ "type": "revolute", "bodyA": "door", "bodyB": "frame", "axis": [0, 1, 0], "limits": [0, 1.5] }]
}
Each body is a root node with a geometry. Its collider is fitted to that geometry at the node scale: box, ball, capsule, cylinder and cone from the bounds, convex from at most 2048 distinct vertices, trimesh from every triangle, or compound with a shapes list of up to 16 sub-colliders (box, ball, capsule, cylinder, cone with optional translation and rotation).
Recipe joints also accept name (what jointMotor events refer to; fracture-node writes glue-a-b), breakImpulse (fixed joints only), spring (restLength, stiffness, damping), motor ({ mode: "position" | "velocity", target, stiffness?, damping, maxForce }) and contactsEnabled. Recipe physics.events schedules up to 128 impulse, kinematicPose and jointMotor events by time in seconds (or tick), and physics.fields applies up to 8 force fields (wind, turbulence, vortex, drag, magnet) to dynamic bodies at every step.
Defaults are box for dynamic bodies and sensors, trimesh for fixed ones.
The live game runtime (game.physics, Jolt) takes the same shapes except trimesh: box, ball, capsule, cylinder, cone, convex and compound (up to 16 sub-colliders). A recipe with a trimesh body is refused with a message that lists these shapes and names box as the replacement. In a compound, events and ray hits report the first sub-collider.
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: 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.
Rapier is loaded on demand, an optional peer dependency. The MCP runtime serves it from node_modules to the preview page, like Manifold, so the server bundle does not carry it.
scene_inspect returns a physics report: per body the finalPosition, finalSpeed and restsAtTime (null while moving), the contacts between bodies with firstTime, count and touchingAtEnd, and the sensor enter and leave events with times.
An agent can check that a ball came to rest on a mesh from these numbers, without a picture.
Floating on the ocean
A crate or a boat can float on the sea that the ocean mesh edit draws. Give the section a sea and mark the bodies that float:
"physics": {
"duration": 8,
"ocean": { "geometry": "sea", "waterDensity": 1000 },
"bodies": [
{ "node": "crate", "density": 500, "float": { "drag": 2, "angularDrag": 2 } },
{ "node": "boat", "shape": "convex", "density": 300, "float": { "points": [[-1.5, 0, -0.6], [1.5, 0, -0.6], [-1.5, 0, 0.6], [1.5, 0, 0.6]] } }
]
}
ocean.geometry names a mesh geometry whose stack has an ocean node with axis y. The body floats on that node's waves (windSpeed, direction, choppiness, size, seed, resolution), read through the same function that moves the drawn vertices, so what the body rides is what the camera sees. The sea clock at physics time 0 is the node's time; drive an oceanTime track at one second per second to keep the drawn sea in step. level is the world height of the calm sea. Leave it out: it then follows the sea as drawn (the node's translation plus its y scale times the mean height of the sheet, so a sheet cut from the top of a unit box drawn at y 2 floats bodies at 2.5). A level that differs from the drawn sea by more than 0.05 m is used as given, and scene_inspect returns a warnings entry in the physics report that names both heights. waterDensity is in kg/m3.
Each float body carries sample points in body space, 16 at most. Without points it gets four, in a 2 x 2 grid across the collider bounds at mid height. Every point owns an equal share of the body's volume as a column as tall as the body. Where the surface stands above the point, the column is submerged by a fraction and the water pushes up at that point with waterDensity x gravity x volume / points x fraction. A body lighter than water bobs and rolls; a box of density 500 sinks to half its height. Spread the points over the hull, wide for roll and long for pitch, so the body rights itself when a wave tips it. drag and angularDrag (1/s, 0 to 100, default 2) damp the linear and angular velocity in proportion to the mean submerged fraction. Each point also damps its own vertical speed relative to the water, at half the critical damping of the heave spring its column makes with the surface, so a hull slammed by a steep wave settles instead of ringing and tumbling; a body riding a wave pays nothing for it. Only dynamic bodies float, and a float body needs a volume, so trimesh does not work.
The definition form of the same thing is ocean on the definition and float on a body (src/physics-buoyancy.js); the live runtime applies it on every step with the same code, and the bake is identical across runs. The cost is waves x points x frames, capped at 100 million wave evaluations, so a long bake with 16 points and resolution 16 is rejected with a message that names the limits.
Boats and wakes

A floating hull becomes a boat with float.boat: throttle pushes the stern along the bow and the rudder pushes it sideways, so the hull still pitches and rolls on the waves. It turns like a real boat: faster water past the rudder turns it harder, and the keel stops it sliding sideways.
{ "node": "hull", "density": 300, "float": { "drag": 1.5, "angularDrag": 3, "boat": {
"thrust": 4, "rudder": 1, "keelDrag": 4, "forward": "-z",
"controls": [{ "time": 0, "throttle": 1 }, { "time": 2, "throttle": 1, "rudder": 0.8 }],
"wake": { "width": 1.2, "height": 0.06, "lifetime": 3 }
} } }
thrustis the push at full throttle in m/s2 (0 to 100, default 4);rudderis the sideways push at the stern at full helm and 3 m/s (default 1);keelDragis the sideways slip removed per second (default 4). Both pushes act atstern([x, y, z] in body space; default the end of the hull oppositeforward, at mid height) and grow with how much of the hull is in the water, full at a quarter submerged, so a hull thrown into the air does not drive.forwardis the bow in body space:-z(default, the way the player controllers face),+z,+xor-x. A positive rudder turns the bow to the right.controlsare up to 256 keyframes{ time, throttle, rudder }with both values from -1 to 1, linear between them and held after the last. A bake reads them, so a film steers the boat with keyframes and the result is identical across runs. A live system ignores them oncesetBoatControlshas been called.- A live system takes the controls from
physics.setBoatControls(bodyName, { throttle, rudder }). Theboatcontroller of the player kit does that from the input axes every step.
wake is off unless you give it. It draws a bounded trail behind the stern into the sea: the last lifetime seconds (0.5 to 60, default 5) of the stern path as at most 62 points (plus two for the hull, so the sea shows white water where the hull meets it) that fade with age and widen as they spread (width 1.2 m at the stern, strength 1, height 0.06 m of choppy displacement). Where a point reaches the sea it raises the foam group the water shader already draws and adds a small choppy displacement along the track, so the churned water is rough and white and never flattened. A slow hull leaves no wake. A hull that starts with a velocity is taken to have been under way on a straight line before time 0, so its wake is there from the first frame. The sea geometry needs an oceanTime track so it is rebuilt each frame; the wake is a pure function of the bake, so frames render in any order. The same field is on the ocean mesh edit: wake: { points: [[x, z, strength, width]], height } draws a trail you place yourself, in the sea geometry's own space.
The boat code is part of the buoyancy chunk, so a scene without floating bodies never loads it.
Spray from the sea
An ocean edit with spray: true writes the vertex group spray and the vector spray (the velocity of the surface, m/s). A particle system takes its droplets from the crests that are rising and sends them off with that velocity:
{ "format": "crucible.scene", "schemaVersion": 1,
"materials": [{ "id": "water", "color": [0.1, 0.3, 0.5] }, { "id": "foam", "color": [0.9, 0.95, 1] }],
"geometries": [
{ "id": "sea", "type": "mesh", "base": { "type": "box", "bevel": 0 },
"edits": [{ "op": "subdivide", "levels": 4 }, { "op": "ocean", "windSpeed": 12, "choppiness": 2, "size": 2, "resolution": 4, "time": 1.5, "seed": 3, "spray": true }] },
{ "id": "speck", "type": "box", "bevel": 0 }],
"nodes": [
{ "id": "surface", "geometry": "sea", "material": "water" },
{ "id": "droplet", "geometry": "speck", "material": "foam" }],
"particles": { "systems": [{ "node": "droplet", "count": 400, "speed": [0, 1], "lifetime": [0.6, 1.4], "size": 0.05, "scale": "shrink",
"emitter": { "shape": "mesh", "mesh": "surface", "from": "vertices", "group": "spray", "groupThreshold": 0.3, "velocityFrom": "spray", "velocityScale": 2 } }] } }
mesh names the node that carries the sea (surface), not its geometry. The droplets read the mesh after its edits, so the ocean op with spray sits in edits. Floating bodies are different: physics.ocean.geometry needs the ocean op in the geometry stack, so a sea that carries boats has it there.
velocityFrom (the name of a vector on the emitter mesh; from "surface" or "vertices") adds that velocity, times velocityScale (1, -1000 to 1000) and in world space, to every particle. A name the mesh lacks is an error that lists the vectors it has. groupThreshold (0 to 1, default 0, needs group) keeps the emitter off weakly painted water: only points where the group weighs at least that much emit, so spray comes from the crests and not from the whole foamy triangle around them. The foam must fold for there to be spray, so a sea with choppiness 0 sprays nowhere. Which points spray depends on the edit's time, size, resolution, windSpeed and choppiness: a sea can have no spray at one time and plenty at another, and then the scene is refused with "no weight in vertex group spray" on the emitter mesh. Raise windSpeed or choppiness, lower groupThreshold, or change time (the example uses resolution 4, time 1.5 and seed 3). A sea animated by a motion track { "kind": "geometry", "id": "sea", "property": "oceanTime" } is followed: each droplet leaves the crests of the sea at the ocean time of its birth (sampled every 1/24 s of ocean time), and a birth at a moment with no spray takes the nearest moment that has some; only when the sea has none anywhere near is the scene refused, with an error that names ocean.time and the track. There is no bow-spray emitter on a boat yet. The same seed gives the same droplets.
Fracture and breakable glue
crucible/addons/fracture splits a closed convex part (a box, cylinder, sphere or any convex mesh of at most 2048 triangles) into Voronoi fragments and describes the glue that holds them together. A concave part is rejected with a message to split it into convex parts first.
import { fractureMesh, fragmentPhysics } from 'crucible/addons/fracture';
const fracture = fractureMesh(wallGeometry, { seed: 7, cells: 24, impact: [1.2, 0.5, 0], impactRadius: 0.6 });
const parts = fragmentPhysics(fracture, { translation: [0, 2, 0], strength: 20, density: 100 });
// parts.bodies, parts.colliders and parts.joints go into a physics definition next to a ball and a floor.
| Field | Meaning |
|---|---|
seed |
Integer from 0 (default 1). The same seed, cell count and impact give the same fragments byte for byte. |
cells |
2 to 64 fragments. |
impact, impactRadius |
Optional point in the part's local space. Half the cells are placed within impactRadius of it (default 0.3 of the part's diagonal), so smaller pieces sit where the hit lands. |
fractureMesh returns fragments, glue and volume. Each fragment has positions, normals, indices, volume and center in the part's local space, and groups: the outside faces are material slot 0 and the new inside faces slot 1, each as a { slot, start, count } range of indices. Fragment volumes sum to the part volume. glue lists each neighbouring pair { a, b, anchor, area }.
fragmentPhysics refuses a density at or below 0, a negative or NaN friction and a translation or rotation that is not finite, and fractureMesh names a NaN position or a stray index. 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.
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:
[
{ "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
Part of issue #96. A ragdoll binds one physics body to every bone of a rig and writes the simulated result back as the local pose of each bone node, so skinning, export and seeking work as for any other pose.
{ "physics": { "duration": 4, "bodies": [{ "node": "floor", "type": "fixed" }], "ragdoll": { "armature": "rig" } } }
For a recipe armature, ragdoll.armature names it. The optional density, friction, restitution and layer (default 1) apply to every bone. An imported asset takes physics: { duration, floor, gravity, ragdoll } in its own recipe (set-physics edits it); every joint of the asset becomes a bone, floor is a world height (default 0) and the character falls from the pose its clip and overrides give at the start.
- Each bone is one capsule from its head to its tail, joined to its parent bone by a spherical joint. Bones never touch each other, so the capsules at a joint do not push apart. The lightest bone weighs a quarter of the longest, because a joint between a very light and a very heavy body blows up the solver.
- The bake is a table of poses by time, recorded at 60 frames a second for at most 10 seconds and 48 bones. A seek to the same time gives the same bytes, and an unchanged section on an unchanged rig reuses the last bake.
- Joints have no swing limits, and Rapier has none for a spherical joint. Linear blend skinning inverts where neighbouring joints turn about 180 degrees apart, and the engine refuses such a pose, so a posed bone stays within 120 degrees of its rest pose. In a deep fold the drawn bone can therefore differ from its collider, and a joint can sit below the floor by a fraction of a bone length. The report is read from the colliders.
- Rigs need uniform scale above the bones (a scale of 100 on an armature node is fine). A bone with no length, more than 48 bones, a bone with a translation or rotation track in the same recipe, or a missing floor body in a scene recipe is refused or falls forever.
- On an asset, physics wins over motion tracks and
ikon joints. scene_inspectreturnsphysics.ragdoll:bones,lowestY,highestY,fastestFinalSpeedandrestsAtTime(null while still moving). Read those instead of a picture.- A fall exports as a glTF clip:
bake-motionover every bone and the fixed bodies, with a tolerance, replaces the recording with LINEAR keys, andexportGlbwrites them as one animation.tests/motion-bake.test.jsbakes and simplifies a ragdoll fall, re-imports the GLB withGLTFLoaderand plays it with anAnimationMixer; every bone stays within 0.05 m and 0.05 in the rotation matrix of the live simulation, sampled every 0.1 s over the first 2.9 s. - Rapier stays an optional peer. A recipe without
physicsloads none of this code.
Recipe cloth
A recipe cloth section records deformable sheets with a position-based solver (src/cloth.js, src/agent-cloth.js). It needs no peer dependency and loads on demand with the cloth module, so a scene without cloth pays nothing.
{ "geometries": [{ "id": "flag", "type": "grid", "segments": 20 }, { "id": "ball", "type": "sphere" }],
"nodes": [{ "id": "flag", "geometry": "flag", "material": "cloth", "translation": [0, 2.5, 0], "scale": [2, 1.2, 1] },
{ "id": "ball", "geometry": "ball", "material": "stone", "translation": [0.2, 1.4, 0.35], "scale": [0.3, 0.3, 0.3] }],
"cloth": { "duration": 3, "wind": [4, 0, 2],
"sheets": [{ "node": "flag", "pin": ["left"] }],
"colliders": [{ "node": "ball", "shape": "ball" }] } }
- A sheet is a root node with any triangle mesh. The
gridgeometry (segments1 to 64) is a flat unit sheet in XY facing +Z, sized by the node scale. Vertices at one position share a particle, so a seam does not tear. pinholds edges of the local bounds in place:top,bottom,left,rightor a corner such astopLeft.- Sheet fields:
stiffness(0.01 to 1, default 0.9),bend(0 to 1, default 0.1),densityin kg/m2 (default 0.2),dampingin 1/s (default 0.3),friction(default 0.3) andthicknessin metres (default 0.01).gravityand a steadywindin m/s sit on the section. - Colliders are fixed root nodes fitted to their geometry bounds as a
ballor an orientedbox(default). A thin box is a floor. - A sheet or fixed collider cannot have a motion translation or rotation track or a physics body. No cloth-to-cloth collision between two sheets.
- Moving colliders and pins follow any node or bone, including a walking character, and are read at every solver substep, so a seek still equals playing to that time:
{ "attach": "leftHand", "shape": "ball", "radius": 0.08, "offset": [0, 0, 0] }is a ball on a node.{ "attach": "upperArm", "shape": "capsule", "to": "lowerArm", "radius": 0.05 }runs a capsule from one node (plusoffset) to another (plustoOffset). Radius 0.001 to 10 m.{ "armature": "rig", "radiusFraction": 0.2, "exclude": ["head"] }adds one capsule per bone, head to tail, the radius a fraction (0.02 to 0.5, default 0.2) of the bone length as the ragdoll fits it. A bone with no length is skipped.- A sheet's
stiffnessGroup: "sleeve"names a vertex group whose weights scale stretch and bend stiffness per vertex; a constraint is as stiff as the softer of its two ends, and a weight under 0.05 counts as 0.05 so the vertex does not drift off. selfCollision: truemakes the sheet's own particles push each other apart, so cloth folded over itself stays in layers instead of passing through. The contact radius is 0.9 of half the shortest edge, or the sheet'sthicknesswhen the sheet sets one (never above half the shortest edge), so a thin cloth on a coarse grid stacks its layers 2 x thickness apart instead of about 4 cm. This changes existing scenes that set bothselfCollision: trueandthickness: they used to ignore the thickness and now stack layers 2 x thickness apart, so their baked frames differ. The recipe takes onlytrueorfalsethere (an object fails withexpected boolean); a fixed radius in metres isselfCollision: { radius }in the library callcreateCloth(src/cloth.js), not in a recipe. A scene that sets no thickness keeps the old radius (tests/cloth-self-collision-thickness.test.js). a spatial hash keeps it near linear (the candidate pairs are listed once per substep, so the iterations only test distances; about 3 times faster than testing every neighbour cell each iteration, with the same frames), two particles joined by an edge are skipped, and a sheet over 5000 particles fails with the count and the fix. A mesh with two vertices at one point (a zero-length edge) fails with those two vertex numbers; weld them first.bendandstiffnessoutside 0 to 1 fail naming the field. It is per particle, so a layer can still slip between particles on a mesh much coarser than the fold. The fold test (tests/soft-body.test.js) keeps every unjoined pair at least 0.8 of the contact distance apart; without it the same fold interpenetrates.softBody: { "shape": 0.2, "pressure": 1 }turns the sheet node into a jelly:shape(0 to 1) pulls every particle toward the best rigid fit of the rest shape (shape matching, rotation extracted with a warm-started iteration), andpressure(0 to 3) is a volume constraint that holds that multiple of the rest volume. Use 1 for a jelly that keeps its volume and squashes on impact; below 1 the body deflates to that volume before it lands (0.85 is a body 15 percent smaller from the first frame), above 1 it inflates. Pressure needs a closed mesh (every edge in two triangles) and fails naming the open edge otherwise; setpressure: 0to keep only shape matching. A box or sphere geometry is closed. It rests on the colliders like cloth and bakes to the same frames every run.softBody.bounce(0 to 1, default 0) sets how much of its landing speed the jelly keeps when it turns around: the body remembers the speed its centre arrived with, and when the centre stops moving into the collider it addsbouncetimes that speed to every free particle along the contact normal. It never slows a body that already leaves faster, and approach speeds under 0.5 m/s are ignored so a resting jelly does not buzz. Leaving it out bakes the same frames as before. How soft the jelly is needs no new field: lowersoftBody.shapefor a looser body and lower the sheet'sstiffnessfor a body that squashes further (the table below).dampingis air drag on every particle, so a highdampingalso takes height off the bounce (withdamping: 0andbounce: 1the cube returns to 1.85 m of its 1.95 m drop).- A sheet on a mesh geometry can hold chosen vertices with
pinGroup: "hem", the name of a vertex group made by avertex_groupmesh edit; vertices of weight 0.5 or more are pinned, on their own or together withpin. An unknown name fails and lists the groups the mesh has. - A sheet's
pinTo: { "node": "chest", "weight": 1 }makes the pinned edges (pin) ride that node, keeping their rest offset in its space. Weight 1 holds them on the node; 0.01 to under 1 pulls them toward it by that fraction on every pass, so they sag and lag. - Up to 64 moving balls and capsules, counting every bone. The node poses come from the recipe's motion tracks and IK; a physics ragdoll or body is not followed. Points are pushed out of the capsules, not whole triangles, so a coarse sheet can still cut a corner of a thin limb: use a finer grid than the limb is wide. A cape on the reference walker (24 by 24 grid, 5 s, about 2.5 s to bake on the dev machine) stays outside every limb capsule in
tests/cloth-moving.test.js.
- The bake runs when the scene is created: 60 frames a second, 4 substeps and 8 constraint passes a frame, constraints solved in a fixed order with no random numbers.
sample(time)blends the two nearest frames, so the same time always gives the same positions and a seek backwards repeats them. Time zero is the authored sheet and a time pastdurationholds the last frame. bendModel: 'dihedral'replaces the distance bend (bendModeldefault'distance') with a bend that holds the angle between neighbouring triangles (position based dynamics, one Newton step per edge, solved on every second iteration). The distance bend gives one hard crease or a smooth tent; the dihedral bend gives many soft folds on a fine grid.bend0.15 suits a 64 by 64 cloth; a higher value flattens the layer, a lower one raises spikes. It tears with its edge like the distance bend. Default scenes are unchanged byte for byte.bendYield(radians, 0 to pi, only withbendModel: 'dihedral', off by default) andbendSet(0 to 1, default 0.1) make a fold keep its crease. The dihedral bend pulls every fold back toward the flat rest angle, so a cloth that crumples in the air slowly smooths out again on the floor. WithbendYield, a bend further than that angle from its rest angle moves the rest anglebendSetof the excess toward the current angle each substep, so the cloth stops pulling that fold flat. The rest angle only moves to angles the sheet has had, the update is deterministic, and a scene withoutbendYieldbakes the same bytes as before.bendYield0.3 withbendSet0.2 suits a 64 by 64 cloth; a lower yield sets creases sooner, a higher one keeps the cloth springier.frictionalone only slows a slide: it removes that share of the sideways travel of each contact, so a layer still creeps.staticFriction(0 to 1, default 0, off) adds Coulomb static friction: a contact whose sideways travel in a substep is no more thanstaticFrictiontimes the depth it was pushed out by is held completely, so a sheet rests on a slope below its friction angle (staticFriction: 1is 45 degrees: a sheet on a 25 degree slope moves 0 m in 2 s, and 0.33 m without it,tests/cloth-friction.test.js). It acts on the floor and colliders, not between layers of the sheet.pinTo.releaseAt(seconds, default never) lets the pinned edges go at that time, and they fall with the rest, so a cloth carried to the floor by a pole is left lying without a corner held up in the air.- Limits: 8 sheets, 16 fixed colliders, 64 moving ones, 10 seconds, 5000 particles a sheet, 3 million recorded particle positions and 500 million solver operations a bake (about 20 seconds; the old 150 million was measured at 18 ns an operation, the 64 by 64 flag measures about 50 ns). Larger input is rejected with the limit in the message. A 32 by 32 grid for 4 seconds bakes in about 1.4 s.
- A seek replaces the sheet's part, so the renderer sees a topology change (
topologyRevision); the MCP preview usesreplacePartsandscene_lookwithmotionTimerepeats the same PNG bytes (npm run smoke:agent-cloth). scene_inspectreturns aclothreport: particles, triangles, pinned count and the final bounds of each sheet.
Soft body films (scripts/soft-body-film.mjs, tests/soft-body-film.test.js): a jelly cube landing and a flag lowered into folds on itself, each one recipe that the test bakes twice and the preview script renders.
- Jelly cube: a rounded box 0.5 m across (384 particles) dropped from 1.95 m,
softBody { shape: 0.15, pressure: 1 }. It first rests on the floor at frame 48 (0.8 s) and is dented 0.0503 m (10 percent of its height) at frame 49, one step later, while its width grows from 0.5 m to 0.547 m; the frame before contact has no dent. - Fine flag (
foldingFlagRecipe({ fine: true }),node scripts/render-soft-body-film.mjs <directory> --fine): the same whip of the pole on a 64 by 64 grid (4096 particles) for 4 s withbendModel: 'dihedral',bend: 0.15,bendYield: 0.3,bendSet: 0.2,damping: 3,friction: 0.6andstaticFriction: 1. The pole lets go as it lands (pinTo.releaseAt: 0.8), so no corner stays held up like a tent and nothing drags the cloth flat; the cloth is left as a heap of 1.6 m2 of sheet in a footprint of about 1.2 by 0.4 m, and it keeps that shape. WithoutbendYieldthe folds were pulled flat again (normal spread 0.65 at step 90, 0.44 at rest). Measured intests/soft-body-film.test.jsand the preview JSON: first touch at step 41, normal spread 0.433 mid fall, 0.634 at settling (step 82) and 0.638 at rest (step 239), highest point at rest 0.102 m, median 0.012 m, 90th percentile 0.035 m, and a line across the middle of the grid crosses 20 folds (row) and 29 (column) at settling and 22 and 29 at rest (height turns of more than 0.5 mm). Closest pair of particles not joined by an edge: 3.5 mm at the final step with self collision (0.3 mm without it), at least 1.5 mm in the sampled frames, the lowest being the first frame at the floor (the contact distance is the 2 mm thickness). Bake 11 to 16 s for 240 steps on the loaded dev machine. The look awaits the owner's review. - Flag: a 38 by 38 grid (1444 particles, the most that fits the cloth work limit for a 3 s film), 1 m tall and 1.6 m wide, held by its two top corners (
pin: ['topLeft', 'topRight'],pinToa pole) so the free edge sags and billows instead of falling as a flat card. The pole whips 0.5 m from side to side and 0.4 m front to back while it drops 2 m in 0.8 s, so the sheet ripples in the air, then zig-zags 0.3 m from side to side while it moves 2 m across the floor, which pulls the cloth into a thin crumpled layer. The sheet setsbend: 0.0002,stiffness: 0.6,damping: 1.5,friction: 0.4andthickness: 0.002, so its self collision layers stack 4 mm apart (earlier rounds: 3.7 cm from the mesh-based radius and a 0.547 m block, then a flat card with a smooth sheet at rest, then one smooth ridge). Measured in the test: first touch at step 39; normal spread (0 flat, toward 1 scattered) is 0 at the start, 0.480 mid fall (step 27, the test fails below 0.25) and 0.674 at rest (fails below 0.5), the sheet bends 0.81 m out of its plane mid fall, and at the final step (179) the highest vertex is 0.0855 m above the floor (a small fold; the test fails above 0.1 m), half of the cloth lies under 0.0042 m and nine tenths of it under 0.0308 m (the test fails above 0.05 m). WithselfCollision: truethe closest pair of particles not joined by an edge is never under 1.8 mm apart in any sampled frame after touch (0.0021 m); the same film without it comes down to 0.2 mm. Those numbers come from the same bake the preview renders, and the film JSON (soft-body-film.json) records the highest, median and 90th percentile height at rest. The bake takes 7 to 17 s on the loaded dev machine (about 30 to 40 ms a step with self collision); the self collision limit is now 5000 particles and a 4 s film at 38 by 38 fits the work limit. The default bake takes about 3.5 s (19 ms a step with self collision) on a quiet machine: the self collision rewrite made it 3 times faster. The look is a red and cream striped cloth (agraphpattern, so every fold bends the stripes) on a mid grey floor under a low grazing key light (environment.lightDirection, fill and ambient lowered), framed from 5.4 m so the cloth fills about a fifth of the picture width. - Both films bake to the same bytes in every frame across two runs; the test compares every frame's vertex buffer.
- Frame time, in milliseconds per solver step (the bake is one call, so this is its total over the steps, on a machine shared with other sessions, so read it as a range): jelly 6 to 9 ms a step over 120 steps, flag 30 to 40 ms a step over 180 steps (29 ms a step without self collision). Sampling a recorded frame for playback costs about 1.5 to 2 ms.
node scripts/render-soft-body-film.mjs <folder> [--flag-only](run it through gpu-lock) writes a 960 by 540, 60 fps preview MP4 of each film (one video frame per simulation step, so frame N is step N), stills at contact and at the deepest dent for the jelly and at start, mid fall, first touch, settling and final rest for the flag (--flag-onlyskips the jelly cube),jelly-cube-compare.png(both side by side with the measured width and height drawn on it) andsoft-body-film.jsonwith every number, its unit and its step. It needsnpm run build:libfirst. No default changes.
Jelly feel (tests/soft-body-bounce.test.js, measured): the 0.5 m rounded cube of tests/support/jelly-cube.mjs, dropped from 1.95 m onto the floor, damping: 2, bend: 0, stiffness: 0.9 unless listed, pressure: 1. It lands at step 48. Dent is the rest height minus the shortest height (rest height 0.5 m); rebound is how far the lowest vertex rises above the floor before the cube falls back.
shape |
stiffness |
Dent | Rebound at bounce 0 |
at 0.5 | at 1 |
|---|---|---|---|---|---|
| 1 | 0.9 | 0.026 m | 0.102 m | 0.192 m | 0.516 m |
| 0.15 (default) | 0.9 | 0.050 m | 0.072 m | 0.149 m | 0.469 m |
| 0.02 | 0.9 | 0.065 m | 0.000 m | 0.093 m | 0.441 m |
| 0.02 | 0.1 | 0.099 m | 0.000 m | 0.100 m | 0.447 m |
Before bounce existed, shape and damping were the only knobs that changed the rebound, and none gave a controlled one. Lowering shape or stiffness deepens the dent (0.026 to 0.099 m), so softness needed no new field. A very low shape has a price: with shape 0.02 and stiffness 0.1, 132 of the cube's 588 triangles turn inside out in the worst frame. That is a real surface fold, and selfCollision, bend, more solver iterations and a gentler volume step do not remove it (measured). A separate cause made a clean dent look ragged: the film's box has a 0.12 bevel, so each flat side is a single quad between two rim rows, the bulge can only sit on the rims, and at the dent the top rim juts past the sunken top face (a ledge and a stepped outline, with no fold and no inverted triangle). A box with a 0.3 bevel has rows of vertices up the sides, and the bulge becomes a belly.
Three presets that step clearly, drawn on a box with bevel 0.3 and subdivisions 4 (JELLY_PRESETS and JELLY_LOOK in tests/support/jelly-cube.mjs, previewed by scripts/render-jelly-bounce.mjs and labelled by scripts/label-jelly-bounce.py; the preview is 960 by 540 at 60 fps, 4 seconds, from a long lens so the cubes carry no perspective skew, and each cube has a name label and its own colour):
| Preset (cube colour in the preview) | shape |
stiffness |
bounce |
Dent | Sideways bulge | Rebound | Stops moving at step |
|---|---|---|---|---|---|---|---|
| firm (blue) | 1 | 0.9 | 0 | 0.029 m | 0.022 m | 0.147 m | 110 |
| medium (orange) | 0.2 | 0.05 | 0.5 | 0.054 m | 0.068 m | 0.223 m | 156 |
| soft (pink) | 0.06 | 0.02 | 0.9 | 0.085 m | 0.106 m | 0.349 m | 210 |
The dent steps 1.9 and 1.6 times and the rebound 1.5 and 1.6 times, so each step shows in the dent and in the air under the cube. Every triangle keeps facing out (0 inverted in the bake, 0 folded at the dent), the top face is level within 0.03 degrees at the deepest dent and at the end, and the widest row of the soft cube at its dent sits at 5 percent of its height (a belly low on the body), not at the top rim. In flight the soft cube is 43.3 to 53.1 cm tall and 48.3 to 58.1 cm wide (the firm one 48.3 to 50.6 cm tall), so it stretches and wobbles while it is airborne.
With damping: 0 and the default shape, bounce 1 sends the cube back to 1.85 m of its 1.95 m drop.
Blender comparison (scripts/blender-cloth.py, Blender 5.2.2, default stiffness, mass set from the same kg/m2; tests/cloth-blender.test.js):
| Case | Result |
|---|---|
| 2 x 1.5 m sheet pinned along its top, 2 s | Mean vertex distance 0.08 percent of the height, free edge 1.2485 m against 1.25 m. Both hang straight, so this is a weak test. |
| 1.6 m sheet dropped on a 0.4 m ball, drag matched | Falls and lands alike: mean vertex distance 5.6 percent of the sheet size at 0.25 s and 4.9 percent at 0.5 s. Blender then drapes more slowly (17 percent at 1 s, 35 percent at 2 s). No parity is claimed for draping. |
Why the first drape comparison said 63 percent (found while comparing pictures, measured):
- The comparison paired vertices in the wrong order.
scripts/blender-cloth.pybuilt the flat grid with row 0 on the near edge, while the Crucible grid turned flat has row 0 on the far edge, so every vertex was compared with its mirror across the sheet. A flat sheet falling straight scores about 50 percent that way. Pairing the rows correctly takes the mean distance at 2 s from 53 to 7.5 percent for the same two bakes. - The drag was 180 times apart. Blender's air damping of 1 on a particle of 0.003 kg is a drag of about 54 per second: a falling sheet reaches a terminal speed of 0.18 m/s (measured in free fall, 1 to 2 s and 2 to 8 s both 0.17 to 0.18 m/s). Crucible defaults to 0.3 per second, so one sheet landed in 0.4 s and the other took over 2 s. The earlier note tried damping 3 and 8; the matching value is about 54, so
dampingnow accepts up to 100. Blender air damping 0.1 (5.4 per second) lands like Crucible within 5 percent. - With air damping 0 Blender's sheet falls through the ball at 2 s (centre vertex at -1.1 m), so a lower drag in Blender is not free either.
- What remains is a model difference, not a defect: matched, the mean distance is 17 percent at 1 s and 35 percent at 2 s, because Blender's sheet drapes slowly as a wrinkled bell (friction 5 on collision, tension 15, bending 0.5) and this one hangs smooth flat panels over the ball (pictures in
bench/reference/images/cloth-drape-*.jpg). Nothing was tuned to close that gap.
Earlier drape measurements (old pairing, Blender air damping 1, Crucible defaults; same 13 x 13 grid, 1.6 m sheet at 1 m, ball radius 0.4 m, mass 0.2 kg/m2, Blender 5.2.2 default stiffness, quality 8). Only the stretch rows still say something:
| Crucible | Blender | |
|---|---|---|
| Longest edge over rest length, at 2 s | 1.021 | 1.048 |
| Mean edge over rest length, at 2 s | 1.001 | 1.007 |
| Sheet area over rest area, at 2 s | 1.003 | 1.013 |
| Frames simulated | 481 (8 s, 4 substeps each) | 481 (8 s) |
| Nearest vertex to the ball centre when resting on it | 0.410 (radius + 0.01 thickness) | 0.427 (radius + 0.01 ball distance + 0.01 cloth distance, plus the 48-segment sphere) |
| Mean vertex motion in the last 2 s | 0.025 m, nearly settled | 0.30 m, still sliding off the ball |
- Stretch is far inside 10 percent in both solvers, so stiffness or iteration count does not explain the gap;
tests/cloth-blender.test.jspins the Crucible drape to 10 percent per edge and 5 percent in area. - The setups match except collision margins, which differ by 17 mm and are too small to matter.
Picture comparison (npm run reference -- --cloth, scores in bench/reference/cloth.json, method and table in bench/reference/README.md): the banner scores at the EEVEE yardstick (FLIP 0.043 and 0.044 against Cycles, EEVEE 0.042) and the drape at about twice it (0.080 to 0.093 against 0.039 to 0.043). By eye, Blender's cloth wrinkles and bells over the ball, and this solver gives smooth flat panels. The solvers differ in kind, so these scores say how alike the motion is, not that one is right. Soft bodies are not built; see the ledger.
Repeat recordings require identical inputs, creation order, timestep, solver options, and Rapier version.
Rapier documents cross-platform determinism for its WASM solver under identical initial conditions.
Input calculations such as Math.sin can differ across platforms and invalidate that guarantee.
This addon does not promise identical trajectories across different Rapier versions.
The implementation uses @dimforge/rapier3d-compat version 0.21.0, licensed under Apache 2.0.
Sources: Rapier JavaScript setup, Rapier joints and Rapier determinism.
Live cloth
A game steps cloth one frame at a time, with pins that move and change while it runs. createCloth(positions, triangles, options) is the solver bakeCloth records from (bakeCloth is now a loop over it), so a live run and a baked recording of the same input give the same numbers, frame for frame. It lives in src/cloth.js; the recipe cloth section above still bakes ahead of time.
import { createCloth } from '@codepawlhq/crucible/addons/cloth';
// A 1 m square sheet, 33 x 33 particles, with two grippers holding two corners.
const cloth = createCloth(positions, triangles, { density: 0.2, bend: 0.1 });
const leftCorner = 0;
const rightCorner = 32;
cloth.pin(leftCorner, leftGripper.position);
cloth.pin(rightCorner, rightGripper.position);
function frame(deltaSeconds) {
// Move the grippers first, then hand the targets to the sheet. Each step carries the pins there in even strides.
cloth.pin(leftCorner, leftGripper.position);
cloth.pin(rightCorner, rightGripper.position);
cloth.step(deltaSeconds, { wind: [0, 0, 1] });
const pull = cloth.pinForce(leftCorner);
if (Math.hypot(...pull) > gripStrength) cloth.unpin(leftCorner); // the grip slips and the sheet falls on that side
sheetGeometryPositions.set(cloth.positions);
}
step(deltaSeconds, { wind, colliders })runs 4 substeps of 8 constraint passes.wind(m/s) andcollidersreplace the ones in the options for this step only; the other options are fixed at creation.cloth.positionsis oneFloat32Array, 3 numbers a particle, rewritten in place by every step.pin(index, position)holds a particle atposition, or where it is now when none is given. Calling it again moves the target, so a gripper that follows a hand calls it every frame.unpin(index)lets go; the particle keeps its velocity.isPinned(index)reads the state.pinForce(index, out)writes the force the cloth pulls the pinned particle with, in newtons, averaged over the last step:out = [x, y, z], so its length is the load. It is an estimate taken from the corrections the solver made, not a measurement: a sheet hanging still from its top row loads the pins with roughly its weight (cloth.particleMass * particleCount * 9.81).setExtraMass(index, kilograms)hangs mass on a particle on top ofcloth.particleMass(density times area, shared evenly). A heavy particle moves less when the constraints pull, so the sheet sags around it.- Tearing:
tearStretch(a stretch constraint breaks when its length passes this multiple of its rest length) andtearForce(it breaks when it carries more than this many newtons) are options; both default to never. The bend constraint across a broken edge breaks with it.cloth.brokenlists them in order as{ constraint, first, second, kind }, wherefirstandsecondare particle indices andkindis'stretch'or'bend';breakConstraint(edge)tears one by hand. A broken constraint never heals, and the triangles are not removed: hide a triangle whose edge is in the list to show the tear. - A particle index is a welded particle (
weldVerticesmaps mesh vertices to them), as inbakeCloth. step(deltaSeconds)takes 0 to 1 second; 0 changes nothing, and a negative, NaN or longer step throws aRangeError.bakeClothneeds a wholeframeCountof at least 1 andframesPerSecondof at least 1.
Deforming a drawn part in place
updatePartVertices(renderer, part, positions, normals) writes new vertex positions, and normals when given, into the buffers a rigid part already uses, with bufferSubData. It needs no replaceParts, no new geometry object and no new draw batch. It comes from @codepawlhq/crucible/addons/update-part-vertices, takes the renderer as its first argument and imports nothing from the renderer, so a scene that never deforms a mesh does not carry it.
import { updatePartVertices } from '@codepawlhq/crucible/addons/update-part-vertices';
updatePartVertices(renderer, sheetPart, sheetPositions, sheetNormals);
renderer.render(frame);
- The vertex count cannot change, and the arrays are
Float32Arrays of 3 numbers a vertex. The values are copied into the part's geometry, so the geometry stays the truth, and every part that uses the same geometry deforms with it. - It refuses skinned, morphed, crowd and level-of-detail parts. A textured part works, since only positions and normals move.
- The culling bounds and the shadow map follow the new positions.
- Per vertex a cloth steps on welded particles, so copy each vertex from its particle (
weldVertices(...).particleOfVertex) and recompute normals (recomputeNormals) before the call.
Settling props
@codepawlhq/crucible/addons/settle drops props as rigid bodies onto colliders, runs Rapier at 60 Hz for a bounded time and returns the resting transforms, so rubble, crates and pebbles lie against each other instead of hovering where they were placed. The caller keeps the result as static parts. Same seed and inputs give the same transforms byte for byte (they are rounded to 1e-5).
import { loadPhysicsEngine } from '@codepawlhq/crucible/addons/physics';
import { settleInstances } from '@codepawlhq/crucible/addons/settle';
await loadPhysicsEngine();
const { instances, report } = settleInstances({
colliders: [
{ shape: 'box', translation: [0, -0.1, 0], halfExtents: [4, 0.1, 4] },
{ shape: 'box', translation: [0, 1, -2], halfExtents: [4, 1, 0.2] },
],
area: { min: [-2, -1.7], max: [2, -0.5] }, count: 80, size: [0.1, 0.25], seed: 5,
});
// instances: [{ translation, rotation (quaternion), size }]; report: { requested, placed, skipped, fellOff, unsettled, duration }
| Setting | Default | Meaning |
|---|---|---|
colliders |
required | Up to 512 box ({ translation, rotation, halfExtents }) or ball ({ translation, radius }) shapes to land on. List earlier settled props here to stack on them. |
shape |
box |
Prop shape, box or ball. |
area, count or density |
required | Where to scatter, and how many (256 at most) or how many per square metre. |
instances |
none | Instead of area, count, density and size: your own start poses [{ translation, rotation, size }] (size is three edge lengths for a box, a diameter for a ball). |
size |
[0.1, 0.25] |
Smallest and largest edge (box) or diameter (ball), in metres. |
aspect |
0.3 | Per-axis edge variation of a box, 0 to 1. |
rotation |
1 | Start tumble, 0 (yaw only) to 1 (any orientation). |
spacing |
0.01 | Minimum gap between props and colliders at the start, so no prop starts overlapping. |
maxSlope |
60 | Props are not placed where the ground below is steeper than this, in degrees. |
duration |
3 | Seconds simulated, 0.5 to 6. |
friction, restitution |
0.6, 0.1 | Contact material of props and colliders. |
A prop that falls off the world is left out (report.fellOff); one still moving at the end is kept (report.unsettled; raise duration). report.skipped counts rejected placement attempts, not props. Props use continuous collision detection, so thin ones do not tunnel through a floor.
In a recipe the same step is the settle operation of scene_apply (see Recipe settle). Clutter tiles (addons/clutter) are streamed meshes, not instance lists, so to settle stones list the poses you want as instances.
Recipe settle
{ "type": "settle", "settle": {
"id": "rubble", "geometry": "block", "material": ["stone", "rust"],
"colliders": ["floor", "wall"],
"area": { "min": [-2, -1.7], "max": [2, -0.5] }, "count": 80, "size": [0.1, 0.25], "seed": 5
} }
colliders are node IDs. A node needs a box or sphere geometry (a sphere must have equal scale on all axes); a group node stands for its mesh children. geometry is a recipe box or sphere geometry and decides the prop shape; material is an ID or a list of up to 8 that props pick from by seed. The operation adds a group node rubble and one static child per resting prop, rubble-0, rubble-1 and so on, with no physics section. List rubble in a later settle's colliders to stack on it. Settling needs the Rapier peer loaded like recipe physics does, and scene_capabilities topic settle has the field list. Remove the group and its children before settling again under the same ID.
Force fields
One list of up to 8 fields, fields on the particles section and on the cloth section, accelerates every particle, hair strand and cloth particle through the same evaluation (src/force-fields.js, evaluateForceFields). Each field has a type:
| type | acceleration | keys |
|---|---|---|
wind |
strength m/s2 along direction (default +x) |
direction |
drag |
-strength times the velocity, in 1/s |
|
vortex |
strength m/s2 around axis (default +y) through position, along axis cross offset |
axis |
magnet |
strength m/s2 toward position; a negative strength pushes away |
|
turbulence |
smooth seeded value noise, each component within strength |
seed, scale (cycles per metre, 1), rate (cycles per second, 0.5) |
Every field also takes strength (default 1, -1000 to 1000), position (default the origin), falloff (exponent of 1 / (1 + distance from position), 0 means none) and radius (cutoff distance, 0 means none). Unknown keys are rejected with the list of known ones.
- Particles under fields have no closed form, so each one is integrated from its own birth at a fixed 1/120 s (semi-implicit Euler, gravity, drag toward the wind, then the fields) every time it is asked. It is still a pure function of time: a seek back repeats exactly, and the same seed gives the same frames. The floor stops a particle where it lands. Cost grows with age, about the age times 120 steps for each live particle.
- Cloth adds the fields to the velocity of every particle at each of the four substeps, with the substep time as the turbulence time, so the recording stays deterministic.
- Hair leans: the strand tip moves by 0.02 m for each m/s2 of field acceleration at the strand root (no velocity, so drag does nothing), clamped to the strand length. A strand without turbulence builds once.
tests/force-fields.test.jschecks each type against a known particle path (wind against constant acceleration, drag against the exponential, magnet against free fall toward a point, vortex against the swirl direction), falloff, seeds and seeks.
Recipe particles and hair
A recipe particles section holds up to 4 systems (src/particles.js, src/hair.js, src/agent-particles.js). It needs no peer dependency and loads on demand with the particles module, so a scene without particles pays nothing. Blender's particle system has the same two kinds, Emitter and Hair.
{ "geometries": [{ "id": "speck", "type": "box", "bevel": 0 }],
"nodes": [{ "id": "sparks", "geometry": "speck", "material": "glow" }],
"particles": { "systems": [{ "node": "sparks", "seed": 11, "count": 300, "rate": 150, "lifetime": [0.8, 1.6],
"speed": [2, 4], "spread": 35, "size": 0.035, "drag": 0.3, "floor": 0, "scale": "shrink",
"emitter": { "shape": "disc", "position": [-0.8, 0, 0], "radius": 0.15 } }] } }
- An emitter system draws its root node's own geometry once per particle, so keep the shape low-poly. The node's transform does not move or scale particles.
countis at most 2000 a system and 4000 in total, and at most 100000 vertices are drawn in total (a box withbevel: 0is 24 per particle, but a defaultboxhas a bevel and is 1176, so give particle shapesbevel: 0; a default sphere is too heavy; the error names the vertices per particle of the node). - Fields and defaults are in
scene_capabilitiesunderparticles:seed,count,rate(omit for one burst at time 0),start(seconds before the first birth, 0;delayis the same field) andstop(seconds, afterstart: nothing is born at or after it, so a system with arateemits only inside the window; particles already born finish their life),lifetime,speedandsize(a number or[min, max]),direction,spread(cone half angle, degrees),emitter(point,box,sphere,discormesh),instancesandorient(see the next two bullets),scale(constant,shrink,grow),dragandfloor.gravityand a steadywindsit on the section; wind pulls the velocity only wheredragis above zero. - A particle is a closed-form function of its own seeded launch values and the time (drag, wind and gravity have an exact solution), checked against a 1e-5 s integration in
tests/particles.test.js. There is no stepping, so the state at time t never depends on earlier seeks: the same time gives the same particles, a seek backwards repeats them, the same seed gives identical bytes, and raisingcountkeeps the particles already there. The landing time on aflooris found once per particle from its launch values. - A hair system (
type: "hair") growscountstrands from area-weighted seeded points of asurfacenode into its ownnode(the surface is only read, so several systems can share one). A strand is a triangular tube of 1 to 8 segments tapering to 15 percent, leaning off the surface normal bylean, bending withdroop, and swaying byswaymetres along the horizontal wind atswayRatehertz. Withoutswaythe mesh is built once. - Both kinds replace their node's part at each sampled time, so the renderer sees a topology change.
npm run smoke:agent-particlesseeks 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_inspectreturns aparticlesreport: per emitter the particle count, vertices per particle,maxAliveandendsAt; per hair system the strands, segments and vertices per strand.- Collision (#614):
colliderslists up to 8 static root nodes (4096 triangles in total, read only); particles bounce off their triangles and the floor plane withbounce(0 to 1; 0 sticks where it lands; 0.3 with colliders, 0 on a floor alone) andfriction(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) andalpha(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" };velocityFromadds a vector of the mesh such as the ocean's spray, see Spray from the sea) 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.fromissurface(a point on a triangle, weighted by area),vertices(one of the mesh vertices),edges(a point along an edge, weighted by edge length;sharpAnglein degrees keeps only the edges that are open or whose two faces bend more than that, so sparks come off a rim, and the normal is the mean of the two face normals) orvolume(a point inside a closed mesh, found by testing random points in its bounds; an open mesh is rejected).groupnames a vertex group of the mesh (made with avertex_groupmesh edit) and weights the points by it:surfaceweighs each triangle by its area times the mean weight of its corners,verticespicks by weight,edgesweighs each edge by its length times the lighter weight of its two ends (an edge is in the group only when both ends are painted), so sparks come off a painted edge or rim; a missing group is an error listing the groups the mesh has, andvolumetakes no group;sharpAngleis only foredges.normalSpeedadds a speed along the surface normal on top ofdirection,spreadandspeed(setspeedto 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.positionoffsets the points. The same seed gives the same points, and raisingcountkeeps the earlier ones. instancesis 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.orientisnone(the default; onlyspinturns a particle),random(a random starting rotation) ornormal(the instance's +Y axis turned onto the surface normal; needs a mesh emitter withfromofsurfaceorvertices). Instances share the one material of the system node, and the vertex limit is counted with the largest instance for every particle.- Spark streaks (#1758):
type: "sparks"is a third kind of system for the bright streaks an explosion throws (src/particle-sparks.js). Each spark is launched like an emitter particle (seed,speed,spread,lifetime,drag, the section'sgravityandwind,floor,bounce) and drawn as an octahedron stretched along its velocity: its tail is where the spark wasshutterseconds earlier (never before its birth), so the streak is as long as the spark travels while the shutter is open.shutteris in seconds, 1/48 by default (half a frame at 24 frames per second); give it theeffects.motionBlur.shutterof the film so the streaks match the blur. A spark cools linearly fromtemperature[0]totemperature[1]kelvin ([2500, 800]), and its colour is the physical blackbody of that temperature, the same table the grid fireball uses (#1751): Stefan-Boltzmann radiance sigma T^4 / pi times the luminance 1 hue, timesintensity(12), tapered to zero over the last 15 percent of its life. At 2500 K that is a yellow orange, at 1650 K a deep orange and at 1055 K a dark red, and the brightness falls 2500 to 800 K by a factor of about 95 before the taper. The colour is written as the vertex colour (linear radiance, above 1), so the node's material must be"tag": "unlit"with colour[1, 1, 1]; bloom then makes the hot head glow.countis at most 4096 in total (800 by default with the preset),speedat most 300 m/s,lifetime0.05 to 5 s,size(the streak radius, metres) 0.0005 to 1,temperature300 to 6000 K and falling,intensity0 to 1000; anything else fails and names the range. The preset"preset": "explosion"fills a blast: 800 sparks,speed[6, 24],spread180 (every direction),lifetime[0.5, 2],size[0.006, 0.014],drag0.9, a 0.2 m sphere emitter;positionis the blast point and any field you give wins over the preset.delay(seconds, 0 to 3600) holds the birth of every spark back, as for an emitter (add-explosionsets it to the blast'sstart). Sparks are a pure function of the seed and the time like every other system, 6 vertices each, andscene_inspectreports them with their temperature and shutter.
{ "geometries": [{ "id": "speck", "type": "box" }],
"materials": [{ "id": "spark", "tag": "unlit", "color": [1, 1, 1], "emission": 0 }],
"nodes": [{ "id": "sparks", "geometry": "speck", "material": "spark" }],
"particles": { "systems": [{ "type": "sparks", "preset": "explosion", "node": "sparks", "position": [0, 0.5, 0], "seed": 1758, "floor": 0 }] } }
scripts/cycles-volume-reference.py takes an optional sparks block (written by scripts/make-spark-spec.mjs from the same launch values) that draws the same streaks in Cycles, camera-visible only, for a side-by-side with the rasterizer. See the pull request for the early, peak and late stills of the #1735 explosion and the frame cost at 1080p.
- 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.
No Blender parity is claimed for either kind: Blender's particle physics, force fields, children and hair dynamics are not reproduced, and no comparison against a Blender render was run.
Decision: smoke, fire and liquid in the browser
Smoke and fire: one baked solver ships, behind add-explosion only. src/gas-sim.js (Stable Fluids advection and pressure projection, buoyancy, vorticity confinement, a fuel to flame burn) bakes one ground blast at 32 cubed for 72 frames, keyed by fuel and seed and cached on disk, and the grid volume's box scales it to the asked size (src/explosion-grids.js, docs/agent-scene.md). A grid volume (shape: "grid", docs/volumetric.md) also draws density, temperature and flame grids baked by EmberGen, Houdini or Blender. There is no general smoke or fire tool with free emitters, colliders or wind. The solver stays one fixed, cached bake rather than a simulation per call because the solver is the cost, not the volume look. A naive CPU step (semi-Lagrangian advection of density plus 20 pressure passes, unoptimised JavaScript, measured on the dev machine) takes about 0.09 s on a 32 cubed grid, 0.14 s on 48 cubed, 0.46 s on 64 cubed and 1.3 s on 96 cubed. A 10 second clip at 60 frames is 600 steps: about 4.6 minutes of baking at 64 cubed, and 157 MB of density frames at 4 bytes a cell, before velocity and temperature. That does not fit an agent's tool call or the package budget. A recipe can already use the depth-clipped volumetric fog, and emitter particles with scale: "grow" for puffs. A longer or larger smoke or fire is baked outside the browser, as Spume does for liquid, and played back as a grid volume sequence.
Liquid: keep addons/spume playback and do not add a browser solver. Spume plays a baked liquid as parts in 8793 bytes gzip (the entry:spume baseline from npm run size), and the bake runs offline in another project. A browser FLIP or SPH solver would add its own code, a bounded step budget and a surface reconstruction, and it would face the same step times as the grid above. No browser liquid solver was written or measured, so no speed claim is made about one. Revisit only when an agent task needs a liquid that Spume cannot play back.