lecodes-sdk 1.0.0 → 1.1.0

package/src/gl/physics/Ragdoll.ts

@@ -1,272 +1,451 @@
-// A ragdoll: the model's skeleton handed to physics. One rigid body per listed bone — a capsule from
-// the bone's origin to the next joint down the chain — joined to its parent part by a swing-twist
-// constraint (a cone + a twist range, or a one-way hinge for knees and elbows). Built once at
-// attach from the pose the model is in (that pose is the joints' neutral for the limits), and
-// switched on and off at will:
-//
-//   const rag = hero.aspect(Ragdoll).get(Ragdoll)!            // 'humanoid': the parts by bone name
-//   rag.activate({ velocity: capsule.controller.velocity })   // drops from its CURRENT pose, keeps its speed
-//   …
-//   rag.deactivate()                                           // the animator owns the bones again
-//
-// While active the engine writes the bodies' poses onto the bones every frame AFTER the animator, so
-// the listed bones hide whatever plays underneath; bones NOT listed (fingers, toes, the rest of a
-// spine chain between two parts) keep their animated local pose under the ragdolled parents, and
-// anything mounted on a bone (a weapon in the hand) rides along. Raycasts hit the parts and report
-// the bone node, so a shot knows which limb it struck — `impulse(bone, …)` pushes that part.
-//
-// The character CONTROLLER is yours to switch off (`node.removeAspect(CharacterController)`): a
-// capsule left standing would keep the fallen body from settling. `root` (the hips) tells you where
-// the body ended up when it is time to get back up.
-//
-// A fallen body is scenery, not an obstacle: by default (`collide: 'static'`) only the static world
-// and other ragdolls stop it — dynamic bodies, character controllers and vehicles pass through, so it
-// never shoves or blocks anything and the solver never pairs it with them — and once every part has
-// come to rest (`freeze`, or `freezeAfter` seconds at the latest) the parts turn static where they
-// lie: the pose holds, nothing can wake them, the solver skips them. Raycasts hit it either way, and
-// a frozen `'all'` body is an obstacle you can stand on.
-
-import { Aspect } from "../../core/Aspect"
-import type { FieldMeta } from "../../core/fields"
-import { cx, cy, cz, type Vec3Like } from "../../math/vec"
-import { Node } from "../Node"
-import { DEFAULT_FRICTION } from "./Physics"
-
-export interface RagdollHinge {
-  /** The hinge axis in the MODEL's space (its rest pose: +Z forward, +Y up, +X the model's left in
-   *  glTF). Perpendicular to the bone; the engine drops any component along it. */
-  axis: Vec3Like
-  /** The bend range about `axis` in degrees, relative to the pose the ragdoll was built in — a knee
-   *  is `{ axis: [1, 0, 0], min: 0, max: 140 }`: it folds one way only. */
-  min: number
-  max: number
-}
-
-export interface RagdollPart {
-  /** The bone the body sits on — its origin is the joint. */
-  bone: string
-  /** The bone the capsule points at (the next joint down). Omitted = a leaf: `length` along the line
-   *  from the parent part's origin (a head, a hand, a foot without toes). */
-  to?: string
-  /** The bone of the part this one hangs from (default: the previous part in the list). The root
-   *  has none. */
-  parent?: string
-  /** Capsule radius in metres (default 0.05). */
-  radius?: number
-  /** Length in metres: a leaf's, or an override of the distance to `to`. */
-  length?: number
-  /** This part's share of the ragdoll's `mass` (relative weight, default 1). */
-  mass?: number
-  /** Cone half-angle in degrees the part may swing off its parent (default 30). Ignored with `hinge`. */
-  swing?: number
-  /** Twist half-angle in degrees about its own axis (default 20). */
-  twist?: number
-  /** A one-way joint instead of the cone. */
-  hinge?: RagdollHinge
-}
-
-const VERSION = 2
-const HEADER = 12
-const STRIDE = 12
-
-// Bone names per humanoid role, tried in order: Mixamo / MotusMan / Unity-style first, then UE-style.
-// `node.bone()` already matches the part after a `:` / `|` prefix (`mixamorig:Hips`).
-/** @internal shared with DynamicBone's `colliders: 'humanoid'` */
-export const HUMANOID: Record<string, string[]> = {
-  hips: [ "Hips", "pelvis", "Pelvis", "hip" ],
-  spine: [ "Spine", "spine_01", "spine", "Spine1" ],
-  neck: [ "Neck", "neck_01", "neck" ],
-  head: [ "Head", "head" ],
-  upperArmL: [ "LeftArm", "upperarm_l", "LeftUpperArm", "UpperArm_L", "L_UpperArm" ],
-  foreArmL: [ "LeftForeArm", "lowerarm_l", "LeftLowerArm", "LowerArm_L", "L_Forearm" ],
-  handL: [ "LeftHand", "hand_l", "Hand_L", "L_Hand" ],
-  upLegL: [ "LeftUpLeg", "thigh_l", "LeftUpperLeg", "UpperLeg_L", "L_Thigh" ],
-  legL: [ "LeftLeg", "calf_l", "LeftLowerLeg", "LowerLeg_L", "L_Calf" ],
-  footL: [ "LeftFoot", "foot_l", "Foot_L", "L_Foot" ],
-  toeL: [ "LeftToeBase", "ball_l", "LeftToe", "Toe_L", "L_Toe" ],
-  upperArmR: [ "RightArm", "upperarm_r", "RightUpperArm", "UpperArm_R", "R_UpperArm" ],
-  foreArmR: [ "RightForeArm", "lowerarm_r", "RightLowerArm", "LowerArm_R", "R_Forearm" ],
-  handR: [ "RightHand", "hand_r", "Hand_R", "R_Hand" ],
-  upLegR: [ "RightUpLeg", "thigh_r", "RightUpperLeg", "UpperLeg_R", "R_Thigh" ],
-  legR: [ "RightLeg", "calf_r", "RightLowerLeg", "LowerLeg_R", "R_Calf" ],
-  footR: [ "RightFoot", "foot_r", "Foot_R", "R_Foot" ],
-  toeR: [ "RightToeBase", "ball_r", "RightToe", "Toe_R", "R_Toe" ],
-}
-
-/** The standard humanoid layout (hips, one spine capsule up to the neck, head, two-segment arms and
- *  legs, hands and feet where the rig has them): sizes for a ~1.8 m human, mass shares from body
- *  segment tables, knees and elbows as hinges that fold the natural way for a model standing in a
- *  T- or A-pose facing +Z. */
-/** @internal shared with DynamicBone's `colliders: 'humanoid'` */
-export const humanoidParts = (find: (role: string) => string | null): RagdollPart[] => {
-  const hips = find("hips"), spine = find("spine"), neck = find("neck"), head = find("head")
-  if (!hips) throw new Error("Ragdoll 'humanoid': no hips bone (Hips / pelvis) on this model — list the parts by name")
-  const parts: RagdollPart[] = []
-  parts.push({ bone: hips, to: spine ?? undefined, length: spine ? 0 : 0.2, radius: 0.12, mass: 15 })
-  const torso = spine ?? hips
-  if (spine) parts.push({ bone: spine, to: neck ?? head ?? undefined, length: neck || head ? 0 : 0.4, parent: hips, radius: 0.11, mass: 25, swing: 25, twist: 25 })
-  if (head) parts.push({ bone: head, parent: torso, radius: 0.1, length: 0.2, mass: 6, swing: 35, twist: 45 })
-  for (const side of [ "L", "R" ] as const) {
-    const upper = find(`upperArm${side}`), fore = find(`foreArm${side}`), hand = find(`hand${side}`)
-    if (upper) parts.push({ bone: upper, to: fore ?? undefined, length: fore ? 0 : 0.3, parent: torso, radius: 0.05, mass: 3, swing: 80, twist: 45 })
-    // the elbow: a T-pose arm along ±X folds its hand forward (+Z) — a negative turn about +Y on the
-    // left, a positive one on the right
-    if (upper && fore) parts.push({ bone: fore, to: hand ?? undefined, length: hand ? 0 : 0.28, parent: upper, radius: 0.04, mass: 2, twist: 30, hinge: { axis: [ 0, 1, 0 ], min: side === "L" ? -140 : 0, max: side === "L" ? 0 : 140 } })
-    if (upper && fore && hand) parts.push({ bone: hand, parent: fore, radius: 0.035, length: 0.16, mass: 1, swing: 30, twist: 20 })
-    const up = find(`upLeg${side}`), leg = find(`leg${side}`), foot = find(`foot${side}`), toe = find(`toe${side}`)
-    if (up) parts.push({ bone: up, to: leg ?? undefined, length: leg ? 0 : 0.45, parent: hips, radius: 0.08, mass: 10, swing: 60, twist: 30 })
-    // the knee: the shin (pointing down) swings its foot backward (−Z) for a positive turn about +X
-    if (up && leg) parts.push({ bone: leg, to: foot ?? undefined, length: foot ? 0 : 0.42, parent: up, radius: 0.06, mass: 5, twist: 10, hinge: { axis: [ 1, 0, 0 ], min: 0, max: 140 } })
-    if (up && leg && foot) parts.push({ bone: foot, to: toe ?? undefined, length: toe ? 0 : 0.2, parent: leg, radius: 0.04, mass: 2, swing: 30, twist: 15 })
-  }
-  return parts
-}
-
-export class Ragdoll extends Aspect<"ragdoll", Node> {
-  static readonly aspect = "ragdoll"
-
-  /** The parts: `'humanoid'` (default) finds the standard bones by name; a list places bodies on any
-   *  bones — parents before children. */
-  parts: RagdollPart[] | "humanoid" = "humanoid"
-  /** Total mass in kg (default 70), split between the parts by their `mass` shares. */
-  mass = 70
-  /** Friction of every part (default 0.6 — the physics default). */
-  friction = DEFAULT_FRICTION
-  /** Linear / angular damping of every part; 0 = Jolt's own 0.05. More angular damping settles a
-   *  flailing body sooner. */
-  linearDamping = 0
-  angularDamping = 0
-  /** What the parts collide with. `'static'` (default): the static geometry and other such ragdolls
-   *  only — dynamic bodies, character controllers and vehicles pass through a fallen body, which then
-   *  never shoves or blocks anything and costs nothing when they meet. `'all'`: a regular dynamic
-   *  body that bumps into everything (and gets kicked awake by everything). */
-  collide: "static" | "all" = "static"
-  /** Once every part has come to rest the parts turn static where they lie (default true): the pose
-   *  holds, nothing can wake a settled body and it costs the solver nothing — `deactivate()` /
-   *  `activate()` still work (activate makes it dynamic again). */
-  freeze = true
-  /** Seconds after `activate()` at which the body freezes whatever it is doing — a twitch on a slope
-   *  or a pile never sleeps on its own. 0 (default) = no cap. */
-  freezeAfter = 0
-
-  static fields: FieldMeta<Ragdoll> = {
-    mass: { min: 1, step: 5 },
-    friction: { min: 0, max: 2, step: 0.05 },
-    linearDamping: { label: "Linear damping", min: 0, max: 5, step: 0.05 },
-    angularDamping: { label: "Angular damping", min: 0, max: 5, step: 0.05 },
-    collide: { options: [ "static", "all" ] },
-    freezeAfter: { label: "Freeze after (s)", min: 0, max: 60, step: 0.5 },
-    parts: { hidden: true },
-  }
-
-  private _id = 0
-  private _active = false
-  private _bones: { name: string; node: Node }[] = []
-
-  onAttach(): void {
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
-    if (!_creator.ragdollCreate) {
-      console.warn("Ragdoll needs a newer host (no ragdollCreate) — the body will not fall")
-      return
-    }
-    const find = (role: string): string | null => {
-      for (const name of HUMANOID[role] ?? []) if (this.node.bone(name)) return name
-      return null
-    }
-    const parts = this.parts === "humanoid" ? humanoidParts(find) : this.parts
-    if (parts.length === 0) throw new Error("Ragdoll: no parts")
-
-    const n = parts.length
-    const bones = new Uint32Array(n * 2)
-    const s = new Float32Array(HEADER + n * STRIDE)
-    s[0] = VERSION; s[1] = n; s[2] = STRIDE; s[3] = this.friction; s[4] = this.linearDamping; s[5] = this.angularDamping
-    s[6] = this.collide === "all" ? 0 : 1; s[7] = this.freeze ? 1 : 0; s[8] = Math.max(0, this.freezeAfter)
-    let shares = 0
-    for (const p of parts) shares += p.mass ?? 1
-    this._bones = []
-    for (let i = 0; i < n; i++) {
-      const p = parts[i]!
-      const bone = this.node.bone(p.bone)
-      if (!bone) throw new Error(`Ragdoll: no bone '${p.bone}' on '${this.node.name}'`)
-      const to = p.to ? this.node.bone(p.to) : null
-      if (p.to && !to) throw new Error(`Ragdoll: no bone '${p.to}' (the 'to' of '${p.bone}') on '${this.node.name}'`)
-      let parent = -1
-      if (i > 0) {
-        parent = p.parent ? parts.findIndex((q, j) => j < i && q.bone === p.parent) : i - 1
-        if (parent < 0) throw new Error(`Ragdoll: the parent '${p.parent}' of '${p.bone}' must be listed before it`)
-      }
-      bones[i * 2] = bone.id
-      bones[i * 2 + 1] = to ? to.id : 0
-      const o = HEADER + i * STRIDE
-      s[o] = parent
-      s[o + 1] = p.radius ?? 0.05
-      s[o + 2] = p.length ?? 0
-      s[o + 3] = this.mass * (p.mass ?? 1) / shares
-      s[o + 4] = p.swing ?? 30
-      s[o + 5] = p.twist ?? 20
-      if (p.hinge) {
-        s[o + 6] = 1
-        s[o + 7] = cx(p.hinge.axis); s[o + 8] = cy(p.hinge.axis); s[o + 9] = cz(p.hinge.axis)
-        s[o + 10] = p.hinge.min; s[o + 11] = p.hinge.max
-      }
-      this._bones.push({ name: p.bone, node: bone })
-    }
-    this._id = _creator.ragdollCreate(this.node.id, bones, s)
-    if (!this._id) console.warn(`Ragdoll: the host refused the parts on '${this.node.name}'`)
-  }
-
-  onDetach(): void {
-    if (this._id) {
-      if (this._active) _creator.ragdollDeactivate!(this._id)
-      _creator.ragdollDestroy!(this._id)
-      this._id = 0
-    }
-    this._active = false
-    this._bones = []
-  }
-
-  /** Hand the bones to physics from the pose they are in right now. `velocity` (world m/s) is given
-   *  to every part — pass the character's, so a running body keeps travelling. */
-  activate(opts: { velocity?: Vec3Like } = {}): boolean {
-    if (!this._id) return false
-    const v = opts.velocity ?? [ 0, 0, 0 ]
-    this._active = _creator.ragdollActivate!(this._id, cx(v), cy(v), cz(v))
-    return this._active
-  }
-
-  /** Take the bones back: the animator's pose shows again from the next frame. */
-  deactivate(): void {
-    if (!this._id || !this._active) return
-    _creator.ragdollDeactivate!(this._id)
-    this._active = false
-  }
-
-  /** Physics owns the bones right now. */
-  get active(): boolean { return this._active }
-
-  /** Active and every part asleep (or frozen) — the body has come to rest. */
-  get settled(): boolean {
-    return this._active && !!this._id && !_creator.ragdollActive!(this._id)
-  }
-
-  /** The root part's bone (the hips): where the body is. */
-  get root(): Node | null { return this._bones[0]?.node ?? null }
-
-  /** The bones that carry a part, in order. */
-  get bones(): string[] { return this._bones.map((b) => b.name) }
-
-  /** The rigid-body id of a part (0 if none) — for the plain body calls. */
-  bodyOf(bone: string): number {
-    const i = this._bones.findIndex((b) => b.name === bone)
-    return i < 0 || !this._id ? 0 : _creator.ragdollBodyId!(this._id, i)
-  }
-
-  /** Push one part: an impulse in N·s, at a world point (a hit) or through its centre. Wakes the body. */
-  impulse(bone: string, v: Vec3Like, at?: Vec3Like): boolean {
-    const id = this.bodyOf(bone)
-    if (!id) return false
-    if (at && _creator.physicsApplyImpulseAt) _creator.physicsApplyImpulseAt(id, cx(v), cy(v), cz(v), cx(at), cy(at), cz(at))
-    else _creator.physicsApplyImpulse(id, cx(v), cy(v), cz(v))
-    return true
-  }
-}
+// A ragdoll: the model's skeleton handed to physics. One rigid body per listed bone — a capsule from
+// the bone's origin to the next joint down the chain — joined to its parent part by a swing-twist
+// constraint (a cone + a twist range, or a one-way hinge for knees and elbows) that carries a motor.
+// Built once at attach from the pose the model is in (that pose is the joints' neutral for the
+// limits); the limits themselves are LEARNED from the animation by default (`limits: 'clips'`: how
+// far each joint swings and twists over every clip bound to the model's animator, measured at the
+// first activation) — and switched on and off at will:
+//
+//   const rag = hero.aspect(Ragdoll).get(Ragdoll)!            // 'humanoid': the parts by bone name
+//   rag.activate()                                             // drops from its CURRENT pose, every bone
+//                                                              // keeps the motion it had (a swinging arm
+//                                                              // keeps swinging, a runner keeps travelling)
+//   rag.goLimp(0.4)                                            // a death: the joints give way over 0.4 s
+//   …
+//   rag.deactivate({ blend: 0.5 })                             // the animator takes the bones back and
+//   hero.anim.play('GetUpBack', { fade: 0.5 })                 // blends OUT of the fallen pose into this
+//
+// POWERED: every joint has a motor that pulls it toward the pose the animator shows — `strength`
+// (0..1) is how hard. With the root `anchored` the hips follow the animation kinematically, so a
+// standing character stays in its clip while physics jolts a limb: `hit(bone, impulse, at)` does
+// exactly that for a flinch — powers the body up, pushes the struck part, and hands the bones back
+// with a blend once the reaction is over. `strength` 0 with no anchor is a limp body.
+//
+// While active the engine writes the bodies' poses onto the bones every frame AFTER the animator, so
+// the listed bones hide whatever plays underneath; the bones NOT listed (fingers, toes, the rest of a
+// spine chain between two parts, the clavicles) follow the animation while the body is driven and
+// hold their pose as it goes limp. Anything mounted on a bone (a weapon in the hand) rides along.
+// Raycasts hit the parts and report the bone node, so a shot knows which limb it struck —
+// `impulse(bone, …)` pushes that part.
+//
+// The character CONTROLLER is yours to switch off for a fall (`node.removeAspect(CharacterController)`):
+// a capsule left standing would keep the fallen body from settling. `root` (the hips), `facing`
+// (on the back / prone / on a side) and `heading` (where the head points, degrees) tell you where and
+// how the body ended up when it is time to get back up.
+//
+// A fallen body is scenery, not an obstacle: by default (`collide: 'static'`) only the static world
+// and other ragdolls stop it — dynamic bodies, character controllers and vehicles pass through, so it
+// never shoves or blocks anything and the solver never pairs it with them — and once every part has
+// come to rest (`freeze`, or `freezeAfter` seconds at the latest) the parts turn static where they
+// lie: the pose holds, nothing can wake them, the solver skips them. Raycasts hit it either way, and
+// a frozen `'all'` body is an obstacle you can stand on.
+
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { Mathf } from "../../math/Mathf"
+import { cx, cy, cz, Vec3, type Vec3Like } from "../../math/vec"
+import { Node } from "../Node"
+import { DEFAULT_FRICTION } from "./Physics"
+
+export interface RagdollHinge {
+  /** The hinge axis in the MODEL's space (its rest pose: +Z forward, +Y up, +X the model's left in
+   *  glTF). Perpendicular to the bone; the engine drops any component along it. */
+  axis: Vec3Like
+  /** The bend range about `axis` in degrees, relative to the pose the ragdoll was built in — a knee
+   *  is `{ axis: [1, 0, 0], min: 0, max: 140 }`: it folds one way only. */
+  min: number
+  max: number
+}
+
+export interface RagdollPart {
+  /** The bone the body sits on — its origin is the joint. */
+  bone: string
+  /** The bone the capsule points at (the next joint down). Omitted = a leaf: `length` along the line
+   *  from the parent part's origin (a head, a hand, a foot without toes). */
+  to?: string
+  /** The bone of the part this one hangs from (default: the previous part in the list). The root
+   *  has none. */
+  parent?: string
+  /** Capsule radius in metres (default 0.05). */
+  radius?: number
+  /** Length in metres: a leaf's, or an override of the distance to `to`. */
+  length?: number
+  /** This part's share of the ragdoll's `mass` (relative weight, default 1). */
+  mass?: number
+  /** Cone half-angle in degrees the part may swing off its parent (default 30). Ignored with `hinge`. */
+  swing?: number
+  /** Twist half-angle in degrees about its own axis (default 20). */
+  twist?: number
+  /** A one-way joint instead of the cone. */
+  hinge?: RagdollHinge
+}
+
+/** How the body lies: on its back (the chest points up), prone (the chest points down), or on a side. */
+export type RagdollFacing = "up" | "down" | "side"
+
+export interface RagdollActivateOptions {
+  /** A LAUNCH added to every part's own motion (world m/s) — an explosion, a throw. The bones' own
+   *  motion (the run, the swinging arms) is measured by the engine and needs no help. */
+  velocity?: Vec3Like
+  /** The motors' strength from the first step (default: the current `strength`). */
+  strength?: number
+  /** The root anchored to the animation from the first step (default: the current `anchored`). */
+  anchored?: boolean
+}
+
+export interface RagdollDeactivateOptions {
+  /** Seconds the animator takes to transition OUT of the fallen pose into whatever plays next (a
+   *  get-up take started right after, or the loop). 0 (default) = a cut. Move the model node under
+   *  the hips before this call: the bones are handed back against its new transform. */
+  blend?: number
+}
+
+export interface RagdollHitOptions {
+  /** How long the body stays powered before the bones go back to the animator (s, default 0.6). */
+  duration?: number
+  /** The transition out of the reaction's last physical pose (s, default 0.25). */
+  blend?: number
+  /** The motors' strength during the reaction (default 1). */
+  strength?: number
+}
+
+const VERSION = 3
+const HEADER = 16
+const STRIDE = 12
+
+// Bone names per humanoid role, tried in order: Mixamo / MotusMan / Unity-style first, then UE-style.
+// `node.bone()` already matches the part after a `:` / `|` prefix (`mixamorig:Hips`).
+/** @internal shared with DynamicBone's `colliders: 'humanoid'` */
+export const HUMANOID: Record<string, string[]> = {
+  hips: [ "Hips", "pelvis", "Pelvis", "hip" ],
+  spine: [ "Spine", "spine_01", "spine", "Spine1" ],
+  neck: [ "Neck", "neck_01", "neck" ],
+  head: [ "Head", "head" ],
+  upperArmL: [ "LeftArm", "upperarm_l", "LeftUpperArm", "UpperArm_L", "L_UpperArm" ],
+  foreArmL: [ "LeftForeArm", "lowerarm_l", "LeftLowerArm", "LowerArm_L", "L_Forearm" ],
+  handL: [ "LeftHand", "hand_l", "Hand_L", "L_Hand" ],
+  upLegL: [ "LeftUpLeg", "thigh_l", "LeftUpperLeg", "UpperLeg_L", "L_Thigh" ],
+  legL: [ "LeftLeg", "calf_l", "LeftLowerLeg", "LowerLeg_L", "L_Calf" ],
+  footL: [ "LeftFoot", "foot_l", "Foot_L", "L_Foot" ],
+  toeL: [ "LeftToeBase", "ball_l", "LeftToe", "Toe_L", "L_Toe" ],
+  upperArmR: [ "RightArm", "upperarm_r", "RightUpperArm", "UpperArm_R", "R_UpperArm" ],
+  foreArmR: [ "RightForeArm", "lowerarm_r", "RightLowerArm", "LowerArm_R", "R_Forearm" ],
+  handR: [ "RightHand", "hand_r", "Hand_R", "R_Hand" ],
+  upLegR: [ "RightUpLeg", "thigh_r", "RightUpperLeg", "UpperLeg_R", "R_Thigh" ],
+  legR: [ "RightLeg", "calf_r", "RightLowerLeg", "LowerLeg_R", "R_Calf" ],
+  footR: [ "RightFoot", "foot_r", "Foot_R", "R_Foot" ],
+  toeR: [ "RightToeBase", "ball_r", "RightToe", "Toe_R", "R_Toe" ],
+}
+
+/** The standard humanoid layout (hips, one spine capsule up to the neck, head, two-segment arms and
+ *  legs, hands and feet where the rig has them): sizes for a ~1.8 m human, mass shares from body
+ *  segment tables, knees and elbows as hinges that fold the natural way for a model standing in a
+ *  T- or A-pose facing +Z. */
+/** @internal shared with DynamicBone's `colliders: 'humanoid'` */
+export const humanoidParts = (find: (role: string) => string | null): RagdollPart[] => {
+  const hips = find("hips"), spine = find("spine"), neck = find("neck"), head = find("head")
+  if (!hips) throw new Error("Ragdoll 'humanoid': no hips bone (Hips / pelvis) on this model — list the parts by name")
+  const parts: RagdollPart[] = []
+  parts.push({ bone: hips, to: spine ?? undefined, length: spine ? 0 : 0.2, radius: 0.12, mass: 15 })
+  const torso = spine ?? hips
+  if (spine) parts.push({ bone: spine, to: neck ?? head ?? undefined, length: neck || head ? 0 : 0.4, parent: hips, radius: 0.11, mass: 25, swing: 25, twist: 25 })
+  if (head) parts.push({ bone: head, parent: torso, radius: 0.1, length: 0.2, mass: 6, swing: 35, twist: 45 })
+  for (const side of [ "L", "R" ] as const) {
+    const upper = find(`upperArm${side}`), fore = find(`foreArm${side}`), hand = find(`hand${side}`)
+    if (upper) parts.push({ bone: upper, to: fore ?? undefined, length: fore ? 0 : 0.3, parent: torso, radius: 0.05, mass: 3, swing: 80, twist: 45 })
+    // the elbow: a T-pose arm along ±X folds its hand forward (+Z) — a negative turn about +Y on the
+    // left, a positive one on the right
+    if (upper && fore) parts.push({ bone: fore, to: hand ?? undefined, length: hand ? 0 : 0.28, parent: upper, radius: 0.04, mass: 2, twist: 30, hinge: { axis: [ 0, 1, 0 ], min: side === "L" ? -140 : 0, max: side === "L" ? 0 : 140 } })
+    if (upper && fore && hand) parts.push({ bone: hand, parent: fore, radius: 0.035, length: 0.16, mass: 1, swing: 30, twist: 20 })
+    const up = find(`upLeg${side}`), leg = find(`leg${side}`), foot = find(`foot${side}`), toe = find(`toe${side}`)
+    if (up) parts.push({ bone: up, to: leg ?? undefined, length: leg ? 0 : 0.45, parent: hips, radius: 0.08, mass: 10, swing: 60, twist: 30 })
+    // the knee: the shin (pointing down) swings its foot backward (−Z) for a positive turn about +X
+    if (up && leg) parts.push({ bone: leg, to: foot ?? undefined, length: foot ? 0 : 0.42, parent: up, radius: 0.06, mass: 5, twist: 10, hinge: { axis: [ 1, 0, 0 ], min: 0, max: 140 } })
+    if (up && leg && foot) parts.push({ bone: foot, to: toe ?? undefined, length: toe ? 0 : 0.2, parent: leg, radius: 0.04, mass: 2, swing: 30, twist: 15 })
+  }
+  return parts
+}
+
+export class Ragdoll extends Aspect<"ragdoll", Node> {
+  static readonly aspect = "ragdoll"
+
+  /** The parts: `'humanoid'` (default) finds the standard bones by name; a list places bodies on any
+   *  bones — parents before children. */
+  parts: RagdollPart[] | "humanoid" = "humanoid"
+  /** Total mass in kg (default 70), split between the parts by their `mass` shares. */
+  mass = 70
+  /** Friction of every part (default 0.6 — the physics default). */
+  friction = DEFAULT_FRICTION
+  /** Linear / angular damping of every part; 0 = Jolt's own 0.05. More angular damping settles a
+   *  flailing body sooner. */
+  linearDamping = 0
+  angularDamping = 0
+  /** What the parts collide with. `'static'` (default): the static geometry and other such ragdolls
+   *  only — dynamic bodies, character controllers and vehicles pass through a fallen body, which then
+   *  never shoves or blocks anything and costs nothing when they meet. `'all'`: a regular dynamic
+   *  body that bumps into everything (and gets kicked awake by everything). */
+  collide: "static" | "all" = "static"
+  /** Once every part of a LIMP body has come to rest the parts turn static where they lie (default
+   *  true): the pose holds, nothing can wake a settled body and it costs the solver nothing —
+   *  `deactivate()` / `activate()` still work (activate makes it dynamic again). A driven or anchored
+   *  body never freezes. */
+  freeze = true
+  /** Seconds limp after which the body freezes whatever it is doing — a twitch on a slope or a pile
+   *  never sleeps on its own. 0 (default) = no cap. */
+  freezeAfter = 0
+  /** The joint motors: the position spring's frequency in Hz (default 6 — higher = a stiffer, quicker
+   *  return to the animated pose) and damping ratio (default 1 = critical, no overshoot). */
+  driveFrequency = 6
+  driveDamping = 1
+  /** The motors' torque limit at strength 1, in N·m per kg of the part (default 12: ~180 N·m at the
+   *  hips of an 80 kg body, ~25 at a forearm). Lower = a hit displaces a limb more before the
+   *  animation wins it back. */
+  driveTorque = 12
+  /** Joint friction in N·m per kg of the part (default 0.3): a torque that resists any joint motion,
+   *  motor or not — a limp body folds instead of flopping like jelly. */
+  jointFriction = 0.3
+  /** Where the joint limits come from. `'clips'` (default): measured from the animation — at the first
+   *  activation that finds clips on the model's animator, every joint's swing and twist range over
+   *  every bound clip becomes its limit (plus `limitsMargin` on each side), so the motors never
+   *  target a pose the limits forbid and a limp body settles into poses the clips use; until clips
+   *  are bound the part table's cones apply. `'table'`: the part table's cones and hinges only. */
+  limits: "clips" | "table" = "clips"
+  /** Degrees added on each side of a learned range (default 10). */
+  limitsMargin = 10
+
+  static fields: FieldMeta<Ragdoll> = {
+    mass: { min: 1, step: 5 },
+    friction: { min: 0, max: 2, step: 0.05 },
+    linearDamping: { label: "Linear damping", min: 0, max: 5, step: 0.05 },
+    angularDamping: { label: "Angular damping", min: 0, max: 5, step: 0.05 },
+    collide: { options: [ "static", "all" ] },
+    freezeAfter: { label: "Freeze after (s)", min: 0, max: 60, step: 0.5 },
+    driveFrequency: { label: "Drive frequency (Hz)", min: 0.5, max: 30, step: 0.5 },
+    driveDamping: { label: "Drive damping", min: 0, max: 3, step: 0.1 },
+    driveTorque: { label: "Drive torque (N·m/kg)", min: 0, max: 100, step: 1 },
+    jointFriction: { label: "Joint friction (N·m/kg)", min: 0, max: 5, step: 0.05 },
+    limits: { options: [ "clips", "table" ] },
+    limitsMargin: { label: "Limits margin (deg)", min: 0, max: 45, step: 1 },
+    parts: { hidden: true },
+  }
+
+  private _id = 0
+  private _active = false
+  private _bones: { name: string; node: Node }[] = []
+  private _strength = 0
+  private _anchored = false
+  // the hips' frame: where the model's forward and up point, in the hips bone's own space (at attach)
+  private _hipsFwd = new Vec3(0, 0, 1)
+  private _hipsUp = new Vec3(0, 1, 0)
+  // goLimp: the strength ramp
+  private _ramp: { from: number; duration: number; t: number } | null = null
+  // hit: the pending hand-back
+  private _release: { left: number; blend: number } | null = null
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    if (!_creator.ragdollCreate) {
+      console.warn("Ragdoll needs a newer host (no ragdollCreate) — the body will not fall")
+      return
+    }
+    const find = (role: string): string | null => {
+      for (const name of HUMANOID[role] ?? []) if (this.node.bone(name)) return name
+      return null
+    }
+    const parts = this.parts === "humanoid" ? humanoidParts(find) : this.parts
+    if (parts.length === 0) throw new Error("Ragdoll: no parts")
+
+    const n = parts.length
+    const bones = new Uint32Array(n * 2)
+    const s = new Float32Array(HEADER + n * STRIDE)
+    s[0] = VERSION; s[1] = n; s[2] = STRIDE; s[3] = this.friction; s[4] = this.linearDamping; s[5] = this.angularDamping
+    s[6] = this.collide === "all" ? 0 : 1; s[7] = this.freeze ? 1 : 0; s[8] = Math.max(0, this.freezeAfter)
+    s[9] = Math.max(0, this.driveFrequency); s[10] = Math.max(0, this.driveDamping); s[11] = Math.max(0, this.driveTorque); s[12] = Math.max(0, this.jointFriction)
+    s[13] = this.limits === "clips" ? 1 : 0; s[14] = Math.max(0, this.limitsMargin)
+    let shares = 0
+    for (const p of parts) shares += p.mass ?? 1
+    this._bones = []
+    for (let i = 0; i < n; i++) {
+      const p = parts[i]!
+      const bone = this.node.bone(p.bone)
+      if (!bone) throw new Error(`Ragdoll: no bone '${p.bone}' on '${this.node.name}'`)
+      const to = p.to ? this.node.bone(p.to) : null
+      if (p.to && !to) throw new Error(`Ragdoll: no bone '${p.to}' (the 'to' of '${p.bone}') on '${this.node.name}'`)
+      let parent = -1
+      if (i > 0) {
+        parent = p.parent ? parts.findIndex((q, j) => j < i && q.bone === p.parent) : i - 1
+        if (parent < 0) throw new Error(`Ragdoll: the parent '${p.parent}' of '${p.bone}' must be listed before it`)
+      }
+      bones[i * 2] = bone.id
+      bones[i * 2 + 1] = to ? to.id : 0
+      const o = HEADER + i * STRIDE
+      s[o] = parent
+      s[o + 1] = p.radius ?? 0.05
+      s[o + 2] = p.length ?? 0
+      s[o + 3] = this.mass * (p.mass ?? 1) / shares
+      s[o + 4] = p.swing ?? 30
+      s[o + 5] = p.twist ?? 20
+      if (p.hinge) {
+        s[o + 6] = 1
+        s[o + 7] = cx(p.hinge.axis); s[o + 8] = cy(p.hinge.axis); s[o + 9] = cz(p.hinge.axis)
+        s[o + 10] = p.hinge.min; s[o + 11] = p.hinge.max
+      }
+      this._bones.push({ name: p.bone, node: bone })
+    }
+    // the model's forward / up in the hips' frame, for `facing` / `heading` later
+    const hips = this._bones[0]!.node
+    const hipsInv = hips.worldMatrix.invert()
+    const model = this.node.worldMatrix
+    this._hipsFwd = hipsInv.transformDirection(model.transformDirection([ 0, 0, 1 ])).normalize()
+    this._hipsUp = hipsInv.transformDirection(model.transformDirection([ 0, 1, 0 ])).normalize()
+    this._id = _creator.ragdollCreate(this.node.id, bones, s)
+    if (!this._id) console.warn(`Ragdoll: the host refused the parts on '${this.node.name}'`)
+    else if (this._strength > 0 || this._anchored) _creator.ragdollSetDrive?.(this._id, this._strength, this._anchored)
+  }
+
+  onDetach(): void {
+    if (this._id) {
+      if (this._active) _creator.ragdollDeactivate!(this._id, 0)
+      _creator.ragdollDestroy!(this._id)
+      this._id = 0
+    }
+    this._active = false
+    this._bones = []
+    this._ramp = null
+    this._release = null
+  }
+
+  /** Hand the bones to physics from the pose they are in right now, each moving as it did over the
+   *  last two frames (the engine measures: a runner keeps travelling, a swinging arm keeps swinging). */
+  activate(opts: RagdollActivateOptions = {}): boolean {
+    if (!this._id) return false
+    if (opts.strength !== undefined || opts.anchored !== undefined) {
+      this._strength = Mathf.clamp(opts.strength ?? this._strength, 0, 1)
+      this._anchored = opts.anchored ?? this._anchored
+      _creator.ragdollSetDrive?.(this._id, this._strength, this._anchored)
+    }
+    const v = opts.velocity ?? [ 0, 0, 0 ]
+    this._active = _creator.ragdollActivate!(this._id, cx(v), cy(v), cz(v))
+    this._ramp = null
+    this._release = null
+    return this._active
+  }
+
+  /** Take the bones back: the animator's pose shows again from the next frame — through a `blend`
+   *  out of the fallen pose when asked (play the get-up take right after, with its own fade: it
+   *  starts from where the body lies). */
+  deactivate(opts: RagdollDeactivateOptions = {}): void {
+    this._ramp = null
+    this._release = null
+    if (!this._id || !this._active) return
+    _creator.ragdollDeactivate!(this._id, Math.max(0, opts.blend ?? 0))
+    this._active = false
+  }
+
+  /** Physics owns the bones right now. */
+  get active(): boolean { return this._active }
+
+  /** Active and every part asleep (or frozen) — the body has come to rest. */
+  get settled(): boolean {
+    return this._active && !!this._id && !_creator.ragdollActive!(this._id)
+  }
+
+  /** The joint motors' strength, 0..1: how hard every joint is pulled toward the pose the animator
+   *  shows (0 = off — a limp body). Kept across activations. */
+  get strength(): number { return this._strength }
+  set strength(v: number) {
+    this._strength = Mathf.clamp(v, 0, 1)
+    this._ramp = null
+    if (this._id) _creator.ragdollSetDrive?.(this._id, this._strength, this._anchored)
+  }
+
+  /** The hips follow the animation kinematically (the body stands in its clip while physics moves the
+   *  limbs — hit reactions, a stagger). Off = the hips are a free body (a fall). */
+  get anchored(): boolean { return this._anchored }
+  set anchored(v: boolean) {
+    this._anchored = v
+    if (this._id) _creator.ragdollSetDrive?.(this._id, this._strength, this._anchored)
+  }
+
+  /** The joints give way: the strength ramps to 0 over `seconds` and the anchor comes off — a body
+   *  shot mid-stride keeps its pose for a moment and then collapses, instead of switching off. */
+  goLimp(seconds = 0.4): void {
+    this._anchored = false
+    if (seconds <= 0 || this._strength <= 0) { this.strength = 0; return }
+    this._ramp = { from: this._strength, duration: seconds, t: 0 }
+    if (this._id) _creator.ragdollSetDrive?.(this._id, this._strength, false)
+  }
+
+  /** A flinch: the body powers up anchored to its animation (if it is not already active), the struck
+   *  part gets the impulse (N·s, at a world point), and after `duration` the bones go back to the
+   *  animator through `blend`. On a limp body (a corpse) it is just the impulse. */
+  hit(bone: string, v: Vec3Like, at?: Vec3Like, opts: RagdollHitOptions = {}): boolean {
+    if (!this._id) return false
+    const limp = this._active && this._strength <= 0 && !this._anchored
+    if (!limp) {
+      if (!this._active) {
+        if (!this.activate({ strength: opts.strength ?? 1, anchored: true })) return false
+      }
+      this._release = { left: opts.duration ?? 0.6, blend: opts.blend ?? 0.25 }
+    }
+    return this.impulse(bone, v, at)
+  }
+
+  /** The root part's bone (the hips): where the body is. */
+  get root(): Node | null { return this._bones[0]?.node ?? null }
+
+  /** How the body lies: `'up'` on its back (the chest points up), `'down'` prone, `'side'` otherwise.
+   *  Read while it is down, to pick the get-up take. */
+  get facing(): RagdollFacing {
+    const hips = this._bones[0]?.node
+    if (!hips) return "up"
+    const y = hips.worldMatrix.transformDirection(this._hipsFwd).normalize().y
+    return y > 0.5 ? "up" : y < -0.5 ? "down" : "side"
+  }
+
+  /** Where the head points along the ground, as a yaw in degrees (the model node's `eulerAngles` y
+   *  that faces that way): where a get-up take that rises head-first ends up facing. A body still
+   *  upright answers with the way its chest faces. */
+  get heading(): number {
+    const hips = this._bones[0]?.node
+    if (!hips) return 0
+    const m = hips.worldMatrix
+    let d = m.transformDirection(this._hipsUp)
+    if (Math.hypot(d.x, d.z) < 0.3) d = m.transformDirection(this._hipsFwd)
+    return Mathf.RAD2DEG * Math.atan2(d.x, d.z)
+  }
+
+  /** The bones that carry a part, in order. */
+  get bones(): string[] { return this._bones.map((b) => b.name) }
+
+  /** The rigid-body id of a part (0 if none) — for the plain body calls. */
+  bodyOf(bone: string): number {
+    const i = this._bones.findIndex((b) => b.name === bone)
+    return i < 0 || !this._id ? 0 : _creator.ragdollBodyId!(this._id, i)
+  }
+
+  /** Push one part: an impulse in N·s, at a world point (a hit) or through its centre. Wakes the body. */
+  impulse(bone: string, v: Vec3Like, at?: Vec3Like): boolean {
+    const id = this.bodyOf(bone)
+    if (!id) return false
+    if (at && _creator.physicsApplyImpulseAt) _creator.physicsApplyImpulseAt(id, cx(v), cy(v), cz(v), cx(at), cy(at), cz(at))
+    else _creator.physicsApplyImpulse(id, cx(v), cy(v), cz(v))
+    return true
+  }
+
+  /** The strength ramp (goLimp) and the hit reaction's hand-back. */
+  update(dt: number): void {
+    if (this._ramp) {
+      const r = this._ramp
+      r.t += dt
+      const k = Mathf.clamp(r.t / r.duration, 0, 1)
+      this._strength = r.from * (1 - k) * (1 - k)   // eases out: the joints hold, then give
+      if (k >= 1) { this._strength = 0; this._ramp = null }
+      if (this._id) _creator.ragdollSetDrive?.(this._id, this._strength, this._anchored)
+    }
+    if (this._release && this._active) {
+      this._release.left -= dt
+      if (this._release.left <= 0) this.deactivate({ blend: this._release.blend })
+    }
+  }
+}