lecodes-sdk 0.20.0 → 1.0.0

package/src/gl/animation/DynamicBone.ts

@@ -0,0 +1,459 @@
+// DynamicBone — secondary motion for tails, ears, hair, ropes and cloaks, simulated in the engine.
+// Attach to the ROOT bone of a chain; the bone's whole subtree becomes Verlet particle chains that
+// swing, lag and settle under gravity, wind and the character's motion, pulled back toward the pose
+// the animation gives them, kept out of the body by capsule colliders and above the floor.
+//
+//   const tail = fox.bone('tail')!
+//   tail.aspect(DynamicBone, { stiffness: [0.6, 0.15], damping: 0.15, gravity: 2, angleLimit: 50 })
+//   fox.bone('earend')!.aspect(DynamicBone, { stiffness: 0.8, angleLimit: 25 })
+//   fox.bone('Hips')!.aspect(DynamicBoneCollider, { radius: 0.12, to: 'chest' })   // a capsule the tail can't enter
+//   tail.dynamicBone.weight = cutscene ? 0 : 1                                       // blend to the animation
+//   tail.dynamicBone.floor = hit.point                                              // the ground under it
+//   tail.dynamicBone.reset()                                                        // after a teleport
+//
+// Per-bone values (`radius`, `stiffness`, `damping`, `gravity`, `angleLimit`) take one number for the
+// whole chain or a `[root, tip]` pair interpolated down the chain — a tail is stiff at the base and
+// loose at the tip. A cloak is one aspect on the common parent of its columns with `link` > 0: the
+// bones at the same depth of neighbouring columns are tied at their rest distance.
+//
+// The simulation runs natively in a stage of its own after the late phase and before the skin flush
+// (docs/parity: gl-dynamic-bones): the animator, an active ragdoll and late-phase aspects (IK) are
+// its input; every field of this aspect is live — the values are pushed when they change.
+
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
+import { Node } from "../Node"
+import { Model } from "../Model"
+import { HUMANOID, humanoidParts } from "../physics/Ragdoll"
+
+/** One value for the chain, or `[root, tip]` interpolated down it by depth. */
+export type DynamicBoneCurve = number | readonly [root: number, tip: number]
+/** `'none'`, `'probe'` (a ray from the chain root down against the physics world, every frame), a
+ *  height (a horizontal plane at that world y) or a world point (a plane through it, `floorNormal` up). */
+export type DynamicBoneFloor = "none" | "probe" | number | Vec3Like
+/** `'auto'` = every DynamicBoneCollider under the model; `'humanoid'` = those plus capsules generated
+ *  on the standard humanoid bones (hips, spine, head, limbs — the Ragdoll's layout); `'none'`; or the
+ *  nodes carrying the colliders to use. */
+export type DynamicBoneColliders = "auto" | "humanoid" | "none" | Node[]
+/** The cloth's OUTSIDE, which makes every collider one-sided: `'none'` = a collider pushes a bone to its
+ *  nearest surface (tails, ropes); `'auto'` = away from the root bone's own axis (a cloak's strips round a
+ *  spine face out from it); a vector = a fixed direction in the root bone's frame (a cape on the back:
+ *  `[0, 0, -1]`). With a side the body is under the cloth by definition: an arm that swung through the
+ *  cape pushes it away, and a bone that ended up inside a capsule leaves it on the outside — never
+ *  through it to be held against the chest from the wrong side. */
+export type DynamicBoneSide = "none" | "auto" | Vec3Like
+
+const VERSION = 1
+const PARAMS = 25                 // CANIM_DYN_COUNT
+const HEADER = 3 + PARAMS
+const STRIDE = 7                  // CANIM_DYN_BONE_STRIDE
+const FLOOR_NONE = 0, FLOOR_PLANE = 1, FLOOR_PROBE = 2
+
+let warned = false
+const supported = (): boolean => {
+  if (_creator.dynamicBoneCreate) return true
+  if (!warned) { warned = true; console.warn("DynamicBone needs a newer host (no dynamicBoneCreate) — the animation shows as is") }
+  return false
+}
+
+const at = (c: DynamicBoneCurve, t: number): number => typeof c === "number" ? c : c[0] + (c[1] - c[0]) * t
+
+/** The model a bone belongs to: the topmost Model ancestor, else the topmost ancestor. */
+const modelOf = (n: Node): Node => {
+  let top: Node = n, model: Node | null = null
+  for (let p: Node | null = n; p; p = p.parent) { top = p; if (p instanceof Model) model = p }
+  return model ?? top
+}
+
+/** A capsule (or a sphere) riding a bone — what dynamic bones stay out of. Attach to a body bone:
+ *  `hips.aspect(DynamicBoneCollider, { radius: 0.12, to: 'Spine' })`. The capsule runs from
+ *  `offset` (the bone's origin by default) to the `to` bone's origin, or to `end` (both in the bone's
+ *  local space); neither = a sphere at `offset`. Picked up by every DynamicBone on the same model
+ *  with `colliders: 'auto'` / `'humanoid'`, or listed explicitly. */
+export class DynamicBoneCollider extends Aspect<"dynamicBoneCollider", Node> {
+  static readonly aspect = "dynamicBoneCollider"
+
+  /** Radius in metres, in the world: the bone's scale does not touch it (`offset` / `end` are in the bone's own units). */
+  radius = 0.1
+  /** Start of the capsule in the bone's local space (default: the bone's origin). */
+  offset: Vec3Like = [ 0, 0, 0 ]
+  /** End of the capsule in the bone's local space (a sphere when neither `end` nor `to` is set). */
+  end?: Vec3Like
+  /** The bone the capsule reaches (its origin), instead of `end`. */
+  to?: string
+
+  static fields: FieldMeta<DynamicBoneCollider> = {
+    radius: { min: 0, max: 2, step: 0.005 },
+    offset: { hidden: true },
+    end: { hidden: true },
+    to: { hidden: true },
+  }
+
+  private _id = 0
+
+  /** @internal the engine's collider id (0 when the host has none). */
+  get _colliderId(): number { return this._id }
+
+  private _segment(): [Vec3, Vec3] {
+    const a = new Vec3(this.offset)
+    if (this.to) {
+      const target = modelOf(this.node).bone(this.to)
+      if (!target) throw new Error(`DynamicBoneCollider: no bone '${this.to}' (the 'to' of '${this.node.name}')`)
+      const b = this.node.worldMatrix.invert().transformPoint(target.worldPosition)
+      return [ a, b ]
+    }
+    return [ a, this.end ? new Vec3(this.end) : a ]
+  }
+
+  onAttach(): void {
+    if (!supported()) return
+    const [ a, b ] = this._segment()
+    this._id = _creator.dynamicBoneColliderCreate!(this.node.id, a.x, a.y, a.z, b.x, b.y, b.z, this.radius)
+    DynamicBone._collidersChanged()
+  }
+
+  onReconfigure(): void {
+    if (!this._id) return
+    const [ a, b ] = this._segment()
+    _creator.dynamicBoneColliderSet!(this._id, a.x, a.y, a.z, b.x, b.y, b.z, this.radius)
+  }
+
+  onDetach(): void {
+    if (this._id) { _creator.dynamicBoneColliderDestroy!(this._id); this._id = 0; DynamicBone._collidersChanged() }
+  }
+}
+
+export class DynamicBone extends Aspect<"dynamicBone", Node> {
+  static readonly aspect = "dynamicBone"
+
+  /** Only these bones (by name) join the chain — the root always does, a bone left out takes its
+   *  subtree with it. Default: the root's whole subtree. */
+  bones?: string[]
+  /** Depth limit under the root (0 = no limit). */
+  depth = 0
+  /** Particle radius for the collisions, metres. */
+  radius: DynamicBoneCurve = 0.02
+  /** 0..1 — how fast a bone returns to the animated shape (per 1/60 s). 0 = a rope, 1 = rigid. */
+  stiffness: DynamicBoneCurve = 0.3
+  /** 0..1 — velocity lost per 1/60 s. 0.02 swings like a rope, 0.1 settles like a tail, 0.3 is honey. */
+  damping: DynamicBoneCurve = 0.1
+  /** m/s² downward. A hanging rest pose feels none of it (the bone length cancels it); a pose that
+   *  sticks out droops by as much as `stiffness` lets it. */
+  gravity: DynamicBoneCurve = 0
+  /** Max deviation from the animated direction, degrees per bone (0 = free). */
+  angleLimit: DynamicBoneCurve = 0
+  /** Relative mass per bone. A bone-length constraint moves its two ends in inverse proportion to
+   *  their masses (the root is kinematic): `[3, 1]` makes a tail's base carry its tip, `1` shares
+   *  evenly like a rope. */
+  mass: DynamicBoneCurve = 1
+  /** Bones (by name) that ride the animation exactly while their subtrees still simulate: a sheet's
+   *  several roots under one anchor (a cloak's seven strips under the spine), so ONE chain owns them all
+   *  and `link` ties neighbouring strips. */
+  pinned?: string[]
+  /** Metres a PINNED bone may be pushed off its animated place by a collider — a soft pin. Its particle
+   *  collides and takes the edge pushes like a free bone (the strip below hangs from where it IS) and is
+   *  drawn back to the animation when the collider leaves; the bone's local translation follows. A hard
+   *  pin (0) at a capsule's edge made the first free bone below it jitter: the edge push on a segment
+   *  with an immovable end is a lever, and a touch near the root threw the child out. 2–3 cm for a
+   *  cloak's roots under a shoulder capsule. */
+  pinGive = 0
+  /** 0..1 of the character's travel the chain takes rigidly (0 = the full whip on a dash, 1 = it
+   *  moves with the body and only the pose's own motion swings it). */
+  follow = 0
+  /** World wind, m/s². */
+  wind: Vec3Like = [ 0, 0, 0 ]
+  /** The BODY'S TURN, ≥ 0. Above 0 the chain lives in the parent bone's ROTATING frame: `damping` acts
+   *  against the body's rigid motion (its travel plus its spin), so a heavily damped cloak RIDES a turn —
+   *  sweeps round with the back — instead of standing in the world while the character spins under it and
+   *  being dragged round after. The turn's inertia comes back as the frame's forces, scaled by this value:
+   *  a centrifugal push `ω² · r` along each bone's animated direction from the axis (the hem, farthest
+   *  from the spine, flies out and, on the chain's length, up). The frame's own physics is built in: the
+   *  whip back when the turn starts and forward when it stops, Coriolis. 1 = the physical push; more = a
+   *  bigger fling. With low damping the frame reproduces a free particle (nothing is counted twice);
+   *  an animation's spine sway is ~1 % of a 900°/s turn. A rotation over 90° in one frame (a respawn
+   *  facing) counts as a snap, not a spin. 0 = the plain translational frame, no turn forces. */
+  spin = 0
+  /** With `spin`: the cloth's INERTIA against the body's turn, seconds — the cloth's own rotation follows the
+   *  body's with this time constant. It falls behind when a turn starts (by about ω·τ: 45° at 900°/s and 0.05),
+   *  rides once caught up, and keeps turning past the back when the body stops (the same angle, eased out over
+   *  τ). Smooth by construction. 0 = glued to the turn; large = the cloth stays in the world while the body spins. */
+  spinInertia = 0
+  /** 0..1 strength of the ties between neighbouring columns at the same depth (a cloak). */
+  link = 0
+  /** 0..1 blend from the animation (0) to the simulation (1). At 0 nothing is simulated and the
+   *  chain re-arms on the animated pose when it comes back. */
+  weight = 1
+  /** Substep rate, Hz (≤ 4 substeps per frame). */
+  rate = 60
+  /** A root jump longer than this in one frame (metres) resets the chain instead of whipping it. */
+  teleport = 1
+  /** What the particles stay above: `'none'`, `'probe'`, a height, or a world point. */
+  floor: DynamicBoneFloor = "none"
+  /** The floor plane's normal when `floor` is a point. */
+  floorNormal: Vec3Like = [ 0, 1, 0 ]
+  /** Friction against the floor, a Coulomb coefficient: a resting bone's slide loses up to
+   *  `floorFriction · gravity · dt` of speed per substep (0 = ice, 1 = a rubber sole). While a bone
+   *  rests on the floor or a collider, `stiffness` and `angleLimit` let go of it: the surface's
+   *  reaction outranks the spring, or a hem folded on the floor would run away along it. */
+  floorFriction = 0.5
+  /** Constraint passes per substep (1..8, default 4). Each pass shares every bone length between its
+   *  ends, so a pull needs passes to travel down a long chain: a long rope may want 8, a short tail is
+   *  fine with 2. */
+  iterations = 4
+  /** What the chain collides with (see DynamicBoneColliders). */
+  colliders: DynamicBoneColliders = "auto"
+  /** The cloth's outside — makes the colliders one-sided (see DynamicBoneSide). */
+  side: DynamicBoneSide = "none"
+  /** How firmly `guide()` targets are HELD through the constraint passes, 0..1. At 0 a guide is applied once
+   *  before the passes and the length / link passes may drag the bone back toward its un-guided neighbours
+   *  within the same frame; at 0.5 it is re-pulled after every pass with half its weight (converges with the
+   *  passes), at 1 with its full weight (a target the bone length cannot reach then jitters). */
+  guideHold = 0
+  /** The chain's EDGES collide with the capsules too — every bone segment and every link, not only the bones'
+   *  particles: a capsule thinner than a bone's length (a forearm) no longer passes through the cloth between
+   *  two bones. Off = particles only. */
+  edges = true
+
+  static fields: FieldMeta<DynamicBone> = {
+    depth: { min: 0, max: 32, step: 1 },
+    radius: { min: 0, max: 1, step: 0.005 },
+    stiffness: { min: 0, max: 1, step: 0.01 },
+    damping: { min: 0, max: 1, step: 0.01 },
+    gravity: { min: 0, max: 30, step: 0.1 },
+    angleLimit: { label: "Angle limit (°)", min: 0, max: 180, step: 1 },
+    mass: { min: 0.1, max: 10, step: 0.1 },
+    follow: { min: 0, max: 1, step: 0.01 },
+    link: { min: 0, max: 1, step: 0.01 },
+    weight: { min: 0, max: 1, step: 0.01 },
+    rate: { min: 30, max: 240, step: 10 },
+    teleport: { min: 0, max: 20, step: 0.1 },
+    floorFriction: { label: "Floor friction", min: 0, max: 1, step: 0.01 },
+    iterations: { min: 1, max: 8, step: 1 },
+    bones: { hidden: true },
+    pinned: { hidden: true },
+    pinGive: { label: "Pin give (m)", min: 0, max: 0.2, step: 0.005 },
+    wind: { hidden: true },
+    spin: { min: 0, max: 4, step: 0.05 },
+    spinInertia: { label: "Spin inertia (s)", min: 0, max: 0.3, step: 0.005 },
+    floor: { hidden: true },
+    floorNormal: { hidden: true },
+    colliders: { hidden: true },
+    side: { hidden: true },
+    guideHold: { min: 0, max: 1, step: 0.05 },
+    edges: { hidden: true },
+  }
+
+  private _id = 0
+  private _chain: Node[] = []
+  private _depths: number[] = []
+  private _blob = new Float32Array(0)
+  private _sent = new Float32Array(0)
+  private _floorKey = ""
+  private _colliderKey = ""
+  private _collidersDirty = true
+  private _collidersRef: DynamicBoneColliders | null = null
+  private _own: number[] = []          // colliders generated for 'humanoid' (destroyed with the aspect)
+  private _colliderSet: (Node | "auto" | "humanoid" | "none")[] | null = null
+
+  /** The bones of the chain, the root first. */
+  get chain(): readonly Node[] { return this._chain }
+
+  onAttach(): void {
+    if (!supported()) return
+    this._collect()
+    if (this._chain.length === 0) return
+    const n = this._chain.length
+    const bones = new Uint32Array(n)
+    for (let i = 0; i < n; i++) bones[i] = this._chain[i]!.id
+    this._blob = new Float32Array(HEADER + n * STRIDE)
+    this._fill(this._blob)
+    this._id = _creator.dynamicBoneCreate!(modelOf(this.node).id, bones, this._blob, this._links())
+    if (!this._id) { console.warn(`DynamicBone: the host refused the chain under '${this.node.name}'`); return }
+    this._sent = this._blob.slice()
+    this._floorKey = ""; this._colliderKey = ""; this._collidersDirty = true
+    this._pushFloor()
+    this._pushColliders()
+  }
+
+  onReconfigure(): void { this._sync() }
+
+  /** Every field is live: what changed since the last frame is pushed here, before the engine's stage. */
+  update(): void { this._sync() }
+
+  onDetach(): void {
+    if (this._id) { _creator.dynamicBoneDestroy!(this._id); this._id = 0 }
+    for (const id of this._own) _creator.dynamicBoneColliderDestroy!(id)
+    this._own = []
+    this._chain = []
+  }
+
+  /** Snap the chain onto the animated pose next frame (a teleport, a camera cut). */
+  reset(): void { if (this._id) _creator.dynamicBoneReset!(this._id) }
+
+  /** GUIDES: world points the bones' particles are drawn to each substep before the constraints —
+   *  weight 1 = there before them, the rest of the chain hangs, collides and links as before (a cape's
+   *  strips riding the arms). Replaces the previous set; an empty list clears. A late-phase script
+   *  (after the animator, before the engine's chain stage) refreshes it every frame. */
+  guide(rows: readonly { bone: Node, at: Vec3Like, weight: number }[]): void {
+    if (!this._id) return
+    const out: number[] = []
+    for (const r of rows) {
+      const i = this._chain.indexOf(r.bone)
+      if (i < 0) continue
+      out.push(i, cx(r.at), cy(r.at), cz(r.at), r.weight)
+    }
+    _creator.dynamicBoneTargets?.(this._id, out.length ? new Float32Array(out) : null)
+  }
+
+  /** The particles' world positions (the bones, then the leaves' virtual tips) — for a debug draw. */
+  get particles(): Vec3[] {
+    if (!this._id) return []
+    const out = new Float32Array((this._chain.length * 2) * 3)
+    const n = _creator.dynamicBoneParticles!(this._id, out)
+    const pts: Vec3[] = []
+    for (let i = 0; i < n; i++) pts.push(new Vec3(out[i * 3]!, out[i * 3 + 1]!, out[i * 3 + 2]!))
+    return pts
+  }
+
+  // ---- internals ----------------------------------------------------------------------------------
+
+  private _collect(): void {
+    const chain: Node[] = [], depths: number[] = []
+    const only = this.bones ? new Set(this.bones) : null
+    const walk = (n: Node, d: number): void => {
+      chain.push(n); depths.push(d)
+      if (this.depth > 0 && d >= this.depth) return
+      for (const c of n.children) {
+        if (only && !only.has(c.name)) continue
+        if (c.has(DynamicBone) || c.has(DynamicBoneCollider)) continue   // another chain / a body bone
+        walk(c, d + 1)
+      }
+    }
+    walk(this.node, 0)
+    this._chain = chain; this._depths = depths
+  }
+
+  private _fill(b: Float32Array): void {
+    const n = this._chain.length
+    let maxDepth = 0
+    for (const d of this._depths) if (d > maxDepth) maxDepth = d
+    b[0] = VERSION; b[1] = n; b[2] = STRIDE
+    b[3] = this.weight; b[4] = this.follow
+    b[5] = cx(this.wind); b[6] = cy(this.wind); b[7] = cz(this.wind)
+    b[8] = this.link; b[9] = this.rate; b[10] = this.teleport
+    b[11] = 0; b[12] = 0; b[13] = 0; b[14] = 0; b[15] = 0; b[16] = 1; b[17] = 0   // the floor goes through setFloor
+    b[18] = this.floorFriction
+    b[19] = Math.max(1, Math.min(8, Math.round(this.iterations)))
+    const side = this.side
+    const sideVec = side === "none" || side === "auto" ? null : side
+    b[20] = side === "none" ? 0 : side === "auto" ? 1 : 2
+    b[21] = sideVec ? cx(sideVec) : 0; b[22] = sideVec ? cy(sideVec) : 0; b[23] = sideVec ? cz(sideVec) : 0
+    b[24] = Math.max(0, Math.min(1, this.guideHold))
+    b[25] = this.edges ? 1 : 0
+    b[26] = Math.max(0, this.spin)
+    b[27] = Math.max(0, this.spinInertia)
+    const pin = this.pinned?.length ? new Set(this.pinned) : null
+    for (let i = 0; i < n; i++) {
+      const t = maxDepth > 0 ? this._depths[i]! / maxDepth : 0
+      const o = HEADER + i * STRIDE
+      b[o] = at(this.radius, t); b[o + 1] = at(this.stiffness, t); b[o + 2] = at(this.damping, t)
+      b[o + 3] = at(this.gravity, t); b[o + 4] = at(this.angleLimit, t)
+      const isPinned = !!pin && i > 0 && pin.has(this._chain[i]!.name)
+      b[o + 5] = isPinned ? -1 : at(this.mass, t)   // mass < 0 = pinned
+      b[o + 6] = isPinned ? Math.max(0, this.pinGive) : 0
+    }
+  }
+
+  /** Neighbour links: the bones at the same depth, in tree order, tied pairwise. */
+  private _links(): Uint16Array | undefined {
+    if (this.link <= 0) return undefined
+    const byDepth = new Map<number, number[]>()
+    this._depths.forEach((d, i) => { if (d > 0) (byDepth.get(d) ?? byDepth.set(d, []).get(d)!).push(i) })
+    const pairs: number[] = []
+    for (const row of byDepth.values()) for (let k = 0; k + 1 < row.length; k++) pairs.push(row[k]!, row[k + 1]!)
+    return pairs.length ? new Uint16Array(pairs) : undefined
+  }
+
+  private _sync(): void {
+    if (!this._id) return
+    this._fill(this._blob)
+    let changed = false
+    for (let i = 0; i < this._blob.length; i++) if (this._blob[i] !== this._sent[i]) { changed = true; break }
+    if (changed) { _creator.dynamicBoneSet!(this._id, this._blob); this._sent.set(this._blob) }
+    this._pushFloor()
+    this._pushColliders()
+  }
+
+  private _pushFloor(): void {
+    const f = this.floor
+    let key: string, mode: 0 | 1 | 2 = FLOOR_NONE, x = 0, y = 0, z = 0, nx = 0, ny = 1, nz = 0
+    if (f === "probe") { mode = FLOOR_PROBE; key = "probe" }
+    else if (f === "none" || f === undefined || f === null) { key = "none" }
+    else if (typeof f === "number") { mode = FLOOR_PLANE; y = f; key = `y${f}` }
+    else {
+      mode = FLOOR_PLANE; x = cx(f); y = cy(f); z = cz(f)
+      nx = cx(this.floorNormal); ny = cy(this.floorNormal); nz = cz(this.floorNormal)
+      key = `p${x},${y},${z},${nx},${ny},${nz}`
+    }
+    if (key === this._floorKey) return
+    this._floorKey = key
+    _creator.dynamicBoneSetFloor!(this._id, mode, x, y, z, nx, ny, nz)
+  }
+
+  private _pushColliders(): void {
+    // re-listed only when a collider came or went, or the field was reassigned (per frame otherwise)
+    if (!this._collidersDirty && this._collidersRef === this.colliders) return
+    this._collidersDirty = false
+    this._collidersRef = this.colliders
+    const ids: number[] = []
+    const model = modelOf(this.node)
+    const c = this.colliders
+    if (c === "auto" || c === "humanoid") {
+      for (const col of Aspect.all(DynamicBoneCollider)) if (col._colliderId && modelOf(col.node) === model) ids.push(col._colliderId)
+      if (c === "humanoid") { if (this._own.length === 0) this._makeHumanoid(model); ids.push(...this._own) }
+    } else if (Array.isArray(c)) {
+      for (const n of c) {
+        const col = n.get(DynamicBoneCollider)
+        if (col?._colliderId) ids.push(col._colliderId)
+      }
+    }
+    const key = ids.join(",")
+    if (key === this._colliderKey) return
+    this._colliderKey = key
+    _creator.dynamicBoneSetColliders!(this._id, new Uint32Array(ids))
+  }
+
+  /** Capsules on the standard humanoid bones, sized like the Ragdoll's parts. */
+  private _makeHumanoid(model: Node): void {
+    const find = (role: string): string | null => {
+      for (const name of HUMANOID[role] ?? []) if (model.bone(name)) return name
+      return null
+    }
+    let parts: ReturnType<typeof humanoidParts>
+    try { parts = humanoidParts(find) } catch { return }   // no hips: not a humanoid, nothing generated
+    for (const p of parts) {
+      const bone = model.bone(p.bone)
+      if (!bone) continue
+      const inv = bone.worldMatrix.invert()
+      let end: Vec3
+      const to = p.to ? model.bone(p.to) : null
+      if (to) end = inv.transformPoint(to.worldPosition)
+      else {
+        // a leaf: along the line from the parent part's origin through this bone
+        const parentBone = p.parent ? model.bone(p.parent) : null
+        const dir = parentBone ? bone.worldPosition.sub(parentBone.worldPosition) : new Vec3(0, 1, 0)
+        const local = inv.transformDirection(dir)
+        const len = local.length()
+        end = len > 1e-6 ? local.scale((p.length ?? 0.2) / len) : new Vec3(0, p.length ?? 0.2, 0)
+      }
+      const id = _creator.dynamicBoneColliderCreate!(bone.id, 0, 0, 0, end.x, end.y, end.z, p.radius ?? 0.05)
+      if (id) this._own.push(id)
+    }
+  }
+
+  /** @internal a collider attached / detached: every chain that collects them re-lists. */
+  static _collidersChanged(): void {
+    for (const d of Aspect.all(DynamicBone)) if (d._id && (d.colliders === "auto" || d.colliders === "humanoid")) { d._collidersDirty = true; d._pushColliders() }
+  }
+}

package/src/gl/{IK.ts → animation/IK.ts}

@@ -11,10 +11,10 @@
 // Pure SDK/JS: a handful of world-matrix reads + two quaternion writes per solve. A native solver can
 // slot in later behind the same API.
 
-import { Aspect } from "../core/Aspect"
-import { Vec3, type Vec3Like } from "../math/vec"
-import { Quat } from "../math/quat"
-import type { Node } from "./Node"
+import { Aspect } from "../../core/Aspect"
+import { Vec3, type Vec3Like } from "../../math/vec"
+import { Quat } from "../../math/quat"
+import type { Node } from "../Node"
 
 type Target = Node | Vec3Like
 

package/src/gl/{Locomotion.ts → animation/Locomotion.ts}

@@ -27,13 +27,13 @@
 // how fast the gait moves, where its foot contacts fall), so nothing here is a hand-measured table.
 // Give `angle` / `speed` only to override a measurement.
 
-import { Aspect } from "../core/Aspect"
-import { Vec3, cx, cz, type Vec3Like } from "../math/vec"
-import { Animator } from "./animation/Animator"
-import type { FeetOptions } from "./animation/Feet"
-import type { WarpOptions } from "./animation/Warp"
-import { CharacterController } from "./CharacterController"
-import type { Node } from "./Node"
+import { Aspect } from "../../core/Aspect"
+import { Vec3, cx, cz, type Vec3Like } from "../../math/vec"
+import { Animator } from "./Animator"
+import type { FeetOptions } from "./Feet"
+import type { WarpOptions } from "./Warp"
+import { CharacterController } from "../physics/CharacterController"
+import type { Node } from "../Node"
 
 /** How fast the character wants to go: the gait picks its clips and its speed. */
 export type Gait = "walk" | "run" | "sprint"

package/src/gl/animation/core.ts

@@ -18,19 +18,17 @@ import type { Node } from "../Node"
 /** A position on a blend axis (1D) or plane (2D). */
 export type BlendPosition = number | readonly [number, number]
 
-/** The transition time (seconds) a play / playLoop without `fade` uses. */
-export const DEFAULT_FADE = 0.2
-
 export type PlayOptions = {
-  /** Transition seconds — how long the difference to the pose the layer SHOWED takes to decay
-   *  (default 0.2; `0` = cut). Also the transition back at the end unless `fadeOut` overrides it. */
+  /** Transition seconds — how long the difference to the pose the layer SHOWED (its loop, a one-shot,
+   *  or rest) takes to decay. Default `0` = cut: a fade is always asked for, never implied. Also the
+   *  transition back to the loop at the end unless `fadeOut` overrides it. */
   fade?: number
   /** Transition seconds for the way in only (overrides `fade`). */
   fadeIn?: number
-  /** One-shots: the transition BACK at the end (overrides `fade`). It starts this long before the
-   *  clip ends — while it still plays — so the hand-over lands on the last pose, not after it. On a
-   *  layer with no loop to return to, giving `fadeOut` releases the layer at the end instead of
-   *  holding the last frame. */
+  /** One-shots: the transition BACK to the loop at the end (overrides `fade`; `0` = cut at the end).
+   *  It starts this long before the clip ends — while it still plays — so the hand-over lands on the
+   *  last pose, not after it. On a layer with no loop the clip HOLDS its last frame (a rock that broke
+   *  stays broken) — `anim.stop({ fade })` is the way back to rest. */
   fadeOut?: number
   /** Playback rate for this clip (default 1). */
   speed?: number
@@ -52,8 +50,8 @@ export type PlayOptions = {
 export type StopOptions = { fade?: number }
 
 export type LoopOptions = {
-  /** Transition seconds from whatever the layer shows — its previous loop, or a one-shot still
-   *  playing (default 0.2; `0` = cut). */
+  /** Transition seconds from whatever the layer shows — its previous loop, a one-shot still playing,
+   *  or rest. Default `0` = cut: a loop wanting a transition asks for one (`{ fade: 0.2 }`). */
   fade?: number
   /** Playback rate of the loop's clips (default 1). */
   speed?: number
@@ -145,6 +143,12 @@ export type ClipInfo = {
   turnAt(time: number): number
   /** the root's own speed at `time`, m/s — how fast the clip is moving the body right there */
   speedAt(time: number): number
+  /** the PELVIS' yaw relative to the clip's heading at `time` (rad, + = left, wrapped to ±π): the stance twist
+   *  the heading leaves out — an idle stands ~43° off the course it starts along, a stop's tail turns into that
+   *  stance while the heading holds. A controller that switches clips mid-pose can keep the PELVIS continuous
+   *  (turn the node by the difference between the two clips' values) where keeping the course would swing
+   *  the body. Without a baked heading: the pelvis' yaw at frame 0 throughout. */
+  pelvisYawAt(time: number): number
   /** the unit travel direction at `time` ([x, z], model space, held through stills) — integrate
    *  direction × d(travel) to reconstruct the root's 2D path (a treadmill display, a turn's arc) */
   directionAt(time: number): [number, number]
@@ -215,7 +219,7 @@ const ensureEvents = (): void => {
   if (eventsInstalled) return
   eventsInstalled = true
   _creator.setOnAnimatorEvent((animatorId, slot, type) => handlers.get(animatorId)?.(slot, type))
-  _creator.setOnAnimatorStep((animatorId, side, x, y, z) => stepHandlers.get(animatorId)?.(side, x, y, z))
+  _creator.setOnAnimatorStep?.((animatorId, side, x, y, z) => stepHandlers.get(animatorId)?.(side, x, y, z))
 }
 
 const settled = (slot: SlotRec): PlaybackRec => {
@@ -364,8 +368,8 @@ export class Core {
     const s = this.slotFor(L, name, clip)
     if (!s) return new Playback(settled({ name, clip, slot: -1, layer: L, inBlend: false }), this)
     if (s.inBlend) { console.warn(`Animator: '${name}' is part of this layer's loop — use playLoop() to change what it rests on`); return new Playback(settled(s), this) }
-    const fadeIn = o.fadeIn ?? o.fade ?? DEFAULT_FADE
-    const fadeOut = o.fadeOut ?? o.fade ?? DEFAULT_FADE
+    const fadeIn = o.fadeIn ?? o.fade ?? 0
+    const fadeOut = o.fadeOut ?? o.fade ?? 0
     const phase = this.entryPhase(L, o.phase)   // read BEFORE the play: what the layer shows now
     this.settleLayer(L)   // the layer had one source: whatever it was, this play takes over from it
     let resolve = (_n: boolean): void => {}
@@ -399,7 +403,7 @@ export class Core {
   // ---- loop ----
   loop(L: LayerRec, def: LoopDef, o: LoopOptions): Loop | undefined {
     if (!this.ensure()) return undefined
-    const fade = o.fade ?? DEFAULT_FADE
+    const fade = o.fade ?? 0
     const phase = this.entryPhase(L, o.phase)   // read BEFORE the members replace the layer's source
     if (L.loop) { L.loop.dead = true; for (const m of L.loop.members) m.slot.inBlend = false; L.loop = undefined }
     this.settleLayer(L)   // a one-shot on the layer is cut short by the new loop
@@ -576,6 +580,7 @@ export class Core {
       travelAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 1, time),
       turnAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 2, time),
       speedAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 3, time),
+      pelvisYawAt: (time: number) => { const v = _creator.animatorSlotCurveAt(id, slot, 6, time); return Math.atan2(Math.sin(v), Math.cos(v)) },
       directionAt: (time: number) => [ _creator.animatorSlotCurveAt(id, slot, 4, time), _creator.animatorSlotCurveAt(id, slot, 5, time) ] as [number, number],
       timeAtTurn: (yaw: number) => _creator.animatorSlotTimeAtTurn(id, slot, yaw),
       kneePoleAt: (side: "left" | "right", time: number) => {