lecodes-sdk 0.20.2 → 1.1.0

package/src/gl/animation/AnimationClip.ts

@@ -82,6 +82,8 @@ export class AnimationClip {
   readonly _index: number
   /** @internal events: seconds + name, sorted (the engine gets them normalized via setClipEvents). */
   _events: { t: number, name: string }[] = []
+  /** @internal anchor spans per bone, seconds (the engine gets them normalized via setClipAnchors). */
+  _anchors: { bone: string, donor: string, spans: { from: number, to: number, socket: string, rotation: number, pin: number }[] }[] = []
 
   private constructor(set: number, index: number, info: ClipInfo) {
     this._set = set
@@ -119,6 +121,48 @@ export class AnimationClip {
     _creator.setClipEvents(this._set, this._index, new Float32Array(this._events.map((e) => (d > 0 ? e.t / d : 0))))
   }
 
+  /** ANCHOR SPANS for a bone — what an anchored IK chain ending in `bone` rides while this clip plays
+   *  (`IK.TwoBone` with `anchor`; the sockets come from `anim.sockets(...)`). `donor` names the socket
+   *  set of the gun the take was AUTHORED on ('' = the live set: no delta); `spans` = `[from, to,
+   *  socket, rotation?, pin?]` in SECONDS — the socket the hand is on through that window (`''` = free:
+   *  it rides the joint itself), `rotation` 0..1 how much of the socket's turn it takes (default 1),
+   *  `pin` 0..1 how much it sits ON the socket instead of keeping its own relation to it (default 0: a
+   *  magazine is REACHED, and the take's motion is what carries the hand there).
+   *  Gaps between spans = the chain's own socket, pinned by the chain's `anchorPin` — that is where a
+   *  hand holding the gun is nailed to the grip, so the layers below cannot slide it. A clip WITHOUT
+   *  anchors takes no part: the hand keeps the take's own relation to the gun. Part of the clip, like
+   *  events; `AnimationClip.from` carries them re-timed. Chainable.
+   *    reload.anchors('hand_l', { donor: 'tr15', spans: [[0.9, 1.4, 'mag'], [1.4, 2.0, ''], [2.0, 2.4, 'mag'], [2.4, 2.7, 'bolt']] }) */
+  anchors(bone: string, def: { donor?: string, spans?: readonly (readonly [number, number, string, number?, number?])[] }): this {
+    const spans = (def.spans ?? []).map(([ from, to, socket, rotation, pin ]) => ({
+      from: Math.min(Math.max(0, from), this.duration), to: Math.min(Math.max(0, to), this.duration), socket,
+      rotation: rotation ?? 1, pin: pin ?? 0,
+    })).filter((s) => s.to > s.from).sort((a, b) => a.from - b.from)
+    const rec = { bone, donor: def.donor ?? "", spans }
+    const i = this._anchors.findIndex((a) => a.bone === bone)
+    if (i >= 0) this._anchors[i] = rec
+    else this._anchors.push(rec)
+    this._pushAnchors(rec)
+    return this
+  }
+  /** Drop a bone's anchor spans. */
+  clearAnchors(bone: string): this {
+    this._anchors = this._anchors.filter((a) => a.bone !== bone)
+    _creator.setClipAnchors?.(this._set, this._index, bone, "", "", new Float32Array(0))
+    return this
+  }
+  private _pushAnchors(a: { bone: string, donor: string, spans: { from: number, to: number, socket: string, rotation: number, pin: number }[] }): void {
+    const d = this.duration
+    const spans = new Float32Array(a.spans.length * 4)
+    a.spans.forEach((s, i) => {
+      spans[i * 4] = d > 0 ? s.from / d : 0
+      spans[i * 4 + 1] = d > 0 ? s.to / d : 0
+      spans[i * 4 + 2] = s.rotation
+      spans[i * 4 + 3] = s.pin
+    })
+    _creator.setClipAnchors?.(this._set, this._index, a.bone, a.donor, a.spans.map((s) => s.socket).join("\n"), spans)
+  }
+
   /** Load ONE clip from a GLB: the file's only/first clip, or the one named / at the given index. */
   static load(source: string | FetchResponse, clip?: string | number): Promise<AnimationClip> {
     return AnimationClip._loadSet(source).then(([setId, infos]) => {
@@ -200,6 +244,14 @@ export class AnimationClip {
     out._events = windowed
       ? clip._events.filter((ev) => ev.t >= st - 1e-6 && ev.t <= e + 1e-6).map((ev) => ({ t: Math.min(Math.max(0, ev.t - st), e - st), name: ev.name }))
       : clip._events.map((ev) => ({ ...ev }))
+    // the anchor spans too: clipped to the window and re-timed (a mirrored clip keeps its bone names —
+    // mirror the sockets yourself if a hand's anchors must swap sides)
+    for (const a of clip._anchors) {
+      const spans = windowed
+        ? a.spans.map((s) => ({ ...s, from: Math.max(0, s.from - st), to: Math.min(e - st, s.to - st) })).filter((s) => s.to > s.from)
+        : a.spans.map((s) => ({ ...s }))
+      if (spans.length > 0 || a.donor) out.anchors(a.bone, { donor: a.donor, spans: spans.map((s) => [ s.from, s.to, s.socket, s.rotation ] as const) })
+    }
     return out
   }
 

package/src/gl/animation/Animator.ts

@@ -17,9 +17,12 @@
 // default. A clip may be replaced at any time; a one-shot on a layer with no loop holds its last frame.
 //
 // The surface, top to bottom: clips → playing → root motion → the feet and the warp (`anim.feet`,
-// `anim.warp` — locomotion's post-processing of the pose) → level of detail → engine-facing.
+// `anim.warp` — locomotion's post-processing of the pose) → sockets (what IK chains ride) → level of
+// detail → engine-facing.
 
 import { Aspect } from "../../core/Aspect"
+import { Vec3, type Vec3Like } from "../../math/vec"
+import { Quat, type QuatLike } from "../../math/quat"
 import type { Node } from "../Node"
 import type { AnimationClip } from "./AnimationClip"
 import { Core, type ActiveClip, type ClipInfo, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core"
@@ -122,6 +125,41 @@ export class Animator extends Aspect<"anim", Node> {
    *  turn too); on for a rig whose root carries the heading (`lecodes assets retarget --root-rotation yaw`). */
   get rootRotation(): boolean { return this._rootRotation }
   set rootRotation(on: boolean) { this._rootRotation = on; if (this._rootMotion) this._c.setRootMotion(true, on) }
+  /** The body's WORLD velocity this frame (m/s): what `anim.warp`'s stride and orientation fit the clips
+   *  to. A `Locomotion` feeds it itself; when you drive the gait by hand set it every frame (the
+   *  CharacterController's velocity, or your own). Reads back the last value fed. */
+  get motion(): readonly [number, number, number] { return this._motion }
+  set motion(v: { x: number, y: number, z: number } | readonly [number, number, number]) {
+    const [ x, y, z ] = Array.isArray(v) ? v as readonly [number, number, number] : [ (v as { x: number }).x, (v as { y: number }).y, (v as { z: number }).z ]
+    this._motion = [ x, y, z ]
+    this._c.setMotion(x, y, z)
+  }
+  private _motion: readonly [number, number, number] = [ 0, 0, 0 ]
+
+  // ---- sockets (what anchored IK chains ride — IK.ts) ---------------------------------------------
+  /** SOCKETS: named frames on a bone of this rig — a weapon's grip / magazine / bolt empties, placed in
+   *  the scene editor. A NODE socket is read by the engine every frame (a socket on a moving part
+   *  follows it); a `{ position, quaternion }` one is fixed in the bone's space. The default set is the
+   *  LIVE one (the weapon in the hands); `set: 'tr15'` names a DONOR set — the same sockets on the gun a
+   *  take was authored on, which a clip's `anchors()` refer to. Chainable.
+   *    arms.anim.sockets('ik_hand_gun', { grip_r: w.gripR, grip_l: w.gripL, mag: w.mag })
+   *    arms.anim.sockets('ik_hand_gun', { grip_l: { position: [0.03, -0.12, -0.05] } }, { set: 'tr15' }) */
+  sockets(joint: Node | string, table: Record<string, Node | { position?: Vec3Like, quaternion?: QuatLike }>, options: { set?: string } = {}): this {
+    const bone = typeof joint === "string" ? this.node.bone(joint) : joint
+    if (!bone) { console.warn(`Animator.sockets: no bone '${String(joint)}' under ${this.node.name || "the node"}`); return this }
+    const set = options.set ?? ""
+    for (const [ name, at ] of Object.entries(table)) {
+      if (typeof (at as Node).id === "number") this._c.setSocket(set, name, bone.id, (at as Node).id, null)
+      else {
+        const o = at as { position?: Vec3Like, quaternion?: QuatLike }
+        const p = new Vec3(o.position ?? [ 0, 0, 0 ]), q = o.quaternion ? new Quat(o.quaternion) : Quat.identity
+        this._c.setSocket(set, name, bone.id, 0, new Float32Array([ p.x, p.y, p.z, q.x, q.y, q.z, q.w ]))
+      }
+    }
+    return this
+  }
+  /** Drop a socket (the live set, or `set`). */
+  removeSocket(name: string, set = ""): this { this._c.removeSocket(set, name); return this }
 
   // ---- level of detail --------------------------------------------------------------------------
   /** `'auto'` (default): a character small on screen or out of view is evaluated every 2nd / 4th frame
@@ -130,9 +168,11 @@ export class Animator extends Aspect<"anim", Node> {
   get lod(): "auto" | "full" { return this._lod }
   set lod(v: "auto" | "full") { this._lod = v; _pushLod(this.node) }
 
-  // ---- engine-facing (a Locomotion, a bench) --------------------------------------------------
+  // ---- engine-facing (a Locomotion, a bench, the IK aspects) ----------------------------------
   /** The native animator's id — 0 until something is played or bound. */
   get _id(): number { return this._c.id }
+  /** @internal the engine-facing core (IK.ts) */
+  get _core(): Core { return this._c }
   /** Bind a clip to the base layer without playing it; its native slot (-1 = no such clip). */
   _slot(clip: string | number): number { return this._c.slotIndex(clip) }
 }

package/src/gl/animation/DynamicBone.ts

@@ -0,0 +1,482 @@
+// 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 (_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
+  /** 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"
+
+  /** 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() }
+  }
+}