lecodes-cli 0.18.2 → 0.19.0

package/runtime/sdk/gl/NavMesh.ts

@@ -0,0 +1,397 @@
+// Navigation meshes (docs/navmesh-plan.md). A level bakes ONE navmesh at dev time from its static
+// collision geometry (`lecodes navmesh bake` — the desktop host dumps every static Jolt body's
+// triangles, Recast builds the mesh in the CLI) and loads it at runtime; agents (`NavAgent`) walk
+// it through DetourCrowd, and the game asks it for paths, nearest points, walkability rays and
+// random spots. A scene FILE does the loading by itself:
+//
+//   env: { navmesh: { data: asset('./assets/nav/yard.navmesh'), agent: { radius: 0.4, height: 1.8 } } }
+//
+// Hand-built scenes call it once the level is complete:
+//
+//   const nav = await NavMesh.load(scene, { data: asset('./assets/nav/yard.navmesh') })
+//   nav?.findPath(a, b)                       // Vec3[] corners (+ .partial)
+//   enemy.aspect(NavAgent, { speed: 3 }).agent.goTo(player.position)
+//
+// Under `lecodes navmesh bake` the same call is where the geometry dump fires ("the scene is
+// complete"); on a host without navigation, or with a placeholder file, `load` resolves null and
+// agents stay inert — the project runs everywhere. All logic lives here in JS; the native side
+// (creator-nav) is the algorithms and the per-step hot path: ONE crowd update + ONE flat read per
+// fixed step for every agent in the scene (`NavCrowd`, a system the mesh attaches to its scene).
+
+import { fetch } from "../runtime/fetch"
+import { System } from "../core/Aspect"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+import { Geometry } from "./Geometry"
+import { Material } from "./Material"
+import { Mesh } from "./Mesh"
+import type { Node } from "./Node"
+import type { Scene } from "./Scene"
+import type { NavAgent } from "./NavAgent"
+
+// Fixed-order layouts — keep in step with creator-nav/creator-nav.h (CNAV_AGENT_* / CNAV_READ_*).
+export const NAV_AGENT = {
+  RADIUS: 0, HEIGHT: 1, MAX_SPEED: 2, MAX_ACCELERATION: 3, COLLISION_QUERY_RANGE: 4, PATH_OPTIMIZATION_RANGE: 5,
+  SEPARATION_WEIGHT: 6, AVOIDANCE: 7, INCLUDE_FLAGS: 8, EXCLUDE_FLAGS: 9, ANTICIPATE_TURNS: 10,
+  OPTIMIZE_VIS: 11, OPTIMIZE_TOPO: 12, COUNT: 13,
+} as const
+export const NAV_READ = {
+  POS_X: 0, POS_Y: 1, POS_Z: 2, VEL_X: 3, VEL_Y: 4, VEL_Z: 5, DVEL_X: 6, DVEL_Y: 7, DVEL_Z: 8,
+  STATE: 9, TARGET_STATE: 10, REMAINING: 11, PARTIAL: 12, STRIDE: 13,
+} as const
+const FLAGS_ALL = 0xffff
+const AREA_UNWALKABLE = 255
+const AREA_SKIP = 254
+
+/** The agent size a navmesh is built for (and the crowd's defaults). */
+export type NavAgentSize = {
+  /** metres — polygons are eroded by it. Default 0.4 */
+  radius?: number
+  /** metres. Default 1.8 */
+  height?: number
+  /** the highest step walked over, metres. Default 0.4 */
+  climb?: number
+  /** the steepest walkable slope, degrees. Default 50 */
+  slope?: number
+}
+
+export type NavMeshLoadOptions = {
+  /** `asset('./assets/nav/<scene>.navmesh')` — what `lecodes navmesh bake` writes. */
+  data: string
+  /** The agent size the bake uses (the file records it; the crowd reads it back). */
+  agent?: NavAgentSize
+  /** Named areas → traversal cost (1 = plain ground). Ids are assigned in this order (1..15); the
+   *  bake stores the names, queries and agents refer to them (`include` / `exclude`, `cost`). */
+  areas?: Record<string, number>
+}
+
+/** The file header `lecodes navmesh bake` wrote. */
+export type NavMeshInfo = {
+  version: number
+  agent: { radius: number, height: number, climb: number, slope: number }
+  cell: number
+  cellHeight: number
+  tileSize: number
+  bounds: [[number, number, number], [number, number, number]]
+  stats: { tiles: number, polys: number, verts: number, triangles: number, volumes: number, links: number }
+  meta: { scene?: string, areas?: Record<string, number>, costs?: Record<string, number>, [k: string]: unknown } | null
+}
+
+/** A straight path: the corners to walk, plus whether it stops short of the target. */
+export type NavPath = Vec3[] & { partial: boolean }
+
+export type NavQueryOptions = {
+  /** Only these areas (names). Default: every area. */
+  include?: string[]
+  /** Never these areas (names). */
+  exclude?: string[]
+  /** Search half-extents around each endpoint (how far off the mesh a point may be). Default [2, 4, 2]. */
+  extents?: Vec3Like
+}
+
+export type NavRaycastHit = { hit: boolean, point: Vec3, normal: Vec3 }
+
+type BakeConfig = { outDir: string, name?: string }
+
+const bakeConfig = (): BakeConfig | null => {
+  const g = (globalThis as unknown as { __lecodesNavmesh?: BakeConfig }).__lecodesNavmesh
+  return g && typeof g.outDir === "string" ? g : null
+}
+
+const hasNav = (): boolean => typeof _creatorNav !== "undefined" && _creatorNav !== null
+
+const scratch = new Float32Array(6)
+const pathScratch = new Float32Array(256 * 3)
+
+/** The crowd behind a scene's agents — a system `NavMesh.load` attaches to the scene so the whole
+ *  crowd advances once per fixed step, BEFORE every `NavAgent` applies its slot (`static after`). */
+export class NavCrowd extends System<"navCrowd"> {
+  static readonly aspect = "navCrowd"
+
+  /** @internal */ _mesh: NavMesh | null = null
+  /** @internal */ _id = 0
+  /** @internal */ _max = 0
+  /** @internal */ _buf = new Float32Array(0)
+  /** @internal */ _agents = new Set<NavAgent>()
+  /** @internal */ _step = 0
+
+  /** @internal Make room for one more agent (the crowd is re-created with double the slots; every
+   *  agent re-joins — slots change, targets are re-requested). */
+  _ensureCapacity(): boolean {
+    if (!this._mesh || !hasNav()) return false
+    if (this._id && this._agents.size < this._max) return true
+    const max = Math.max(16, this._max * 2)
+    const id = _creatorNav.crowdCreate(this._mesh.id, max, Math.max(0.6, this._mesh._maxRadius))
+    if (!id) { console.warn(`NavCrowd: ${_creatorNav.lastError()}`); return false }
+    const old = this._id
+    this._id = id
+    this._max = max
+    this._buf = new Float32Array(max * NAV_READ.STRIDE)
+    if (old) {
+      for (const a of this._agents) a._rejoin()
+      _creatorNav.crowdDestroy(old)
+    }
+    return true
+  }
+
+  updateFixed(dt: number): void {
+    if (!this._id) return
+    _creatorNav.crowdUpdate(this._id, dt)
+    _creatorNav.crowdRead(this._id, this._buf)
+    this._step++
+  }
+
+  onDetach(): void {
+    if (this._id && hasNav()) _creatorNav.crowdDestroy(this._id)
+    this._id = 0
+    this._max = 0
+    this._agents.clear()
+  }
+}
+
+export class NavMesh {
+  /** True while `lecodes navmesh bake` runs the app — skip menus and build the level straight away. */
+  static get baking(): boolean { return bakeConfig() !== null }
+
+  /** The navmesh agents bind to (the last one loaded; one per world at a time). */
+  static active: NavMesh | null = null
+
+  private static byScene = new WeakMap<Scene, NavMesh>()
+  private static overrides = new Map<number, number | string>()   // entity → area id / name / skip
+  private static warned = false
+  private static baked = false
+
+  /** Leave a static body out of the bake (`nav: false` in a scene file). */
+  static exclude(node: Node): void { NavMesh.overrides.set(node.id, AREA_SKIP) }
+  /** A static body nobody may walk on (`nav: 'unwalkable'`): its footprint is cut out. */
+  static unwalkable(node: Node): void { NavMesh.overrides.set(node.id, AREA_UNWALKABLE) }
+  /** A static body's surface belongs to a named area (`navArea: 'road'`; names from `load`'s `areas`). */
+  static area(node: Node, name: string): void { NavMesh.overrides.set(node.id, name) }
+  /** Forget every override (a scene rebuild). */
+  static clear(): void { NavMesh.overrides.clear() }
+
+  static of(scene: Scene): NavMesh | null { return NavMesh.byScene.get(scene) ?? null }
+
+  /** Load the level's navmesh — or, under `lecodes navmesh bake`, dump the collision geometry for
+   *  it. Resolves null when nothing was loaded (no bake yet, a host without navigation, bake mode). */
+  static async load(scene: Scene, opts: NavMeshLoadOptions): Promise<NavMesh | null> {
+    const bake = bakeConfig()
+    if (bake) { NavMesh.bake(bake, opts); return null }
+    if (!hasNav()) {
+      if (!NavMesh.warned) { NavMesh.warned = true; console.warn("NavMesh: this host has no navigation support — agents stay still") }
+      return null
+    }
+    if (_creatorNav.ready) await _creatorNav.ready()
+    let id = 0
+    try {
+      const resp = await fetch(opts.data, { useOnce: true })
+      if (resp.status >= 400) { console.warn(`NavMesh: no navmesh at ${opts.data} (HTTP ${resp.status}) — run \`lecodes navmesh bake\``); return null }
+      id = _creatorNav.load((resp as unknown as { _id: number })._id)
+      resp.dispose()
+    } catch (e) {
+      console.warn(`NavMesh: could not read ${opts.data}: ${String(e)}`)
+      return null
+    }
+    if (!id) { console.warn(`NavMesh: ${opts.data}: ${_creatorNav.lastError()}`); return null }
+    let info: NavMeshInfo
+    try { info = JSON.parse(_creatorNav.header(id)) as NavMeshInfo } catch { info = { version: 0 } as NavMeshInfo }
+    if (!info.stats || info.stats.polys === 0) {
+      console.warn(`NavMesh: ${opts.data} is a placeholder — run \`lecodes navmesh bake\``)
+      _creatorNav.unload(id)
+      return null
+    }
+    const previous = NavMesh.byScene.get(scene)
+    if (previous) previous.dispose()
+    const nav = new NavMesh(scene, id, info, opts)
+    NavMesh.byScene.set(scene, nav)
+    NavMesh.active = nav
+    return nav
+  }
+
+  readonly scene: Scene
+  /** @internal the host handle */
+  readonly id: number
+  readonly info: NavMeshInfo
+  /** The agent size the mesh was built for. */
+  readonly agent: { radius: number, height: number, climb: number, slope: number }
+  /** Named areas → ids (from the bake; `load`'s `areas` when the file has none). */
+  readonly areas: Record<string, number>
+  /** @internal the largest agent radius seen (sizes the crowd's grid) */
+  _maxRadius = 0
+  private _debug: Mesh[] = []
+  private _seed = 0x9e3779b9
+  private _disposed = false
+
+  private constructor(scene: Scene, id: number, info: NavMeshInfo, opts: NavMeshLoadOptions) {
+    this.scene = scene
+    this.id = id
+    this.info = info
+    this.agent = info.agent ?? { radius: opts.agent?.radius ?? 0.4, height: opts.agent?.height ?? 1.8, climb: opts.agent?.climb ?? 0.4, slope: opts.agent?.slope ?? 50 }
+    this._maxRadius = this.agent.radius
+    this.areas = info.meta?.areas ?? NavMesh.areaIds(opts.areas)
+    const costs = { ...(info.meta?.costs ?? {}), ...(opts.areas ?? {}) }
+    for (const [ name, cost ] of Object.entries(costs)) this.cost(name, cost)
+  }
+
+  private static areaIds(areas: Record<string, number> | undefined): Record<string, number> {
+    const out: Record<string, number> = {}
+    let next = 1
+    for (const name of Object.keys(areas ?? {})) {
+      if (next > 15) { console.warn(`NavMesh: more than 15 areas — "${name}" ignored`); break }
+      out[name] = next++
+    }
+    return out
+  }
+
+  /** The include/exclude flag mask for a list of area names (undefined = every area). */
+  flags(names?: string[]): number {
+    if (!names) return FLAGS_ALL
+    let mask = 0
+    for (const n of names) {
+      const id = this.areas[n]
+      if (id === undefined) { console.warn(`NavMesh: unknown area "${n}"`); continue }
+      mask |= 1 << id
+    }
+    return mask
+  }
+
+  private masks(opts?: NavQueryOptions): [number, number] {
+    return [ opts?.include ? this.flags(opts.include) : FLAGS_ALL, opts?.exclude ? this.flags(opts.exclude) : 0 ]
+  }
+
+  /** Traversal cost of a named area (1 = plain ground; > 1 = avoided when a cheaper way exists). */
+  cost(area: string, cost: number): void {
+    const id = this.areas[area]
+    if (id === undefined) { console.warn(`NavMesh: unknown area "${area}"`); return }
+    if (!this._disposed) _creatorNav.setAreaCost(this.id, id, cost)
+  }
+
+  /** The straight (string-pulled) path from → to. Empty when an endpoint is off the mesh;
+   *  `.partial` when the target is unreachable (the path ends at the closest polygon). */
+  findPath(from: Vec3Like, to: Vec3Like, opts?: NavQueryOptions & { maxCorners?: number }): NavPath {
+    const path = [] as unknown as NavPath
+    path.partial = false
+    if (this._disposed) return path
+    const [ inc, exc ] = this.masks(opts)
+    const e = opts?.extents
+    const max = Math.min(opts?.maxCorners ?? 256, 256)
+    const n = _creatorNav.findPath(this.id, cx(from), cy(from), cz(from), cx(to), cy(to), cz(to),
+      e ? cx(e) : 0, e ? cy(e) : 0, e ? cz(e) : 0, inc, exc, max, pathScratch)
+    const count = Math.abs(n)
+    for (let i = 0; i < count; i++) path.push(new Vec3(pathScratch[i * 3]!, pathScratch[i * 3 + 1]!, pathScratch[i * 3 + 2]!))
+    path.partial = n < 0
+    return path
+  }
+
+  /** The closest point on the mesh (within `extents` of `p`), or null. */
+  nearest(p: Vec3Like, opts?: NavQueryOptions): Vec3 | null {
+    if (this._disposed) return null
+    const [ inc, exc ] = this.masks(opts)
+    const e = opts?.extents
+    const ok = _creatorNav.nearest(this.id, cx(p), cy(p), cz(p), e ? cx(e) : 0, e ? cy(e) : 0, e ? cz(e) : 0, inc, exc, scratch)
+    return ok ? new Vec3(scratch[0]!, scratch[1]!, scratch[2]!) : null
+  }
+
+  /** Can an agent walk straight from → to? `hit` = a wall in between (at `point`, facing `normal`). */
+  raycast(from: Vec3Like, to: Vec3Like, opts?: NavQueryOptions): NavRaycastHit {
+    if (this._disposed) return { hit: true, point: new Vec3(cx(from), cy(from), cz(from)), normal: new Vec3(0, 0, 0) }
+    const [ inc, exc ] = this.masks(opts)
+    const hit = _creatorNav.raycast(this.id, cx(from), cy(from), cz(from), cx(to), cy(to), cz(to), inc, exc, scratch)
+    return { hit, point: new Vec3(scratch[0]!, scratch[1]!, scratch[2]!), normal: new Vec3(scratch[3]!, scratch[4]!, scratch[5]!) }
+  }
+
+  /** A random reachable point — within walking distance `radius` of `center`, or anywhere on the
+   *  mesh. Deterministic: the sequence depends only on the calls made (a seeded generator). */
+  randomPoint(center?: Vec3Like, radius = 0, opts?: NavQueryOptions): Vec3 | null {
+    if (this._disposed) return null
+    const [ inc, exc ] = this.masks(opts)
+    this._seed = (Math.imul(this._seed, 1664525) + 1013904223) >>> 0
+    const c = center && radius > 0
+    const ok = _creatorNav.randomPoint(this.id, c ? cx(center) : 0, c ? cy(center) : 0, c ? cz(center) : 0, c ? radius : 0, this._seed || 1, inc, exc, scratch)
+    return ok ? new Vec3(scratch[0]!, scratch[1]!, scratch[2]!) : null
+  }
+
+  /** Draw the polygon mesh (a flat unlit surface 3 cm above the walkable area). */
+  get debug(): boolean { return this._debug.length > 0 }
+  set debug(on: boolean) {
+    if (on === this.debug || this._disposed) return
+    if (!on) { for (const m of this._debug) m.destroy(); this._debug = []; return }
+    const tris = _creatorNav.debugTriangles(this.id)
+    const material = Material.unlit({ color: "#3b82f6" })
+    // Geometry indexes with 16-bit indices: chunk the soup
+    const perChunk = 65535 - (65535 % 3)
+    for (let start = 0; start < tris.length / 3; start += perChunk) {
+      const count = Math.min(perChunk, tris.length / 3 - start)
+      const vertices = new Float32Array(count * 3)
+      const normals = new Float32Array(count * 3)
+      const uv = new Float32Array(count * 2)
+      const indices = new Uint16Array(count)
+      for (let i = 0; i < count; i++) {
+        vertices[i * 3] = tris[(start + i) * 3]!
+        vertices[i * 3 + 1] = tris[(start + i) * 3 + 1]! + 0.03
+        vertices[i * 3 + 2] = tris[(start + i) * 3 + 2]!
+        normals[i * 3 + 1] = 1
+        indices[i] = i
+      }
+      const mesh = new Mesh(new Geometry(vertices, normals, indices, uv), material)
+      mesh.name = "navmesh-debug"
+      mesh.castShadows = false
+      this.scene.add(mesh)
+      this._debug.push(mesh)
+    }
+  }
+
+  /** @internal The scene's crowd system (created on the first agent). */
+  _crowd(): NavCrowd {
+    const existing = this.scene.get(NavCrowd)
+    if (existing && existing._mesh === this) return existing
+    const crowd = this.scene.system(NavCrowd).navCrowd
+    crowd._mesh = this
+    return crowd
+  }
+
+  /** Release the host handles (a scene teardown). Agents fall back to inert. */
+  dispose(): void {
+    if (this._disposed) return
+    this._disposed = true
+    this.debug = false
+    const crowd = this.scene.get(NavCrowd)
+    if (crowd && crowd._mesh === this) {
+      for (const a of crowd._agents) a._leave()
+      this.scene.removeSystem(NavCrowd)
+    }
+    if (hasNav()) _creatorNav.unload(this.id)
+    if (NavMesh.byScene.get(this.scene) === this) NavMesh.byScene.delete(this.scene)
+    if (NavMesh.active === this) NavMesh.active = null
+  }
+
+  // ---- bake mode ----------------------------------------------------------------------------------
+
+  private static bake(cfg: BakeConfig, opts: NavMeshLoadOptions): void {
+    if (NavMesh.baked) { console.log("[navmesh] a second NavMesh.load — skipped (one bake per run; use --entry per scene)"); return }
+    NavMesh.baked = true
+    if (!_creator.physicsStaticGeometry) {
+      console.error("[navmesh] error: this host cannot dump collision geometry (build the desktop host from packages/desktop, or update: lecodes desktop update)")
+      return
+    }
+    const areaIds = NavMesh.areaIds(opts.areas)
+    const ids: number[] = []
+    const areas: number[] = []
+    for (const [ entity, area ] of NavMesh.overrides) {
+      let id: number
+      if (typeof area === "string") {
+        id = areaIds[area] ?? -1
+        if (id < 0) { console.warn(`[navmesh] unknown area "${area}" on entity ${entity} — declare it in the navmesh 'areas'`); continue }
+      } else id = area
+      ids.push(entity)
+      areas.push(id)
+    }
+    const path = `${cfg.outDir}/${cfg.name ?? "scene"}.navgeo`
+    const n = _creator.physicsStaticGeometry(path, Uint32Array.from(ids), Uint8Array.from(areas))
+    if (n < 0) { console.error(`[navmesh] error: the geometry dump failed (${path})`); return }
+    if (n === 0) { console.error("[navmesh] error: no static collision geometry — agents walk on STATIC Physics bodies (Shape + Physics { motion: 'static' })"); return }
+    const agent = { radius: opts.agent?.radius ?? 0.4, height: opts.agent?.height ?? 1.8, climb: opts.agent?.climb ?? 0.4, slope: opts.agent?.slope ?? 50 }
+    console.log(`[navmesh] geometry ${n} triangles → ${path}`)
+    console.log(`[navmesh] config ${JSON.stringify({ agent, areas: areaIds, costs: opts.areas ?? {}, data: opts.data })}`)
+    console.log("[navmesh] done")
+  }
+}

package/runtime/sdk/gl/Ragdoll.ts

@@ -0,0 +1,270 @@
+// 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`).
+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. */
+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
+  }
+}