@vgai/engine 0.5.0 → 0.5.1

package/dist/character/cloth-sim.js

@@ -1,334 +0,0 @@
-/**
- * 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 * as THREE from 'three';
-const LAYER_NON_MOVING = 0;
-const LAYER_MOVING = 1;
-const NUM_OBJECT_LAYERS = 2;
-const NUM_BROAD_PHASE_LAYERS = 2;
-export function createJoltWorld(jolt, options = {}) {
-    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) {
-            joltInterface.Step(dt, collisionSteps);
-        },
-        dispose() {
-            jolt.destroy(joltInterface);
-        },
-    };
-}
-export function buildKinematicCollider(world, shape) {
-    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, dt) {
-            tmpPos.Set(worldPos.x, worldPos.y, worldPos.z);
-            body.MoveKinematic(tmpPos, identityQuat, dt);
-        },
-        dispose() {
-            bodyInterface.RemoveBody(body.GetID());
-            bodyInterface.DestroyBody(body.GetID());
-            jolt.destroy(tmpPos);
-            jolt.destroy(identityQuat);
-        },
-    };
-}
-/** 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, options, pins, idx) {
-    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, options, idx) {
-    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 = [];
-    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, scene, options) {
-    const { jolt, bodyInterface } = world;
-    const { cols, rows } = options;
-    const pins = options.pins ?? Array.from({ length: cols }, (_, col) => ({ row: 0, col }));
-    const idx = (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 = pins.map((p) => options.restPosition(p.row, p.col));
-    return {
-        cols,
-        rows,
-        vertexCount: rows * cols,
-        pins,
-        mesh,
-        geometry,
-        tick(dt, pinTargets) {
-            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;
-            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 = []) {
-            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() {
-            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();
-        },
-    };
-}

package/dist/character/spring-chain.d.ts

@@ -1,135 +0,0 @@
-/**
- * Character primitive — spring-bone chains (hair, ponytails, cloth strips)
- * on top of `@pixiv/three-vrm-springbone`'s raw API.
- *
- * This is a THIN COMPOSITION HELPER, not a wrapper (CLAUDE.md "use libraries
- * directly"): every export here is a small function that assembles the
- * library's own objects (`THREE.Bone`, `VRMSpringBoneJoint`,
- * `VRMSpringBoneCollider`, `VRMSpringBoneManager`) — nothing from the
- * library is re-exported, and callers still import `@pixiv/three-vrm-
- * springbone` types directly for anything beyond what's here. Kept
- * deliberately bare: composing a specific character (a caped viking, a
- * ponytailed ranger) is ordinary calling code on top of these pieces, not a
- * costume/preset system in the engine.
- *
- * Sharp edge this module exists partly to contain (see the mission brief /
- * `cloth-hair-bench/spring-rig.ts`'s header for the full discovery):
- * `VRMSpringBoneCollider` overrides `updateWorldMatrix` (the ON-DEMAND,
- * manually-invoked method), NOT `updateMatrixWorld` (the one the renderer
- * calls automatically) — `SpringColliderRig.reposition()` below calls
- * `collider.updateWorldMatrix(true, false)` itself every tick so callers
- * can't forget it.
- */
-import { VRMSpringBoneCollider, type VRMSpringBoneColliderGroup, VRMSpringBoneJoint, VRMSpringBoneManager } from '@pixiv/three-vrm-springbone';
-import * as THREE from 'three';
-export interface BoneChain {
-    /** Swinging bones, root (nearest the anchor) first. */
-    bones: THREE.Bone[];
-    /** A non-simulated leaf `Object3D` past the last bone — the spring joint
-     *  "tail" target for the last bone in the chain. */
-    tip: THREE.Object3D;
-}
-/** World-space offset from `parent`'s CURRENT world position -> the local
- *  position a new direct child of `parent` must have to sit there. Requires
- *  `parent.matrixWorld` to be current. Sidesteps ever reasoning about a
- *  bone's local rest-axis convention (arbitrary per-bone on an imported
- *  rig) — the caller only ever thinks in world-space directions. */
-export declare function worldOffsetToLocalPos(parent: THREE.Object3D, worldDir: THREE.Vector3, length: number): THREE.Vector3;
-/** Build a straight chain of `count` new `THREE.Bone`s under `parent`, each
- *  offset `segmentLength` further along the WORLD-space unit vector
- *  `worldDir` — the natural rest shape for hair/cloth hanging under gravity.
- *  Ends with a `tip` `Object3D` (one more segment past the last bone) so
- *  every bone has an explicit spring-joint child target. Can be anchored to
- *  either an existing rig bone (hair off a head) or any plain `Object3D`. */
-export declare function buildBoneChain(parent: THREE.Object3D, namePrefix: string, count: number, segmentLength: number, worldDir: THREE.Vector3): BoneChain;
-export interface ChainJointSettings {
-    stiffness?: number;
-    gravityPower?: number;
-    gravityDir?: THREE.Vector3;
-    dragForce?: number;
-    hitRadius?: number;
-}
-export interface ChainJointHandle {
-    joints: VRMSpringBoneJoint[];
-    /** Deregisters every joint this chain added from `manager`. Does NOT
-     *  detach the bones from the scene graph (the caller owns that). */
-    dispose(): void;
-}
-/** Register one `VRMSpringBoneJoint` per bone in `chain` on `manager` (each
- *  targeting the next bone, the last targeting `chain.tip`). Does not call
- *  `manager.setInitState()` — batch that once after all chains for a
- *  manager are registered and the scene's world matrices are current (sharp
- *  edge: `VRMSpringBoneJoint` sets `bone.matrixAutoUpdate = false`, so
- *  `setInitState()` must run AFTER `scene.updateMatrixWorld(true)`). */
-export declare function registerChainJoints(manager: VRMSpringBoneManager, chain: BoneChain, colliderGroups: VRMSpringBoneColliderGroup[], settings?: ChainJointSettings): ChainJointHandle;
-export interface SphereColliderDef {
-    shape: 'sphere';
-    name: string;
-    /** The collider tracks this object's world position every `reposition()`. */
-    followBone: THREE.Object3D;
-    radius: number;
-    /** Extra WORLD-space offset added after sampling `followBone`'s position
-     *  (e.g. nudging a head collider up from the neck joint). */
-    worldOffset?: THREE.Vector3;
-}
-export interface CapsuleColliderDef {
-    shape: 'capsule';
-    name: string;
-    followBone: THREE.Object3D;
-    radius: number;
-    /** Capsule tail, in the collider's own local space (world-axis-aligned —
-     *  colliders are parented directly to the scene, see `buildSpringColliderRig`). */
-    tail: THREE.Vector3;
-    worldOffset?: THREE.Vector3;
-}
-export type ColliderDef = SphereColliderDef | CapsuleColliderDef;
-export interface SpringColliderRig {
-    group: VRMSpringBoneColliderGroup;
-    colliders: Map<string, VRMSpringBoneCollider>;
-    /** Reposition every collider from its `followBone`'s CURRENT world
-     *  transform and refresh its `colliderMatrix` (see module header). Call
-     *  once per tick, BEFORE `manager.update(dt)`. */
-    reposition(): void;
-    dispose(): void;
-}
-/** Build sphere/capsule colliders parented directly to `scene` (world
- *  space) — sidesteps reasoning about any bone's local rest-axis convention
- *  for the collider shape's offset/tail vectors. */
-export declare function buildSpringColliderRig(scene: THREE.Scene, defs: ColliderDef[]): SpringColliderRig;
-export interface SpringChainRigOptions {
-    parent: THREE.Object3D;
-    namePrefix: string;
-    count: number;
-    segmentLength: number;
-    worldDir: THREE.Vector3;
-    /** Colliders this chain collides against. Omit for a chain with no
-     *  collision (e.g. a side strand tucked away from the body). */
-    colliderRig?: SpringColliderRig;
-    settings?: ChainJointSettings;
-}
-export interface SpringChainRig {
-    bones: THREE.Bone[];
-    tip: THREE.Object3D;
-    /** The manager owning this chain's joints — a "manager-compatible handle"
-     *  a caller can also register additional joints on directly. */
-    manager: VRMSpringBoneManager;
-    /** Repositions `colliderRig` (if given) and steps the spring simulation.
-     *  Handles the collider `updateWorldMatrix` footgun internally — callers
-     *  never need to call `collider.updateWorldMatrix` themselves. */
-    tick(dt: number): void;
-    dispose(): void;
-}
-/** Compose `buildBoneChain` + `registerChainJoints` behind one call for the
- *  common single-chain case: builds the chain, gives it its OWN
- *  `VRMSpringBoneManager` (managers are cheap — one per independent chain
- *  keeps `dispose()`/`tick()` fully self-contained), registers its joints,
- *  and calls `setInitState()` once construction is complete.
- *
- *  For MULTIPLE chains sharing one collider rig (e.g. a ponytail + two side
- *  strands all colliding against the same head), build each chain with its
- *  own `buildSpringChainRig` call (same `colliderRig` passed to each) and
- *  tick all of them — `colliderRig.reposition()` is idempotent per frame, so
- *  calling it once per chain tick is correct, just slightly redundant work
- *  (cheap: it only touches a handful of colliders). */
-export declare function buildSpringChainRig(options: SpringChainRigOptions): SpringChainRig;
-//# sourceMappingURL=spring-chain.d.ts.map

package/dist/character/spring-chain.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"spring-chain.d.ts","sourceRoot":"","sources":["../../src/character/spring-chain.ts"],"names":[],"mappings":"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"}

package/dist/character/spring-chain.js

@@ -1,165 +0,0 @@
-/**
- * Character primitive — spring-bone chains (hair, ponytails, cloth strips)
- * on top of `@pixiv/three-vrm-springbone`'s raw API.
- *
- * This is a THIN COMPOSITION HELPER, not a wrapper (CLAUDE.md "use libraries
- * directly"): every export here is a small function that assembles the
- * library's own objects (`THREE.Bone`, `VRMSpringBoneJoint`,
- * `VRMSpringBoneCollider`, `VRMSpringBoneManager`) — nothing from the
- * library is re-exported, and callers still import `@pixiv/three-vrm-
- * springbone` types directly for anything beyond what's here. Kept
- * deliberately bare: composing a specific character (a caped viking, a
- * ponytailed ranger) is ordinary calling code on top of these pieces, not a
- * costume/preset system in the engine.
- *
- * Sharp edge this module exists partly to contain (see the mission brief /
- * `cloth-hair-bench/spring-rig.ts`'s header for the full discovery):
- * `VRMSpringBoneCollider` overrides `updateWorldMatrix` (the ON-DEMAND,
- * manually-invoked method), NOT `updateMatrixWorld` (the one the renderer
- * calls automatically) — `SpringColliderRig.reposition()` below calls
- * `collider.updateWorldMatrix(true, false)` itself every tick so callers
- * can't forget it.
- */
-import { VRMSpringBoneCollider, VRMSpringBoneColliderShapeCapsule, VRMSpringBoneColliderShapeSphere, VRMSpringBoneJoint, VRMSpringBoneManager, } from '@pixiv/three-vrm-springbone';
-import * as THREE from 'three';
-const DEFAULT_GRAVITY_DIR = new THREE.Vector3(0, -1, 0);
-/** World-space offset from `parent`'s CURRENT world position -> the local
- *  position a new direct child of `parent` must have to sit there. Requires
- *  `parent.matrixWorld` to be current. Sidesteps ever reasoning about a
- *  bone's local rest-axis convention (arbitrary per-bone on an imported
- *  rig) — the caller only ever thinks in world-space directions. */
-export function worldOffsetToLocalPos(parent, worldDir, length) {
-    const parentWorld = new THREE.Vector3();
-    parent.getWorldPosition(parentWorld);
-    const targetWorld = parentWorld.clone().addScaledVector(worldDir, length);
-    return parent.worldToLocal(targetWorld.clone());
-}
-/** Build a straight chain of `count` new `THREE.Bone`s under `parent`, each
- *  offset `segmentLength` further along the WORLD-space unit vector
- *  `worldDir` — the natural rest shape for hair/cloth hanging under gravity.
- *  Ends with a `tip` `Object3D` (one more segment past the last bone) so
- *  every bone has an explicit spring-joint child target. Can be anchored to
- *  either an existing rig bone (hair off a head) or any plain `Object3D`. */
-export function buildBoneChain(parent, namePrefix, count, segmentLength, worldDir) {
-    const bones = [];
-    let cur = parent;
-    cur.updateWorldMatrix(true, false);
-    for (let i = 0; i < count; i++) {
-        const localPos = worldOffsetToLocalPos(cur, worldDir, segmentLength);
-        const bone = new THREE.Bone();
-        bone.name = `${namePrefix}${i}`;
-        bone.position.copy(localPos);
-        cur.add(bone);
-        bone.updateWorldMatrix(true, false);
-        bones.push(bone);
-        cur = bone;
-    }
-    const tip = new THREE.Object3D();
-    tip.name = `${namePrefix}Tip`;
-    tip.position.copy(worldOffsetToLocalPos(cur, worldDir, segmentLength));
-    cur.add(tip);
-    return { bones, tip };
-}
-/** Register one `VRMSpringBoneJoint` per bone in `chain` on `manager` (each
- *  targeting the next bone, the last targeting `chain.tip`). Does not call
- *  `manager.setInitState()` — batch that once after all chains for a
- *  manager are registered and the scene's world matrices are current (sharp
- *  edge: `VRMSpringBoneJoint` sets `bone.matrixAutoUpdate = false`, so
- *  `setInitState()` must run AFTER `scene.updateMatrixWorld(true)`). */
-export function registerChainJoints(manager, chain, colliderGroups, settings = {}) {
-    const joints = [];
-    for (let i = 0; i < chain.bones.length; i++) {
-        const bone = chain.bones[i];
-        const child = chain.bones[i + 1] ?? chain.tip;
-        const joint = new VRMSpringBoneJoint(bone, child, {
-            stiffness: settings.stiffness ?? 1.2,
-            gravityPower: settings.gravityPower ?? 0.9,
-            gravityDir: settings.gravityDir ?? DEFAULT_GRAVITY_DIR,
-            dragForce: settings.dragForce ?? 0.35,
-            hitRadius: settings.hitRadius ?? 0.02,
-        }, colliderGroups);
-        manager.addJoint(joint);
-        joints.push(joint);
-    }
-    return {
-        joints,
-        dispose() {
-            for (const joint of joints)
-                manager.deleteJoint(joint);
-        },
-    };
-}
-/** Build sphere/capsule colliders parented directly to `scene` (world
- *  space) — sidesteps reasoning about any bone's local rest-axis convention
- *  for the collider shape's offset/tail vectors. */
-export function buildSpringColliderRig(scene, defs) {
-    const colliders = new Map();
-    const followers = [];
-    for (const def of defs) {
-        const collider = def.shape === 'sphere'
-            ? new VRMSpringBoneCollider(new VRMSpringBoneColliderShapeSphere({ radius: def.radius }))
-            : new VRMSpringBoneCollider(new VRMSpringBoneColliderShapeCapsule({
-                radius: def.radius,
-                offset: new THREE.Vector3(0, 0, 0),
-                tail: def.tail,
-            }));
-        scene.add(collider);
-        colliders.set(def.name, collider);
-        followers.push({ def, collider });
-    }
-    const group = {
-        name: 'body',
-        colliders: [...colliders.values()],
-    };
-    const worldTmp = new THREE.Vector3();
-    return {
-        group,
-        colliders,
-        reposition() {
-            for (const { def, collider } of followers) {
-                def.followBone.getWorldPosition(worldTmp);
-                collider.position.copy(worldTmp);
-                if (def.worldOffset)
-                    collider.position.add(def.worldOffset);
-                collider.updateWorldMatrix(true, false);
-            }
-        },
-        dispose() {
-            for (const collider of colliders.values())
-                scene.remove(collider);
-            colliders.clear();
-        },
-    };
-}
-/** Compose `buildBoneChain` + `registerChainJoints` behind one call for the
- *  common single-chain case: builds the chain, gives it its OWN
- *  `VRMSpringBoneManager` (managers are cheap — one per independent chain
- *  keeps `dispose()`/`tick()` fully self-contained), registers its joints,
- *  and calls `setInitState()` once construction is complete.
- *
- *  For MULTIPLE chains sharing one collider rig (e.g. a ponytail + two side
- *  strands all colliding against the same head), build each chain with its
- *  own `buildSpringChainRig` call (same `colliderRig` passed to each) and
- *  tick all of them — `colliderRig.reposition()` is idempotent per frame, so
- *  calling it once per chain tick is correct, just slightly redundant work
- *  (cheap: it only touches a handful of colliders). */
-export function buildSpringChainRig(options) {
-    const chain = buildBoneChain(options.parent, options.namePrefix, options.count, options.segmentLength, options.worldDir);
-    const manager = new VRMSpringBoneManager();
-    const colliderGroups = options.colliderRig ? [options.colliderRig.group] : [];
-    const jointHandle = registerChainJoints(manager, chain, colliderGroups, options.settings);
-    manager.setInitState();
-    return {
-        bones: chain.bones,
-        tip: chain.tip,
-        manager,
-        tick(dt) {
-            options.colliderRig?.reposition();
-            manager.update(dt);
-        },
-        dispose() {
-            jointHandle.dispose();
-            chain.bones[0]?.removeFromParent();
-        },
-    };
-}