@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/character/spring-chain.ts

@@ -1,307 +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,
-  VRMSpringBoneColliderShapeCapsule,
-  VRMSpringBoneColliderShapeSphere,
-  VRMSpringBoneJoint,
-  VRMSpringBoneManager,
-} from '@pixiv/three-vrm-springbone';
-import * as THREE from 'three';
-
-const DEFAULT_GRAVITY_DIR = new THREE.Vector3(0, -1, 0);
-
-// ---------------------------------------------------------------------------
-// Bone chains
-// ---------------------------------------------------------------------------
-
-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 function worldOffsetToLocalPos(
-  parent: THREE.Object3D,
-  worldDir: THREE.Vector3,
-  length: number,
-): THREE.Vector3 {
-  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: THREE.Object3D,
-  namePrefix: string,
-  count: number,
-  segmentLength: number,
-  worldDir: THREE.Vector3,
-): BoneChain {
-  const bones: THREE.Bone[] = [];
-  let cur: THREE.Object3D = 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 };
-}
-
-// ---------------------------------------------------------------------------
-// Spring joints
-// ---------------------------------------------------------------------------
-
-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 function registerChainJoints(
-  manager: VRMSpringBoneManager,
-  chain: BoneChain,
-  colliderGroups: VRMSpringBoneColliderGroup[],
-  settings: ChainJointSettings = {},
-): ChainJointHandle {
-  const joints: VRMSpringBoneJoint[] = [];
-  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(): void {
-      for (const joint of joints) manager.deleteJoint(joint);
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Colliders
-// ---------------------------------------------------------------------------
-
-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 function buildSpringColliderRig(scene: THREE.Scene, defs: ColliderDef[]): SpringColliderRig {
-  const colliders = new Map<string, VRMSpringBoneCollider>();
-  const followers: Array<{ def: ColliderDef; collider: VRMSpringBoneCollider }> = [];
-
-  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: VRMSpringBoneColliderGroup = {
-    name: 'body',
-    colliders: [...colliders.values()],
-  };
-
-  const worldTmp = new THREE.Vector3();
-  return {
-    group,
-    colliders,
-    reposition(): void {
-      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(): void {
-      for (const collider of colliders.values()) scene.remove(collider);
-      colliders.clear();
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Composed chain rig (the common case: one chain, its own manager)
-// ---------------------------------------------------------------------------
-
-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 function buildSpringChainRig(options: SpringChainRigOptions): SpringChainRig {
-  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: number): void {
-      options.colliderRig?.reposition();
-      manager.update(dt);
-    },
-    dispose(): void {
-      jointHandle.dispose();
-      chain.bones[0]?.removeFromParent();
-    },
-  };
-}