lecodes-gl-lite 2.0.0

package/src/core/sceneCore.ts

@@ -0,0 +1,833 @@
+// The GL-free scene core for the lite 3D engine — one CPU-side implementation of the `_creator`
+// scene semantics (sdk/src/bridges.d.ts, mirroring creator-gl's scene.cpp /
+// transformUtils.cpp / collider.cpp) that BOTH lite backends drive:
+//
+//   • the WebGL backend (viewer-lite, browser)  — builds OGL programs/geometry from core state, and
+//   • the headless backend (lecodes-headless)    — records + serializes the same state to scene3d JSON.
+//
+// The core owns entities, hierarchy, local matrices, semantic materials/meshes/lights, GLB structure,
+// colliders, and the animation playback clock. It creates NO GL objects: where GL work is needed it
+// calls an optional `SceneBackend` hook, and the backend reacts at its edge (build a Program, sample
+// a clip, invalidate a cached world matrix). Headless supplies only `allocMatrix`; every GL hook is a
+// no-op there, so the recorded state IS the core state — that's why the two views can't disagree.
+//
+// Divergences between the old ports are resolved to creator-gl native here (see gl-lite-core-plan.md):
+// destroyEntity destroys the whole subtree (scene.cpp), cloneEntity attaches to the source's parent +
+// scene (scene.cpp), and the camera fov is the real engines' 60° (backend-configurable).
+
+import {
+  composeTRS, getEulerYXZDeg, getScale, identity, invertTRS, multiply, perspective,
+  setEulerOn, setQuaternionOn, setScaleOn, type Mat4, type Mat4Like,
+} from "./math3d"
+import { parseGlbStructure, type GlbAnimation } from "./glbStructure"
+import { createAnimationSystem } from "./animBridge"
+import { createPhysicsSystem } from "./physicsBridge"
+import { createParticleRuntime, type ParticleFrame } from "./particleBridge"
+import { nameMatchRank, shortName } from "./boneNames"
+
+export type UniformRec =
+  | { kind: "rgb" | "rgba", v: number }
+  | { kind: "float", v: number }
+  | { kind: "bool", v: boolean }
+  | { kind: "texture", v: number }
+  | { kind: "array", v: number[] }
+  | { kind: "null" }
+
+export type MaterialRec = { shader: string, uniforms: Record<string, UniformRec> }
+
+export type MeshRec = {
+  kind: number
+  vertexCount: number
+  size?: [number, number, number]
+  center?: [number, number, number]
+  primitives?: number
+}
+
+export type TextureRec = { source?: string, width: number, height: number }
+
+/** The animation playback clock — lives in the core; the backend only *samples* poses (onAnimationApply). */
+
+export type Ent = {
+  id: number
+  name: string
+  /** Local transform (column-major), supplied by the backend so mutations flow to the renderer. */
+  m: Mat4Like
+  parent: number // 0 = none
+  children: number[]
+  visible: boolean
+  mesh?: MeshRec
+  materials: number[]
+  light?: { direction: [number, number, number], intensity: number, color: number, shadowsQuality: number, shadowDistance?: number, shadowCascades?: number }
+  /** `buffer` = the GLB bytes, retained on the root for mesh colliders built from the model
+   *  (physicsBuildMeshFromEntity / glbTriangles) — the fetch store's copy may be gone by then. */
+  model?: { source?: string, systemId?: number, animations: GlbAnimation[], loaded: boolean, clipSet?: number, buffer?: ArrayBuffer }
+  /** A skin joint of a loaded GLB (the Animator prefers these over same-named plain nodes). */
+  skinJoint?: boolean
+  castShadows?: boolean
+  receiveShadows?: boolean
+  // --- headless recording surface (populated by recording.ts; the WebGL backend leaves these empty) ---
+  particles?: Record<string, unknown>
+  physics?: Record<string, unknown>
+  /** A Ragdoll's parts on the model entity (recording.ts ragdollCreate) + active/velocity while on. */
+  ragdoll?: Record<string, unknown>
+  collider?: { type: string, [k: string]: unknown }
+  anchor?: string
+}
+
+/** A scene's camera projection (setCameraProjection) — vertical fov in degrees + clip distances. */
+export type Projection = { fov: number, near: number, far: number }
+
+/** An inspection camera: eye + look-at point in world units (Y up), optional vertical fov (deg). */
+export type CameraOverride = { eye: [number, number, number], target: [number, number, number], fov?: number }
+
+export type SceneRec = {
+  id: number
+  entities: Set<number>
+  overlays: number[]
+  overlayOf?: number
+  camera?: number
+  /** Set by setCameraProjection; absent = the core defaults (fov option / 0.01 / 1000). */
+  projection?: Projection
+  skybox?: number
+  ibl?: number
+  bloom?: { strength: number }
+  antialias?: boolean
+  arMode?: string
+}
+
+/** The seam between the shared core and a concrete backend. Headless implements only `allocMatrix`. */
+export interface SceneBackend {
+  /** Allocate an entity's local matrix. Headless: a fresh identity Float32Array. The WebGL backend
+   *  hands back the OGL Transform's own matrix so the core mutates the renderable in place. */
+  allocMatrix(entityId: number): Mat4Like
+  /** A local matrix was mutated in place (WebGL: worldMatrixNeedsUpdate = true). */
+  localMatrixChanged?(entityId: number): void
+  /** Parent changed (WebGL: OGL setParent / reparent under the owning scene root). */
+  parentChanged?(childId: number, parentId: number): void
+  /** A scene was created (WebGL: create its root Transform). */
+  sceneCreated?(sceneId: number): void
+  /** Entity added (added=true) or removed from a scene (WebGL: reparent under / off the scene root). */
+  entitySceneChanged?(entityId: number, sceneId: number, added: boolean): void
+  /** Visibility toggled (WebGL: Transform.visible). */
+  visibleChanged?(entityId: number, visible: boolean): void
+  /** A material was created (WebGL: build the Program for this shader). `systemId` is present for
+   *  createMaterial (a fetched shader — needed to load a custom .mat buffer), absent for a built-in
+   *  one (createMaterialNamed: `rec.shader` is its name). */
+  materialCreated?(materialId: number, rec: MaterialRec, systemId?: number): void
+  /** A uniform was set with its SEMANTIC value (WebGL: convert hex→linear + set on the Program). */
+  uniformChanged?(materialId: number, uniform: string, u: UniformRec): void
+  /** A mesh was set (WebGL: build Geometry/Mesh from the raw arrays). */
+  meshSet?(entityId: number, materialId: number, mesh: MeshRec, arrays: {
+    vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, colors?: Uint8Array,
+  }): void
+  /** GLB entities were created from the structure (WebGL: run GLTFLoader + attach drawables by node
+   *  index). `nodeEntityIds[i]` is the entity for glTF node i; `rootId` is the synthetic model root.
+   *  May be async (createGlb awaits it before firing the SDK's onComplete). */
+  glbAttach?(systemId: number, rootId: number, nodeEntityIds: number[]): void | Promise<void>
+  /** An Animator sampled morph-target weights for an entity (WebGL: write the node's blendshape weights). */
+  morphWeights?(entityId: number, weights: Float32Array): void
+  /** An entity is being destroyed (WebGL: tear down its drawables). */
+  entityDestroyed?(entityId: number): void
+  /** A particle system was created on the entity with a material (WebGL: prepare its drawable). */
+  particleSystemCreated?(entityId: number, materialId: number): void
+  /** A particle system's vertex stream for this frame (WebGL: upload + draw; headless ignores it).
+   *  `frame.bytes` is a view into the wasm heap — copy or upload before the next tick. */
+  particlesFrame?(entityId: number, frame: ParticleFrame): void
+  particleSystemDestroyed?(entityId: number): void
+  /** An entity was cloned (WebGL: clone drawables). Called after the core copies scalar state. */
+  entityCloned?(sourceId: number, cloneId: number): void
+  /** A whole `cloneEntity` finished; `map` is source entity → clone entity for every node of the
+   *  subtree. `entityCloned` runs node by node in pre-order, so a skinned mesh is cloned before the
+   *  clones of its joints exist — this is where a backend re-points such cross-node references. */
+  subtreeCloned?(sourceRootId: number, cloneRootId: number, map: ReadonlyMap<number, number>): void
+}
+
+export type SceneCoreOptions = {
+  getBuffer: (systemId: number) => ArrayBuffer | undefined
+  getSourceName?: (systemId: number) => string | undefined
+  /** Viewport in logical px (drives getDisplaySize + the camera projection). */
+  width?: number
+  height?: number
+  /** Vertical camera fov in degrees (creator-gl native / web-lite use 60). */
+  fov?: number
+}
+
+/** Copy up to `n` elements from `src` into `dst` in place — works for Float32Array and Array alike
+ *  (the WebGL backend's matrix is an OGL Array subclass, which has no typed-array `.set`). */
+const copyInto = (dst: Mat4Like, src: ArrayLike<number>, n = 16): void => {
+  for (let i = 0; i < n; i++) (dst as number[])[i] = src[i]
+}
+
+export function createSceneCore(backend: SceneBackend, opts: SceneCoreOptions) {
+  const width = opts.width ?? 390
+  const height = opts.height ?? 844
+  const fov = opts.fov ?? 60
+  /** Matches creator-gl's SceneStruct defaults (scene.cpp applyCameraProjection). */
+  const defaultProjection: Projection = { fov, near: 0.01, far: 1000 }
+
+  const entities = new Map<number, Ent>()
+  const scenes = new Map<number, SceneRec>()
+  const materials = new Map<number, MaterialRec>()
+  const textures = new Map<number, TextureRec>()
+  let nextEntity = 1
+  let nextMaterial = 1
+  let nextTexture = 1
+  let activeScene = -1
+
+  let earlyUpdate: ((dt: number) => void) | null = null
+  let lateUpdate: ((dt: number) => void) | null = null
+  let fixedUpdate: ((dt: number) => void) | null = null   // the SDK's updateFixed: once per physics substep (creator-physics' frame protocol)
+
+  // The physics system (creator-physics' wasm — the same Jolt simulation creator-gl runs). Bodies and
+  // characters write world poses back into entity local matrices; the backend is told via localMatrixChanged.
+  const physics = createPhysicsSystem({
+    ent: (id) => ent(id),
+    get: (id) => entities.get(id),
+    world: (id) => worldMatrixF(id),
+    setWorldTRS: (id, x, y, z, qx, qy, qz, qw, sx, sy, sz) => writeWorldMatrix(id, composeTRS([x, y, z], [qx, qy, qz, qw], [sx, sy, sz])),
+    setWorldPosition: (id, x, y, z) => writeWorldPosition(id, x, y, z),
+    localMatrixChanged: (id) => backend.localMatrixChanged?.(id),
+    parentOf: (id) => entities.get(id)?.parent ?? 0,
+    glbBytes: (id) => entities.get(id)?.model?.buffer,
+    // a ragdoll let go with a blend: the animator transitions out of the fallen pose (`anim` is
+    // created right below; the hook only runs long after)
+    seedAnimator: (joint, blend) => anim.methods.animatorSeedPose(joint, blend),
+    // learned ragdoll limits: the clips' joint ranges from the same animator
+    jointRanges: (joint, pairs, frames) => anim.methods.animatorJointRanges(joint, pairs, frames),
+  })
+
+  // The particle runtime (creator-particles' wasm — the same simulation creator-gl runs): emitters
+  // read their world matrix here, the streams go to the backend's uploader, the counts to the record.
+  const particles = createParticleRuntime({
+    ent: (id) => ent(id),
+    world: (id) => worldMatrixF(id),
+    cameraPosition: () => {
+      const cam = scenes.get(activeScene)?.camera
+      if (cam === undefined) return null
+      const w = worldMatrix(cam)
+      return [w[12], w[13], w[14]]
+    },
+    created: (id, materialId) => backend.particleSystemCreated?.(id, materialId),
+    frame: (id, frame) => backend.particlesFrame?.(id, frame),
+    destroyed: (id) => backend.particleSystemDestroyed?.(id),
+  })
+
+  // The animation system (AnimationClip sets + Animators — creator-anim.s wasm, the same evaluator creator-gl runs).
+  // Joint writes go straight into entity local matrices; the backend is told via localMatrixChanged.
+  const anim = createAnimationSystem({
+    get: (id) => entities.get(id),
+    world: (id) => worldMatrixF(id),
+    localMatrixChanged: (id) => backend.localMatrixChanged?.(id),
+    getBuffer: (systemId) => opts.getBuffer(systemId),
+    setMorphWeights: (id, w) => backend.morphWeights?.(id, w),
+    applyRootMotion: (id, dx, dy, dz, dt, yaw) => {
+      const w = worldMatrixF(id)   // node-local → world direction
+      return physics.applyRootMotion(id, w[0] * dx + w[4] * dy + w[8] * dz, w[2] * dx + w[6] * dy + w[10] * dz, dt, yaw)
+    },
+  })
+
+  const makeEnt = (id: number): Ent => {
+    const e: Ent = {
+      id, name: "", m: backend.allocMatrix(id), parent: 0, children: [], visible: true, materials: [],
+    }
+    // allocMatrix may hand back an un-initialised buffer — ensure identity.
+    if (e.m[0] !== 1 || e.m[5] !== 1 || e.m[10] !== 1 || e.m[15] !== 1) copyInto(e.m, identity())
+    entities.set(id, e)
+    return e
+  }
+  const newEnt = (): Ent => makeEnt(nextEntity++)
+  // The SDK can hand back ids it saw from callbacks; be forgiving and materialize unknown ids.
+  const ent = (id: number): Ent => {
+    let e = entities.get(id)
+    if (!e) { e = makeEnt(id); if (id >= nextEntity) nextEntity = id + 1 }
+    return e
+  }
+
+  const worldMatrix = (id: number): Mat4Like => {
+    const e = ent(id)
+    if (e.parent === 0) return e.m
+    return multiply(new Float32Array(16), worldMatrix(e.parent), e.m)
+  }
+  /** worldMatrix as a concrete Float32Array (for math that needs `.set`/`.subarray`). */
+  const worldMatrixF = (id: number): Float32Array => {
+    const w = worldMatrix(id)
+    return w instanceof Float32Array ? w : Float32Array.from(w as ArrayLike<number>)
+  }
+
+  const detach = (e: Ent): void => {
+    if (e.parent !== 0) {
+      const p = entities.get(e.parent)
+      if (p) p.children = p.children.filter((c) => c !== e.id)
+      e.parent = 0
+    }
+  }
+
+  const setParentInternal = (childId: number, parentId: number, worldPositionStays: boolean): void => {
+    const e = ent(childId)
+    if (e.parent === parentId) return
+    if (worldPositionStays) {
+      const world = worldMatrixF(childId)
+      const local = parentId === 0 ? world : multiply(new Float32Array(16), invertTRS(worldMatrixF(parentId)), world)
+      copyInto(e.m, local)
+    }
+    detach(e)
+    if (parentId !== 0) {
+      e.parent = parentId
+      ent(parentId).children.push(childId)
+    }
+    backend.parentChanged?.(childId, parentId)
+    backend.localMatrixChanged?.(childId)
+  }
+
+  // A world-space transform onto an entity (into its parent's space when parented) — the physics
+  // system's pose writers (creator-gl's writeWorldTransform / writeWorldPosition twins).
+  const writeWorldMatrix = (id: number, world: Mat4Like): void => {
+    const e = ent(id)
+    copyInto(e.m, e.parent === 0 ? world : multiply(new Float32Array(16), invertTRS(worldMatrixF(e.parent)), world))
+    backend.localMatrixChanged?.(id)
+  }
+  const writeWorldPosition = (id: number, x: number, y: number, z: number): void => {
+    const e = ent(id)
+    const m = e.m as number[]
+    if (e.parent === 0) { m[12] = x; m[13] = y; m[14] = z }
+    else {
+      const inv = invertTRS(worldMatrixF(e.parent))
+      m[12] = inv[0] * x + inv[4] * y + inv[8] * z + inv[12]
+      m[13] = inv[1] * x + inv[5] * y + inv[9] * z + inv[13]
+      m[14] = inv[2] * x + inv[6] * y + inv[10] * z + inv[14]
+    }
+    backend.localMatrixChanged?.(id)
+  }
+
+  /** A scene's projection, falling back to the core defaults. Overlays follow their parent (they
+   *  share its camera, exactly like createOverlayScene in scene.cpp). */
+  const projectionOf = (sceneId: number): Projection => {
+    const s = scenes.get(sceneId)
+    const owner = s?.overlayOf !== undefined ? scenes.get(s.overlayOf) : s
+    return owner?.projection ?? defaultProjection
+  }
+
+  const sceneOf = (id: number): SceneRec | null => {
+    for (let cur = id; cur !== 0;) {
+      for (const s of scenes.values()) if (s.entities.has(cur)) return s
+      cur = ent(cur).parent
+    }
+    return null
+  }
+
+  const sourceName = (systemId: number): string | undefined => {
+    const name = opts.getSourceName?.(systemId)
+    if (!name) return undefined
+    // Local project assets arrive as lecodesfile://<abs-path>; keep just the file name.
+    const clean = name.startsWith("lecodesfile://") ? decodeURIComponent(name.slice("lecodesfile://".length)) : name
+    const isPathy = clean.includes("/") || clean.includes("\\")
+    return isPathy && !clean.startsWith("http") ? (clean.split(/[\\/]/).pop() ?? clean) : clean
+  }
+
+  const material = (id: number): MaterialRec => {
+    let m = materials.get(id)
+    if (!m) { m = { shader: "unknown", uniforms: {} }; materials.set(id, m) }
+    return m
+  }
+  const setUniform = (materialId: number, uniform: string, u: UniformRec): void => {
+    material(materialId).uniforms[uniform] = u
+    backend.uniformChanged?.(materialId, uniform, u)
+  }
+
+  // Stage 1 of GLB load (gl-free): parse the JSON structure and create the entity hierarchy (the
+  // synthetic model root + one entity per glTF node, in node-index order). Returns the ids so the
+  // backend's stage-2 glbAttach can attach drawables by node index (both derive from the same glTF
+  // JSON, so indices align). `entIds` is empty when the buffer isn't a parseable GLB.
+  const buildGlbEntities = (systemId: number): { rootId: number, entIds: number[] } => {
+    const buf = opts.getBuffer(systemId)
+    const structure = buf ? parseGlbStructure(buf) : null
+    const root = newEnt()
+    root.model = { source: sourceName(systemId), systemId, animations: structure?.animations ?? [], loaded: structure !== null, ...(buf && { buffer: buf }) }
+    // Embedded clips are parsed NOW (like native loadGlb): the fetched buffer is `useOnce` and may be
+    // gone by the time an Animator asks for the set. Only when the file has animations.
+    if (structure && structure.animations.length > 0 && buf) root.model.clipSet = anim.registerGlbClips(buf)
+    if (!structure) return { rootId: root.id, entIds: [] }
+    const entIds = structure.nodes.map(() => newEnt().id)
+    structure.nodes.forEach((n, i) => {
+      const e = ent(entIds[i])
+      e.name = n.name ?? ""
+      copyInto(e.m, n.matrix)
+      backend.localMatrixChanged?.(e.id)
+      if (n.skinJoint) e.skinJoint = true
+      if (n.mesh) {
+        e.mesh = { kind: 0, vertexCount: 0, primitives: n.mesh.primitives }
+        if (n.mesh.min && n.mesh.max) {
+          e.mesh.size = [n.mesh.max[0] - n.mesh.min[0], n.mesh.max[1] - n.mesh.min[1], n.mesh.max[2] - n.mesh.min[2]]
+          e.mesh.center = [(n.mesh.max[0] + n.mesh.min[0]) / 2, (n.mesh.max[1] + n.mesh.min[1]) / 2, (n.mesh.max[2] + n.mesh.min[2]) / 2]
+        }
+      }
+      for (const c of n.children) setParentInternal(entIds[c], e.id, false)
+    })
+    for (const r of structure.roots) setParentInternal(entIds[r], root.id, false)
+    return { rootId: root.id, entIds }
+  }
+
+  // cloneEntity → creator-gl native: the clone attaches to the source's parent and joins the source's
+  // scene (scene.cpp cloneEntity). The subtree is cloned recursively (shared by both TS ports).
+  const cloneSubtree = (id: number, map: Map<number, number>): number => {
+    const src = ent(id)
+    const copy = newEnt()
+    map.set(src.id, copy.id)
+    copy.name = src.name
+    copyInto(copy.m, src.m)
+    copy.visible = src.visible
+    if (src.skinJoint) copy.skinJoint = true
+    if (src.light) copy.light = { ...src.light }
+    if (src.mesh) copy.mesh = { ...src.mesh }
+    copy.materials = [...src.materials]
+    if (src.model) copy.model = { ...src.model, animations: src.model.animations }
+    if (src.castShadows !== undefined) copy.castShadows = src.castShadows
+    if (src.receiveShadows !== undefined) copy.receiveShadows = src.receiveShadows
+    if (src.particles) copy.particles = structuredClone(src.particles)
+    if (src.physics) copy.physics = structuredClone(src.physics)
+    if (src.collider) copy.collider = structuredClone(src.collider)
+    if (src.anchor) copy.anchor = src.anchor
+    backend.localMatrixChanged?.(copy.id)
+    backend.entityCloned?.(src.id, copy.id)
+    for (const c of src.children) setParentInternal(cloneSubtree(c, map), copy.id, false)
+    return copy.id
+  }
+
+  const destroySubtree = (id: number): void => {
+    const e = entities.get(id)
+    if (!e) return
+    for (const c of [...e.children]) destroySubtree(c)
+    detach(e)
+    for (const s of scenes.values()) s.entities.delete(id)
+    backend.entityDestroyed?.(id)
+    anim.onEntityDestroyed(id)
+    particles.onEntityDestroyed(id)
+    entities.delete(id)
+  }
+
+  // Visible only if the whole ancestor chain is visible (native isVisible).
+  const visibleChain = (entityId: number): boolean => {
+    for (let id = entityId; id !== 0; id = ent(id).parent) if (!ent(id).visible) return false
+    return true
+  }
+
+  /** One render step: aspect update(dt) phases around the animator evaluation (creator-gl's
+   *  render-loop order — early → physics → animators → late → particles). The WebGL backend drives this per frame with the
+   *  real frame dt; headless drives it in fixed 16ms steps from `simulate`. */
+  // The engine clock multiplier (SDK Time.scale / Time.paused): the sims advance by dt × scale, the JS
+  // phases keep the raw dt — creator-gl's setTimeScale contract.
+  let timeScale = 1
+  const tick = (dt: number): void => {
+    const sim = dt * timeScale
+    earlyUpdate?.(dt)
+    // creator-gl's frame (init.cpp stepFrameUpdates): the physics steps right after the early phase
+    // (controllers feed it) with the fixed phase between the substeps — once per 1/60 of GAME time, at
+    // most 4 per frame, backlog dropped past the cap, dt always exactly 1/60 — then the render poses
+    // land on the entities, the animators run, and the active ragdolls overwrite their bones.
+    physics.frame(sim, fixedUpdate)
+    anim.evaluate(sim)
+    physics.syncRagdolls(sim)
+    lateUpdate?.(dt)
+    anim.lateSolve()           // creator-gl's lateSolveAnimators: the IK chains on the joints as the late phase left them
+    // creator-gl's updateParticles — AFTER the late phase since 2026-09-20 (init.cpp stepFrameUpdates has the why): a
+    // world-space stream is written against the emitter's matrix, so it must be the matrix the draw uses, and an
+    // emitter moved by a default `update(dt)` aspect / system is moved in the late phase.
+    particles.update(sim)
+  }
+
+  /** Advance to `timeMs` in fixed 16ms steps (headless). 0 = don't step (the initial state). */
+  const simulate = (timeMs: number): void => {
+    const steps = Math.min(1000, Math.floor(timeMs / 16))
+    for (let i = 0; i < steps; i++) tick(0.016)
+  }
+
+  const hasActiveScene = (): boolean => activeScene >= 0 || scenes.size > 0
+  const activeSceneId = (): number => activeScene
+
+  // ---- the shared, backend-agnostic `_creator` methods --------------------------------------------
+
+  const methods = {
+    // --- scenes ---
+    createScene(): number {
+      const id = scenes.size
+      scenes.set(id, { id, entities: new Set(), overlays: [] })
+      backend.sceneCreated?.(id)
+      return id
+    },
+    createOverlayScene(parentId: number): number {
+      const id = scenes.size
+      // Overlays render through the parent scene's camera (the WebGL backend draws them with the main
+      // camera object), so we don't give the overlay its own camera — matching what serializes today.
+      scenes.set(id, { id, entities: new Set(), overlays: [], overlayOf: parentId })
+      scenes.get(parentId)?.overlays.push(id)
+      backend.sceneCreated?.(id)
+      return id
+    },
+    createGLView(): void {},
+    openScene(sceneId: number): void { activeScene = sceneId },
+    closeScene(): void { activeScene = -1 },
+    addEntityToScene(sceneId: number, entityId: number): void {
+      const s = scenes.get(sceneId)
+      if (!s) return
+      // An entity lives in exactly one scene (native scene.cpp move_elements): drop it from any other.
+      for (const other of scenes.values()) if (other !== s) other.entities.delete(entityId)
+      s.entities.add(entityId)
+      backend.entitySceneChanged?.(entityId, sceneId, true)
+    },
+    removeEntityFromScene(sceneId: number, entityId: number): void {
+      const s = scenes.get(sceneId)
+      if (!s) return
+      s.entities.delete(entityId)
+      backend.entitySceneChanged?.(entityId, sceneId, false)
+    },
+
+    // --- entities + hierarchy ---
+    createEntity: (): number => newEnt().id,
+    cloneEntity(entityId: number): number {
+      const src = ent(entityId)
+      const map = new Map<number, number>()
+      const cloneId = cloneSubtree(entityId, map)
+      // Native: attach to the source's parent; if the source is a bare scene member, join its scene.
+      if (src.parent !== 0) {
+        setParentInternal(cloneId, src.parent, false)
+      } else {
+        const scene = sceneOf(entityId)
+        if (scene) {
+          scene.entities.add(cloneId)
+          backend.entitySceneChanged?.(cloneId, scene.id, true)
+        }
+      }
+      backend.subtreeCloned?.(entityId, cloneId, map)
+      return cloneId
+    },
+    destroyEntity(entityId: number): void { destroySubtree(entityId) },
+
+    setMatrix(entityId: number, mat: Float32Array): void {
+      const e = ent(entityId)
+      copyInto(e.m, mat)
+      backend.localMatrixChanged?.(entityId)
+    },
+    setWorldMatrix(entityId: number, mat: Float32Array): void {
+      const e = ent(entityId)
+      if (e.parent === 0) { copyInto(e.m, mat); backend.localMatrixChanged?.(entityId); return }
+      const local = multiply(new Float32Array(16), invertTRS(worldMatrixF(e.parent)), Float32Array.from(mat.subarray(0, 16)))
+      copyInto(e.m, local)
+      backend.localMatrixChanged?.(entityId)
+    },
+    getChildCount: (entityId: number): number => ent(entityId).children.length,
+    getChild: (entityId: number, index: number): number => ent(entityId).children[index] ?? 0,
+
+    setPosition(entityId: number, x: number, y: number, z: number): void {
+      const m = ent(entityId).m
+      m[12] = x; m[13] = y; m[14] = z
+      backend.localMatrixChanged?.(entityId)
+    },
+    setQuaternion(entityId: number, x: number, y: number, z: number, w: number): void {
+      setQuaternionOn(ent(entityId).m, x, y, z, w); backend.localMatrixChanged?.(entityId)
+    },
+    setEulerAngles(entityId: number, x: number, y: number, z: number, order: number): void {
+      setEulerOn(ent(entityId).m, x, y, z, order); backend.localMatrixChanged?.(entityId)
+    },
+    setScale(entityId: number, x: number, y: number, z: number): void {
+      setScaleOn(ent(entityId).m, x, y, z); backend.localMatrixChanged?.(entityId)
+    },
+
+    setParent(entityId: number, parentEntityId: number, worldPositionStays: boolean): void {
+      setParentInternal(entityId, parentEntityId, worldPositionStays)
+    },
+    setParentNull(entityId: number, worldPositionStays: boolean): void {
+      setParentInternal(entityId, 0, worldPositionStays)
+    },
+    getParent: (entityId: number): number => ent(entityId).parent,
+    traverse(entityId: number, callback: (entityId: number) => void): void {
+      // Descendants only (the SDK's Node.traverse visits `this` itself before delegating here).
+      const walk = (id: number): void => { callback(id); for (const c of ent(id).children) walk(c) }
+      for (const c of ent(entityId).children) walk(c)
+    },
+    findNode(entityId: number, name: string): number {
+      // Descendant by name with the Animator's binding rule (boneNames.ts): exact before short name,
+      // skin joints before plain nodes, first in tree order otherwise. 0 = absent. Native twin:
+      // creator-gl scene.cpp findNode.
+      const want = shortName(name)
+      let best = 0, bestRank = 4
+      const walk = (id: number): void => {
+        const e = ent(id)
+        const rank = nameMatchRank(e.name, !!e.skinJoint, name, want)
+        if (rank < bestRank && rank >= 0) { best = id; bestRank = rank }
+        for (const c of e.children) { if (bestRank === 0) return; walk(c) }
+      }
+      for (const c of ent(entityId).children) { if (bestRank === 0) break; walk(c) }
+      return best
+    },
+
+    // --- lights + environment ---
+    createSunLight(entityId: number, x: number, y: number, z: number, intensity: number, color: number, shadowsQuality: number, shadowDistance = 100, shadowCascades = 1): void {
+      ent(entityId).light = { direction: [x, y, z], intensity, color, shadowsQuality, shadowDistance, shadowCascades }
+    },
+    setDefaultIbl(sceneId: number, intensity: number): void { const s = scenes.get(sceneId); if (s) s.ibl = intensity },
+    setBloomOptions(sceneId: number, enabled: boolean, strength: number): void {
+      const s = scenes.get(sceneId)
+      if (s) s.bloom = enabled ? { strength } : undefined
+    },
+    setSkybox(sceneId: number, color: number): void { const s = scenes.get(sceneId); if (s) s.skybox = color },
+    setSceneMultiSampleAntiAliasing(sceneId: number, enabled: boolean): void {
+      const s = scenes.get(sceneId); if (s) s.antialias = enabled
+    },
+    // Recorded only: the lite engine draws at canvas resolution (web-lite) or reports JSON (headless) —
+    // neither scales its buffers. Kept so the call is not a missing-method error on older bundles.
+    setSceneRenderOptions(): void {},
+    setMaterialGlobalParameter(): void {},
+    getCameraFov(sceneId: number, fovType: number): number {
+      const { fov: vfov } = projectionOf(sceneId)
+      if (fovType !== 1) return vfov
+      const vert = (vfov * Math.PI) / 180
+      return (2 * Math.atan(Math.tan(vert / 2) * (width / height)) * 180) / Math.PI
+    },
+    setCameraProjection(sceneId: number, newFov: number, near: number, far: number): void {
+      const s = scenes.get(sceneId)
+      if (s) s.projection = { fov: newFov, near, far }
+    },
+
+    // --- transform reads ---
+    getMatrix(entityId: number, mat: Float32Array): boolean { mat.set(localMatrixF(entityId)); return true },
+    getWorldMatrix(entityId: number, mat: Float32Array): void { mat.set(worldMatrixF(entityId)) },
+    getWorldPosition(entityId: number, out: Float32Array): void {
+      const w = worldMatrix(entityId)
+      out[0] = w[12]; out[1] = w[13]; out[2] = w[14]
+    },
+    getWorldDirection(entityId: number, mode: number, out: Float32Array): void {
+      const w = worldMatrix(entityId)
+      out[0] = w[mode * 4]; out[1] = w[mode * 4 + 1]; out[2] = w[mode * 4 + 2]
+    },
+    getWorldMatrixInverse(entityId: number, mat: Float32Array): void { mat.set(invertTRS(worldMatrixF(entityId))) },
+    getCameraViewDirection(sceneId: number, screenX: number, screenY: number, out: Float32Array): void {
+      // A real unproject through the camera world matrix + the same projection we report.
+      const camId = scenes.get(sceneId)?.camera
+      const w = camId ? worldMatrix(camId) : identity()
+      const aspect = width / height
+      const t = Math.tan((projectionOf(sceneId).fov * Math.PI) / 360)
+      const cx = ((screenX / width) * 2 - 1) * t * aspect
+      const cy = (1 - (screenY / height) * 2) * t
+      const dx = w[0] * cx + w[4] * cy - w[8]
+      const dy = w[1] * cx + w[5] * cy - w[9]
+      const dz = w[2] * cx + w[6] * cy - w[10]
+      const len = Math.hypot(dx, dy, dz) || 1
+      out[0] = dx / len; out[1] = dy / len; out[2] = dz / len
+    },
+
+    // --- meshes ---
+    setMesh(entityId: number, materialId: number, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, meshType: number, _uv1?: Float32Array, colors?: Uint8Array): void {
+      const e = ent(entityId)
+      let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity
+      for (let i = 0; i + 2 < vertices.length; i += 3) {
+        const x = vertices[i], y = vertices[i + 1], z = vertices[i + 2]
+        if (x < minX) minX = x; if (x > maxX) maxX = x
+        if (y < minY) minY = y; if (y > maxY) maxY = y
+        if (z < minZ) minZ = z; if (z > maxZ) maxZ = z
+      }
+      const has = vertices.length >= 3
+      const mesh: MeshRec = {
+        kind: meshType,
+        vertexCount: Math.floor(vertices.length / 3),
+        size: has ? [maxX - minX, maxY - minY, maxZ - minZ] : undefined,
+        center: has ? [(maxX + minX) / 2, (maxY + minY) / 2, (maxZ + minZ) / 2] : undefined,
+      }
+      e.mesh = mesh
+      e.materials[0] = materialId
+      backend.meshSet?.(entityId, materialId, mesh, { vertices, normals, indices, uv, colors })
+    },
+    setCulling(): void {},
+    setRenderPriority(): void {},
+    setMaterialDepthTest(): void {},
+    setMaterialDepthWrite(): void {},
+    setMaterialCulling(): void {},
+    // no stencil in the lite renderer: a stencil test passes, a write is dropped (the outline recipe
+    // then draws its hull everywhere — an approximation, like lite's lighting)
+    setMaterialStencil(): void {},
+    setSceneStencil(): void {},
+    setCastShadows(entityId: number, v: boolean): void { ent(entityId).castShadows = v },
+    setReceiveShadows(entityId: number, v: boolean): void { ent(entityId).receiveShadows = v },
+    // creator-gl walks every renderable of the GLB instance; the twin walks the entity subtree
+    setGlbShadows(entityId: number, cast: boolean, receive: boolean): void {
+      const walk = (id: number): void => {
+        const e = ent(id)
+        e.castShadows = cast
+        e.receiveShadows = receive
+        for (const c of e.children) walk(c)
+      }
+      walk(entityId)
+    },
+    setCastShadowsGlobal(): void {},
+    setReceiveShadowsGlobal(): void {},
+    hasMesh: (entityId: number): boolean => ent(entityId).mesh !== undefined,
+
+    // --- materials + uniforms ---
+    createMaterial(systemId: number): number {
+      const id = nextMaterial++
+      const rec: MaterialRec = { shader: sourceName(systemId) ?? "unknown", uniforms: {} }
+      materials.set(id, rec)
+      backend.materialCreated?.(id, rec, systemId)
+      return id
+    },
+    /** A built-in material by NAME (`_creator.builtinMaterial`): this engine draws with its own programs,
+     *  picked by that name — there is no shader file to find. */
+    createMaterialNamed(name: string): number {
+      const id = nextMaterial++
+      const rec: MaterialRec = { shader: name, uniforms: {} }
+      materials.set(id, rec)
+      backend.materialCreated?.(id, rec)
+      return id
+    },
+    setMaterial(entityId: number, materialId: number, index: number): void { ent(entityId).materials[index] = materialId },
+    getMaterial: (entityId: number, index: number): number => ent(entityId).materials[index] ?? 0,
+
+    setUniformRgb(materialId: number, uniform: string, color: number): void { setUniform(materialId, uniform, { kind: "rgb", v: color }) },
+    setUniformRgba(materialId: number, uniform: string, color: number): void { setUniform(materialId, uniform, { kind: "rgba", v: color }) },
+    setUniformFloat(materialId: number, uniform: string, value: number): void { setUniform(materialId, uniform, { kind: "float", v: value }) },
+    setUniformBoolean(materialId: number, uniform: string, value: boolean): void { setUniform(materialId, uniform, { kind: "bool", v: value }) },
+    setUniformTexture(materialId: number, uniform: string, systemId: number): void { setUniform(materialId, uniform, { kind: "texture", v: systemId }) },
+    setUniformArray(materialId: number, uniform: string, value: Float32Array): void { setUniform(materialId, uniform, { kind: "array", v: Array.from(value) }) },
+    setUniformNull(materialId: number, uniform: string): void { setUniform(materialId, uniform, { kind: "null" }) },
+
+    // --- textures ---
+    createTexture(systemId: number, onComplete: (id: number, width: number, height: number) => void, onReject: () => void): void {
+      const buf = opts.getBuffer(systemId)
+      if (!buf || buf.byteLength === 0) { onReject(); return }
+      const [w, h] = sniffImageSize(buf)
+      const id = nextTexture++
+      textures.set(id, { source: sourceName(systemId), width: w, height: h })
+      onComplete(id, w, h)
+    },
+    createTextureFromCanvas(surfaceId: number): number {
+      const id = nextTexture++
+      textures.set(id, { source: `canvas#${surfaceId}`, width: 0, height: 0 })
+      return id
+    },
+    updateTextureFromCanvas(): void {},
+    // Raw-pixel textures (Texture.fromPixels / a terrain's control map): the size is recorded, the
+    // WebGL backend overrides both with real uploads.
+    createTexturePixels(width: number, height: number, channels: number): number {
+      const id = nextTexture++
+      textures.set(id, { source: `pixels ${width}x${height}x${channels}`, width, height })
+      return id
+    },
+    updateTexturePixels(): void {},
+    createMediaPlayerTexture(playerId: number): number {
+      const id = nextTexture++
+      textures.set(id, { source: `mediaplayer#${playerId}`, width: 0, height: 0 })
+      return id
+    },
+
+    // --- camera ---
+    attachCameraToAR(sceneId: number, cameraEntityId: number, onProjectionChange: (mat: Float32Array, fov: number) => void): void {
+      const s = scenes.get(sceneId)
+      if (s) s.camera = cameraEntityId
+      // Headless (recording) reports the projection so a captured scene knows its camera; the WebGL
+      // backend (like the Filament viewer) ignores this callback and drives projection via the viewport.
+      const p = projectionOf(sceneId)
+      onProjectionChange(perspective(p.fov, width / height, p.near, p.far), p.fov)
+    },
+    getDisplaySize: (): Float32Array => Float32Array.of(width, height),
+
+    // --- visibility / names ---
+    setVisible(entityId: number, visible: boolean): void {
+      ent(entityId).visible = visible
+      backend.visibleChanged?.(entityId, visible)
+      // a hidden subtree's particle systems stop simulating (creator-gl renderable.cpp updateVisibleChild)
+      const walk = (id: number): void => {
+        const e = ent(id)
+        if (e.particles) particles.setVisible(id, visibleChain(id))
+        for (const c of e.children) walk(c)
+      }
+      walk(entityId)
+    },
+    isVisible: (entityId: number): boolean => visibleChain(entityId),
+    getName: (entityId: number): string => ent(entityId).name,
+    setName(entityId: number, name: string): void { ent(entityId).name = name },
+
+    // --- GLB models ---
+    // Two-stage: the core builds the entity structure (sync, gl-free), then the backend attaches
+    // drawables. Headless has no glbAttach → completes synchronously; the WebGL backend's glbAttach is
+    // async (GLTFLoader) → onComplete fires once geometry/skins are ready.
+    createGlb(systemId: number, onComplete: (entityId: number) => void, onReject?: (err: unknown) => void): void {
+      const { rootId, entIds } = buildGlbEntities(systemId)
+      if (!backend.glbAttach) { onComplete(rootId); return }
+      Promise.resolve(backend.glbAttach(systemId, rootId, entIds)).then(() => onComplete(rootId)).catch((e) => onReject?.(e))
+    },
+    setGlbCulling(): void {},
+    // The model's embedded clip set (docs/animation-plan.md), parsed at createGlb; clones share it. 0 = none.
+    getGlbClipSet: (entityId: number): number => entities.get(entityId)?.model?.clipSet ?? 0,
+    ...anim.methods,
+
+    setEarlyUpdate(cb: (dt: number) => void): void { earlyUpdate = cb },
+    setLateUpdate(cb: (dt: number) => void): void { lateUpdate = cb },
+    setFixedUpdate(cb: ((dt: number) => void) | null): void { fixedUpdate = cb },
+    setTimeScale(scale: number): void { timeScale = Number.isFinite(scale) && scale > 0 ? scale : 0 },
+    ...physics.methods,
+    ...particles.methods,
+  }
+
+  // The LOCAL matrix as a concrete Float32Array (native getMatrix reads local, not world).
+  function localMatrixF(entityId: number): Float32Array {
+    const m = ent(entityId).m
+    return m instanceof Float32Array ? m : Float32Array.from(m as ArrayLike<number>)
+  }
+
+  // Inspection camera override (host tooling — the headless twin of creator-gl's setCameraOverride):
+  // while set, the frame report + serialized camera project through THIS eye/look-at (and fov)
+  // instead of the scene's camera entity. The entity itself is untouched — raycasts still use it.
+  let cameraOverride: CameraOverride | null = null
+
+  return {
+    // config
+    width, height, fov,
+    // state (read by serialize.ts; written by recording.ts)
+    entities, scenes, materials, textures,
+    cameraOverride: (): CameraOverride | null => cameraOverride,
+    setCameraOverride: (o: CameraOverride | null): void => { cameraOverride = o },
+    // helpers (used by recording.ts + the WebGL backend)
+    ent, newEnt, worldMatrix, worldMatrixF, sourceName, setParentInternal, sceneOf, projectionOf,
+    /** Repoint an entity's local matrix at a backend-owned buffer (WebGL uses this for GLB nodes so
+     *  the entity IS the loader's animated transform — animation/skinning keep working). */
+    rebindMatrix: (entityId: number, m: Mat4Like): void => { ent(entityId).m = m },
+    // lifecycle
+    methods, simulate, tick, hasActiveScene, activeSceneId,
+    /** The physics world config the SDK set (serialize.ts), undefined if never configured. */
+    physicsConfig: physics.config,
+    /** A particle system's index pattern for its current capacity (the WebGL backend's index buffer). */
+    particleIndexPattern: particles.indexPattern,
+    nextTextureId: () => nextTexture++,
+    nextMaterialId: () => nextMaterial++,
+  }
+}
+
+export type SceneCore = ReturnType<typeof createSceneCore>
+
+/** Sniff PNG/JPEG pixel dimensions from encoded bytes (headless textures aren't decoded). */
+export const sniffImageSize = (buf: ArrayBuffer): [number, number] => {
+  const b = new Uint8Array(buf)
+  if (b.length > 24 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) {
+    const dv = new DataView(buf)
+    return [dv.getUint32(16), dv.getUint32(20)]
+  }
+  // KTX2 («KTX 20» CR LF 0x1A LF): pixelWidth/pixelHeight little-endian @20/@24.
+  if (b.length >= 28 && b[0] === 0xab && b[1] === 0x4b && b[2] === 0x54 && b[3] === 0x58 && b[4] === 0x20 && b[5] === 0x32 && b[6] === 0x30 && b[7] === 0xbb) {
+    const dv = new DataView(buf)
+    return [dv.getUint32(20, true), dv.getUint32(24, true)]
+  }
+  if (b.length > 4 && b[0] === 0xff && b[1] === 0xd8) {
+    const dv = new DataView(buf)
+    let p = 2
+    while (p + 9 < b.length) {
+      if (b[p] !== 0xff) break
+      const marker = b[p + 1]
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return [dv.getUint16(p + 7), dv.getUint16(p + 5)]
+      }
+      p += 2 + dv.getUint16(p + 2)
+    }
+  }
+  return [0, 0]
+}
+
+export { copyInto }