3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Name the zero-length edge when cloth self collision fails (#2429)
Nguyen Xuan An18ab55b9bb6d
diff --git a/changes/2429.md b/changes/2429.mdnew file mode 100644index 00000000..635649a6--- /dev/null+++ b/changes/2429.md@@ -0,0 +1 @@+- Cloth self collision on a mesh with two vertices at one point names those vertices and says to weld them, instead of blaming a radius the caller never gave.diff --git a/docs/physics.md b/docs/physics.mdindex 8e9f50ae..53a35684 100644--- a/docs/physics.md+++ b/docs/physics.md@@ -547,7 +547,7 @@ A recipe `cloth` section records deformable sheets with a position-based solver- `{ "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 `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: true` makes 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's `thickness` when 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 both `selfCollision: true` and `thickness`: they used to ignore the thickness and now stack layers 2 x thickness apart, so their baked frames differ. The recipe takes only `true` or `false` there (an object fails with `expected boolean`); a fixed radius in metres is `selfCollision: { radius }` in the library call `createCloth` (`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. 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.+ - `selfCollision: true` makes 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's `thickness` when 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 both `selfCollision: true` and `thickness`: they used to ignore the thickness and now stack layers 2 x thickness apart, so their baked frames differ. The recipe takes only `true` or `false` there (an object fails with `expected boolean`); a fixed radius in metres is `selfCollision: { radius }` in the library call `createCloth` (`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. `bend` and `stiffness` outside 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), and `pressure` (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; set `pressure: 0` to 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 adds `bounce` times 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: lower `softBody.shape` for a looser body and lower the sheet's `stiffness` for a body that squashes further (the table below). `damping` is air drag on every particle, so a high `damping` also takes height off the bounce (with `damping: 0` and `bounce: 1` the 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 a `vertex_group` mesh edit; vertices of weight 0.5 or more are pinned, on their own or together with `pin`. An unknown name fails and lists the groups the mesh has.diff --git a/src/cloth.js b/src/cloth.jsindex 434f7f3b..77c9eeb0 100644--- a/src/cloth.js+++ b/src/cloth.js@@ -474,6 +474,14 @@ function checkUnit(value, field, maximum) {return value;}+// Self collision needs a radius above 0, so two vertices at one point have to be welded first.+function assertNoZeroLengthEdge(constraints) {+ for (let edge = 0; edge < constraints.stretchCount; edge++) {+ if (constraints.restLengths[edge] > 0) continue;+ throw new RangeError(`Cloth selfCollision: vertices ${constraints.firsts[edge]} and ${constraints.seconds[edge]} share one point; weld them.`);+ }+}+// Soft body and self collision terms, as two hooks the step calls: once per substep and once per iteration.function prepareExtras(options, positions, triangles, particleCount, constraints) {const softBody = options.softBody ?? null;@@ -500,6 +508,7 @@ function prepareExtras(options, positions, triangles, particleCount, constraintsif (particleCount > SELF_COLLISION_LIMITS.maxParticles) {throw new RangeError(`Cloth selfCollision handles ${SELF_COLLISION_LIMITS.maxParticles} particles at most; this sheet has ${particleCount}. Use a coarser grid or drop selfCollision.`);}+ assertNoZeroLengthEdge(constraints);const longest = maxSelfCollisionRadius(constraints);const radius = selfCollision === true ? defaultSelfCollisionRadius(longest, options.thickness) : selfCollision.radius;if (!(radius > 0 && radius <= longest)) {diff --git a/tests/cloth-input-checks.test.js b/tests/cloth-input-checks.test.jsindex deee8032..34c4ac2e 100644--- a/tests/cloth-input-checks.test.js+++ b/tests/cloth-input-checks.test.js@@ -30,3 +30,21 @@ test('createCloth names a triangle index that is not a particle instead of blamiassert.throws(() => createCloth(positions, Uint32Array.from([0, 1, 999])), /triangle 0 uses particle 999; the sheet has 4/);assert.throws(() => createCloth(positions, Uint32Array.from([0, 1, 2, 3])), /3 indices each/);});++test('createCloth names bend and stiffness for every value outside 0 to 1', () => {+ const { positions, triangles } = smallSheet();+ for (const option of ['bend', 'stiffness']) {+ for (const value of [Number.NaN, Infinity, -1, 5, 'x']) {+ assert.throws(() => createCloth(positions, triangles, { [option]: value }), new RegExp(`Cloth ${option} must be a number from 0 to 1`), `${option} ${value}`);+ }+ }+});++test('createCloth self collision names a zero-length edge instead of the radius', () => {+ const positions = Float32Array.from([0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 1, 1, 0, 1]);+ const triangles = Uint32Array.from([0, 2, 1, 1, 2, 3, 3, 4, 2]);+ for (const selfCollision of [true, { radius: 0.1 }]) {+ assert.throws(() => createCloth(positions, triangles, { selfCollision }), /vertices 3 and 4 share one point/);+ }+ assert.doesNotThrow(() => createCloth(positions, triangles, {}));+});