@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/animation/xstate-animation-meta.ts

@@ -16,20 +16,13 @@ import { z } from 'zod';
  * `meta.animation` is a loud Zod "unrecognized key" error, not a silently
  * ignored field (E1 AC: "Metadata contains no transition language").
  *
- * ## Deliberately out of scope: layers, additive blending, bone masks
+ * ## Native layered composition
  *
- * The spec asks for layer/weight/additive metadata "if retained" and bone
- * masks "if supported by the Three implementation" (§11 E1). Neither is
- * supported by the current Three-facing animation code: no bone-masking or
- * blend-compositing across layers exists (the former `AnimGraph` layers, now
- * removed by E5, never had it either, and rejected `blendMode`/`weight`/
- * `boneMask` at parse for exactly this reason — those fields had no runtime
- * reader anywhere in the engine). Per this repo's policy ("Do not author
- * schema fields that have no runtime reader" — CLAUDE.md), this module does
- * not declare fields for capabilities nothing reads. A single XState machine
- * drives one mixer's weight budget; multi-machine/multi-layer composition
- * (if ever added) is a distinct, future binding concern with its own reader,
- * not a dead field here.
+ * Parallel XState regions may drive independent named layers. Each layer can
+ * filter a clip to selected bone subtrees, scale its weight, and use normal
+ * override or Three's native additive blend mode. XState still owns all
+ * state/transition semantics; these fields only describe how the active
+ * state's native `AnimationAction`s are composed by the binding.
  *
  * ## Blend tree shape
  *
@@ -136,6 +129,48 @@ const AnimationCrossfadeMetaSchema = z
 
 export type AnimationCrossfadeMeta = z.infer<typeof AnimationCrossfadeMetaSchema>;
 
+const AnimationBoneMaskSchema = z
+  .object({
+    include: z
+      .array(z.string().min(1))
+      .min(1)
+      .optional()
+      .describe('Bone/object names whose complete descendant subtrees are retained'),
+    exclude: z
+      .array(z.string().min(1))
+      .min(1)
+      .optional()
+      .describe('Bone/object names whose complete descendant subtrees are removed'),
+  })
+  .strict()
+  .refine((mask) => Boolean(mask.include?.length || mask.exclude?.length), {
+    message: 'boneMask needs at least one include or exclude bone name',
+  })
+  .describe('Filters animation tracks by named Object3D/Bone subtrees');
+
+export type AnimationBoneMask = z.infer<typeof AnimationBoneMaskSchema>;
+
+const AnimationLayerFields = {
+  layer: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Composition layer name; omitted means the single base layer'),
+  weight: z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe('Layer weight multiplier from 0 to 1; defaults to 1'),
+  blendMode: z
+    .enum(['override', 'additive'])
+    .optional()
+    .describe('Native Three normal/override or additive action blending; defaults to override'),
+  boneMask: AnimationBoneMaskSchema.optional().describe(
+    'Optional include/exclude filter applied to every clip track in this state',
+  ),
+};
+
 // ---------------------------------------------------------------------------
 // Per-state animation metadata: single clip OR blend tree, plus crossfade
 // ---------------------------------------------------------------------------
@@ -155,6 +190,7 @@ const ClipAnimationMetaSchema = z
       .default(1)
       .describe('Playback speed multiplier (AnimationAction.timeScale)'),
     crossfade: AnimationCrossfadeMetaSchema.optional(),
+    ...AnimationLayerFields,
   })
   .strict();
 
@@ -166,6 +202,7 @@ const BlendTreeAnimationMetaSchema = z
       'Multiple clips blended by a live context/selector-driven parameter',
     ),
     crossfade: AnimationCrossfadeMetaSchema.optional(),
+    ...AnimationLayerFields,
   })
   .strict();
 

package/src/character/cloth-sim.ts

@@ -0,0 +1,533 @@
+/**
+ * Character primitive — Jolt soft-body cloth grids (capes, skirts, banners)
+ * on top of the raw `jolt-physics` WASM bindings.
+ *
+ * THIN COMPOSITION HELPER, not a wrapper (CLAUDE.md "use libraries
+ * directly"): every export assembles the library's own objects
+ * (`Jolt.SoftBodySharedSettings`, `Jolt.Body`, `Jolt.JoltInterface`) —
+ * nothing from the library is re-exported. This file never imports the WASM
+ * module itself — the caller does the async `JoltInit()` and passes the
+ * resolved module in, mirroring `setup-physics.ts`'s `setupPhysics(rapier:
+ * typeof RAPIER, ...)` pattern for Rapier. `import type Jolt from
+ * 'jolt-physics/wasm-compat'` below is TYPE-ONLY (erased at compile time —
+ * no runtime WASM import here).
+ *
+ * Sharp edges this module exists partly to contain (see the mission brief /
+ * `cloth-hair-bench/jolt-cloth.ts`'s header for the full discovery):
+ *   - `Body.GetMotionProperties()` needs the `Jolt.castObject` downcast to
+ *     `Jolt.SoftBodyMotionProperties` to reach `GetVertex`.
+ *   - `SoftBodySharedSettings.CreateConstraints` takes a POINTER-typed
+ *     1-element `ArraySoftBodySharedSettingsVertexAttributes` (push_back,
+ *     not resize+at — `.at()` on these embind vectors returns a copy).
+ *   - Kinematic pins must set BOTH `SoftBodyVertex.mPosition` and
+ *     `.mVelocity` (finite-differenced) every tick, or the cloth's own
+ *     constraint solver fights a teleporting anchor.
+ *   - NO per-frame embind allocations (reviewer finding on Phase 1's
+ *     spike, which leaked a `new Jolt.Vec3(...)`/`new Jolt.RVec3(...)` per
+ *     pinned vertex per frame): `tick()` below preallocates ONE `Jolt.Vec3`
+ *     for position and ONE for velocity and reuses them via `.Set(...)` —
+ *     embind property setters (`vertex.mPosition = tmpVec3`) copy the value
+ *     in, so reassigning the SAME wrapper object across many vertices in one
+ *     frame is safe. `KinematicCollider.moveTo` does the same with one
+ *     `Jolt.RVec3` + one `Jolt.Quat` (identity, orientation is not simulated
+ *     here) allocated once at construction.
+ *   - CONSTRUCTION-TIME embind temporaries need `Jolt.destroy(...)` too, once
+ *     Jolt has copied their data out (reviewer finding on Phase 2 — these
+ *     were leaking WASM heap per build/dispose cycle even with `tick()`
+ *     itself allocation-free). Two different lifetimes are at play:
+ *     - Per-vertex/per-face grid temporaries (`SoftBodySharedSettingsVertex`
+ *       + its `Float3`, `SoftBodySharedSettingsFace`, the single
+ *       `vertexAttr`) are copied BY VALUE into `sharedSettings`'s own
+ *       storage the instant `push_back`/the property setter runs — freed
+ *       right there, matching the reuse-then-`Jolt.destroy()`-once pattern
+ *       in Jolt's own `soft-body-creator.js` sample. `bodyCreation`
+ *       (`SoftBodyCreationSettings`) is the same story: `CreateSoftBody`
+ *       copies what it needs, so it's freed right after — same contract as
+ *       `JoltSettings` → `JoltInterface` below.
+ *     - `sharedSettings` itself (`SoftBodySharedSettings`) is different: it
+ *       is REFCOUNTED (`AddRef`/`Release`/`GetRefCount` in the vendored
+ *       typings, like `Shape`) and the body reads it every step
+ *       (`SoftBodyMotionProperties.GetSettings()`) for face/constraint
+ *       topology. Refcounted RefTargets are freed BY JOLT ITSELF when the
+ *       last reference drops (Release of the final ref IS the delete) —
+ *       so it gets NO explicit `Jolt.destroy(...)` at all: destroying
+ *       `bodyCreation` releases the ctor's ref, and `dispose()`'s
+ *       `DestroyBody` releases the body's (last) ref, which deletes it.
+ *       An explicit destroy on top would be a use-after-free (empirically
+ *       confirmed with a `GetRefCount()` probe against real Jolt WASM).
+ *       Same rule for the collider's `Shape`: `destroy(creation)` releases
+ *       the creation-settings ref, `DestroyBody` releases the body's —
+ *       never destroy the shape directly.
+ *   - The preallocated tick-loop temporaries described above (`tmpPos`/
+ *     `tmpVel` in `buildClothGrid`, `tmpPos`/`identityQuat` in
+ *     `buildKinematicCollider`) are plain (non-refcounted) `Vec3`/`RVec3`/
+ *     `Quat` wrappers reused for the object's whole lifetime — freed in that
+ *     object's own `dispose()`.
+ */
+
+import type JoltNS from 'jolt-physics/wasm-compat';
+import * as THREE from 'three';
+
+/** The type of an ALREADY-INITIALIZED `jolt-physics/wasm-compat` module
+ *  (i.e. what `await JoltInit()` resolves to) — the parameter type every
+ *  function below takes instead of importing/initializing Jolt itself. */
+export type JoltModule = typeof JoltNS;
+
+const LAYER_NON_MOVING = 0;
+const LAYER_MOVING = 1;
+const NUM_OBJECT_LAYERS = 2;
+const NUM_BROAD_PHASE_LAYERS = 2;
+
+// ---------------------------------------------------------------------------
+// Jolt world (the minimal two-layer broadphase boilerplate every Jolt scene
+// needs, regardless of what bodies it holds)
+// ---------------------------------------------------------------------------
+
+export interface JoltWorld {
+  jolt: JoltModule;
+  joltInterface: JoltNS.JoltInterface;
+  physicsSystem: JoltNS.PhysicsSystem;
+  bodyInterface: JoltNS.BodyInterface;
+  /** The single "moving" object layer every body built through this world's
+   *  helpers is placed on (cloth + kinematic colliders all collide with
+   *  each other; nothing here needs more than one moving layer). */
+  movingLayer: number;
+  /** Advance the simulation by `dt` seconds (`options.collisionSteps` Jolt
+   *  collision sub-steps). Position any kinematic bodies (colliders, cloth
+   *  pins) for this frame BEFORE calling `step` — this is what
+   *  `ClothGrid.tick` does internally. */
+  step(dt: number): void;
+  dispose(): void;
+}
+
+export interface JoltWorldOptions {
+  gravity?: { x: number; y: number; z: number };
+  /** Jolt collision sub-steps per `step()` call. Soft-body contact has no
+   *  CCD — a cloth vertex moving faster than its collision radius per
+   *  collision step TUNNELS through kinematic colliders (measured live on a
+   *  whipping cape). 2 halves the per-step travel for ~2x the (sub-ms) sim
+   *  cost. @default 1 */
+  collisionSteps?: number;
+}
+
+export function createJoltWorld(jolt: JoltModule, options: JoltWorldOptions = {}): JoltWorld {
+  const gravity = options.gravity ?? { x: 0, y: -9.81, z: 0 };
+  const collisionSteps = options.collisionSteps ?? 1;
+  const objectFilter = new jolt.ObjectLayerPairFilterTable(NUM_OBJECT_LAYERS);
+  objectFilter.EnableCollision(LAYER_MOVING, LAYER_MOVING);
+  const bpInterface = new jolt.BroadPhaseLayerInterfaceTable(
+    NUM_OBJECT_LAYERS,
+    NUM_BROAD_PHASE_LAYERS,
+  );
+  bpInterface.MapObjectToBroadPhaseLayer(
+    LAYER_NON_MOVING,
+    new jolt.BroadPhaseLayer(LAYER_NON_MOVING),
+  );
+  bpInterface.MapObjectToBroadPhaseLayer(LAYER_MOVING, new jolt.BroadPhaseLayer(LAYER_MOVING));
+
+  const settings = new jolt.JoltSettings();
+  settings.mObjectLayerPairFilter = objectFilter;
+  settings.mBroadPhaseLayerInterface = bpInterface;
+  settings.mObjectVsBroadPhaseLayerFilter = new jolt.ObjectVsBroadPhaseLayerFilterTable(
+    bpInterface,
+    NUM_BROAD_PHASE_LAYERS,
+    objectFilter,
+    NUM_OBJECT_LAYERS,
+  );
+  const joltInterface = new jolt.JoltInterface(settings);
+  jolt.destroy(settings);
+  const physicsSystem = joltInterface.GetPhysicsSystem();
+  physicsSystem.SetGravity(new jolt.Vec3(gravity.x, gravity.y, gravity.z));
+  const bodyInterface = physicsSystem.GetBodyInterface();
+
+  return {
+    jolt,
+    joltInterface,
+    physicsSystem,
+    bodyInterface,
+    movingLayer: LAYER_MOVING,
+    step(dt: number): void {
+      joltInterface.Step(dt, collisionSteps);
+    },
+    dispose(): void {
+      jolt.destroy(joltInterface);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Kinematic colliders (torso/head/limb shapes the cloth drapes over)
+// ---------------------------------------------------------------------------
+
+export type KinematicColliderShape =
+  | { kind: 'sphere'; radius: number }
+  | { kind: 'capsule'; radius: number; halfHeight: number };
+
+export interface KinematicCollider {
+  body: JoltNS.Body;
+  /** Move the collider to `worldPos` (identity rotation — these fixtures
+   *  only need translation) for tick `dt`. Call BEFORE the cloth grid's
+   *  `tick()` for the same frame (that is what steps the Jolt world). */
+  moveTo(worldPos: THREE.Vector3, dt: number): void;
+  dispose(): void;
+}
+
+export function buildKinematicCollider(
+  world: JoltWorld,
+  shape: KinematicColliderShape,
+): KinematicCollider {
+  const { jolt, bodyInterface } = world;
+  const joltShape =
+    shape.kind === 'sphere'
+      ? new jolt.SphereShape(shape.radius)
+      : new jolt.CapsuleShape(shape.halfHeight, shape.radius);
+  const creation = new jolt.BodyCreationSettings(
+    joltShape,
+    new jolt.RVec3(0, 0, 0),
+    new jolt.Quat(0, 0, 0, 1),
+    jolt.EMotionType_Kinematic,
+    world.movingLayer,
+  );
+  // A per-tick-driven kinematic collider must NEVER sleep: Jolt puts a
+  // near-zero-velocity kinematic body to sleep after ~0.5 s, and
+  // `Body.MoveKinematic` (unlike the BodyInterface variant) does NOT wake
+  // it — after any brief stillness (e.g. a garment-settle warm-up) the
+  // collider would silently freeze at its old pose FOREVER while the
+  // character walks away (observed live: the whole cape sailed through the
+  // torso and every contact-robustness knob was powerless against it).
+  creation.mAllowSleeping = false;
+  const body = bodyInterface.CreateBody(creation);
+  bodyInterface.AddBody(body.GetID(), jolt.EActivation_Activate);
+  // `CreateBody` copied what it needs — free the one-shot settings struct
+  // now (same contract as `SoftBodyCreationSettings` in `buildClothGrid`).
+  // This also releases `creation`'s reference on the REFCOUNTED `joltShape`;
+  // the body holds the remaining shape ref, so `joltShape` must NOT get a
+  // `jolt.destroy` anywhere — `DestroyBody` in `dispose()` releases that
+  // last ref and Jolt deletes the shape itself (see module header).
+  jolt.destroy(creation);
+
+  // Preallocated once, reused every `moveTo` call — see module header.
+  const tmpPos = new jolt.RVec3(0, 0, 0);
+  const identityQuat = new jolt.Quat(0, 0, 0, 1);
+
+  return {
+    body,
+    moveTo(worldPos: THREE.Vector3, dt: number): void {
+      tmpPos.Set(worldPos.x, worldPos.y, worldPos.z);
+      body.MoveKinematic(tmpPos, identityQuat, dt);
+    },
+    dispose(): void {
+      bodyInterface.RemoveBody(body.GetID());
+      bodyInterface.DestroyBody(body.GetID());
+      jolt.destroy(tmpPos);
+      jolt.destroy(identityQuat);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Cloth grid
+// ---------------------------------------------------------------------------
+
+export interface ClothPin {
+  row: number;
+  col: number;
+}
+
+export interface ClothGridOptions {
+  cols: number;
+  rows: number;
+  /** World-space rest position for grid vertex (row, col) — row 0 is
+   *  conventionally the top/pinned edge, but that's a caller convention,
+   *  not enforced here. */
+  restPosition(row: number, col: number): THREE.Vector3;
+  /** Which vertices are pinned (kinematically driven every tick, infinite
+   *  mass). Default: every vertex in row 0. */
+  pins?: ClothPin[];
+  vertexMassKg?: number;
+  compliance?: number;
+  shearCompliance?: number;
+  bendCompliance?: number;
+  numIterations?: number;
+  gravityFactor?: number;
+  /** Collision radius of every cloth vertex (Jolt `mVertexRadius`), metres.
+   *  The default 0 lets a pressed vertex sit exactly ON (and, under
+   *  sustained gait-driven contact, sink INTO) a collider surface; a few cm
+   *  here keeps the cloth standing off colliders and makes contact
+   *  resolution far more robust against sinking. @default 0 (Jolt's own) */
+  vertexRadius?: number;
+  /** Jolt `mLinearDamping` for the soft body (higher = calmer cloth).
+   *  @default Jolt's own default */
+  linearDamping?: number;
+  color?: number;
+  /** @default true */
+  doubleSided?: boolean;
+}
+
+export interface ClothGrid {
+  cols: number;
+  rows: number;
+  vertexCount: number;
+  /** Pin list this grid was built with, in the order `tick()`'s
+   *  `pinTargets` must match. */
+  pins: ClothPin[];
+  mesh: THREE.Mesh;
+  geometry: THREE.BufferGeometry;
+  /** One tick: overwrite each pinned vertex's position/velocity from
+   *  `pinTargets[i]` (world-space, matching `pins` order — velocity is
+   *  finite-differenced against the previous call), STEP the owning
+   *  `JoltWorld` (this is the only thing in this module that calls
+   *  `world.step`, so build at most one `ClothGrid` per `JoltWorld` unless
+   *  you step the world yourself and skip that side effect), then sync
+   *  `geometry`'s `position` attribute + recompute normals from the
+   *  simulated vertices. Position any kinematic colliders for this frame
+   *  BEFORE calling this. */
+  tick(dt: number, pinTargets: readonly THREE.Vector3[]): void;
+  /** World-space position of every vertex, row-major (`row * cols + col`).
+   *  Reuses `out` if given (avoids an allocation for callers sampling every
+   *  frame, e.g. a numeric collision-clearance check). */
+  samplePoints(out?: THREE.Vector3[]): THREE.Vector3[];
+  dispose(): void;
+}
+
+type GridIndex = (row: number, col: number) => number;
+
+/** Build the `SoftBodySharedSettings` (vertex grid + face list + edge/shear/
+ *  bend constraints) for a `cols`x`rows` cloth. Split out of `buildClothGrid`
+ *  purely to keep that function's complexity down — not reused elsewhere. */
+function buildSoftBodySharedSettings(
+  jolt: JoltModule,
+  options: ClothGridOptions,
+  pins: ClothPin[],
+  idx: GridIndex,
+): JoltNS.SoftBodySharedSettings {
+  const { cols, rows } = options;
+  const vertexMassKg = options.vertexMassKg ?? 0.02;
+  const pinSet = new Set(pins.map((p) => idx(p.row, p.col)));
+
+  const sharedSettings = new jolt.SoftBodySharedSettings();
+  const vertices = sharedSettings.mVertices;
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < cols; col++) {
+      const p = options.restPosition(row, col);
+      const v = new jolt.SoftBodySharedSettingsVertex();
+      const pos = new jolt.Float3(p.x, p.y, p.z);
+      v.mPosition = pos;
+      v.mInvMass = pinSet.has(idx(row, col)) ? 0 : 1 / vertexMassKg;
+      vertices.push_back(v);
+      // `push_back` (like the property-setter assignment above it) copies
+      // BY VALUE into `sharedSettings`'s own storage — Jolt's own
+      // `soft-body-creator.js` sample reuses/destroys a single `v` the same
+      // way across its whole grid loop — so both temporaries are safe to
+      // free the instant the copy has happened.
+      jolt.destroy(pos);
+      jolt.destroy(v);
+    }
+  }
+  sharedSettings.mVertices = vertices;
+
+  const faces = sharedSettings.mFaces;
+  for (let row = 0; row < rows - 1; row++) {
+    for (let col = 0; col < cols - 1; col++) {
+      const faceA = new jolt.SoftBodySharedSettingsFace(
+        idx(row, col),
+        idx(row + 1, col),
+        idx(row, col + 1),
+        0,
+      );
+      faces.push_back(faceA);
+      jolt.destroy(faceA);
+      const faceB = new jolt.SoftBodySharedSettingsFace(
+        idx(row, col + 1),
+        idx(row + 1, col),
+        idx(row + 1, col + 1),
+        0,
+      );
+      faces.push_back(faceB);
+      jolt.destroy(faceB);
+    }
+  }
+  sharedSettings.mFaces = faces;
+
+  const vertexAttr = new jolt.SoftBodySharedSettingsVertexAttributes();
+  vertexAttr.mCompliance = options.compliance ?? 0.0002;
+  vertexAttr.mShearCompliance = options.shearCompliance ?? 0.0002;
+  vertexAttr.mBendCompliance = options.bendCompliance ?? 0.002;
+  const vertexAttrArr = new jolt.ArraySoftBodySharedSettingsVertexAttributes();
+  vertexAttrArr.push_back(vertexAttr);
+  // Same value-copy-then-free story as above: `CreateConstraints` below
+  // reads from `vertexAttrArr`'s OWN backing copy (via `.data()`), not this
+  // original wrapper, so it's safe to free right after the push_back.
+  jolt.destroy(vertexAttr);
+  sharedSettings.CreateConstraints(
+    vertexAttrArr.data(),
+    vertexAttrArr.size(),
+    jolt.SoftBodySharedSettings_EBendType_Distance,
+  );
+  sharedSettings.Optimize();
+  jolt.destroy(vertexAttrArr);
+  return sharedSettings;
+}
+
+/** Build the renderable (non-skinned) mesh: a plain `BufferGeometry` whose
+ *  `position` attribute `ClothGrid.tick` overwrites every frame. */
+function buildClothMesh(
+  scene: THREE.Scene,
+  options: ClothGridOptions,
+  idx: GridIndex,
+): {
+  mesh: THREE.Mesh;
+  geometry: THREE.BufferGeometry;
+  positionAttr: THREE.BufferAttribute;
+  material: THREE.MeshStandardMaterial;
+} {
+  const { cols, rows } = options;
+  const geometry = new THREE.BufferGeometry();
+  const positionAttr = new THREE.BufferAttribute(new Float32Array(rows * cols * 3), 3);
+  positionAttr.setUsage(THREE.DynamicDrawUsage);
+  geometry.setAttribute('position', positionAttr);
+  const indices: number[] = [];
+  for (let row = 0; row < rows - 1; row++) {
+    for (let col = 0; col < cols - 1; col++) {
+      indices.push(idx(row, col), idx(row + 1, col), idx(row, col + 1));
+      indices.push(idx(row, col + 1), idx(row + 1, col), idx(row + 1, col + 1));
+    }
+  }
+  geometry.setIndex(indices);
+  const material = new THREE.MeshStandardMaterial({
+    color: options.color ?? 0x7a2f3a,
+    roughness: 0.85,
+    side: options.doubleSided === false ? THREE.FrontSide : THREE.DoubleSide,
+  });
+  const mesh = new THREE.Mesh(geometry, material);
+  mesh.castShadow = true;
+  mesh.frustumCulled = false;
+  scene.add(mesh);
+  return { mesh, geometry, positionAttr, material };
+}
+
+export function buildClothGrid(
+  world: JoltWorld,
+  scene: THREE.Scene,
+  options: ClothGridOptions,
+): ClothGrid {
+  const { jolt, bodyInterface } = world;
+  const { cols, rows } = options;
+  const pins = options.pins ?? Array.from({ length: cols }, (_, col) => ({ row: 0, col }));
+  const idx: GridIndex = (row, col) => row * cols + col;
+
+  const sharedSettings = buildSoftBodySharedSettings(jolt, options, pins, idx);
+
+  const bodyCreation = new jolt.SoftBodyCreationSettings(
+    sharedSettings,
+    new jolt.RVec3(0, 0, 0),
+    new jolt.Quat(0, 0, 0, 1),
+    world.movingLayer,
+  );
+  bodyCreation.mNumIterations = options.numIterations ?? 4;
+  if (options.vertexRadius !== undefined) bodyCreation.mVertexRadius = options.vertexRadius;
+  if (options.linearDamping !== undefined) bodyCreation.mLinearDamping = options.linearDamping;
+  bodyCreation.mPressure = 0;
+  bodyCreation.mGravityFactor = options.gravityFactor ?? 1;
+  bodyCreation.mFacesDoubleSided = true;
+  bodyCreation.mUpdatePosition = false;
+  // Kinematically-pinned cloth must never sleep either: `tick()` drives the
+  // pins by writing `SoftBodyVertex.mPosition/.mVelocity` DIRECTLY, which
+  // does not count as activity — a cape that settles still for ~0.5 s would
+  // sleep and stay frozen while its pins walk away.
+  bodyCreation.mAllowSleeping = false;
+  const clothBody = bodyInterface.CreateSoftBody(bodyCreation);
+  bodyInterface.AddBody(clothBody.GetID(), jolt.EActivation_Activate);
+  // `CreateSoftBody` copies what it needs out of `bodyCreation` into the
+  // body's own storage (same "settings object is a one-shot constructor
+  // argument" contract as `JoltSettings` → `JoltInterface` above) — safe to
+  // free right away, same as that pattern. `bodyCreation` itself is a plain
+  // (non-refcounted) settings struct, unlike `sharedSettings` below: freeing
+  // it here still correctly releases bodyCreation's OWN internal reference
+  // to `sharedSettings` (which the body has, by now, separately taken its
+  // own reference to via `CreateSoftBody`).
+  jolt.destroy(bodyCreation);
+  // `Body` only exposes the base `GetMotionProperties()`; soft bodies need
+  // the downcast to reach `GetVertex`/`GetVertices`.
+  const motionProperties = jolt.castObject(
+    clothBody.GetMotionProperties(),
+    jolt.SoftBodyMotionProperties,
+  );
+
+  const { mesh, geometry, positionAttr, material } = buildClothMesh(scene, options, idx);
+
+  // Preallocated tick-loop temporaries — see module header.
+  const tmpPos = new jolt.Vec3(0, 0, 0);
+  const tmpVel = new jolt.Vec3(0, 0, 0);
+  const prevPinWorld: THREE.Vector3[] = pins.map((p) => options.restPosition(p.row, p.col));
+
+  return {
+    cols,
+    rows,
+    vertexCount: rows * cols,
+    pins,
+    mesh,
+    geometry,
+    tick(dt: number, pinTargets: readonly THREE.Vector3[]): void {
+      for (let i = 0; i < pins.length; i++) {
+        const target = pinTargets[i];
+        if (!target) continue;
+        const pin = pins[i]!;
+        const prev = prevPinWorld[i]!;
+        const vertex = motionProperties.GetVertex(idx(pin.row, pin.col));
+        tmpPos.Set(target.x, target.y, target.z);
+        vertex.mPosition = tmpPos;
+        if (dt > 0) {
+          tmpVel.Set((target.x - prev.x) / dt, (target.y - prev.y) / dt, (target.z - prev.z) / dt);
+        } else {
+          tmpVel.Set(0, 0, 0);
+        }
+        vertex.mVelocity = tmpVel;
+        prev.copy(target);
+      }
+
+      world.step(dt);
+
+      const posArr = positionAttr.array as Float32Array;
+      for (let i = 0; i < rows * cols; i++) {
+        const v = motionProperties.GetVertex(i);
+        const p = v.mPosition;
+        posArr[i * 3] = p.GetX();
+        posArr[i * 3 + 1] = p.GetY();
+        posArr[i * 3 + 2] = p.GetZ();
+      }
+      positionAttr.needsUpdate = true;
+      geometry.computeVertexNormals();
+    },
+    samplePoints(out: THREE.Vector3[] = []): THREE.Vector3[] {
+      const n = rows * cols;
+      out.length = n;
+      for (let i = 0; i < n; i++) {
+        const v = motionProperties.GetVertex(i);
+        const p = v.mPosition;
+        if (!out[i]) out[i] = new THREE.Vector3();
+        out[i]!.set(p.GetX(), p.GetY(), p.GetZ());
+      }
+      return out;
+    },
+    dispose(): void {
+      bodyInterface.RemoveBody(clothBody.GetID());
+      // NO explicit `jolt.destroy(sharedSettings)` — anywhere. It is a
+      // refcounted RefTarget that Jolt frees ITSELF when its last reference
+      // drops, and in Jolt's RefTarget::Release releasing the last ref IS
+      // the delete. Refcount chain, probed live against real Jolt WASM via
+      // `GetRefCount()`: 0 after `new` → 1 after the
+      // `SoftBodyCreationSettings` ctor took its ref → 2 after
+      // `CreateSoftBody` (the body's own ref) → back to 1 after the
+      // construction-time `destroy(bodyCreation)` → `DestroyBody` below
+      // releases that last (body) reference and thereby deletes it. Any
+      // `destroy(sharedSettings)` after this line would be a use-after-free.
+      bodyInterface.DestroyBody(clothBody.GetID());
+      jolt.destroy(tmpPos);
+      jolt.destroy(tmpVel);
+      scene.remove(mesh);
+      geometry.dispose();
+      material.dispose();
+    },
+  };
+}