lecodes-gl-lite 2.0.0

package/src/core/physicsBridge.ts

@@ -0,0 +1,305 @@
+// The web hosts' physics system: creator-physics' wasm (JoltPhysics) behind the same `_creator`
+// physics / character / vehicle / ragdoll method shapes creator-gl exposes natively — ONE simulation
+// for every host, no kinematic stand-in. Shared by viewer-lite's WebGL engine and lecodes-headless
+// (headless); the host only supplies its scene graph (`PhysicsHost`).
+//
+// Lazy like the animation system: the module loads asynchronously (`loadCreatorPhysics()`, awaited by
+// createViewerLite / runProject before the scene core exists), and the real bridge is created on the
+// first physics call. `physicsHasSupport()` answers whether the module is resident — a host that never
+// loaded it reports no physics and the SDK's aspects no-op, exactly like a physics-less native build.
+//
+// On top of the simulation this layer RECORDS what the SDK configured onto the entities (Ent.physics /
+// Ent.ragdoll + the world config) for the headless JSON snapshots: the collider a node carries, its
+// motion / mass / friction, a vehicle's tunables, a ragdoll's parts — so `lecodes render` shows the
+// setup, and the simulation shows what it did.
+
+import { createPhysicsBridge, loadCreatorPhysics, isCreatorPhysicsLoaded, type PhysicsHost, type PhysicsBridge } from "../vendor/creator-physics/js/index"
+import type { Ent } from "./sceneCore"
+
+export { loadCreatorPhysics, isCreatorPhysicsLoaded }
+export type { PhysicsHost, PhysicsBridge }
+
+type Methods = PhysicsBridge["methods"]
+const METHOD_NAMES: (keyof Methods)[] = [
+  "physicsConfigure", "setInterpolation",
+  "physicsBuildBox", "physicsBuildSphere", "physicsBuildCylinder", "physicsBuildCapsule", "physicsBuildMesh",
+  "physicsBuildMeshFromEntity", "physicsBuildHeightField", "physicsUpdateHeightField", "glbTriangles",
+  "physicsSetShapeOrigin", "physicsSetBodyShape", "physicsDestroyShape",
+  "physicsCreateBody", "physicsSetPickable", "physicsSetFriction", "physicsGetFriction", "physicsRaycast",
+  "physicsCreateBox", "physicsCreateSphere", "physicsCreateCylinder",
+  "physicsSetLinearVelocity", "physicsGetLinearVelocity", "physicsSetAngularVelocity", "physicsGetAngularVelocity",
+  "physicsApplyImpulse", "physicsApplyImpulseAt", "physicsSetBodyPosition", "physicsSetBodyRotation", "physicsRemoveBody",
+  "characterCreate", "characterDestroy", "characterMove", "characterMoveFree", "characterSetVerticalVelocity",
+  "characterSetVelocity", "characterSetGravityScale", "characterSetMaxSlope", "characterSetShape",
+  "characterGetVelocity", "characterGetGroundState", "characterSetPosition",
+  "vehicleCreate", "vehicleDestroy", "vehicleSetInput", "vehicleSetTuning",
+  "vehicleGetState", "vehicleReset", "vehicleBodyId",
+  "ragdollCreate", "ragdollDestroy", "ragdollActivate", "ragdollDeactivate", "ragdollActive", "ragdollBodyId", "ragdollSetDrive",
+  "setOnPhysicsEvent",
+]
+
+export type PhysicsSystemHost = PhysicsHost & { ent(id: number): Ent }
+
+const FIXED_DT = 1 / 60
+const MOTION = ["static", "kinematic", "dynamic"]
+
+// Vehicle settings blob v15 — see bridges.d.ts for the field-by-field layout.
+const VEHICLE_HEADER = 34
+const VEHICLE_WHEEL = 15
+const VEHICLE_WHEELS_AT = 32
+const VEHICLE_CURVES_AT = 33
+/** The half of the blob a live retune may change, decoded for the snapshot. */
+const vehicleTunables = (s: Float32Array, curveCount: number): Record<string, unknown> => ({
+  engine: { torque: s[4], maxRpm: s[5], idleRpm: s[6], inertia: s[7], braking: s[8] },
+  clutchStrength: s[9],
+  clutchCapacity: s[31],
+  differential: s[10]! <= 0 ? "open" : s[10],
+  antiRoll: s[11],
+  maxTilt: s[12],
+  aero: { downforce: s[13], drag: s[14] },
+  steering: s[15] ? { feedback: { inertia: s[16], damping: s[17], parkingFriction: s[18], powerSteering: s[24], friction: s[29] }, caster: s[19], trail: s[20] } : { caster: s[19], trail: s[20] },
+  ...(curveCount > 0
+    ? { torqueCurve: Array.from(s.subarray(VEHICLE_HEADER, VEHICLE_HEADER + curveCount * 2)) }
+    : {}),
+})
+
+export const createPhysicsSystem = (host: PhysicsSystemHost) => {
+  let real: PhysicsBridge | null = null
+  const get = (): PhysicsBridge => {
+    if (!real) {
+      if (!isCreatorPhysicsLoaded()) throw new Error("creator-physics is not loaded: await loadCreatorPhysics() (viewer-lite/src/gl/core/physicsBridge) before the first physics call")
+      real = createPhysicsBridge(host)
+    }
+    return real
+  }
+  const sim = {} as Methods
+  for (const name of METHOD_NAMES) {
+    (sim as Record<string, unknown>)[name] = (...args: unknown[]) => (get().methods[name] as (...a: unknown[]) => unknown)(...args)
+  }
+
+  // ---- the JSON record (what the SDK configured; the simulation moves the entities) ----
+  const shapes = new Map<number, Record<string, unknown>>()
+  const bodyOwner = new Map<number, number>()      // bodyId → entity
+  const charOwner = new Map<number, number>()      // charId → entity
+  const vehicleOwner = new Map<number, number>()   // vehicleId → entity
+  const ragdollOwner = new Map<number, number>()   // ragdollId → model entity
+  let config: Record<string, unknown> | undefined
+  const shapeRec = (id: number, rec: Record<string, unknown>): number => { if (id) shapes.set(id, rec); return id }
+  const physicsOf = (owner: Map<number, number>, id: number): Record<string, unknown> | undefined => {
+    const e = owner.get(id)
+    return e === undefined ? undefined : host.ent(e).physics
+  }
+  const legacyBody = (id: number, entityId: number, motion: number, mass: number, shape: Record<string, unknown>): number => {
+    if (id) { bodyOwner.set(id, entityId); host.ent(entityId).physics = { motion: MOTION[motion] ?? motion, mass, shape } }
+    return id
+  }
+
+  const methods = {
+    ...sim,
+    physicsHasSupport: (): boolean => isCreatorPhysicsLoaded(),
+    physicsConfigure(gx: number, gy: number, gz: number, maxBodies: number): void {
+      config = { gravity: [gx, gy, gz], maxBodies }
+      sim.physicsConfigure(gx, gy, gz, maxBodies)
+    },
+    physicsBuildBox: (hx: number, hy: number, hz: number): number =>
+      shapeRec(sim.physicsBuildBox(hx, hy, hz), { type: "box", size: [hx * 2, hy * 2, hz * 2] }),
+    physicsBuildSphere: (radius: number): number =>
+      shapeRec(sim.physicsBuildSphere(radius), { type: "sphere", radius }),
+    physicsBuildCylinder: (halfHeight: number, radius: number): number =>
+      shapeRec(sim.physicsBuildCylinder(halfHeight, radius), { type: "cylinder", height: halfHeight * 2, radius }),
+    physicsBuildCapsule: (halfHeight: number, radius: number): number =>
+      shapeRec(sim.physicsBuildCapsule(halfHeight, radius), { type: "capsule", height: halfHeight * 2, radius }),
+    physicsBuildMesh: (vertices: Float32Array, indices: Uint32Array, convex: boolean, sx: number, sy: number, sz: number): number =>
+      shapeRec(sim.physicsBuildMesh(vertices, indices, convex, sx, sy, sz),
+        { type: convex ? "convexHull" : "mesh", vertices: vertices.length / 3, triangles: Math.floor(indices.length / 3), scale: [sx, sy, sz] }),
+    physicsBuildMeshFromEntity: (entityId: number, convex: boolean, sx: number, sy: number, sz: number): number =>
+      shapeRec(sim.physicsBuildMeshFromEntity(entityId, convex, sx, sy, sz),
+        { type: convex ? "convexHull" : "mesh", source: entityId, scale: [sx, sy, sz] }),
+    physicsBuildHeightField(heights: Float32Array, sizeX: number, sizeZ: number, cellSize: number, holes: Uint8Array | null, sx: number, sy: number, sz: number): number {
+      let holeCount = 0
+      if (holes) for (let i = 0; i < holes.length; i++) if (holes[i]) holeCount++
+      return shapeRec(sim.physicsBuildHeightField(heights, sizeX, sizeZ, cellSize, holes, sx, sy, sz),
+        { type: "heightfield", size: [sizeX, sizeZ], cellSize, samples: heights.length, holes: holeCount, scale: [sx, sy, sz] })
+    },
+    // Shape `origin`: on the shape record too (a JSON snapshot shows where the collider sits relative
+    // to the node). Zero clears it, matching the engine's "set, don't accumulate" rule.
+    physicsSetShapeOrigin(shapeId: number, x: number, y: number, z: number): void {
+      const shape = shapes.get(shapeId)
+      if (shape) { if (x === 0 && y === 0 && z === 0) delete shape.origin; else shape.origin = [x, y, z] }
+      sim.physicsSetShapeOrigin(shapeId, x, y, z)
+    },
+    physicsSetBodyShape(bodyId: number, shapeId: number, updateMass: boolean): void {
+      const p = physicsOf(bodyOwner, bodyId)
+      if (p) p.shape = shapes.get(shapeId)
+      sim.physicsSetBodyShape(bodyId, shapeId, updateMass)
+    },
+    physicsDestroyShape(shapeId: number): void { shapes.delete(shapeId); sim.physicsDestroyShape(shapeId) },
+    physicsCreateBody(entityId: number, shapeId: number, motion: number, mass: number, sensor: boolean, pickOnly: boolean): number {
+      const id = sim.physicsCreateBody(entityId, shapeId, motion, mass, sensor, pickOnly)
+      if (id) {
+        bodyOwner.set(id, entityId)
+        host.ent(entityId).physics = {
+          motion: MOTION[motion] ?? motion, mass,
+          ...(sensor && { sensor }), ...(pickOnly && { pickOnly }),
+          shape: shapes.get(shapeId),
+        }
+      }
+      return id
+    },
+    physicsSetFriction(bodyId: number, friction: number): void {
+      const p = physicsOf(bodyOwner, bodyId)
+      if (p) p.friction = friction
+      sim.physicsSetFriction(bodyId, friction)
+    },
+    physicsRemoveBody(bodyId: number): void { bodyOwner.delete(bodyId); sim.physicsRemoveBody(bodyId) },
+    physicsCreateBox: (entityId: number, hx: number, hy: number, hz: number, motionType: number, mass: number): number =>
+      legacyBody(sim.physicsCreateBox(entityId, hx, hy, hz, motionType, mass), entityId, motionType, mass, { type: "box", size: [hx * 2, hy * 2, hz * 2] }),
+    physicsCreateSphere: (entityId: number, radius: number, motionType: number, mass: number): number =>
+      legacyBody(sim.physicsCreateSphere(entityId, radius, motionType, mass), entityId, motionType, mass, { type: "sphere", radius }),
+    physicsCreateCylinder: (entityId: number, halfHeight: number, radius: number, motionType: number, mass: number): number =>
+      legacyBody(sim.physicsCreateCylinder(entityId, halfHeight, radius, motionType, mass), entityId, motionType, mass, { type: "cylinder", height: halfHeight * 2, radius }),
+
+    characterCreate(entityId: number, shapeId: number, maxSlopeDeg: number): number {
+      const id = sim.characterCreate(entityId, shapeId, maxSlopeDeg)
+      if (id) {
+        charOwner.set(id, entityId)
+        host.ent(entityId).physics = { character: true, maxSlopeDeg, shape: shapes.get(shapeId) }
+      }
+      return id
+    },
+    characterDestroy(charId: number): void { charOwner.delete(charId); sim.characterDestroy(charId) },
+    characterSetMaxSlope(charId: number, maxSlopeDeg: number): void {
+      const p = physicsOf(charOwner, charId)
+      if (p) p.maxSlopeDeg = maxSlopeDeg
+      sim.characterSetMaxSlope(charId, maxSlopeDeg)
+    },
+    characterSetShape(charId: number, shapeId: number): boolean {
+      const ok = sim.characterSetShape(charId, shapeId)
+      if (ok) { const p = physicsOf(charOwner, charId); if (p) p.shape = shapes.get(shapeId) }
+      return ok
+    },
+
+    // The blob layout is the one in bridges.d.ts (v5) — decoded back to readable keys so a JSON
+    // snapshot shows the car the SDK actually configured.
+    vehicleCreate(entityId: number, shapeId: number, settings: Float32Array): number {
+      const id = sim.vehicleCreate(entityId, shapeId, settings)
+      if (!id) return 0
+      const wheelCount = settings[VEHICLE_WHEELS_AT] ?? 0
+      const curveCount = settings[VEHICLE_CURVES_AT] ?? 0
+      let w = VEHICLE_HEADER + curveCount * 2
+      const wheels: Record<string, unknown>[] = []
+      for (let i = 0; i < wheelCount; i++) {
+        // Variable length: the fixed slots, then the two tire curves (their point counts are the last two).
+        const sideCount = settings[w + 13] ?? 0
+        const forwardCount = settings[w + 14] ?? 0
+        wheels.push({
+          position: [settings[w], settings[w + 1], settings[w + 2]],
+          radius: settings[w + 3], width: settings[w + 4],
+          ...(settings[w + 5] ? { steerDeg: settings[w + 5] } : {}),
+          ...(settings[w + 6] ? { driven: settings[w + 6] } : {}),
+          axle: settings[w + 7],
+          suspension: { travel: settings[w + 8], stiffness: settings[w + 9], damping: settings[w + 10] },
+          tire: { traction: settings[w + 11], circle: settings[w + 12], side: sideCount, forward: forwardCount },
+        })
+        w += VEHICLE_WHEEL + (sideCount + forwardCount) * 2
+      }
+      vehicleOwner.set(id, entityId)
+      host.ent(entityId).physics = {
+        motion: "dynamic", mass: settings[1], vehicle: true,
+        ...vehicleTunables(settings, curveCount),
+        wheels, shape: shapes.get(shapeId),
+      }
+      return id
+    },
+    vehicleDestroy(vehicleId: number): void { vehicleOwner.delete(vehicleId); sim.vehicleDestroy(vehicleId) },
+    vehicleSetTuning(vehicleId: number, settings: Float32Array): void {
+      const p = physicsOf(vehicleOwner, vehicleId)
+      if (p) Object.assign(p, vehicleTunables(settings, settings[VEHICLE_CURVES_AT] ?? 0))
+      sim.vehicleSetTuning(vehicleId, settings)
+    },
+    vehicleSetInput(vehicleId: number, input: Float32Array): void {
+      const p = physicsOf(vehicleOwner, vehicleId)
+      if (p) p.input = { throttle: input[0], steer: input[1], steerForce: input[2], ratio: input[3], clutch: input[4], brakes: Array.from(input.subarray(5)) }
+      sim.vehicleSetInput(vehicleId, input)
+    },
+
+    // The parts are decoded from the blob (layout in bridges.d.ts) onto the model entity so a JSON
+    // snapshot shows the skeleton the SDK handed to physics.
+    ragdollCreate(rootEntityId: number, bones: Uint32Array, settings: Float32Array): number {
+      const id = sim.ragdollCreate(rootEntityId, bones, settings)
+      if (!id) return 0
+      const header = 16   // blob v3 (bridges.d.ts)
+      const count = settings[1] ?? 0, stride = settings[2] ?? 12
+      const parts: Record<string, unknown>[] = []
+      for (let i = 0; i < count; i++) {
+        const o = header + i * stride
+        parts.push({
+          bone: bones[i * 2], ...(bones[i * 2 + 1] ? { to: bones[i * 2 + 1] } : {}),
+          parent: settings[o], radius: settings[o + 1], ...(settings[o + 2] ? { length: settings[o + 2] } : {}),
+          mass: settings[o + 3],
+          ...(settings[o + 6]
+            ? { hinge: { axis: [settings[o + 7], settings[o + 8], settings[o + 9]], min: settings[o + 10], max: settings[o + 11] } }
+            : { swing: settings[o + 4], twist: settings[o + 5] }),
+        })
+      }
+      ragdollOwner.set(id, rootEntityId)
+      host.ent(rootEntityId).ragdoll = {
+        friction: settings[3],
+        collide: settings[6] ? "static" : "all", freeze: !!settings[7], freezeAfter: settings[8] ?? 0,
+        drive: { frequency: settings[9], damping: settings[10], torque: settings[11] }, jointFriction: settings[12],
+        limits: settings[13] ? "clips" : "table", limitsMargin: settings[14],
+        parts,
+      }
+      return id
+    },
+    ragdollDestroy(ragdollId: number): void { ragdollOwner.delete(ragdollId); sim.ragdollDestroy(ragdollId) },
+    ragdollActivate(ragdollId: number, vx: number, vy: number, vz: number): boolean {
+      const ok = sim.ragdollActivate(ragdollId, vx, vy, vz)
+      const e = ragdollOwner.get(ragdollId)
+      const rag = e === undefined ? undefined : host.ent(e).ragdoll
+      if (ok && rag) { rag.active = true; rag.launch = [vx, vy, vz] }
+      return ok
+    },
+    ragdollDeactivate(ragdollId: number, blend: number): void {
+      const e = ragdollOwner.get(ragdollId)
+      const rag = e === undefined ? undefined : host.ent(e).ragdoll
+      if (rag) { rag.active = false; delete rag.launch; if (blend > 0) rag.blendOut = blend }
+      sim.ragdollDeactivate(ragdollId, blend)
+    },
+    ragdollSetDrive(ragdollId: number, strength: number, anchor: boolean): void {
+      const e = ragdollOwner.get(ragdollId)
+      const rag = e === undefined ? undefined : host.ent(e).ragdoll
+      if (rag) { rag.strength = strength; rag.anchored = anchor }
+      sim.ragdollSetDrive(ragdollId, strength, anchor)
+    },
+  }
+
+  let acc = 0
+  return {
+    methods,
+    /** The simulation exists (something was created). */
+    loaded: (): boolean => real !== null,
+    /** One frame of GAME time: the fixed steps with the SDK's fixed phase between them, the render
+     *  poses onto the entities, the contact events. Without a simulation (nothing created yet, or the
+     *  module never loaded) the fixed phase still runs on its own 1/60 accumulator — creator-gl's
+     *  physics-less build does the same (init.cpp). */
+    frame(dt: number, fixedUpdate: ((dt: number) => void) | null): void {
+      if (real) { real.frame(dt, fixedUpdate); return }
+      if (!fixedUpdate) { acc = 0; return }
+      acc += dt
+      let steps = 0
+      while (acc >= FIXED_DT && steps < 4) { fixedUpdate(FIXED_DT); acc -= FIXED_DT; steps++ }
+      if (steps === 4) acc = 0
+    },
+    /** After the animators: the animated poses are cached (velocities / the motors' target), then the
+     *  active ragdolls' bodies overwrite their bones. */
+    syncRagdolls(dt: number): void { if (real) real.syncRagdolls(dt) },
+    /** Root motion → a CharacterController on the node or above it. False = nobody took it. */
+    applyRootMotion: (entityId: number, wx: number, wz: number, dt: number, yaw: number): boolean =>
+      real ? real.applyRootMotion(entityId, wx, wz, dt, yaw) : false,
+    /** The world config the SDK set (serialized at scene level), undefined if never configured. */
+    config: (): Record<string, unknown> | undefined => config,
+  }
+}
+
+export type PhysicsSystem = ReturnType<typeof createPhysicsSystem>

package/src/core/recording.ts

@@ -0,0 +1,59 @@
+// Headless recording method groups for the lite 3D scene core — the parts of the `_creator` bridge
+// whose behavior legitimately differs per consumer (gl-lite-core-plan.md "Capabilities"): AR/VR &
+// anchors, colliders, scene-material and capture. Headless records them (so SDK code paths execute
+// and get captured); the WebGL backend supplies its own honest versions (AR throws). All of these
+// mutate the shared core state (entity.collider/anchor, scene.arMode), so a recorded scene serializes
+// with the parameters the SDK actually set.
+// Physics, particles and noise are NOT recorded here any more: the core simulates them for real
+// (physicsBridge.ts / particleBridge.ts — creator-physics' and creator-particles' wasm) and records
+// the configuration alongside.
+
+import type { SceneCore } from "./sceneCore"
+
+export type RecordingHandle = {
+  methods: Record<string, (...args: any[]) => any>
+}
+
+export function createRecording(core: SceneCore): RecordingHandle {
+  const { ent, newEnt, scenes, sourceName, materials } = core
+
+  const methods = {
+    // --- AR / VR lifecycle (permissive: records + completes) ---
+    launchAR(_sceneId: number, onComplete: () => void): void { onComplete() },
+    stopAR(): void {},
+    launchVR(_sceneId: number, onComplete: () => void): void { onComplete() },
+    stopVR(): void {},
+    warmRender(_sceneId: number, onComplete: () => void): void { onComplete() },
+
+    // --- colliders (recorded on the entity for serialization; the CPU pick path has no raycast headless) ---
+    setColliderFromMesh(entityId: number, _meshEntityId: number, form: number): void { ent(entityId).collider = { type: "mesh", form } },
+    setColliderBox(entityId: number, cx: number, cy: number, cz: number, sx: number, sy: number, sz: number): void {
+      ent(entityId).collider = { type: "box", center: [cx, cy, cz], size: [sx, sy, sz] }
+    },
+    setColliderSphere(entityId: number, cx: number, cy: number, cz: number, radius: number): void {
+      ent(entityId).collider = { type: "sphere", center: [cx, cy, cz], radius }
+    },
+
+    // --- AR controllers + anchors ---
+    createARController(sceneId: number, _cameraId: number, mode: string): void {
+      const s = scenes.get(sceneId)
+      if (s) s.arMode = mode
+    },
+    createRootAnchor(_sceneId: number): number {
+      const e = newEnt()
+      e.anchor = "root"
+      return e.id
+    },
+    createAnchor(_sceneId: number, physicalWidth: number, systemId: number): number {
+      const e = newEnt()
+      e.anchor = sourceName(systemId) ?? "image"
+      void physicalWidth
+      return e.id
+    },
+
+    // --- capture (can't rasterize headless) ---
+    captureImage(_sceneId: number, _onComplete: unknown, onReject: () => void): void { onReject() },
+  }
+
+  return { methods }
+}