Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Call out the thickness behaviour change for cloth self collision, fix the size note, test the unchanged default (#696)

Nguyen Xuan Ancc0ccd2fac7b
diff --git a/changes/696-thin-cloth-layers.md b/changes/696-thin-cloth-layers.md
index e5218378..ec7a22fe 100644
--- a/changes/696-thin-cloth-layers.md
+++ b/changes/696-thin-cloth-layers.md
@@ -1 +1 @@
-- A cloth sheet with `selfCollision: true` and its own `thickness` stacks folded layers `2 x thickness` apart (never past half the shortest edge), so a flag dropped to the floor lies as a thin crumpled layer; sheets that set no thickness are unchanged (#696)
+- A cloth sheet with `selfCollision: true` now reads its own `thickness` as the contact radius (never past half the shortest edge), so a flag dropped to the floor lies as a thin crumpled layer. Behaviour change: a sheet that sets both `selfCollision: true` and `thickness` used to ignore the thickness (radius 0.9 of half the shortest edge) and now keeps layers `2 x thickness` apart, so its baked frames differ; pass `selfCollision: { radius }` to keep a fixed radius. Sheets that set no thickness keep the old radius (#696)
diff --git a/changes/696-thin-cloth-layers.size.md b/changes/696-thin-cloth-layers.size.md
index 5d3bb443..61bf5e59 100644
--- a/changes/696-thin-cloth-layers.size.md
+++ b/changes/696-thin-cloth-layers.size.md
@@ -1,3 +1,2 @@
-- entry:cloth: the self collision radius reads the sheet thickness, a four-line helper, so thin cloth can fold in layers 1 cm apart instead of about 4 cm.
-- tool-cost: the scene_capabilities cloth note gains nine words saying that thickness sets the self collision radius.
-- goal:agent-scene: 12 bytes of capability text tell agents that a sheet's thickness sets the self collision layer spacing, which they need to build a thin folded cloth.
+- entry:cloth: the self collision radius reads the sheet thickness, a four-line helper, so thin cloth can fold in layers 1 cm apart instead of about 4 cm (+19 bytes gzip).
+- goal:agent-scene: the scene_capabilities cloth note gains 33 bytes of text (nine words, 12 bytes gzip in entry:agent-scene) saying that thickness sets the self collision radius; no tool schema changed, so the tool cost gate reports no growth.
diff --git a/docs/physics.md b/docs/physics.md
index 0a93eecc..25723b1f 100644
--- a/docs/physics.md
+++ b/docs/physics.md
@@ -430,7 +430,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; a scene that sets no thickness keeps the old radius byte for byte (`tests/cloth-self-collision-thickness.test.js`). a spatial hash keeps it near linear, two particles joined by an edge are skipped, and a sheet over 2000 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; pass `selfCollision: { radius }` to keep a fixed radius. A scene that sets no thickness keeps the old radius (`tests/cloth-self-collision-thickness.test.js`). a spatial hash keeps it near linear, two particles joined by an edge are skipped, and a sheet over 2000 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.
- `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.
- 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.
- 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.
diff --git a/tests/cloth-self-collision-thickness.test.js b/tests/cloth-self-collision-thickness.test.js
index aa62ebc4..26b29720 100644
--- a/tests/cloth-self-collision-thickness.test.js
+++ b/tests/cloth-self-collision-thickness.test.js
@@ -51,3 +51,15 @@ test('a thickness beyond half the shortest edge is capped, so layers never fight
test('the thick-layer bake is deterministic', () => {
assert.equal(restingGap({ thickness: 0.01 }), restingGap({ thickness: 0.01 }));
});
+
+test('a sheet without a thickness rests exactly like an explicit radius of 0.9 x half the shortest edge', () => {
+ const byDefault = restingGap({});
+ const explicit = restingGap({ selfCollision: { radius: SPACING / 2 * 0.9 } });
+ assert.ok(Math.abs(byDefault - explicit) < 1e-6, `default ${byDefault} m against explicit ${explicit} m`);
+});
+
+test('a sheet that sets both selfCollision true and a thickness uses the thickness, unlike an explicit radius', () => {
+ const withThickness = restingGap({ thickness: 0.01 });
+ const explicitOld = restingGap({ thickness: 0.01, selfCollision: { radius: SPACING / 2 * 0.9 } });
+ assert.ok(explicitOld - withThickness > 0.02, `thickness layers ${withThickness} m, explicit old radius ${explicitOld} m`);
+});