lecodes-sdk 2.4.0 → 2.4.2

package/src/gl/animation/DynamicBone.ts

@@ -1,486 +1,549 @@
-// 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 SIDE of every collider marked `oneSided`: `'none'` = no side, every 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 hanging BEHIND
- *  the arms: the body's backward). A one-sided collider that is moving AWAY from that side — an arm swinging
- *  forward under the cape — puts a bone it has run into over to the side instead of carrying it: the arm
- *  passes through the cloth and the cape hangs behind it again, instead of being dragged round the body.
- *  Still, or moving toward the cloth, it pushes like any other collider, so cloth draped on an arm at rest
- *  stays where it is. Two-sided colliders (the body's) never read the 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 (DynamicBone.supported) return true
-  if (!warned) { warned = true; console.warn("DynamicBone: this host has no dynamic bones (DynamicBone.supported is false) — 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
-  /** ONE-SIDED: the cloth belongs on the chain's `side` of this capsule (see DynamicBone.side). While the capsule
-   *  moves away from that side it puts a bone it has run into over to the side instead of carrying it — an arm
-   *  under a cape may push the cape back, never drag it forward round the body. Needs a `side` on the DynamicBone. */
-  oneSided = false
-
-  static fields: FieldMeta<DynamicBoneCollider> = {
-    radius: { min: 0, max: 2, step: 0.005 },
-    offset: { hidden: true },
-    end: { hidden: true },
-    to: { hidden: true },
-    oneSided: { label: "One-sided" },
-  }
-
-  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, this.oneSided ? 1 : 0)
-    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, this.oneSided ? 1 : 0)
-  }
-
-  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"
-
-  /** Whether this host simulates dynamic bones. False, never a throw, on Web Lite and in headless
-   *  tests; there the aspect attaches, warns once, and `chain` stays empty. */
-  static get supported(): boolean { return typeof _creator !== "undefined" && !!_creator && typeof _creator.dynamicBoneCreate === "function" }
-
-  /** 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 — neighbours in THIS order, so list the strips round the ring
-   *  (front-left … back … front-right); the front stays open. */
-  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 tied pairwise, the columns in the order of `pinned` (a cloak's
-   *  strips listed round the ring) — columns not listed there follow in tree order. Tree order alone is the
-   *  engine's child order, which for a GLB is the file's node order REVERSED (Filament prepends each child), so
-   *  strips added to a rig later were tied across the body instead of to their neighbours: the ermine's cloak
-   *  had one true neighbour pair out of eight, the rest were rods through the chest. */
-  private _links(): Uint16Array | undefined {
-    if (this.link <= 0) return undefined
-    const index = new Map<Node, number>(this._chain.map((n, i) => [ n, i ]))
-    const column = new Int32Array(this._chain.length).fill(-1)   // per bone: the chain index of its depth-1 ancestor
-    for (let i = 1; i < this._chain.length; i++) {
-      const p = index.get(this._chain[i]!.parent!) ?? 0
-      column[i] = this._depths[i] === 1 ? i : column[p]!
-    }
-    const ring = this.pinned ?? []
-    const key = (i: number): number => { const k = ring.indexOf(this._chain[column[i]!]!.name); return k < 0 ? ring.length + column[i]! : k }
-    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()) {
-      row.sort((a, b) => key(a) - key(b))
-      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, 0)
-      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() }
-  }
-}
+// 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 — a write is pushed before the next step.
+
+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 SIDE of every collider marked `oneSided`: `'none'` = no side, every 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 hanging BEHIND
+ *  the arms: the body's backward). A one-sided collider that is moving AWAY from that side — an arm swinging
+ *  forward under the cape — puts a bone it has run into over to the side instead of carrying it: the arm
+ *  passes through the cloth and the cape hangs behind it again, instead of being dragged round the body.
+ *  Still, or moving toward the cloth, it pushes like any other collider, so cloth draped on an arm at rest
+ *  stays where it is. Two-sided colliders (the body's) never read the 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 (DynamicBone.supported) return true
+  if (!warned) { warned = true; console.warn("DynamicBone: this host has no dynamic bones (DynamicBone.supported is false) — 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"
+
+  private _radius: number = 0.1
+  /** Radius in metres, in the world: the bone's scale does not touch it (`offset` / `end` are in the bone's own units). */
+  get radius(): number { return this._radius }
+  set radius(v: number) { this._radius = v; this.dirty() }
+  private _offset: Vec3Like = [ 0, 0, 0 ]
+  /** Start of the capsule in the bone's local space (default: the bone's origin). */
+  get offset(): Vec3Like { return this._offset }
+  set offset(v: Vec3Like) { this._offset = v; this.dirty() }
+  private _end?: Vec3Like
+  /** End of the capsule in the bone's local space (a sphere when neither `end` nor `to` is set). */
+  get end(): Vec3Like | undefined { return this._end }
+  set end(v: Vec3Like | undefined) { this._end = v; this.dirty() }
+  private _to?: string
+  /** The bone the capsule reaches (its origin), instead of `end`. */
+  get to(): string | undefined { return this._to }
+  set to(v: string | undefined) { this._to = v; this.dirty() }
+  private _oneSided: boolean = false
+  /** ONE-SIDED: the cloth belongs on the chain's `side` of this capsule (see DynamicBone.side). While the capsule
+   *  moves away from that side it puts a bone it has run into over to the side instead of carrying it — an arm
+   *  under a cape may push the cape back, never drag it forward round the body. Needs a `side` on the DynamicBone. */
+  get oneSided(): boolean { return this._oneSided }
+  set oneSided(v: boolean) { this._oneSided = v; this.dirty() }
+
+  static fields: FieldMeta<DynamicBoneCollider> = {
+    radius: { min: 0, max: 2, step: 0.005 },
+    offset: { hidden: true },
+    end: { hidden: true },
+    to: { hidden: true },
+    oneSided: { label: "One-sided" },
+  }
+
+  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, this.oneSided ? 1 : 0)
+    DynamicBone._collidersChanged()
+  }
+
+  /** A field changed: re-describe the capsule to the engine. Every field is live. */
+  protected flush(): 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, this.oneSided ? 1 : 0)
+  }
+
+  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"
+
+  /** Whether this host simulates dynamic bones. False, never a throw, on Web Lite and in headless
+   *  tests; there the aspect attaches, warns once, and `chain` stays empty. */
+  static get supported(): boolean { return typeof _creator !== "undefined" && !!_creator && typeof _creator.dynamicBoneCreate === "function" }
+
+  private _bones?: string[]
+  /** 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. */
+  get bones(): string[] | undefined { return this._bones }
+  set bones(v: string[] | undefined) { this._bones = v; this.dirty() }
+  private _depth: number = 0
+  /** Depth limit under the root (0 = no limit). */
+  get depth(): number { return this._depth }
+  set depth(v: number) { this._depth = v; this.dirty() }
+  private _radius: DynamicBoneCurve = 0.02
+  /** Particle radius for the collisions, metres. */
+  get radius(): DynamicBoneCurve { return this._radius }
+  set radius(v: DynamicBoneCurve) { this._radius = v; this.dirty() }
+  private _stiffness: DynamicBoneCurve = 0.3
+  /** 0..1 — how fast a bone returns to the animated shape (per 1/60 s). 0 = a rope, 1 = rigid. */
+  get stiffness(): DynamicBoneCurve { return this._stiffness }
+  set stiffness(v: DynamicBoneCurve) { this._stiffness = v; this.dirty() }
+  private _damping: DynamicBoneCurve = 0.1
+  /** 0..1 — velocity lost per 1/60 s. 0.02 swings like a rope, 0.1 settles like a tail, 0.3 is honey. */
+  get damping(): DynamicBoneCurve { return this._damping }
+  set damping(v: DynamicBoneCurve) { this._damping = v; this.dirty() }
+  private _gravity: DynamicBoneCurve = 0
+  /** 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. */
+  get gravity(): DynamicBoneCurve { return this._gravity }
+  set gravity(v: DynamicBoneCurve) { this._gravity = v; this.dirty() }
+  private _angleLimit: DynamicBoneCurve = 0
+  /** Max deviation from the animated direction, degrees per bone (0 = free). */
+  get angleLimit(): DynamicBoneCurve { return this._angleLimit }
+  set angleLimit(v: DynamicBoneCurve) { this._angleLimit = v; this.dirty() }
+  private _mass: DynamicBoneCurve = 1
+  /** 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. */
+  get mass(): DynamicBoneCurve { return this._mass }
+  set mass(v: DynamicBoneCurve) { this._mass = v; this.dirty() }
+  private _pinned?: string[]
+  /** 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 — neighbours in THIS order, so list the strips round the ring
+   *  (front-left … back … front-right); the front stays open. */
+  get pinned(): string[] | undefined { return this._pinned }
+  set pinned(v: string[] | undefined) { this._pinned = v; this.dirty() }
+  private _pinGive: number = 0
+  /** 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. */
+  get pinGive(): number { return this._pinGive }
+  set pinGive(v: number) { this._pinGive = v; this.dirty() }
+  private _follow: number = 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). */
+  get follow(): number { return this._follow }
+  set follow(v: number) { this._follow = v; this.dirty() }
+  private _wind: Vec3Like = [ 0, 0, 0 ]
+  /** World wind, m/s². */
+  get wind(): Vec3Like { return this._wind }
+  set wind(v: Vec3Like) { this._wind = v; this.dirty() }
+  private _spin: number = 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. */
+  get spin(): number { return this._spin }
+  set spin(v: number) { this._spin = v; this.dirty() }
+  private _spinInertia: number = 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. */
+  get spinInertia(): number { return this._spinInertia }
+  set spinInertia(v: number) { this._spinInertia = v; this.dirty() }
+  private _link: number = 0
+  /** 0..1 strength of the ties between neighbouring columns at the same depth (a cloak). */
+  get link(): number { return this._link }
+  set link(v: number) { this._link = v; this.dirty() }
+  private _weight: number = 1
+  /** 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. */
+  get weight(): number { return this._weight }
+  set weight(v: number) { this._weight = v; this.dirty() }
+  private _rate: number = 60
+  /** Substep rate, Hz (≤ 4 substeps per frame). */
+  get rate(): number { return this._rate }
+  set rate(v: number) { this._rate = v; this.dirty() }
+  private _teleport: number = 1
+  /** A root jump longer than this in one frame (metres) resets the chain instead of whipping it. */
+  get teleport(): number { return this._teleport }
+  set teleport(v: number) { this._teleport = v; this.dirty() }
+  private _floor: DynamicBoneFloor = "none"
+  /** What the particles stay above: `'none'`, `'probe'`, a height, or a world point. */
+  get floor(): DynamicBoneFloor { return this._floor }
+  set floor(v: DynamicBoneFloor) { this._floor = v; this.dirty() }
+  private _floorNormal: Vec3Like = [ 0, 1, 0 ]
+  /** The floor plane's normal when `floor` is a point. */
+  get floorNormal(): Vec3Like { return this._floorNormal }
+  set floorNormal(v: Vec3Like) { this._floorNormal = v; this.dirty() }
+  private _floorFriction: number = 0.5
+  /** 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. */
+  get floorFriction(): number { return this._floorFriction }
+  set floorFriction(v: number) { this._floorFriction = v; this.dirty() }
+  private _iterations: number = 4
+  /** 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. */
+  get iterations(): number { return this._iterations }
+  set iterations(v: number) { this._iterations = v; this.dirty() }
+  private _colliders: DynamicBoneColliders = "auto"
+  /** What the chain collides with (see DynamicBoneColliders). */
+  get colliders(): DynamicBoneColliders { return this._colliders }
+  set colliders(v: DynamicBoneColliders) { this._colliders = v; this.dirty() }
+  private _side: DynamicBoneSide = "none"
+  /** The cloth's outside — makes the colliders one-sided (see DynamicBoneSide). */
+  get side(): DynamicBoneSide { return this._side }
+  set side(v: DynamicBoneSide) { this._side = v; this.dirty() }
+  private _guideHold: number = 0
+  /** 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). */
+  get guideHold(): number { return this._guideHold }
+  set guideHold(v: number) { this._guideHold = v; this.dirty() }
+  private _edges: boolean = true
+  /** 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. */
+  get edges(): boolean { return this._edges }
+  set edges(v: boolean) { this._edges = v; this.dirty() }
+
+  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()
+  }
+
+  /** Every field is live: a write marks the chain dirty and what changed is pushed here, once, before
+   *  the next step (the floor and the collider list are each keyed, so a point written every frame
+   *  costs one compare). */
+  protected flush(): 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 tied pairwise, the columns in the order of `pinned` (a cloak's
+   *  strips listed round the ring) — columns not listed there follow in tree order. Tree order alone is the
+   *  engine's child order, which for a GLB is the file's node order REVERSED (Filament prepends each child), so
+   *  strips added to a rig later were tied across the body instead of to their neighbours: the ermine's cloak
+   *  had one true neighbour pair out of eight, the rest were rods through the chest. */
+  private _links(): Uint16Array | undefined {
+    if (this.link <= 0) return undefined
+    const index = new Map<Node, number>(this._chain.map((n, i) => [ n, i ]))
+    const column = new Int32Array(this._chain.length).fill(-1)   // per bone: the chain index of its depth-1 ancestor
+    for (let i = 1; i < this._chain.length; i++) {
+      const p = index.get(this._chain[i]!.parent!) ?? 0
+      column[i] = this._depths[i] === 1 ? i : column[p]!
+    }
+    const ring = this.pinned ?? []
+    const key = (i: number): number => { const k = ring.indexOf(this._chain[column[i]!]!.name); return k < 0 ? ring.length + column[i]! : k }
+    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()) {
+      row.sort((a, b) => key(a) - key(b))
+      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, 0)
+      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() }
+  }
+}