lecodes-gl-lite 2.0.0

package/src/vendor/creator-physics/js/index.ts

@@ -0,0 +1,515 @@
+// creator-physics' TypeScript side over the wasm build (dist/creatorPhysics.js): the physics bridge
+// the WEB hosts (viewer-lite's WebGL engine, lecodes-headless headless) hand to the app — the same
+// `_creator` physics / character / vehicle / ragdoll method shapes creator-gl exposes natively, so
+// the SDK never knows which host it runs on, and the SAME simulation (one C++ implementation, no TS
+// twin, no kinematic stand-in).
+//
+// The host supplies its scene graph (`PhysicsHost`): entity lookup with a local matrix per node, the
+// world matrix, two pose writers (a full world TRS for bodies, a world position for characters), the
+// hierarchy (parent lookup — the ground probe's "on the character or under it" rule), and the GLB
+// bytes behind a model root (mesh colliders). Each frame the host calls `frame(dt, fixedUpdate)`
+// (the protocol at the top of include/creator-physics/creator-physics.h) and, after its animators,
+// `syncRagdolls()`.
+//
+// `loadCreatorPhysics()` must have resolved before `createPhysicsBridge` — the web hosts await it in
+// their async setup so the SDK's first physics call finds the module ready.
+
+import createCreatorPhysics, { type CreatorPhysicsModule } from "../dist/creatorPhysics.js"
+
+export type Mat4Like = Float32Array | number[]
+
+export const POSE_STRIDE = 10
+const PULL_RENDER = 0
+const PULL_LIVE = 1
+
+export type PhysicsHost = {
+  /** Entity lookup (undefined when unknown): the local matrix + parent (0 = none). */
+  get(id: number): { id: number, m: Mat4Like, parent: number } | undefined
+  /** The entity's world matrix (column-major). */
+  world(id: number): Mat4Like
+  /** Write a world-space TRS onto the entity (into its parent's space when parented). */
+  setWorldTRS(id: number, x: number, y: number, z: number, qx: number, qy: number, qz: number, qw: number, sx: number, sy: number, sz: number): void
+  /** Write a world position only — the node keeps its rotation and scale (characters). */
+  setWorldPosition(id: number, x: number, y: number, z: number): void
+  /** The local matrix was rewritten in place (WebGL: worldMatrixNeedsUpdate). */
+  localMatrixChanged(id: number): void
+  parentOf(id: number): number
+  /** The GLB bytes behind a model root (mesh colliders from a model, glbTriangles). */
+  glbBytes?(entityId: number): ArrayBuffer | Uint8Array | undefined
+  /** A ragdoll let go with a blend: seed the animator that drives `jointEntityId` from the joints'
+   *  current locals so it transitions out of the fallen pose over `blend` seconds (creator-anim's
+   *  animatorSeedPose). */
+  seedAnimator?(jointEntityId: number, blend: number): void
+  /** Learned ragdoll limits: how far the clips bound to the animator driving `jointEntityId` rotate each
+   *  (child entity, parent entity) pair, measured against `frames` (8 floats per pair — creator-anim's
+   *  animatorJointRanges). 6 radians per pair, or null when nothing is bound yet. */
+  jointRanges?(jointEntityId: number, pairs: ArrayLike<number>, frames: Float32Array): Float32Array | null
+}
+
+let modulePromise: Promise<CreatorPhysicsModule> | null = null
+let loaded: CreatorPhysicsModule | null = null
+/** The wasm module, loaded once per process. */
+export const loadCreatorPhysics = (): Promise<CreatorPhysicsModule> => (modulePromise ??= createCreatorPhysics().then((m) => (loaded = m)))
+export const isCreatorPhysicsLoaded = (): boolean => loaded !== null
+
+// ---- heap helpers --------------------------------------------------------------------------------
+
+const withF32 = <T>(mod: CreatorPhysicsModule, values: ArrayLike<number>, fn: (ptr: number) => T): T => {
+  const ptr = mod._malloc(Math.max(4, values.length * 4))
+  mod.HEAPF32.set(values, ptr >> 2)
+  try { return fn(ptr) } finally { mod._free(ptr) }
+}
+const withU32 = <T>(mod: CreatorPhysicsModule, values: ArrayLike<number>, fn: (ptr: number) => T): T => {
+  const ptr = mod._malloc(Math.max(4, values.length * 4))
+  mod.HEAPU32.set(values, ptr >> 2)
+  try { return fn(ptr) } finally { mod._free(ptr) }
+}
+const withBytes = <T>(mod: CreatorPhysicsModule, bytes: Uint8Array, fn: (ptr: number) => T): T => {
+  const ptr = mod._malloc(Math.max(1, bytes.length))
+  mod.HEAPU8.set(bytes, ptr)
+  try { return fn(ptr) } finally { mod._free(ptr) }
+}
+const asBytes = (buf: ArrayBuffer | Uint8Array): Uint8Array => (buf instanceof Uint8Array ? buf : new Uint8Array(buf))
+
+// ---- matrix helpers (column-major 4×4) -----------------------------------------------------------
+
+/** A column-major TRS → a POSE (t xyz, r xyzw, s xyz) written at `out[o..o+10)`. */
+export const decomposeInto = (m: Mat4Like, out: Float32Array, o: number): void => {
+  const sx = Math.hypot(m[0], m[1], m[2]) || 1, sy = Math.hypot(m[4], m[5], m[6]) || 1, sz = Math.hypot(m[8], m[9], m[10]) || 1
+  // rotation rows/cols of the normalized upper 3×3 (r[row][col])
+  const r00 = m[0] / sx, r10 = m[1] / sx, r20 = m[2] / sx
+  const r01 = m[4] / sy, r11 = m[5] / sy, r21 = m[6] / sy
+  const r02 = m[8] / sz, r12 = m[9] / sz, r22 = m[10] / sz
+  const tr = r00 + r11 + r22
+  let x: number, y: number, z: number, w: number
+  if (tr > 0) {
+    const s = Math.sqrt(tr + 1) * 2
+    w = 0.25 * s; x = (r21 - r12) / s; y = (r02 - r20) / s; z = (r10 - r01) / s
+  } else if (r00 > r11 && r00 > r22) {
+    const s = Math.sqrt(1 + r00 - r11 - r22) * 2
+    w = (r21 - r12) / s; x = 0.25 * s; y = (r01 + r10) / s; z = (r02 + r20) / s
+  } else if (r11 > r22) {
+    const s = Math.sqrt(1 + r11 - r00 - r22) * 2
+    w = (r02 - r20) / s; x = (r01 + r10) / s; y = 0.25 * s; z = (r12 + r21) / s
+  } else {
+    const s = Math.sqrt(1 + r22 - r00 - r11) * 2
+    w = (r10 - r01) / s; x = (r02 + r20) / s; y = (r12 + r21) / s; z = 0.25 * s
+  }
+  out[o] = m[12]; out[o + 1] = m[13]; out[o + 2] = m[14]
+  out[o + 3] = x; out[o + 4] = y; out[o + 5] = z; out[o + 6] = w
+  out[o + 7] = sx; out[o + 8] = sy; out[o + 9] = sz
+}
+
+/** Rotate a local matrix about its own Y axis in place (a character's root-motion yaw). */
+const rotateLocalY = (m: Mat4Like, yaw: number): void => {
+  const cs = Math.cos(yaw), sn = Math.sin(yaw)
+  const x0 = m[0], x1 = m[1], x2 = m[2], z0 = m[8], z1 = m[9], z2 = m[10]
+  const a = m as number[]
+  a[0] = x0 * cs - z0 * sn; a[1] = x1 * cs - z1 * sn; a[2] = x2 * cs - z2 * sn
+  a[8] = x0 * sn + z0 * cs; a[9] = x1 * sn + z1 * cs; a[10] = x2 * sn + z2 * cs
+}
+
+// ---- shape pictures -------------------------------------------------------------------------------
+
+/** The triangles (9 floats each) of the convex hull Jolt would build from `positions` (xyz triples)
+ *  scaled by (sx, sy, sz) — the editor's picture of a `Shape { mesh: 'convex' }`, straight from the
+ *  simulation's own hull builder (256-point cap, its tolerances), so the overlay shows what collides.
+ *  Needs no world. Null when the module is not loaded or the hull is degenerate. */
+export const convexHullTriangles = (positions: ArrayLike<number>, sx = 1, sy = 1, sz = 1): Float32Array | null => {
+  const mod = loaded
+  if (!mod || positions.length < 12) return null
+  const shape = withF32(mod, positions, (vp) => mod._cphysShapeMesh(vp, Math.floor(positions.length / 3), 0, 0, 1, sx, sy, sz))
+  if (!shape) return null
+  const countPtr = mod._malloc(4)
+  const ptr = mod._cphysShapeTriangles(shape, countPtr)
+  const count = mod.HEAPU32[countPtr >> 2]
+  const out = ptr && count ? Float32Array.from(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + count)) : null
+  if (ptr) mod._free(ptr)
+  mod._free(countPtr)
+  mod._cphysShapeDestroy(shape)
+  return out
+}
+
+// ---- the bridge -----------------------------------------------------------------------------------
+
+export function createPhysicsBridge(host: PhysicsHost) {
+  const mod = loaded
+  if (!mod) throw new Error("creator-physics: await loadCreatorPhysics() before createPhysicsBridge()")
+
+  // scratch heap cells, allocated once
+  const pose = mod._malloc(POSE_STRIDE * 4)
+  const out8 = mod._malloc(32)
+  const u32a = mod._malloc(4)
+  let stateScratch = 0, stateScratchCount = 0
+  const stateBuffer = (count: number): number => {
+    if (count > stateScratchCount) {
+      if (stateScratch) mod._free(stateScratch)
+      stateScratch = mod._malloc(count * 4)
+      stateScratchCount = count
+    }
+    return stateScratch
+  }
+
+  const characterEntity = new Map<number, number>()   // charId → entity (the live shape swap writes the node)
+  // Per ragdoll: its part bones, the two most recent frames' post-animator world poses (activation
+  // hands physics each bone's measured motion; a driven body hands them on as the motors' target).
+  // Followers (the joints between two parts holding their pose while limp — creator-gl's
+  // writeRagdollFollowers) are not mirrored here: the headless twin records poses, not pixels.
+  type RagRec = { entities: number[], prev: Float32Array, cur: Float32Array, valid: number, dt: number, active: boolean, driven: boolean, learn: boolean, margin: number, learned: boolean }
+  const ragdolls = new Map<number, RagRec>()
+
+  // Learned limits (blob `limits` = 1): the joints' constraint frames from the simulation, the clips'
+  // ranges from the animator (host.jointRanges), the ranges + margin back to the simulation, which
+  // rebuilds the joints — creator-gl's learnRagdollLimits. Once, at the first activation with clips.
+  const learnLimits = (id: number, r: RagRec): void => {
+    if (!host.jointRanges) return
+    const n = r.entities.length
+    const frames = new Float32Array(n * 9)
+    const got = withF32(mod, frames, (fp) => { const c = mod._cphysRagdollJointFrames(id, fp); frames.set(mod.HEAPF32.subarray(fp >> 2, (fp >> 2) + n * 9)); return c })
+    if (got !== n) return
+    const pairs: number[] = [], pairFrames: number[] = [], pairPart: number[] = []
+    for (let i = 0; i < n; i++) {
+      const parent = frames[i * 9]
+      if (parent < 0) continue
+      pairs.push(r.entities[i], r.entities[parent])
+      for (let k = 1; k < 9; k++) pairFrames.push(frames[i * 9 + k])
+      pairPart.push(i)
+    }
+    if (pairs.length === 0) return
+    const ranges = host.jointRanges(r.entities[0], pairs, Float32Array.from(pairFrames))
+    if (!ranges) return
+    const limits = new Float32Array(n * 6)
+    const toDeg = 180 / Math.PI
+    for (let k = 0; k < pairPart.length; k++) {
+      for (let m = 0; m < 3; m++) {
+        limits[pairPart[k] * 6 + m * 2] = ranges[k * 6 + m * 2] * toDeg - r.margin
+        limits[pairPart[k] * 6 + m * 2 + 1] = ranges[k * 6 + m * 2 + 1] * toDeg + r.margin
+      }
+    }
+    if (withF32(mod, limits, (lp) => mod._cphysRagdollSetLimits(id, lp))) r.learned = true
+  }
+  const meshCache = new WeakMap<object, number[]>()   // GLB buffer → unscaled base shape per convex flag
+  let onEvent: ((a: number, b: number, type: number) => void) | null = null
+
+  const parentFn = mod.addFunction((e: number) => host.parentOf(e) | 0, "ii")
+  mod._cphysSetParentLookup(parentFn)
+  mod._cphysInit()   // the world exists from the start (creator-gl does the same at engine init)
+
+  // The entity's world transform → the scratch pose cell.
+  const poseOf = (entityId: number): number => {
+    decomposeInto(host.world(entityId), mod.HEAPF32, pose >> 2)
+    return pose
+  }
+  const read3 = (out: Float32Array, ptr: number): void => {
+    const f = mod.HEAPF32, o = ptr >> 2
+    out[0] = f[o]; out[1] = f[o + 1]; out[2] = f[o + 2]
+  }
+
+  // Pulled poses → the host's entities.
+  const applyBodies = (n: number): void => {
+    if (n === 0) return
+    const ids = mod.HEAPU32, idsO = mod._cphysPulledIds() >> 2
+    const f = mod.HEAPF32, o = mod._cphysPulledPoses() >> 2
+    for (let i = 0; i < n; i++) {
+      const p = o + i * POSE_STRIDE
+      host.setWorldTRS(ids[idsO + i], f[p], f[p + 1], f[p + 2], f[p + 3], f[p + 4], f[p + 5], f[p + 6], f[p + 7], f[p + 8], f[p + 9])
+    }
+  }
+  const applyCharacters = (n: number): void => {
+    if (n === 0) return
+    const ids = mod.HEAPU32, idsO = mod._cphysPulledIds() >> 2
+    const f = mod.HEAPF32, o = mod._cphysPulledPoses() >> 2
+    for (let i = 0; i < n; i++) {
+      const p = o + i * POSE_STRIDE
+      host.setWorldPosition(ids[idsO + i], f[p], f[p + 1], f[p + 2])
+    }
+  }
+
+  const glbBase = (entityId: number, convex: boolean): number => {
+    const buf = host.glbBytes?.(entityId)
+    if (!buf) return 0
+    let cached = meshCache.get(buf)
+    if (!cached) { cached = [0, 0]; meshCache.set(buf, cached) }
+    const slot = convex ? 1 : 0
+    if (!cached[slot]) {
+      const bytes = asBytes(buf)
+      cached[slot] = withBytes(mod, bytes, (p) => mod._cphysShapeMeshFromGlb(p, bytes.length, convex ? 1 : 0))
+    }
+    return cached[slot]
+  }
+
+  const bodyWithShape = (entityId: number, shapeId: number, motion: number, mass: number, sensor: boolean, pickOnly: boolean): number =>
+    shapeId ? mod._cphysBodyCreate(entityId, shapeId, motion | 0, mass, sensor ? 1 : 0, pickOnly ? 1 : 0, 1, poseOf(entityId)) : 0
+  // Legacy coupled shape+body: the shape lives only as long as the body holds it.
+  const legacyBody = (entityId: number, shapeId: number, motion: number, mass: number): number => {
+    const body = bodyWithShape(entityId, shapeId, motion, mass, false, false)
+    if (shapeId) mod._cphysShapeDestroy(shapeId)
+    return body
+  }
+
+  const methods = {
+    physicsHasSupport: (): boolean => true,
+    physicsConfigure(gx: number, gy: number, gz: number, maxBodies: number): void { mod._cphysConfigure(gx, gy, gz, (maxBodies | 0) > 0 ? maxBodies | 0 : 0) },
+    setInterpolation(enabled: boolean): void { mod._cphysSetInterpolation(enabled ? 1 : 0) },
+
+    // --- shapes ---
+    physicsBuildBox: (hx: number, hy: number, hz: number): number => mod._cphysShapeBox(hx, hy, hz),
+    physicsBuildSphere: (radius: number): number => mod._cphysShapeSphere(radius),
+    physicsBuildCylinder: (halfHeight: number, radius: number): number => mod._cphysShapeCylinder(halfHeight, radius),
+    physicsBuildCapsule: (halfHeight: number, radius: number): number => mod._cphysShapeCapsule(halfHeight, radius),
+    physicsBuildMesh(vertices: Float32Array, indices: Uint32Array, convex: boolean, sx: number, sy: number, sz: number): number {
+      return withF32(mod, vertices, (vp) => withU32(mod, indices, (ip) =>
+        mod._cphysShapeMesh(vp, Math.floor(vertices.length / 3), ip, indices.length, convex ? 1 : 0, sx, sy, sz)))
+    },
+    physicsBuildMeshFromEntity(entityId: number, convex: boolean, sx: number, sy: number, sz: number): number {
+      const base = glbBase(entityId, convex)
+      return base ? mod._cphysShapeScaled(base, sx, sy, sz) : 0
+    },
+    physicsBuildHeightField(heights: Float32Array, sizeX: number, sizeZ: number, cellSize: number, holes: Uint8Array | null, sx: number, sy: number, sz: number): number {
+      return withF32(mod, heights, (hp) => holes
+        ? withBytes(mod, holes, (op) => mod._cphysShapeHeightField(hp, sizeX, sizeZ, cellSize, op, sx, sy, sz))
+        : mod._cphysShapeHeightField(hp, sizeX, sizeZ, cellSize, 0, sx, sy, sz))
+    },
+    physicsUpdateHeightField(shapeId: number, heights: Float32Array, sizeX: number, sizeZ: number, x0: number, z0: number, w: number, h: number, holes: Uint8Array | null): void {
+      withF32(mod, heights, (hp) => holes
+        ? withBytes(mod, holes, (op) => mod._cphysShapeUpdateHeightField(shapeId, hp, sizeX, sizeZ, x0, z0, w, h, op))
+        : mod._cphysShapeUpdateHeightField(shapeId, hp, sizeX, sizeZ, x0, z0, w, h, 0))
+    },
+    glbTriangles(entityId: number): Float32Array {
+      const buf = host.glbBytes?.(entityId)
+      if (!buf) return new Float32Array(0)
+      const bytes = asBytes(buf)
+      const ptr = withBytes(mod, bytes, (p) => mod._cphysGlbTriangles(p, bytes.length, u32a))
+      if (!ptr) return new Float32Array(0)
+      const count = mod.HEAPU32[u32a >> 2]
+      const out = Float32Array.from(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + count))
+      mod._free(ptr)
+      return out
+    },
+    physicsSetShapeOrigin(shapeId: number, x: number, y: number, z: number): void { mod._cphysShapeSetOrigin(shapeId, x, y, z) },
+    physicsSetBodyShape(bodyId: number, shapeId: number, updateMass: boolean): void { mod._cphysBodySetShape(bodyId, shapeId, updateMass ? 1 : 0) },
+    physicsDestroyShape(shapeId: number): void { mod._cphysShapeDestroy(shapeId) },
+
+    // --- bodies ---
+    physicsCreateBody: (entityId: number, shapeId: number, motion: number, mass: number, sensor: boolean, pickOnly: boolean): number =>
+      bodyWithShape(entityId, shapeId, motion, mass, sensor, pickOnly),
+    physicsSetPickable(bodyId: number, pickable: boolean): void { mod._cphysBodySetPickable(bodyId, pickable ? 1 : 0) },
+    physicsSetFriction(bodyId: number, friction: number): void { mod._cphysBodySetFriction(bodyId, friction) },
+    physicsGetFriction: (bodyId: number): number => mod._cphysBodyGetFriction(bodyId),
+    physicsRaycast(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDist: number, out?: Float32Array): number {
+      const hit = mod._cphysRaycast(ox, oy, oz, dx, dy, dz, maxDist, out8)
+      if (hit && out) out.set(mod.HEAPF32.subarray(out8 >> 2, (out8 >> 2) + Math.min(7, out.length)))
+      return hit
+    },
+    physicsCreateBox: (entityId: number, hx: number, hy: number, hz: number, motionType: number, mass: number): number =>
+      legacyBody(entityId, mod._cphysShapeBox(hx, hy, hz), motionType, mass),
+    physicsCreateSphere: (entityId: number, radius: number, motionType: number, mass: number): number =>
+      legacyBody(entityId, mod._cphysShapeSphere(radius), motionType, mass),
+    physicsCreateCylinder: (entityId: number, halfHeight: number, radius: number, motionType: number, mass: number): number =>
+      legacyBody(entityId, mod._cphysShapeCylinder(halfHeight, radius), motionType, mass),
+    physicsSetLinearVelocity(bodyId: number, x: number, y: number, z: number): void { mod._cphysBodySetLinearVelocity(bodyId, x, y, z) },
+    physicsGetLinearVelocity(bodyId: number, out: Float32Array): void { mod._cphysBodyGetLinearVelocity(bodyId, out8); read3(out, out8) },
+    physicsSetAngularVelocity(bodyId: number, x: number, y: number, z: number): void { mod._cphysBodySetAngularVelocity(bodyId, x, y, z) },
+    physicsGetAngularVelocity(bodyId: number, out: Float32Array): void { mod._cphysBodyGetAngularVelocity(bodyId, out8); read3(out, out8) },
+    physicsApplyImpulse(bodyId: number, x: number, y: number, z: number): void { mod._cphysBodyApplyImpulse(bodyId, x, y, z) },
+    physicsApplyImpulseAt(bodyId: number, x: number, y: number, z: number, px: number, py: number, pz: number): void { mod._cphysBodyApplyImpulseAt(bodyId, x, y, z, px, py, pz) },
+    physicsSetBodyPosition(bodyId: number, x: number, y: number, z: number): void { mod._cphysBodySetPosition(bodyId, x, y, z) },
+    physicsSetBodyRotation(bodyId: number, qx: number, qy: number, qz: number, qw: number): void { mod._cphysBodySetRotation(bodyId, qx, qy, qz, qw) },
+    physicsRemoveBody(bodyId: number): void { mod._cphysBodyRemove(bodyId) },
+
+    // --- characters ---
+    characterCreate(entityId: number, shapeId: number, maxSlopeDeg: number): number {
+      const id = shapeId ? mod._cphysCharacterCreate(entityId, shapeId, maxSlopeDeg, poseOf(entityId)) : 0
+      if (id) characterEntity.set(id, entityId)
+      return id
+    },
+    characterDestroy(charId: number): void { mod._cphysCharacterDestroy(charId); characterEntity.delete(charId) },
+    characterMove(charId: number, x: number, z: number): void { mod._cphysCharacterMove(charId, x, z) },
+    characterMoveFree(charId: number, x: number, y: number, z: number): void { mod._cphysCharacterMoveFree(charId, x, y, z) },
+    characterSetVerticalVelocity(charId: number, vy: number): void { mod._cphysCharacterSetVerticalVelocity(charId, vy) },
+    characterSetVelocity(charId: number, x: number, y: number, z: number): void { mod._cphysCharacterSetVelocity(charId, x, y, z) },
+    characterSetGravityScale(charId: number, scale: number): void { mod._cphysCharacterSetGravityScale(charId, scale) },
+    characterSetMaxSlope(charId: number, maxSlopeDeg: number): void { mod._cphysCharacterSetMaxSlope(charId, maxSlopeDeg) },
+    // Discontinuous: the node is pushed NOW (the caller reads its own height this same frame).
+    characterSetShape(charId: number, shapeId: number): boolean {
+      if (!mod._cphysCharacterSetShape(charId, shapeId)) return false
+      const entity = characterEntity.get(charId)
+      if (entity !== undefined) {
+        mod._cphysCharacterPosition(charId, out8)
+        const f = mod.HEAPF32, o = out8 >> 2
+        host.setWorldPosition(entity, f[o], f[o + 1], f[o + 2])
+      }
+      return true
+    },
+    characterGetVelocity(charId: number, out: Float32Array): void { mod._cphysCharacterGetVelocity(charId, out8); read3(out, out8) },
+    characterGetGroundState: (charId: number): number => mod._cphysCharacterGetGroundState(charId),
+    characterSetPosition(charId: number, x: number, y: number, z: number): void { mod._cphysCharacterSetPosition(charId, x, y, z) },
+
+    // --- vehicles ---
+    vehicleCreate(entityId: number, shapeId: number, settings: Float32Array): number {
+      if (!shapeId) return 0
+      return withF32(mod, settings, (sp) => mod._cphysVehicleCreate(entityId, shapeId, sp, settings.length, poseOf(entityId)))
+    },
+    vehicleDestroy(vehicleId: number): void { mod._cphysVehicleDestroy(vehicleId) },
+    vehicleSetInput(vehicleId: number, input: Float32Array): void { withF32(mod, input, (ip) => mod._cphysVehicleSetInput(vehicleId, ip, input.length)) },
+    vehicleSetTuning(vehicleId: number, settings: Float32Array): void { withF32(mod, settings, (sp) => mod._cphysVehicleSetTuning(vehicleId, sp, settings.length)) },
+    vehicleGetState(vehicleId: number, out: Float32Array): void {
+      const ptr = stateBuffer(out.length)
+      mod._cphysVehicleGetState(vehicleId, ptr, out.length)
+      out.set(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + out.length))
+    },
+    vehicleReset(vehicleId: number, x: number, y: number, z: number, qx: number, qy: number, qz: number, qw: number): void { mod._cphysVehicleReset(vehicleId, x, y, z, qx, qy, qz, qw) },
+    vehicleBodyId: (vehicleId: number): number => mod._cphysVehicleBodyId(vehicleId),
+
+    // --- ragdolls ---
+    ragdollCreate(rootEntityId: number, bones: Uint32Array, settings: Float32Array): number {
+      const partCount = settings.length > 1 ? settings[1] | 0 : 0
+      if (partCount <= 0 || bones.length < partCount * 2) return 0
+      const rootPose = new Float32Array(POSE_STRIDE)
+      decomposeInto(host.world(rootEntityId), rootPose, 0)
+      // per part: the bone's pose + the `to` entity's world position
+      const bonePoses = new Float32Array(partCount * (POSE_STRIDE + 3))
+      const entities: number[] = []
+      for (let i = 0; i < partCount; i++) {
+        const o = i * (POSE_STRIDE + 3)
+        decomposeInto(host.world(bones[i * 2]), bonePoses, o)
+        entities.push(bones[i * 2])
+        const to = bones[i * 2 + 1]
+        if (to) {
+          const w = host.world(to)
+          bonePoses[o + POSE_STRIDE] = w[12]; bonePoses[o + POSE_STRIDE + 1] = w[13]; bonePoses[o + POSE_STRIDE + 2] = w[14]
+        }
+      }
+      const id = withF32(mod, rootPose, (rp) => withU32(mod, bones, (bp) => withF32(mod, bonePoses, (pp) => withF32(mod, settings, (sp) =>
+        mod._cphysRagdollCreate(rp, bp, bones.length, pp, sp, settings.length)))))
+      if (id) ragdolls.set(id, { entities, prev: new Float32Array(partCount * POSE_STRIDE), cur: new Float32Array(partCount * POSE_STRIDE), valid: 0, dt: 1 / 60, active: false, driven: false, learn: settings.length > 14 && settings[13] !== 0, margin: settings.length > 14 ? Math.max(0, settings[14]) : 0, learned: false })
+      return id
+    },
+    ragdollDestroy(ragdollId: number): void { mod._cphysRagdollDestroy(ragdollId); ragdolls.delete(ragdollId) },
+    /** The bones' current poses become the bodies', each moving as the last two frames measured its bone
+     *  (plus the launch) — creator-gl's ragdollActivate. */
+    ragdollActivate(ragdollId: number, vx: number, vy: number, vz: number): boolean {
+      const r = ragdolls.get(ragdollId)
+      if (!r) return false
+      if (!r.active && r.learn && !r.learned) learnLimits(ragdollId, r)
+      const n = r.entities.length
+      const bonePoses = new Float32Array(n * POSE_STRIDE)
+      for (let i = 0; i < n; i++) decomposeInto(host.world(r.entities[i]), bonePoses, i * POSE_STRIDE)
+      let vel: Float32Array | null = null
+      if (!r.active && r.valid >= 2 && r.dt > 1e-5) {
+        vel = new Float32Array(n * 6)
+        const inv = 1 / r.dt
+        for (let i = 0; i < n; i++) {
+          const a = i * POSE_STRIDE, o = i * 6
+          vel[o] = (r.cur[a] - r.prev[a]) * inv; vel[o + 1] = (r.cur[a + 1] - r.prev[a + 1]) * inv; vel[o + 2] = (r.cur[a + 2] - r.prev[a + 2]) * inv
+          // the world-frame rotation from prev to cur: d = qb · conj(qa) → angle-axis / dt
+          const ax = r.prev[a + 3], ay = r.prev[a + 4], az = r.prev[a + 5], aw = r.prev[a + 6]
+          const bx = r.cur[a + 3], by = r.cur[a + 4], bz = r.cur[a + 5], bw = r.cur[a + 6]
+          let dx = bw * -ax + bx * aw + by * -az - bz * -ay
+          let dy = bw * -ay - bx * -az + by * aw + bz * -ax
+          let dz = bw * -az + bx * -ay - by * -ax + bz * aw
+          let dw = bw * aw - bx * -ax - by * -ay - bz * -az
+          if (dw < 0) { dx = -dx; dy = -dy; dz = -dz; dw = -dw }
+          const s = Math.sqrt(Math.max(0, 1 - dw * dw))
+          if (s > 1e-6) {
+            const k = 2 * Math.acos(Math.min(1, dw)) / s * inv
+            vel[o + 3] = dx * k; vel[o + 4] = dy * k; vel[o + 5] = dz * k
+          }
+        }
+      }
+      const ok = withF32(mod, bonePoses, (pp) => (vel ? withF32(mod, vel, (vp) => mod._cphysRagdollActivate(ragdollId, vx, vy, vz, pp, vp)) : mod._cphysRagdollActivate(ragdollId, vx, vy, vz, pp, 0))) !== 0
+      if (ok) r.active = true
+      return ok
+    },
+    /** The bodies' last pose onto the bones against the parents' current worlds, the animator seeded with
+     *  it (blend > 0), then physics lets go. */
+    ragdollDeactivate(ragdollId: number, blend: number): void {
+      const r = ragdolls.get(ragdollId)
+      if (r?.active) {
+        applyBodies(mod._cphysRagdollPose(ragdollId))
+        if (blend > 0 && r.entities.length > 0) host.seedAnimator?.(r.entities[0], blend)
+        r.active = false
+        r.valid = 0
+      }
+      mod._cphysRagdollDeactivate(ragdollId)
+    },
+    ragdollSetDrive(ragdollId: number, strength: number, anchor: boolean): void {
+      const r = ragdolls.get(ragdollId)
+      if (r) r.driven = strength > 0 || anchor
+      mod._cphysRagdollSetDrive(ragdollId, strength, anchor ? 1 : 0)
+    },
+    ragdollActive: (ragdollId: number): boolean => mod._cphysRagdollActive(ragdollId) !== 0,
+    ragdollBodyId: (ragdollId: number, index: number): number => mod._cphysRagdollBodyId(ragdollId, index),
+
+    setOnPhysicsEvent(cb: (a: number, b: number, type: number) => void): void { onEvent = cb },
+  }
+
+  return {
+    methods,
+    /** One host frame of GAME time: the fixed steps (with the host's fixed-phase callback between
+     *  them, reading the live poses), the interpolation snapshot, the render poses onto the entities,
+     *  then the contact events. */
+    frame(dt: number, fixedUpdate: ((dt: number) => void) | null): void {
+      const steps = mod._cphysFrameBegin(dt)
+      const fixedDt = mod._cphysFixedDt()
+      for (let i = 0; i < steps; i++) {
+        if (fixedUpdate) {
+          applyBodies(mod._cphysPullBodies(PULL_LIVE))
+          applyCharacters(mod._cphysPullCharacters(PULL_LIVE))
+          fixedUpdate(fixedDt)
+        }
+        mod._cphysStep()
+      }
+      mod._cphysFrameEnd()
+      applyBodies(mod._cphysPullBodies(PULL_RENDER))
+      applyCharacters(mod._cphysPullCharacters(PULL_RENDER))
+      const n = mod._cphysEventCount()
+      if (n > 0 && onEvent) {
+        // copied first: a handler may swap the world, and the buffer is the library's
+        const o = mod._cphysEventData() >> 2
+        const events = Array.from(mod.HEAPU32.subarray(o, o + n * 3))
+        for (let i = 0; i < n; i++) onEvent(events[i * 3], events[i * 3 + 1], events[i * 3 + 2])
+      }
+    },
+    /** After the host's animators: the part bones' animated poses go into the cache (the next activation's
+     *  velocities, a driven body's motor target), then the active ragdolls' bodies overwrite their bones
+     *  (parent-first). `dt` = the frame's game time. */
+    syncRagdolls(dt: number): void {
+      if (ragdolls.size === 0) return
+      for (const [ id, r ] of ragdolls) {
+        const swap = r.prev; r.prev = r.cur; r.cur = swap
+        for (let i = 0; i < r.entities.length; i++) decomposeInto(host.world(r.entities[i]), r.cur, i * POSE_STRIDE)
+        if (dt > 1e-5) r.dt = dt
+        if (r.valid < 2) r.valid++
+        if (r.active && r.driven) withF32(mod, r.cur, (pp) => mod._cphysRagdollSetTarget(id, pp))
+      }
+      applyBodies(mod._cphysPullRagdolls())
+    },
+    /** Root motion from an animator on `entityId`: a CharacterController on the node or an ancestor takes
+     *  the world travel as its external velocity for the next step and yaws its node; true when one did. */
+    applyRootMotion(entityId: number, wx: number, wz: number, dt: number, yaw: number): boolean {
+      for (let e = entityId; e; e = host.parentOf(e)) {
+        const c = mod._cphysCharacterForEntity(e)
+        if (!c) continue
+        mod._cphysCharacterSetExternalVelocity(c, dt > 0 ? wx / dt : 0, dt > 0 ? wz / dt : 0)
+        if (yaw !== 0) {
+          const node = host.get(e)
+          if (node) { rotateLocalY(node.m, yaw); host.localMatrixChanged(e) }
+        }
+        return true
+      }
+      return false
+    },
+    /** Tear the world down (a project switch). */
+    dispose(): void {
+      mod._cphysShutdown()
+      mod._cphysSetParentLookup(0)
+      mod.removeFunction(parentFn)
+      mod._free(pose); mod._free(out8); mod._free(u32a)
+      if (stateScratch) mod._free(stateScratch)
+      characterEntity.clear(); ragdolls.clear()
+    },
+  }
+}
+
+export type PhysicsBridge = ReturnType<typeof createPhysicsBridge>

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />