Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Cloth follows moving, skinned characters (closes #326)

Nguyen Xuan An6edcc6beac66
diff --git a/changes/326.md b/changes/326.md
new file mode 100644
index 00000000..104b251f
--- /dev/null
+++ b/changes/326.md
@@ -0,0 +1 @@
+- Cloth follows moving characters (issue #326). Colliders can be a ball or capsule attached to any node or bone, or one capsule per bone of an armature fitted as the ragdoll does; a sheet's `pinTo` makes its pinned edges ride a node with a pin weight. Both are sampled at every 60 Hz solver step, so a seek equals playing to that time. A cape pinned to the reference walker stays outside every limb capsule through a 5 s walk, and the same cape without colliders sinks 20 mm or more into them. Up to 64 moving colliders; a 5 s walk bakes in about 2.5 s.
diff --git a/docs/parity.md b/docs/parity.md
index a8f93f3c..fc1ea226 100644
--- a/docs/parity.md
+++ b/docs/parity.md
@@ -110,7 +110,7 @@ To move to a new Blender release, run `node scripts/parity-manual-snapshot.mjs`.
| Modeling > Modifiers > Normals > Normal Edit Modifier | missing | No equivalent. | | |
| Modeling > Modifiers > Normals > Weighted Normal Modifier | partial | `weighted_normal` edit and stack node: face area weighting with a `weight` from 1 to 100 (power weight / 50) inside smooth groups bounded by sharp edges and an `angle`, stored as one normal per corner that the render uses. No corner angle or face influence modes, no keep-sharp switch, no vertex groups and no Blender comparison of normals. | [mesh-normal-modifiers](../tests/mesh-normal-modifiers.test.js) | #42 |
| Modeling > Modifiers > Normals > Smooth By Angle Modifier | done | `smooth_by_angle` edit and stack node with `angle` and `ignoreSharp`: edges bending more than the angle become sharp, the rest smooth, over the geometry `smoothAngle`. Hand-marked sharp edges stay unless ignored, as in Blender. No vertex groups and no Blender comparison of normals. | [mesh-normal-modifiers](../tests/mesh-normal-modifiers.test.js) | |
-| Modeling > Modifiers > Physics > Cloth Modifier | partial | Recipe `cloth`: a position-based sheet solver with pinned edges, steady wind, gravity and fixed ball or box colliders, recorded at 60 frames a second so a seek repeats exactly. No self collision, no per-vertex stiffness or pin weights. A hanging sheet matches a Blender bake to 0.08 percent of its height. A sheet dropped on a ball lands like Blender with the drag matched (mean vertex distance 5 percent at 0.5 s) and then drapes as smooth flat panels where Blender wrinkles into a bell (17 percent at 1 s, 35 percent at 2 s); the old 63 percent came from mirrored vertex pairing and a 180 times difference in air drag. Picture scores against Cycles (FLIP): banner 0.043, drape 0.08 to 0.09, EEVEE 0.04. See docs/physics.md and bench/reference/README.md. | [cloth](../tests/cloth.test.js), [cloth-blender](../tests/cloth-blender.test.js) | #62 |
+| Modeling > Modifiers > Physics > Cloth Modifier | partial | Recipe `cloth`: a position-based sheet solver with pinned edges, steady wind, gravity and ball or box colliders, recorded at 60 frames a second so a seek repeats exactly. Since issue #326 colliders can be balls or capsules riding on a node or bone, a fitted capsule per bone of an armature (the ragdoll radius), and a sheet can pin its edges to a moving node with a pin weight: a cape pinned to the reference walker stays outside every limb capsule through a 5 s walk (`tests/cloth-moving.test.js`). Collision is per point, not per triangle, and a physics ragdoll is not followed. No self collision, no per-vertex stiffness or vertex-group pin weights (one weight per pinned edge set). A hanging sheet matches a Blender bake to 0.08 percent of its height. A sheet dropped on a ball lands like Blender with the drag matched (mean vertex distance 5 percent at 0.5 s) and then drapes as smooth flat panels where Blender wrinkles into a bell (17 percent at 1 s, 35 percent at 2 s); the old 63 percent came from mirrored vertex pairing and a 180 times difference in air drag. Picture scores against Cycles (FLIP): banner 0.043, drape 0.08 to 0.09, EEVEE 0.04. See docs/physics.md and bench/reference/README.md. | [cloth](../tests/cloth.test.js), [cloth-blender](../tests/cloth-blender.test.js), [moving cloth](../tests/cloth-moving.test.js) | #62, #326 |
| Modeling > Modifiers > Physics > Collision Modifier | partial | Rapier colliders fitted to recipe geometry as box, ball, capsule, convex hull or trimesh, so a body rests on an authored mesh. | [agent-physics](../tests/agent-physics.test.js) | #61 |
| Modeling > Modifiers > Physics > Dynamic Paint Modifier | missing | No equivalent. | | |
| Modeling > Modifiers > Physics > Explode Modifier | missing | No equivalent. | | |
@@ -176,7 +176,7 @@ To move to a new Blender release, run `node scripts/parity-manual-snapshot.mjs`.
| Physics > Rigid Body > Rigid Body Properties | partial | Dynamic, fixed and kinematic bodies with mass, density, friction, restitution and velocity, in code and in recipes. Trimesh and convex colliders, no bone-bound bodies yet. | [physics-colliders](../tests/physics-colliders.test.js) | #61 |
| Physics > Rigid Body > Rigid Body World | partial | Recorded simulation with deterministic seeks, in code and in a recipe `physics` section (MCP, a seek back repeats the PNG). | [agent-physics](../tests/agent-physics.test.js) | #61 |
| Physics > Rigid Body > Rigid Body Constraints | partial | Fixed, spherical, revolute and prismatic joints, with limits and motors, in code. | [physics](../tests/physics.test.js) | #61 |
-| Physics > Cloth | partial | Same solver as the Cloth Modifier row: gravity, wind, pins, ball and box collisions, thickness and friction, and a `scene_inspect` report. Blender's tension, compression, shear and bending stiffness map to one `stiffness` and one `bend`. | [cloth](../tests/cloth.test.js) | #62 |
+| Physics > Cloth | partial | Same solver as the Cloth Modifier row: gravity, wind, pins (static, or riding a moving node with a weight), ball, capsule and box collisions (moving ones follow a skinned character), thickness and friction, and a `scene_inspect` report. Blender's tension, compression, shear and bending stiffness map to one `stiffness` and one `bend`. | [cloth](../tests/cloth.test.js) | #62 |
| Physics > Soft Body | missing | No soft bodies. | | #62 |
| Physics > Fluid | partial | `addons/spume` plays back a liquid baked outside the browser. There is no smoke or fire, by decision (#63): docs/physics.md "Decision" has the measured grid cost. | [spume](../tests/spume.test.js) | #63 |
| Physics > Particle System | partial | Recipe `particles` emitters and hair: see the Particle System Modifier row. Sparks, dust (drag, grow) and fur work from a recipe and seek deterministically. | [particles](../tests/particles.test.js) | #63 |
diff --git a/docs/physics.md b/docs/physics.md
index 34655fc1..9e9f4e30 100644
--- a/docs/physics.md
+++ b/docs/physics.md
@@ -420,9 +420,14 @@ A recipe `cloth` section records deformable sheets with a position-based solver
- `pin` holds edges of the local bounds in place: `top`, `bottom`, `left`, `right` or a corner such as `topLeft`.
- Sheet fields: `stiffness` (0.01 to 1, default 0.9), `bend` (0 to 1, default 0.1), `density` in kg/m2 (default 0.2), `damping` in 1/s (default 0.3), `friction` (default 0.3) and `thickness` in metres (default 0.01). `gravity` and a steady `wind` in m/s sit on the section.
- Colliders are fixed root nodes fitted to their geometry bounds as a `ball` or an oriented `box` (default). A thin box is a floor.
-- A sheet or collider cannot have a motion translation or rotation track or a physics body. No cloth-to-cloth or self collision, and no soft bodies yet.
+- A sheet or fixed collider cannot have a motion translation or rotation track or a physics body. No cloth-to-cloth or self collision, and no soft bodies yet.
+- 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 (plus `offset`) to another (plus `toOffset`). 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 `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 past `duration` holds the last frame.
-- Limits: 8 sheets, 16 colliders, 10 seconds, 5000 particles a sheet, 3 million recorded particle positions and 150 million solver operations a bake (about 3 seconds). Larger input is rejected with the limit in the message. A 32 by 32 grid for 4 seconds bakes in about 1.4 s.
+- Limits: 8 sheets, 16 fixed colliders, 64 moving ones, 10 seconds, 5000 particles a sheet, 3 million recorded particle positions and 150 million solver operations a bake (about 3 seconds). 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 uses `replaceParts` and `scene_look` with `motionTime` repeats the same PNG bytes (`npm run smoke:agent-cloth`).
- `scene_inspect` returns a `cloth` report: particles, triangles, pinned count and the final bounds of each sheet.
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 71659f8d..e337fb2d 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -491,9 +491,11 @@ const physics = z.strictObject({
bodies: z.array(physicsBody).min(1).max(64),
joints: z.array(physicsJoint).max(64).optional().describe('Joint bodies are the node IDs of physics bodies.'),
}).describe('Rigid bodies recorded offline with Rapier (optional peer) at 60 fps and seeked by motionTime. scene_inspect reports contacts and resting state. A node cannot have a body and a motion translation or rotation track.');
+const looseRecord = z.record(z.string(), z.unknown()).meta({ id: 'LooseRecord' });
const clothSheet = z.strictObject({
- node: identifier.describe('Root mesh node that stays put, such as a grid.'),
+ node: identifier.describe('Root mesh node.'),
pin: z.array(z.enum(['top', 'bottom', 'left', 'right', 'topLeft', 'topRight', 'bottomLeft', 'bottomRight'])).max(8).optional(),
+ pinTo: looseRecord.optional(),
stiffness: unit.optional(), bend: unit.optional(), density: positive.optional(), damping: nonnegative.optional(), friction: unit.optional(), thickness: nonnegative.optional(),
});
const cloth = z.strictObject({
@@ -501,8 +503,8 @@ const cloth = z.strictObject({
gravity: vector3.optional(),
wind: vector3.optional(),
sheets: z.array(clothSheet).min(1).max(8),
- colliders: z.array(z.strictObject({ node: identifier, shape: z.enum(['ball', 'box']).optional() })).max(16).optional(),
-}).describe('Cloth baked at 60 fps and seeked by motionTime. Units and defaults: scene_capabilities cloth.');
+ colliders: z.array(looseRecord).max(80).optional().describe('Fields: scene_capabilities cloth.'),
+}).describe('Baked at 60 fps, seeked by motionTime. Units, defaults: scene_capabilities cloth.');
// The full motion schema (tracks, ik, constraints, drivers) is in scene_create's recipe. scene_apply and asset recipes
// take the same object, validated by the backend, without repeating about 35 KB of schema in each tool.
const recipeMotionReference = z.record(z.string(), z.unknown()).describe('The same object as recipe.motion in scene_create: duration, loop, tracks, ik, constraints, drivers. Read that tool for the fields. On an imported asset it also takes layers, up to 8 clips played at motion time before tracks and ik: { clip (scene_inspect animations id), mask: { joints, descendants, exclude } of node IDs, weight, speed, offset, loop, additive, reference, bones: { clip node: asset node } to retarget by name, morph }. A masked layer waves while another walks.');
diff --git a/src/agent-cloth.js b/src/agent-cloth.js
index 58759bd9..c8210d51 100644
--- a/src/agent-cloth.js
+++ b/src/agent-cloth.js
@@ -1,19 +1,35 @@
-import { mat4 } from 'gl-matrix';
+import { mat4, vec3 } from 'gl-matrix';
import { runKernel } from './kernel-offload.js';
-import { bakeCloth, sampleClothFrames, weldVertices } from './cloth.js';
+import { bakeCloth, sampleClothFrames, weldVertices, CLOTH_LIMITS } from './cloth.js';
import { recomputeNormals } from './geometry-normals.js';
import { bakingContext, boundedArray, finiteNumber, knownKeys, rootNodeWithGeometry, vectorOfThree } from './agent-recipe-checks.js';
+import { boneNodeId, boneTails, restWorldMatrix } from './rig.js';
+// Matches the ragdoll's bone capsule radius (src/ragdoll.js), without loading the ragdoll for one number.
+const RADIUS_OF_LENGTH = 0.2;
const FRAMES_PER_SECOND = 60;
const MAX_DURATION_SECONDS = 10;
const MAX_SHEETS = 8;
const MAX_COLLIDERS = 16;
+// Moving balls and capsules, counting every bone capsule a fitted armature expands to.
+const MAX_MOVING_COLLIDERS = 64;
+const MIN_MOVING_RADIUS = 0.001;
+const MAX_MOVING_RADIUS = 10;
+const OFFSET_LIMIT = 100;
+const MIN_BONE_LENGTH = 1e-4;
const PIN_EDGES = ['top', 'bottom', 'left', 'right', 'topLeft', 'topRight', 'bottomLeft', 'bottomRight'];
const COLLIDER_SHAPES = ['ball', 'box'];
+const MOVING_SHAPES = ['ball', 'capsule'];
const CLOTH_FIELDS = ['duration', 'gravity', 'wind', 'sheets', 'colliders'];
-const SHEET_FIELDS = ['node', 'pin', 'stiffness', 'bend', 'density', 'damping', 'friction', 'thickness'];
-const COLLIDER_FIELDS = ['node', 'shape'];
+const SHEET_FIELDS = ['node', 'pin', 'pinTo', 'stiffness', 'bend', 'density', 'damping', 'friction', 'thickness'];
+const PIN_TO_FIELDS = ['node', 'weight'];
+const FIXED_COLLIDER_FIELDS = ['node', 'shape'];
+// A ball or capsule that rides on a node: the capsule runs from `attach` (plus offset) to `to` (plus toOffset).
+const MOVING_COLLIDER_FIELDS = ['attach', 'shape', 'radius', 'offset', 'to', 'toOffset'];
+// One capsule per bone of an armature, radius a fraction of the bone length as the ragdoll fits it.
+const FITTED_COLLIDER_FIELDS = ['armature', 'radiusFraction', 'exclude'];
const PIN_TOLERANCE = 1e-4;
+const NO_PATCHES = new Map();
function normalizeSheet(input, context) {
knownKeys(input, SHEET_FIELDS, 'cloth sheet');
@@ -28,6 +44,17 @@ function normalizeSheet(input, context) {
}
sheet.pin = [...new Set(edges)];
}
+ if (input.pinTo !== undefined) {
+ knownKeys(input.pinTo, PIN_TO_FIELDS, 'cloth pinTo');
+ if (!sheet.pin?.length) {
+ throw new RangeError('Cloth pinTo moves the pinned edges, so the sheet needs pin too.');
+ }
+ const target = existingNode(input.pinTo.node, context, 'Cloth pinTo');
+ if (target === input.node) {
+ throw new RangeError('Cloth pinTo cannot name the sheet itself.');
+ }
+ sheet.pinTo = { node: target, weight: input.pinTo.weight === undefined ? 1 : finiteNumber(input.pinTo.weight, 'Cloth pinTo weight', 0.01, 1) };
+ }
const ranges = { stiffness: [0.01, 1], bend: [0, 1], density: [0.01, 10], damping: [0, 100], friction: [0, 1], thickness: [0, 0.5] };
for (const [field, [minimum, maximum]] of Object.entries(ranges)) {
if (input[field] !== undefined) sheet[field] = finiteNumber(input[field], `Cloth ${field}`, minimum, maximum);
@@ -35,8 +62,62 @@ function normalizeSheet(input, context) {
return sheet;
}
-function normalizeCollider(input, context) {
- knownKeys(input, COLLIDER_FIELDS, 'cloth collider');
+function existingNode(nodeId, context, label) {
+ if (typeof nodeId !== 'string' || !context.recipeNodes.has(nodeId)) {
+ throw new RangeError(`${label} node was not found: ${String(nodeId).slice(0, 64)}.`);
+ }
+ return nodeId;
+}
+
+function normalizeMovingCollider(input, context) {
+ knownKeys(input, MOVING_COLLIDER_FIELDS, 'cloth moving collider');
+ const shape = input.shape ?? 'ball';
+ if (!MOVING_SHAPES.includes(shape)) {
+ throw new RangeError(`Cloth moving collider shape must be one of ${MOVING_SHAPES.join(', ')}.`);
+ }
+ if ((shape === 'capsule') !== (input.to !== undefined)) {
+ throw new RangeError('A capsule collider needs to (the node its other end rides on); a ball takes no to.');
+ }
+ const collider = {
+ attach: existingNode(input.attach, context, 'Cloth collider attach'), shape,
+ radius: finiteNumber(input.radius, 'Cloth collider radius', MIN_MOVING_RADIUS, MAX_MOVING_RADIUS),
+ };
+ if (input.offset !== undefined) collider.offset = vectorOfThree(input.offset, 'Cloth collider offset', OFFSET_LIMIT);
+ if (shape === 'capsule') {
+ collider.to = existingNode(input.to, context, 'Cloth collider to');
+ if (input.toOffset !== undefined) collider.toOffset = vectorOfThree(input.toOffset, 'Cloth collider toOffset', OFFSET_LIMIT);
+ } else if (input.toOffset !== undefined) {
+ throw new RangeError('A ball collider takes no toOffset.');
+ }
+ return collider;
+}
+
+function normalizeFittedCollider(input, recipe) {
+ knownKeys(input, FITTED_COLLIDER_FIELDS, 'cloth fitted collider');
+ const armature = (recipe.armatures ?? []).find(candidate => candidate.id === input.armature);
+ if (!armature) {
+ throw new RangeError(`Cloth collider armature was not found: ${JSON.stringify(String(input.armature).slice(0, 48))}. Add it to the recipe armatures.`);
+ }
+ const collider = { armature: armature.id };
+ if (input.radiusFraction !== undefined) collider.radiusFraction = finiteNumber(input.radiusFraction, 'Cloth collider radiusFraction', 0.02, 0.5);
+ if (input.exclude !== undefined) {
+ const names = new Set(armature.bones.map(bone => bone.name));
+ collider.exclude = [...new Set(boundedArray(input.exclude, MAX_MOVING_COLLIDERS, 'Cloth collider exclude'))];
+ for (const name of collider.exclude) {
+ if (!names.has(name)) throw new RangeError(`Cloth collider exclude names a bone that ${armature.id} does not have: ${JSON.stringify(String(name).slice(0, 48))}.`);
+ }
+ }
+ return collider;
+}
+
+function normalizeCollider(input, context, recipe) {
+ if (input !== null && typeof input === 'object' && Object.hasOwn(input, 'attach')) {
+ return normalizeMovingCollider(input, context);
+ }
+ if (input !== null && typeof input === 'object' && Object.hasOwn(input, 'armature')) {
+ return normalizeFittedCollider(input, recipe);
+ }
+ knownKeys(input, FIXED_COLLIDER_FIELDS, 'cloth collider');
rootNodeWithGeometry(input.node, context.recipeNodes, context.claimedNodes, context.motionNodeIds, context.physicsNodeIds, 'Cloth collider');
const shape = input.shape ?? 'box';
if (!COLLIDER_SHAPES.includes(shape)) {
@@ -60,7 +141,13 @@ export function normalizeAgentCloth(input, recipe) {
if (input.gravity !== undefined) result.gravity = vectorOfThree(input.gravity, 'Cloth gravity', 1000);
if (input.wind !== undefined) result.wind = vectorOfThree(input.wind, 'Cloth wind', 100);
if (input.colliders !== undefined) {
- result.colliders = boundedArray(input.colliders, MAX_COLLIDERS, 'Cloth colliders').map(collider => normalizeCollider(collider, context));
+ const entries = boundedArray(input.colliders, MAX_COLLIDERS + MAX_MOVING_COLLIDERS, 'Cloth colliders');
+ boundedArray(entries.filter(entry => !Object.hasOwn(entry ?? {}, 'attach') && !Object.hasOwn(entry ?? {}, 'armature')), MAX_COLLIDERS, 'Cloth colliders on fixed nodes');
+ result.colliders = entries.map(collider => normalizeCollider(collider, context, recipe));
+ const movingCount = movingColliderSpecs(result, recipe).length;
+ if (movingCount > MAX_MOVING_COLLIDERS) {
+ throw new RangeError(`Cloth moving colliders are limited to ${MAX_MOVING_COLLIDERS} balls and capsules, counting one per armature bone; this has ${movingCount}.`);
+ }
}
return result;
}
@@ -122,7 +209,134 @@ function pinnedParticles(localPositions, representatives, pin) {
return pinned;
}
-function bakeSheet(sheet, cloth, node, geometry, colliders, frameCount) {
+/**
+ * Balls and capsules that ride on nodes, as plain specs: a ball is { node, offset, radius }, a capsule runs from
+ * { startNode, startOffset } to { endNode, endOffset }. A fitted armature expands to one capsule per bone, from its head to
+ * its tail, with the radius the ragdoll would give that bone. Offsets are in the owning node's own space.
+ */
+export function movingColliderSpecs(cloth, recipe) {
+ const nodesById = new Map(recipe.nodes.map(node => [node.id, node]));
+ const specs = [];
+ for (const collider of cloth.colliders ?? []) {
+ if (collider.attach !== undefined) {
+ const zero = [0, 0, 0];
+ specs.push(collider.shape === 'ball'
+ ? { kind: 'ball', node: collider.attach, offset: collider.offset ?? zero, radius: collider.radius }
+ : { kind: 'capsule', startNode: collider.attach, startOffset: collider.offset ?? zero, endNode: collider.to, endOffset: collider.toOffset ?? zero, radius: collider.radius });
+ } else if (collider.armature !== undefined) {
+ specs.push(...armatureCapsuleSpecs(collider, recipe, nodesById));
+ }
+ }
+ return specs;
+}
+
+function armatureCapsuleSpecs(collider, recipe, nodesById) {
+ const armature = recipe.armatures.find(candidate => candidate.id === collider.armature);
+ const armatureWorld = restWorldMatrix(armature.id, nodesById);
+ const tails = boneTails(armature);
+ const excluded = new Set(collider.exclude ?? []);
+ const specs = [];
+ armature.bones.forEach((bone, index) => {
+ if (excluded.has(bone.name)) return;
+ const boneId = boneNodeId(armature, bone.name);
+ const boneWorld = restWorldMatrix(boneId, nodesById);
+ const head = vec3.transformMat4(vec3.create(), [0, 0, 0], boneWorld);
+ const tail = vec3.transformMat4(vec3.create(), tails[index], armatureWorld);
+ const length = vec3.distance(head, tail);
+ if (length < MIN_BONE_LENGTH) return;
+ const tailInBone = vec3.transformMat4(vec3.create(), tail, mat4.invert(mat4.create(), boneWorld));
+ specs.push({
+ kind: 'capsule', startNode: boneId, startOffset: [0, 0, 0], endNode: boneId, endOffset: Array.from(tailInBone),
+ radius: length * (collider.radiusFraction ?? RADIUS_OF_LENGTH),
+ });
+ });
+ return specs;
+}
+
+// World matrices of recipe nodes at a time: the recipe's local transforms with the motion tracks laid over them.
+function createNodePoses(recipe, motionSampler) {
+ const nodesById = new Map(recipe.nodes.map(node => [node.id, node]));
+ return function worldMatricesAt(time) {
+ const patches = motionSampler ? motionSampler.sample(time).nodes : NO_PATCHES;
+ const worlds = new Map();
+ const worldOf = nodeId => {
+ let world = worlds.get(nodeId);
+ if (!world) {
+ const node = nodesById.get(nodeId);
+ const patch = patches.get(nodeId);
+ world = mat4.fromRotationTranslationScale(mat4.create(), patch?.rotation ?? node.rotation, patch?.translation ?? node.translation, patch?.scale ?? node.scale);
+ if (node.parent !== null) mat4.multiply(world, worldOf(node.parent), world);
+ worlds.set(nodeId, world);
+ }
+ return world;
+ };
+ return worldOf;
+ };
+}
+
+// Time of each solver substep after the first frame, so the same frame always meets the same colliders and anchors.
+function substepTimes(frameCount) {
+ const times = [];
+ for (let frame = 1; frame < frameCount; frame++) {
+ for (let substep = 1; substep <= CLOTH_LIMITS.substeps; substep++) {
+ times.push((frame - 1 + substep / CLOTH_LIMITS.substeps) / FRAMES_PER_SECOND);
+ }
+ }
+ return times;
+}
+
+// Every moving collider at every substep as a capsule (a ball has both ends at its centre): start, end, radius.
+function sampleColliderTrack(specs, worldMatricesAt, times) {
+ const track = new Float64Array(times.length * specs.length * 7);
+ const point = vec3.create();
+ const place = (index, worldOf, nodeId, offset) => {
+ vec3.transformMat4(point, offset, worldOf(nodeId));
+ track.set(point, index);
+ };
+ times.forEach((time, step) => {
+ const worldOf = worldMatricesAt(time);
+ specs.forEach((spec, collider) => {
+ const base = (step * specs.length + collider) * 7;
+ const ball = spec.kind === 'ball';
+ place(base, worldOf, ball ? spec.node : spec.startNode, ball ? spec.offset : spec.startOffset);
+ place(base + 3, worldOf, ball ? spec.node : spec.endNode, ball ? spec.offset : spec.endOffset);
+ track[base + 6] = spec.radius;
+ });
+ });
+ return track;
+}
+
+// Where the pinned particles go at every substep: their rest offset in the node's space carried by the node's pose.
+function sampleAnchorTrack(pinTo, particles, worldPositions, worldMatricesAt, times) {
+ const toNode = mat4.invert(mat4.create(), worldMatricesAt(0)(pinTo.node));
+ const offsets = particles.map(particle => vec3.transformMat4(vec3.create(), worldPositions.subarray(particle * 3, particle * 3 + 3), toNode));
+ const track = new Float64Array(times.length * particles.length * 3);
+ const target = vec3.create();
+ times.forEach((time, step) => {
+ const matrix = worldMatricesAt(time)(pinTo.node);
+ offsets.forEach((offset, anchor) => {
+ vec3.transformMat4(target, offset, matrix);
+ track.set(target, (step * particles.length + anchor) * 3);
+ });
+ });
+ return track;
+}
+
+function createMovingBodies(sheet, pinned, worldPositions, movingSetup, frameCount) {
+ const { specs, worldMatricesAt } = movingSetup;
+ const times = substepTimes(frameCount);
+ movingSetup.colliderTrack ??= sampleColliderTrack(specs, worldMatricesAt, times);
+ const anchorParticles = Uint32Array.from(sheet.pinTo ? pinned : []);
+ return {
+ anchorParticles,
+ anchorWeights: new Float64Array(anchorParticles.length).fill(sheet.pinTo?.weight ?? 1),
+ anchorTrack: sheet.pinTo ? sampleAnchorTrack(sheet.pinTo, pinned, worldPositions, worldMatricesAt, times) : new Float64Array(0),
+ colliderCount: specs.length,
+ colliderTrack: movingSetup.colliderTrack,
+ };
+}
+
+function bakeSheet(sheet, cloth, node, geometry, colliders, frameCount, movingSetup) {
const welded = weldVertices(geometry.positions, geometry.indices);
const matrix = nodeMatrix(node);
const worldPositions = new Float64Array(welded.representatives.length * 3);
@@ -134,8 +348,11 @@ function bakeSheet(sheet, cloth, node, geometry, colliders, frameCount) {
}
worldPositions.set(world, particle * 3);
});
+ const pinned = pinnedParticles(geometry.positions, welded.representatives, sheet.pin);
+ const needsMoving = Boolean(movingSetup && (sheet.pinTo || movingSetup.specs.length));
+ const moving = needsMoving ? createMovingBodies(sheet, pinned, worldPositions, movingSetup, frameCount) : null;
const recording = Object.freeze({ ...runKernel('cloth', [worldPositions, welded.triangles, {
- pinned: pinnedParticles(geometry.positions, welded.representatives, sheet.pin),
+ pinned: sheet.pinTo ? [] : pinned, moving,
gravity: cloth.gravity, wind: cloth.wind, stiffness: sheet.stiffness, bend: sheet.bend,
density: sheet.density, damping: sheet.damping, friction: sheet.friction, thickness: sheet.thickness,
colliders, frameCount, framesPerSecond: FRAMES_PER_SECOND,
@@ -181,13 +398,16 @@ function sheetReport(baked, node, sheet) {
* Bake the cloth section. The result is a pure function of time: `sample(t)` returns the deformed geometry of each
* sheet node (null at time zero, where the sheet is at rest), and a seek never runs the solver again.
*/
-export function bakeAgentCloth(cloth, recipe, geometries) {
+export function bakeAgentCloth(cloth, recipe, geometries, motionSampler = null) {
const nodes = new Map(recipe.nodes.map(node => [node.id, node]));
const frameCount = Math.round(cloth.duration * FRAMES_PER_SECOND) + 1;
- const colliders = (cloth.colliders ?? []).map(collider => colliderFor(collider, nodes.get(collider.node), geometries.get(nodes.get(collider.node).geometry)));
+ const specs = movingColliderSpecs(cloth, recipe);
+ const usesMotion = specs.length > 0 || cloth.sheets.some(sheet => sheet.pinTo);
+ const movingSetup = usesMotion ? { specs, worldMatricesAt: createNodePoses(recipe, motionSampler) } : null;
+ const colliders = (cloth.colliders ?? []).filter(collider => collider.node !== undefined).map(collider => colliderFor(collider, nodes.get(collider.node), geometries.get(nodes.get(collider.node).geometry)));
const baked = new Map(cloth.sheets.map(sheet => {
const node = nodes.get(sheet.node);
- return [sheet.node, bakeSheet(sheet, cloth, node, geometries.get(node.geometry), colliders, frameCount)];
+ return [sheet.node, bakeSheet(sheet, cloth, node, geometries.get(node.geometry), colliders, frameCount, movingSetup)];
}));
let reportCache = null;
return Object.freeze({
diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.js
index e33dfedb..5520b944 100644
--- a/src/agent-scene-capabilities.js
+++ b/src/agent-scene-capabilities.js
@@ -246,8 +246,8 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({
cloth: Object.freeze({
sheetGeometry: 'grid { segments 1-64 }: unit sheet in XY facing +Z, sized by node scale; any triangle mesh works',
defaults: Object.freeze({ stiffness: 0.9, bend: 0.1, density: 0.2, damping: 0.3, friction: 0.3, thickness: 0.01, colliderShape: 'box' }),
- notes: 'density kg/m2, damping 1/s, thickness m, wind m/s steady. Pin edges are of the local bounds. Colliders are fixed ball or box fits to geometry bounds. No self collision, no soft bodies. Sheets and colliders are root nodes with no motion track or physics body.',
- limits: Object.freeze({ maxSheets: 8, maxColliders: 16, maxDuration: 10, maxParticles: 5000, framesPerSecond: 60, substeps: 4, iterations: 8 }),
+ notes: 'density kg/m2, damping 1/s, thickness m, wind m/s steady. Pin edges are of the local bounds. Colliders { node, shape ball|box } are fixed fits to geometry bounds and, like sheets, root nodes with no motion track or physics body. Moving: { attach, shape ball|capsule, radius, offset, to, toOffset } or { armature, radiusFraction, exclude } (a capsule per bone). Sheet pinTo { node, weight } rides the pinned edges on a node. No self collision.',
+ limits: Object.freeze({ maxSheets: 8, maxColliders: 16, maxMovingColliders: 64, maxDuration: 10, maxParticles: 5000, framesPerSecond: 60, substeps: 4, iterations: 8 }),
}),
// Recipe particles: closed-form from seeded launch values, so any time is computed directly and a seek never replays.
particles: Object.freeze({
diff --git a/src/agent-scene.js b/src/agent-scene.js
index 5c1fb349..6a6e69e8 100644
--- a/src/agent-scene.js
+++ b/src/agent-scene.js
@@ -1088,7 +1088,7 @@ export function createAgentScene(input, inputLimits = {}) {
stagedState.skinStages = createSkinStages(skinBindings);
stagedState.motionSampler = recipe.motion ? agentSceneModule('motion').compileAgentMotion(recipe.motion, recipe) : null;
stagedState.physicsSampler = stagePhysics(recipe, geometryRecords);
- stagedState.clothSampler = stageCloth(recipe, geometryRecords);
+ stagedState.clothSampler = stageCloth(recipe, geometryRecords, stagedState.motionSampler);
stagedState.particleSampler = stageParticles(recipe, geometryRecords);
const animated = Boolean(stagedState.motionSampler || stagedState.physicsSampler || stagedState.clothSampler || stagedState.particleSampler);
stagedState.poseGraph = animated ? compile(recipe, geometries, localBounds, limits) : null;
@@ -1209,16 +1209,17 @@ export function createAgentScene(input, inputLimits = {}) {
}
// Same rule as physics: an unchanged cloth section on unchanged geometry and nodes reuses the last bake.
- function stageCloth(recipe, geometryRecords) {
+ function stageCloth(recipe, geometryRecords, motionSampler) {
if (!recipe.cloth) {
return null;
}
const involved = new Set([...recipe.cloth.sheets, ...(recipe.cloth.colliders ?? [])].map(entry => entry.node));
const involvedNodes = recipe.nodes.filter(node => involved.has(node.id));
- const key = JSON.stringify([recipe.cloth, involvedNodes, involvedNodes.map(node => geometryRecords.get(node.geometry).signature)]);
+ const followsMotion = recipe.cloth.sheets.some(sheet => sheet.pinTo) || (recipe.cloth.colliders ?? []).some(collider => collider.node === undefined);
+ const key = JSON.stringify([recipe.cloth, involvedNodes, involvedNodes.map(node => geometryRecords.get(node.geometry)?.signature), followsMotion ? [recipe.motion, recipe.nodes, recipe.armatures] : null]);
if (clothBake?.key !== key) {
const geometries = new Map([...geometryRecords].map(([id, record]) => [id, record.geometry]));
- clothBake = { key, sampler: agentSceneModule('cloth').bakeAgentCloth(recipe.cloth, recipe, geometries) };
+ clothBake = { key, sampler: agentSceneModule('cloth').bakeAgentCloth(recipe.cloth, recipe, geometries, motionSampler) };
}
return clothBake.sampler;
}
diff --git a/src/cloth.js b/src/cloth.js
index 8b0d9446..65fc77c8 100644
--- a/src/cloth.js
+++ b/src/cloth.js
@@ -199,6 +199,33 @@ function pushOutOfBall(point, ball, thickness, normal) {
return true;
}
+// A capsule is a ball whose centre slides to the closest point of its axis segment.
+const capsuleBall = { center: [0, 0, 0], radius: 0 };
+
+function pushOutOfCapsule(point, capsule, thickness, normal) {
+ const { start, end } = capsule;
+ const axisX = end[0] - start[0];
+ const axisY = end[1] - start[1];
+ const axisZ = end[2] - start[2];
+ const lengthSquared = axisX * axisX + axisY * axisY + axisZ * axisZ;
+ const along = (point[0] - start[0]) * axisX + (point[1] - start[1]) * axisY + (point[2] - start[2]) * axisZ;
+ const fraction = lengthSquared > 0 ? Math.min(Math.max(along / lengthSquared, 0), 1) : 0;
+ const centerX = start[0] + axisX * fraction;
+ const centerY = start[1] + axisY * fraction;
+ const centerZ = start[2] + axisZ * fraction;
+ const reach = capsule.radius + thickness;
+ const offsetX = point[0] - centerX;
+ const offsetY = point[1] - centerY;
+ const offsetZ = point[2] - centerZ;
+ // Most particles are far from most capsules, so leave before the square root and the shared push.
+ if (offsetX * offsetX + offsetY * offsetY + offsetZ * offsetZ >= reach * reach) return false;
+ capsuleBall.center[0] = centerX;
+ capsuleBall.center[1] = centerY;
+ capsuleBall.center[2] = centerZ;
+ capsuleBall.radius = capsule.radius;
+ return pushOutOfBall(point, capsuleBall, thickness, normal);
+}
+
function pushOutOfBox(point, box, thickness, normal) {
const { center, axes, halfExtents } = box;
const offset = [point[0] - center[0], point[1] - center[1], point[2] - center[2]];
@@ -234,6 +261,8 @@ function pushOutOfBox(point, box, thickness, normal) {
return true;
}
+const PUSH_OUT = { ball: pushOutOfBall, capsule: pushOutOfCapsule, box: pushOutOfBox };
+
function collide(state, previous, colliders, thickness, friction) {
const { positions, inverseMasses, particleCount } = state;
const point = [0, 0, 0];
@@ -245,7 +274,7 @@ function collide(state, previous, colliders, thickness, friction) {
point[1] = positions[offset + 1];
point[2] = positions[offset + 2];
for (const collider of colliders) {
- const touched = collider.kind === 'ball' ? pushOutOfBall(point, collider, thickness, normal) : pushOutOfBox(point, collider, thickness, normal);
+ const touched = PUSH_OUT[collider.kind](point, collider, thickness, normal);
if (!touched) continue;
// Friction removes part of the sideways travel this substep, so cloth drags over a surface instead of skating.
const travel = [point[0] - previous[offset], point[1] - previous[offset + 1], point[2] - previous[offset + 2]];
@@ -260,6 +289,30 @@ function collide(state, previous, colliders, thickness, friction) {
}
}
+const MOVING_COLLIDER_NUMBERS = 7;
+
+function movingColliders(track, offset, count) {
+ const colliders = [];
+ for (let collider = 0; collider < count; collider++) {
+ const base = offset + collider * MOVING_COLLIDER_NUMBERS;
+ colliders.push({ kind: 'capsule', start: track.subarray(base, base + 3), end: track.subarray(base + 3, base + 6), radius: track[base + 6] });
+ }
+ return colliders;
+}
+
+// Pulls anchored particles toward where their node is now. A weight of 1 holds the particle on the target exactly.
+function followAnchors(positions, moving, targets, softOnly) {
+ const { anchorParticles, anchorWeights } = moving;
+ for (let anchor = 0; anchor < anchorParticles.length; anchor++) {
+ const weight = anchorWeights[anchor];
+ if (softOnly && weight >= 1) continue;
+ for (let axis = 0; axis < 3; axis++) {
+ const index = anchorParticles[anchor] * 3 + axis;
+ positions[index] += (targets[anchor * 3 + axis] - positions[index]) * weight;
+ }
+ }
+}
+
function checkWork(particleCount, constraintCount, triangleCount, colliderCount, frameCount) {
const work = frameCount * CLOTH_LIMITS.substeps * (CLOTH_LIMITS.iterations * constraintCount + triangleCount + particleCount * (colliderCount + 1));
if (particleCount > CLOTH_LIMITS.maxParticles) {
@@ -276,15 +329,21 @@ function checkWork(particleCount, constraintCount, triangleCount, colliderCount,
/**
* Simulate one sheet. `positions` are world-space rest positions (3 numbers per particle), `triangles` index them.
* Options: pinned (particle indices that stay put), gravity, wind (m/s), stiffness and bend (0 to 1), density (kg/m2),
- * damping (1/s), friction (0 to 1), thickness (m), colliders ({ kind: 'ball', center, radius } or
- * { kind: 'box', center, axes, halfExtents }), frameCount and framesPerSecond.
+ * damping (1/s), friction (0 to 1), thickness (m), colliders ({ kind: 'ball', center, radius },
+ * { kind: 'capsule', start, end, radius } or { kind: 'box', center, axes, halfExtents }), frameCount and framesPerSecond.
+ * `moving` follows a body that moves with time, sampled ahead as plain numbers so it can cross to a worker. One entry per
+ * substep (frame 1 substep 0 first): anchorTrack holds each anchor's target (3 numbers), colliderTrack each moving
+ * collider as a capsule (start 3, end 3, radius 1; a ball has start equal to end). A particle in anchorParticles with
+ * weight 1 sits on its target; a lower weight pulls it there by that fraction each iteration.
+ * { anchorParticles, anchorWeights, anchorTrack, colliderCount, colliderTrack }
* Returns the recorded frames: Float32Array of frameCount * particleCount * 3.
*/
export function bakeCloth(positions, triangles, options) {
const particleCount = positions.length / 3;
const colliders = options.colliders ?? [];
+ const moving = options.moving ?? null;
const constraints = buildConstraints(positions, triangles, particleCount, options.bend ?? 0.1, options.stiffness ?? 0.9);
- checkWork(particleCount, constraints.count, triangles.length / 3, colliders.length, options.frameCount);
+ checkWork(particleCount, constraints.count, triangles.length / 3, colliders.length + (moving?.colliderCount ?? 0), options.frameCount);
const gravity = options.gravity ?? GRAVITY_DEFAULT;
const wind = options.wind ?? [0, 0, 0];
const density = options.density ?? 0.2;
@@ -300,6 +359,11 @@ export function bakeCloth(positions, triangles, options) {
for (const particle of options.pinned ?? []) {
inverseMasses[particle] = 0;
}
+ const anchorStride = (moving?.anchorParticles.length ?? 0) * 3;
+ const colliderStride = (moving?.colliderCount ?? 0) * MOVING_COLLIDER_NUMBERS;
+ moving?.anchorParticles.forEach((particle, anchor) => {
+ if (moving.anchorWeights[anchor] >= 1) inverseMasses[particle] = 0;
+ });
const state = {
particleCount, inverseMasses, positions: Float64Array.from(positions),
velocities: new Float64Array(positions.length), windScratch: new Float64Array(positions.length),
@@ -311,6 +375,14 @@ export function bakeCloth(positions, triangles, options) {
for (let substep = 0; substep < CLOTH_LIMITS.substeps; substep++) {
if (hasWind) applyWind(state, wind, areas, triangles, substepSeconds, density);
previous.set(state.positions);
+ let activeColliders = colliders;
+ let anchorTargets = null;
+ if (moving) {
+ const substepIndex = (frame - 1) * CLOTH_LIMITS.substeps + substep;
+ anchorTargets = moving.anchorTrack.subarray(substepIndex * anchorStride, (substepIndex + 1) * anchorStride);
+ activeColliders = colliders.concat(movingColliders(moving.colliderTrack, substepIndex * colliderStride, moving.colliderCount));
+ followAnchors(state.positions, moving, anchorTargets, false);
+ }
for (let particle = 0; particle < particleCount; particle++) {
if (inverseMasses[particle] === 0) continue;
for (let axis = 0; axis < 3; axis++) {
@@ -321,7 +393,8 @@ export function bakeCloth(positions, triangles, options) {
}
for (let iteration = 0; iteration < CLOTH_LIMITS.iterations; iteration++) {
solveDistances(state.positions, inverseMasses, constraints);
- collide(state, previous, colliders, thickness, friction);
+ if (moving) followAnchors(state.positions, moving, anchorTargets, true);
+ collide(state, previous, activeColliders, thickness, friction);
}
for (let index = 0; index < positions.length; index++) {
state.velocities[index] = (state.positions[index] - previous[index]) / substepSeconds * dampingFactor;
diff --git a/tests/cloth-moving.test.js b/tests/cloth-moving.test.js
new file mode 100644
index 00000000..945fb7a7
--- /dev/null
+++ b/tests/cloth-moving.test.js
@@ -0,0 +1,179 @@
+import './support/load-agent-scene-modules.mjs';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mat4, vec3 } from 'gl-matrix';
+import { createAgentScene } from '../src/agent-scene.js';
+import { bakeCloth } from '../src/cloth.js';
+import { armatureNodes } from '../src/rig.js';
+import { compileAgentMotion } from '../src/agent-motion.js';
+import { CAPE, CAPE_THICKNESS, WALK_SECONDS, walkingCapeRecipe } from './support/walking-cape.mjs';
+
+const FRAMES_PER_SECOND = 60;
+const PENETRATION_TOLERANCE = 0.002;
+
+// World matrices of the walker's nodes at a time, composed here from the motion sampler so the check does not lean on the cloth module's pose code.
+function createPoser(recipe) {
+ const exported = createAgentScene(recipe).exportRecipe();
+ const nodes = [...exported.armatures.flatMap(armatureNodes), ...exported.nodes];
+ const byId = new Map(nodes.map(node => [node.id, node]));
+ const sampler = compileAgentMotion(exported.motion, { ...exported, nodes });
+ return {
+ armature: exported.armatures[0],
+ worldAt(time) {
+ const patches = time === null ? new Map() : sampler.sample(time).nodes;
+ const worlds = new Map();
+ const worldOf = nodeId => {
+ if (!worlds.has(nodeId)) {
+ const node = byId.get(nodeId);
+ const patch = patches.get(nodeId);
+ const local = mat4.fromRotationTranslationScale(mat4.create(), patch?.rotation ?? node.rotation, patch?.translation ?? node.translation, patch?.scale ?? node.scale);
+ worlds.set(nodeId, node.parent === null ? local : mat4.multiply(local, worldOf(node.parent), local));
+ }
+ return worlds.get(nodeId);
+ };
+ return worldOf;
+ },
+ };
+}
+
+// One capsule per bone, head to tail, radius a fifth of the bone length as the ragdoll fits it.
+function boneCapsules(poser, time) {
+ const bones = poser.armature.bones;
+ const restWorld = poser.worldAt(null);
+ const posedWorld = poser.worldAt(time);
+ const origin = [0, 0, 0];
+ return bones.flatMap(bone => {
+ const children = bones.filter(candidate => candidate.parent === bone.name);
+ const tailInArmature = bone.tail ?? (children.length
+ ? [0, 1, 2].map(axis => children.reduce((total, child) => total + child.head[axis], 0) / children.length)
+ : null);
+ if (!tailInArmature) return [];
+ const head = vec3.transformMat4(vec3.create(), origin, restWorld(bone.name));
+ const tail = vec3.transformMat4(vec3.create(), tailInArmature, restWorld(poser.armature.id));
+ const tailInBone = vec3.transformMat4(vec3.create(), tail, mat4.invert(mat4.create(), restWorld(bone.name)));
+ return [{
+ name: bone.name, radius: vec3.distance(head, tail) * 0.2,
+ start: vec3.transformMat4(vec3.create(), origin, posedWorld(bone.name)),
+ end: vec3.transformMat4(vec3.create(), tailInBone, posedWorld(bone.name)),
+ }];
+ });
+}
+
+function distanceToSegment(point, start, end) {
+ const axis = vec3.subtract(vec3.create(), end, start);
+ const along = vec3.dot(vec3.subtract(vec3.create(), point, start), axis) / Math.max(vec3.dot(axis, axis), 1e-12);
+ const closest = vec3.scaleAndAdd(vec3.create(), start, axis, Math.min(Math.max(along, 0), 1));
+ return vec3.distance(point, closest);
+}
+
+function capeWorldVertices(scene, nodeId = 'cape') {
+ const part = scene.parts.find(candidate => candidate.name === nodeId);
+ const positions = part.geometry.positions;
+ const matrix = part.matrix;
+ const world = [];
+ for (let vertex = 0; vertex < positions.length; vertex += 3) {
+ world.push(vec3.transformMat4(vec3.create(), [positions[vertex], positions[vertex + 1], positions[vertex + 2]], matrix));
+ }
+ return world;
+}
+
+// How far inside the limb capsules (past the cloth thickness) any cape vertex gets in the walk, and how far the cape travels.
+function walkMeasure(cloth) {
+ const recipe = walkingCapeRecipe(cloth);
+ const scene = createAgentScene(recipe);
+ const poser = createPoser(recipe);
+ const rest = capeWorldVertices(scene);
+ let deepest = Infinity;
+ let travelled = 0;
+ for (let frame = 1; frame <= WALK_SECONDS * FRAMES_PER_SECOND; frame += 3) {
+ scene.sampleMotion(frame / FRAMES_PER_SECOND);
+ const capsules = boneCapsules(poser, frame / FRAMES_PER_SECOND);
+ const vertices = capeWorldVertices(scene);
+ for (const vertex of vertices) {
+ for (const capsule of capsules) {
+ deepest = Math.min(deepest, distanceToSegment(vertex, capsule.start, capsule.end) - capsule.radius - CAPE_THICKNESS);
+ }
+ }
+ travelled = Math.max(travelled, vec3.distance(vertices[vertices.length - 1], rest[rest.length - 1]));
+ }
+ return { deepest, travelled };
+}
+
+test('a cape pinned to a walking humanoid never enters the limb capsules in a 5 second walk', () => {
+ const { deepest, travelled } = walkMeasure(CAPE);
+ assert.ok(deepest > -PENETRATION_TOLERANCE, `a vertex sits ${(-deepest * 1000).toFixed(2)} mm inside a capsule`);
+ assert.ok(travelled > 3, `the cape rode the walker ${travelled.toFixed(2)} m forward`);
+ const { colliders, ...withoutColliders } = CAPE;
+ const free = walkMeasure(withoutColliders);
+ assert.ok(free.deepest < -0.02, `the same cape without colliders is only ${(-free.deepest * 1000).toFixed(1)} mm inside, so the check proves nothing`);
+});
+
+test('the pinned top edge stays on the chest while the walker moves', () => {
+ const scene = createAgentScene(walkingCapeRecipe(CAPE));
+ const poser = createPoser(walkingCapeRecipe(CAPE));
+ const offsets = [];
+ for (const time of [0, 1.7, 4.2]) {
+ scene.sampleMotion(time);
+ const chest = vec3.transformMat4(vec3.create(), [0, 0, 0], poser.worldAt(time)('chest'));
+ const topCorner = capeWorldVertices(scene).reduce((best, vertex) => (vertex[1] > best[1] ? vertex : best));
+ offsets.push(vec3.distance(chest, topCorner));
+ }
+ assert.ok(Math.max(...offsets) - Math.min(...offsets) < 0.2, `top edge drifted: ${offsets.map(offset => offset.toFixed(3))}`);
+});
+
+test('seeking to a time gives the cloth that playing to it gives', () => {
+ const played = createAgentScene(walkingCapeRecipe(CAPE));
+ for (let time = 0; time <= 3.01; time += 0.5) played.sampleMotion(time);
+ const playedVertices = capeWorldVertices(played);
+ const sought = createAgentScene(walkingCapeRecipe(CAPE));
+ sought.sampleMotion(4.4);
+ sought.sampleMotion(3);
+ assert.deepEqual(capeWorldVertices(sought), playedVertices);
+ const fresh = createAgentScene(walkingCapeRecipe(CAPE));
+ fresh.sampleMotion(3);
+ assert.deepEqual(capeWorldVertices(fresh), playedVertices, 'a second scene from the same recipe bakes the same cloth');
+});
+
+test('a ball and a capsule on nodes follow their node and push cloth aside', () => {
+ const recipe = {
+ format: '67js.scene', schemaVersion: 1,
+ geometries: [{ id: 'sheet', type: 'grid', segments: 20 }],
+ materials: [{ id: 'fabric', doubleSided: true }],
+ nodes: [
+ { id: 'cloth', geometry: 'sheet', material: 'fabric', translation: [0, 1, 0], rotation: [-0.7071068, 0, 0, 0.7071068], scale: [2, 2, 1] },
+ { id: 'hand', translation: [0, 0.5, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1], parent: null },
+ { id: 'fingertip', translation: [0.3, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1], parent: 'hand' },
+ ],
+ motion: { duration: 2, loop: false, tracks: [{ kind: 'node', id: 'hand', property: 'translation', interpolation: 'LINEAR', keyframes: [{ time: 0, value: [0, 0.5, 0] }, { time: 2, value: [0, 1.2, 0] }] }] },
+ cloth: { duration: 2, sheets: [{ node: 'cloth', thickness: 0.01 }], colliders: [{ attach: 'hand', shape: 'capsule', to: 'fingertip', radius: 0.15 }] },
+ };
+ const scene = createAgentScene(recipe);
+ scene.sampleMotion(2);
+ const raised = capeWorldVertices(scene, 'cloth');
+ const highest = Math.max(...raised.map(vertex => vertex[1]));
+ assert.ok(highest > 1.3, `cloth lifted to ${highest.toFixed(2)} m by the rising capsule`);
+});
+
+test('a soft pin pulls the particle less than a hard pin', () => {
+ const positions = Float64Array.from([0, 0, 0, 1, 0, 0]);
+ const triangles = Uint32Array.from([0, 1, 0]);
+ const track = Float64Array.from({ length: 4 * 60 * 3 }, (_, index) => (index % 3 === 1 ? 5 : 0));
+ const bake = weight => bakeCloth(positions, triangles, {
+ frameCount: 61, gravity: [0, 0, 0],
+ moving: { anchorParticles: Uint32Array.of(0), anchorWeights: Float64Array.of(weight), anchorTrack: track, colliderCount: 0, colliderTrack: new Float64Array(0) },
+ });
+ const hardEnd = bake(1).frames.subarray(60 * 6, 60 * 6 + 3);
+ const softEnd = bake(0.2).frames.subarray(60 * 6, 60 * 6 + 3);
+ assert.equal(hardEnd[1], 5);
+ assert.ok(softEnd[1] > 4 && softEnd[1] < 5.0001, `soft pin reached ${softEnd[1]}`);
+});
+
+test('recipe checks refuse bad moving colliders and pins', () => {
+ const bad = cloth => () => createAgentScene(walkingCapeRecipe({ ...CAPE, ...cloth }));
+ assert.throws(bad({ colliders: [{ attach: 'chest', shape: 'capsule', radius: 0.1 }] }), /capsule collider needs to/);
+ assert.throws(bad({ colliders: [{ attach: 'nowhere', radius: 0.1 }] }), /not found/);
+ assert.throws(bad({ colliders: [{ armature: 'rig', exclude: ['tail'] }] }), /does not have/);
+ assert.throws(bad({ colliders: [{ armature: 'ghost' }] }), /armature was not found/);
+ assert.throws(bad({ sheets: [{ node: 'cape', pinTo: { node: 'chest' } }] }), /needs pin too/);
+ assert.throws(bad({ sheets: [{ node: 'cape', pin: ['top'], pinTo: { node: 'chest', weight: 0 } }] }), /weight/);
+});
diff --git a/tests/support/walking-cape.mjs b/tests/support/walking-cape.mjs
new file mode 100644
index 00000000..e6c4933c
--- /dev/null
+++ b/tests/support/walking-cape.mjs
@@ -0,0 +1,28 @@
+import { walkerRecipe } from '../../bench/agent-modeling/walker.mjs';
+
+export const WALK_SECONDS = 5;
+const CYCLE_SECONDS = 1;
+export const CAPE_THICKNESS = 0.01;
+
+// The reference walker, walking forward for five seconds: its one second cycle repeated and the whole rig moved on.
+export function walkingCapeRecipe(cloth) {
+ const recipe = walkerRecipe();
+ const cycles = WALK_SECONDS / CYCLE_SECONDS;
+ const repeated = keyframes => Array.from({ length: cycles }, (_, cycle) => keyframes.map(keyframe => ({ ...keyframe, time: keyframe.time + cycle * CYCLE_SECONDS })))
+ .flat()
+ .filter((keyframe, index, all) => index === 0 || keyframe.time > all[index - 1].time);
+ const tracks = recipe.motion.tracks.map(track => ({ ...track, keyframes: repeated(track.keyframes) }));
+ tracks.push({ kind: 'node', id: 'rig', property: 'translation', interpolation: 'LINEAR', keyframes: [{ time: 0, value: [0, 0, 0] }, { time: WALK_SECONDS, value: [0, 0, 5] }] });
+ recipe.motion = { duration: WALK_SECONDS, loop: false, tracks };
+ recipe.geometries.push({ id: 'cape-sheet', type: 'grid', segments: 24 });
+ recipe.materials.push({ id: 'cape-cloth', color: [0.7, 0.1, 0.1], doubleSided: true });
+ recipe.nodes.push({ id: 'cape', geometry: 'cape-sheet', material: 'cape-cloth', translation: [0, 1.05, -0.16], scale: [0.5, 0.7, 1] });
+ recipe.cloth = cloth;
+ return recipe;
+}
+
+export const CAPE = {
+ duration: WALK_SECONDS,
+ sheets: [{ node: 'cape', pin: ['top'], pinTo: { node: 'chest' }, thickness: CAPE_THICKNESS }],
+ colliders: [{ armature: 'rig' }],
+};