lecodes-viewer 0.19.0

package/src/viewer/createViewer.ts

@@ -0,0 +1,993 @@
+// @ts-ignore
+import createModule from './creator-gl.js'
+import { _fetch, _fetchLocal, getBlob, getBuffer, putBuffer, putLocalBuffer } from '../utils/fetch'
+
+import wasmLib from './creator-gl.wasm?url'
+import litMaterialSrc from './lit.filamat?url'
+import unlitMaterialSrc from './unlit.filamat?url'
+import unlitTransparentMaterialSrc from './unlit-transparent.filamat?url'
+import videoMaterialSrc from './video.filamat?url'
+import shadowMaterialSrc from './shadow.filamat?url'
+import particlesMaterialSrc from './particles.filamat?url'
+import particlesQuadMaterialSrc from './particles-quad.filamat?url'
+import iblTexture from '../assets/neutral_ibl128.ktx?url'
+import uberarchieve from './uberarchive.bin?url'
+
+// const wasmLib = `https://cdn.jt3.ru/le/creator-gl.wasm`
+// const litMaterialSrc = `https://cdn.jt3.ru/le/lit.filamat`
+// const unlitMaterialSrc = `https://cdn.jt3.ru/le/unlit.filamat`
+// const iblTexture = `https://cdn.jt3.ru/le/neutral_ibl.ktx`
+// const uberarchieve = `https://cdn.jt3.ru/le/uberarchive.bin`
+
+import { getPlayer, removePlayers } from './mediaplayer'
+import { installWasmCrashSymbolizer, symbolizeWasmError } from './wasmCrashSymbolizer'
+import type { CanvasHost } from '../canvas/createCanvasHost'
+
+export const baseProps = {
+  backend: "opengl",
+}
+
+export const initModule = async (canvas: HTMLCanvasElement, viewerOptions: ViewerOptions) => {
+  installWasmCrashSymbolizer()
+  const wasmBuffer = await fetch(wasmLib).then(resp => resp.arrayBuffer())
+
+  const options: WebGLContextAttributes = {
+    // majorVersion: 2,
+    // minorVersion: 0,
+    antialias: false,
+    depth: true,
+    alpha: false,
+    stencil: false,
+    desynchronized: false,
+    failIfMajorPerformanceCaveat: false,
+    powerPreference: "high-performance",
+    premultipliedAlpha: true,
+    preserveDrawingBuffer: viewerOptions.preloads?.has('capture') ?? false
+  }
+  Object.assign(options, {
+    majorVersion: 2,
+    minorVersion: 0
+  })
+
+  const ctx = canvas.getContext("webgl2", options)!
+  // @ts-ignore
+  window.filament_glContext = ctx
+  // @ts-ignore
+  window.filament_glOptions = options;
+
+  const module = await createModule({
+    wasmBinary: wasmBuffer,
+    canvas
+  })
+
+  module._init()
+  module._createSwapChainHeadless()
+  
+  if (viewerOptions.preloads?.has('uberarchive')) {
+    const uberarchiveBuffer = await fetch(uberarchieve).then(resp => resp.arrayBuffer())
+    const ptr = module._malloc(uberarchiveBuffer.byteLength)
+    module.HEAPU8.set(new Uint8Array(uberarchiveBuffer), ptr)
+    module._initGlbSupport(ptr, uberarchiveBuffer.byteLength)
+  }
+
+  return module
+}
+
+const decoder = new TextDecoder('utf-8')
+
+export type ViewerOptions = {
+  preloads?: Set<string>
+  /** The core 2D-canvas host (`_creatorCanvas`); lets createTextureFromCanvas read baked surfaces. */
+  canvasHost?: CanvasHost
+}
+
+export const createViewer = async (canvas: HTMLCanvasElement, options: ViewerOptions = {}) => {
+
+  const module = await initModule(canvas, options)
+
+  if (options.preloads?.has('lit.filamat')) {
+    const litMaterial = await (await fetch(litMaterialSrc)).arrayBuffer()
+    putLocalBuffer("lit.filamat", litMaterial)
+  }
+  if (options.preloads?.has('unlit.filamat')) {
+    const unlitMaterial = await (await fetch(unlitMaterialSrc)).arrayBuffer()
+    putLocalBuffer("unlit.filamat", unlitMaterial)
+  }
+  // The blended twin of unlit (Material.unlit({ transparent: true })) — its own package because
+  // matc bakes the blending mode in.
+  if (options.preloads?.has('unlit-transparent.filamat')) {
+    const unlitTransparentMaterial = await (await fetch(unlitTransparentMaterialSrc)).arrayBuffer()
+    putLocalBuffer("unlit-transparent.filamat", unlitTransparentMaterial)
+  }
+  if (options.preloads?.has('video.filamat')) {
+    const videoMaterial = await (await fetch(videoMaterialSrc)).arrayBuffer()
+    putLocalBuffer("video.filamat", videoMaterial)
+  }
+  if (options.preloads?.has('shadow.filamat')) {
+    const shadowMaterial = await (await fetch(shadowMaterialSrc)).arrayBuffer()
+    putLocalBuffer("shadow.filamat", shadowMaterial)
+  }
+  if (options.preloads?.has('particles.filamat')) {
+    const particlesMaterial = await (await fetch(particlesMaterialSrc)).arrayBuffer()
+    putLocalBuffer("particles.filamat", particlesMaterial)
+  }
+  if (options.preloads?.has('particles-quad.filamat')) {
+    const particlesQuadMaterial = await (await fetch(particlesQuadMaterialSrc)).arrayBuffer()
+    putLocalBuffer("particles-quad.filamat", particlesQuadMaterial)
+  }
+  const iblBuffer = await (await fetch(iblTexture)).arrayBuffer()
+
+  // const HEAPU8 = module.HEAPU8 as Uint8Array
+  // const HEAPU16 = module.HEAPU16 as Uint16Array
+  // const HEAPU32 = module.HEAPU32 as Uint32Array
+  // const HEAPF32 = module.HEAPF32 as Float32Array
+
+  const activePlayers: { player: HTMLVideoElement, glTexture: WebGLTexture, lastTime: number, bindWidth: number, bindHeight: number }[] = []
+  let arController: any = null
+
+  const updateVideoPlayers = () => {
+    for (let player of activePlayers) {
+      const video = player.player
+      if (video.videoWidth === 0 || video.currentTime === player.lastTime) continue
+      
+      gl.bindTexture(gl.TEXTURE_2D, player.glTexture);
+      
+      // if (video.videoWidth !== player.bindWidth || video.videoHeight !== player.bindHeight) {
+      //   gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA8, video.videoWidth, video.videoHeight)
+      //   player.bindWidth = video.videoWidth
+      //   player.bindHeight = video.videoHeight
+      //   console.info("Bind video to ", player.bindWidth, player.bindHeight)
+      // }
+      // gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, video.videoWidth, video.videoHeight, gl.RGBA, gl.UNSIGNED_BYTE, video);
+      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, video.videoWidth, video.videoHeight, 0, gl.RGBA, gl.UNSIGNED_BYTE, video)
+      player.lastTime = video.currentTime
+    }
+  }
+
+  const gl = (window as any).filament_glContext as WebGL2RenderingContext
+
+  const materialsMap = new Map<number, number>()
+
+  // Compile a filamat buffer once per systemId; both createMaterial and createMaterialS share this
+  // cache, so Material.lit() and createMaterialS("lit") produce instances of ONE Filament material.
+  const compileMaterial = (systemId: number): number => {
+    if (!materialsMap.has(systemId)) {
+      const arrayBuffer = getBuffer(systemId)
+      const ptr = module._malloc(arrayBuffer.byteLength)
+      module.HEAPU8.set(new Uint8Array(arrayBuffer), ptr)
+      const materialId = module._createMaterial(ptr, arrayBuffer.byteLength)
+      module._free(ptr)
+      materialsMap.set(systemId, materialId)
+    }
+    return materialsMap.get(systemId)!
+  }
+
+  const call = (method: string, arg1: number, arg2: string, arg3: any, arg4?: any, arg5?: any) => {
+    const maxLen = arg2.length + 1;
+    const uniformPtr = module._malloc(maxLen);
+    module.stringToUTF8(arg2, uniformPtr, maxLen);
+    if (arg5 !== undefined) {
+      module[method](arg1, uniformPtr, arg3, arg4, arg5)
+    } else if (arg4 !== undefined) {
+      module[method](arg1, uniformPtr, arg3, arg4)
+    } else {
+      module[method](arg1, uniformPtr, arg3)
+    }
+    module._free(uniformPtr)
+  }
+  
+  let sceneOpened = false
+
+  // Resolution factor (devicePixelRatio × CSS zoom) the backing store is sized at, and the logical
+  // (CSS-px) viewport size. The bridge's screen-space contract is LOGICAL px — the touch system,
+  // getBoundingClientRect and user code all speak logical — so raycast / view-direction inputs are
+  // scaled up to backing px by the factor, and getDisplaySize reports the logical size. Set by
+  // _onResize (docs/simulator-plan.md phase 3).
+  let resFactor = 1
+  let logicalW = 0, logicalH = 0
+
+  // One frame, no scheduling. Split out of the loop so a host can force a draw right before reading
+  // the canvas back: the WebGL context has no preserveDrawingBuffer unless the app asked for it
+  // (`// preload: capture`), so the pixels are only valid inside the task that drew them.
+  const renderOnce = (): boolean => {
+    if (!sceneOpened) return false
+    if (module._beginFrame()) {
+      if (arController !== null) {
+        arController.track(true)
+      }
+      updateVideoPlayers()
+      module._render(BigInt(Date.now()))
+      return true
+    }
+    if (arController !== null) {
+      arController.track(false)
+    }
+    return false // Filament declined this frame (its own pacing) — see warmRender's retry loop
+  }
+
+  const render = () => {
+    if (!sceneOpened) return
+    renderOnce()
+    requestAnimationFrame(render)
+  }
+
+  const createMediaPlayerTexture = (id: number) => {
+    const player = getPlayer(id) as HTMLVideoElement
+    const glTextureId = module.GL.getNewId(module.GL.textures)
+    const glTexture = gl.createTexture()
+    module.GL.textures[glTextureId] = glTexture
+
+    gl.bindTexture(gl.TEXTURE_2D, glTexture)
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+    gl.pixelStorei( gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE );
+
+    activePlayers.push({ player, glTexture, lastTime: 0, bindWidth: 0, bindHeight: 0 })
+
+    const textureId = module._importTexture(glTextureId, 0, 0)
+    return textureId
+  }
+
+  // One persistent wasm scratch for native float read-backs, sized to the largest reader (a 4x4
+  // matrix = 16). Its address is stable across heap growth, so we malloc once instead of per call.
+  // Each read-back writes into a caller-owned `out`, so there's no shared-buffer aliasing — we only
+  // drop the per-call malloc/free + view allocation. Read module.HEAPF32 FRESH each call (emscripten
+  // swaps that view on heap growth; the scratch address survives).
+  const READ_SCRATCH = 64   // largest reader: vehicleGetState = 7 + 3 per wheel
+  const readScratchPtr = module._malloc(READ_SCRATCH * 4)
+  const readInto = (out: Float32Array, n: number, fn: (ptr: number) => void): void => {
+    fn(readScratchPtr)
+    const base = readScratchPtr >> 2
+    const heap = module.HEAPF32
+    for (let i = 0; i < n; i++) out[i] = heap[base + i]
+  }
+
+  // 12-byte KTX2 magic («KTX 20» CR LF 0x1A LF) — createTexture routes these to the wasm transcoder.
+  const KTX2_MAGIC = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a]
+  const isKtx2Bytes = (b: Uint8Array) => b.length >= 12 && KTX2_MAGIC.every((v, i) => b[i] === v)
+  // PNG/JPG/WebP… via the browser decoder → sRGB8_A8 GL texture imported into Filament.
+  const createBitmapTexture = (blob: Blob, onComplete: (textureId: number, width: number, height: number) => void, onReject: any) => {
+    createImageBitmap(blob)
+      .then((bitmap) => {
+        const glTextureId = module.GL.getNewId(module.GL.textures)
+        const texture = gl.createTexture()
+        module.GL.textures[glTextureId] = texture
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+
+        gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+        gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+        gl.pixelStorei( gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE );
+      
+        gl.texStorage2D(gl.TEXTURE_2D, 1, gl.SRGB8_ALPHA8, bitmap.width, bitmap.height)
+        gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, bitmap.width, bitmap.height, gl.RGBA, gl.UNSIGNED_BYTE, bitmap);
+        const textureId = module._importTexture(glTextureId, bitmap.width, bitmap.height)
+        onComplete(textureId, bitmap.width, bitmap.height)
+      })
+      .catch(onReject)
+  }
+  return {
+    ...baseProps,
+    createScene: module._createScene,
+    createEntity: module._createEntity,
+    destroyEntity: module._destroyEntity as (entityId: number) => void,
+    addEntityToScene: module._addEntityToScene as (sceneId: number, entityId: number) => void,
+    removeEntityFromScene: module._removeEntityFromScene as (sceneId: number, entityId: number) => void,
+    createOverlayScene: module._createOverlayScene,
+    setMaterial: module._setMaterial,
+    createSunLight: module._createSunLight,
+    setSkybox: module._setSkybox,
+    setVisible: module._setVisible,
+    isVisible: module._isVisible,
+    setCastShadowsGlobal: module._setCastShadowsGlobal,
+    setReceiveShadowsGlobal: module._setReceiveShadowsGlobal,
+    setReceiveShadows: module._setReceiveShadows,
+    setCastShadows: module._setCastShadows,
+    setSceneMultiSampleAntiAliasing: module._setMultiSampleAntiAliasing as (sceneId: number, enabled: boolean, samples: number) => void,
+    // Only present once the wasm is rebuilt with the export (creator-gl scene.cpp setSceneRenderOptions);
+    // the SDK feature-detects it. The web viewer draws to its own canvas, so only the dynamic-resolution
+    // half applies (renderScale is for hosts that own a scene texture).
+    setSceneRenderOptions: module._setSceneRenderOptions as ((sceneId: number, renderScale: number, dynamicResolution: boolean, minScale: number) => void) | undefined,
+    
+    setPosition: module._setPosition,
+    setQuaternion: module._setQuaternion,
+    setEulerAngles: module._setEulerAngles,
+    setScale: module._setScale,
+
+    setColliderFromMesh: module._setColliderFromMesh,
+    setColliderBox: module._setColliderBox,
+    setColliderSphere: module._setColliderSphere,
+
+    // JoltPhysics (see physics.ts). All args are plain numbers, so these are direct
+    // passthroughs. The step + dynamic-body transform sync run entirely in C++ inside
+    // module._render — JS never touches per-frame transforms.
+    physicsHasSupport: () => !!module._creatorHasPhysics?.(),
+    physicsConfigure: (gx: number, gy: number, gz: number, maxBodies: number) =>
+      module._physicsConfigure(gx, gy, gz, maxBodies),
+    setInterpolation: (enabled: boolean) => module._setPhysicsInterpolation?.(enabled),
+    physicsCreateBox: (entityId: number, hx: number, hy: number, hz: number, motionType: number, mass: number): number =>
+      module._physicsCreateBox(entityId, hx, hy, hz, motionType, mass),
+    physicsCreateSphere: (entityId: number, radius: number, motionType: number, mass: number): number =>
+      module._physicsCreateSphere(entityId, radius, motionType, mass),
+    physicsCreateCylinder: (entityId: number, halfHeight: number, radius: number, motionType: number, mass: number): number =>
+      module._physicsCreateCylinder(entityId, halfHeight, radius, motionType, mass),
+    physicsSetLinearVelocity: (bodyId: number, x: number, y: number, z: number) =>
+      module._physicsSetLinearVelocity(bodyId, x, y, z),
+    physicsGetLinearVelocity: (bodyId: number, out: Float32Array) =>
+      readInto(out, 3, ptr => module._physicsGetLinearVelocity(bodyId, ptr)),
+    physicsSetAngularVelocity: (bodyId: number, x: number, y: number, z: number) =>
+      module._physicsSetAngularVelocity(bodyId, x, y, z),
+    physicsGetAngularVelocity: (bodyId: number, out: Float32Array) =>
+      readInto(out, 3, ptr => module._physicsGetAngularVelocity(bodyId, ptr)),
+    physicsApplyImpulse: (bodyId: number, x: number, y: number, z: number) =>
+      module._physicsApplyImpulse(bodyId, x, y, z),
+    physicsSetBodyPosition: (bodyId: number, x: number, y: number, z: number) =>
+      module._physicsSetBodyPosition(bodyId, x, y, z),
+    physicsSetBodyRotation: (bodyId: number, qx: number, qy: number, qz: number, qw: number) =>
+      module._physicsSetBodyRotation(bodyId, qx, qy, qz, qw),
+    physicsRemoveBody: (bodyId: number) => module._physicsRemoveBody(bodyId),
+    // Shape registry + body creation (Shape/Physics/Trigger aspects).
+    physicsBuildBox: (hx: number, hy: number, hz: number): number => module._physicsBuildBox(hx, hy, hz),
+    physicsBuildSphere: (radius: number): number => module._physicsBuildSphere(radius),
+    physicsBuildCylinder: (halfHeight: number, radius: number): number => module._physicsBuildCylinder(halfHeight, radius),
+    physicsBuildCapsule: (halfHeight: number, radius: number): number => module._physicsBuildCapsule(halfHeight, radius),
+    physicsBuildMesh: (vertices: Float32Array, indices: Uint32Array, convex: boolean, sx: number, sy: number, sz: number): number => {
+      // Jolt copies the data into the shape during the call — the staging buffers are freed right after.
+      const ptrV = module._malloc(vertices.byteLength)
+      const ptrI = module._malloc(indices.byteLength)
+      module.HEAPF32.set(vertices, ptrV / 4)
+      module.HEAPU32.set(indices, ptrI / 4)
+      const id = module._physicsBuildMesh(ptrV, Math.floor(vertices.length / 3), ptrI, indices.length, convex, sx, sy, sz)
+      module._free(ptrV)
+      module._free(ptrI)
+      return id
+    },
+    physicsBuildMeshFromEntity: (entityId: number, convex: boolean, sx: number, sy: number, sz: number): number =>
+      module._physicsBuildMeshFromEntity(entityId, convex, sx, sy, sz),
+    // Optional ABI members: left UNDEFINED when the loaded wasm predates them, so the SDK's
+    // feature-detect (`if (!_creator.physicsSetShapeOrigin)`) degrades with a warning instead of
+    // calling through to a missing export. Drop the guards after the next creator-gl wasm rebuild.
+    physicsSetShapeOrigin: module._physicsSetShapeOrigin
+      ? (shapeId: number, x: number, y: number, z: number) => module._physicsSetShapeOrigin(shapeId, x, y, z)
+      : undefined,
+    physicsSetBodyShape: module._physicsSetBodyShape
+      ? (bodyId: number, shapeId: number, updateMass: boolean) => module._physicsSetBodyShape(bodyId, shapeId, updateMass)
+      : undefined,
+    physicsDestroyShape: (shapeId: number) => module._physicsDestroyShape(shapeId),
+    physicsCreateBody: (entityId: number, shapeId: number, motion: number, mass: number, sensor: boolean, pickOnly: boolean): number =>
+      module._physicsCreateBody(entityId, shapeId, motion, mass, sensor, pickOnly),
+    physicsSetPickable: (bodyId: number, pickable: boolean) => module._physicsSetPickable(bodyId, pickable),
+    physicsSetFriction: (bodyId: number, friction: number) => module._physicsSetFriction(bodyId, friction),
+    physicsGetFriction: (bodyId: number): number => module._physicsGetFriction(bodyId),
+    physicsRaycast: (ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDist: number, out?: Float32Array): number => {
+      if (!out) return module._physicsRaycast(ox, oy, oz, dx, dy, dz, maxDist, 0)
+      let id = 0
+      readInto(out, 7, ptr => { id = module._physicsRaycast(ox, oy, oz, dx, dy, dz, maxDist, ptr) })
+      return id
+    },
+    // CharacterController (Jolt CharacterVirtual).
+    characterCreate: (entityId: number, shapeId: number, maxSlopeDeg: number): number =>
+      module._characterCreate(entityId, shapeId, maxSlopeDeg),
+    characterDestroy: (charId: number) => module._characterDestroy(charId),
+    characterMove: (charId: number, x: number, z: number) => module._characterMove(charId, x, z),
+    characterMoveFree: (charId: number, x: number, y: number, z: number) =>
+      module._characterMoveFree(charId, x, y, z),
+    characterSetVerticalVelocity: (charId: number, vy: number) =>
+      module._characterSetVerticalVelocity(charId, vy),
+    characterSetVelocity: (charId: number, x: number, y: number, z: number) =>
+      module._characterSetVelocity(charId, x, y, z),
+    characterSetGravityScale: (charId: number, scale: number) =>
+      module._characterSetGravityScale(charId, scale),
+    characterSetMaxSlope: (charId: number, maxSlopeDeg: number) =>
+      module._characterSetMaxSlope(charId, maxSlopeDeg),
+    characterSetShape: (charId: number, shapeId: number): boolean =>
+      !!module._characterSetShape(charId, shapeId),
+    characterGetVelocity: (charId: number, out: Float32Array) =>
+      readInto(out, 3, ptr => module._characterGetVelocity(charId, ptr)),
+    characterGetGroundState: (charId: number): number => module._characterGetGroundState(charId),
+    characterSetPosition: (charId: number, x: number, y: number, z: number) =>
+      module._characterSetPosition(charId, x, y, z),
+    // Vehicle (Jolt VehicleConstraint). The settings blob + wheel-entity ids are staged into the wasm
+    // heap for the call; Jolt copies everything it keeps, so both buffers are freed right after.
+    vehicleCreate: (entityId: number, shapeId: number, settings: Float32Array): number => {
+      const ptrS = module._malloc(settings.byteLength)
+      module.HEAPF32.set(settings, ptrS / 4)
+      const id = module._vehicleCreate(entityId, shapeId, ptrS, settings.length)
+      module._free(ptrS)
+      return id
+    },
+    vehicleDestroy: (vehicleId: number) => module._vehicleDestroy(vehicleId),
+    vehicleSetTransmission: (vehicleId: number, ratio: number, clutch: number) =>
+      module._vehicleSetTransmission(vehicleId, ratio, clutch),
+    vehicleSetTuning: (vehicleId: number, settings: Float32Array) => {
+      const ptr = module._malloc(settings.byteLength)
+      module.HEAPF32.set(settings, ptr / 4)
+      module._vehicleSetTuning(vehicleId, ptr, settings.length)
+      module._free(ptr)
+    },
+    vehicleSetInput: (vehicleId: number, forward: number, right: number, brake: number, handBrake: number) =>
+      module._vehicleSetInput(vehicleId, forward, right, brake, handBrake),
+    vehicleGetState: (vehicleId: number, out: Float32Array) =>
+      readInto(out, Math.min(out.length, READ_SCRATCH), (ptr) => module._vehicleGetState(vehicleId, ptr, Math.min(out.length, READ_SCRATCH))),
+    vehicleReset: (vehicleId: number, x: number, y: number, z: number, qx: number, qy: number, qz: number, qw: number) =>
+      module._vehicleReset(vehicleId, x, y, z, qx, qy, qz, qw),
+    vehicleBodyId: (vehicleId: number): number => module._vehicleBodyId(vehicleId),
+    // Ragdoll (Jolt Ragdoll over a model's bones). Bone list + settings blob staged into the wasm heap
+    // for the call; Jolt copies everything it keeps, so both buffers are freed right after.
+    ragdollCreate: (rootEntityId: number, bones: Uint32Array, settings: Float32Array): number => {
+      const ptrB = module._malloc(bones.byteLength)
+      module.HEAPU32.set(bones, ptrB / 4)
+      const ptrS = module._malloc(settings.byteLength)
+      module.HEAPF32.set(settings, ptrS / 4)
+      const id = module._ragdollCreate(rootEntityId, ptrB, bones.length, ptrS, settings.length)
+      module._free(ptrS)
+      module._free(ptrB)
+      return id
+    },
+    ragdollDestroy: (ragdollId: number) => module._ragdollDestroy(ragdollId),
+    ragdollActivate: (ragdollId: number, vx: number, vy: number, vz: number): boolean =>
+      !!module._ragdollActivate(ragdollId, vx, vy, vz),
+    ragdollDeactivate: (ragdollId: number) => module._ragdollDeactivate(ragdollId),
+    ragdollActive: (ragdollId: number): boolean => !!module._ragdollActive(ragdollId),
+    ragdollBodyId: (ragdollId: number, index: number): number => module._ragdollBodyId(ragdollId, index),
+    computeBoundingBox(entityId: number) {
+      // Returns a fresh 6-float [minX,minY,minZ, maxX,maxY,maxZ]. Uses the shared scratch (the old
+      // code malloc'd per call AND never freed it — a leak) and copies out, so the result is a
+      // standalone, retainable array (no live view over the wasm heap that detaches on growth).
+      const out = new Float32Array(6)
+      readInto(out, 6, ptr => module._computeBoundingBox(entityId, ptr))
+      return out
+    },
+    // Screen inputs are logical px; scale to backing px for the native (viewport-space) pick.
+    raycastView: (offsetX: number, offsetY: number) => module._raycastView(offsetX * resFactor, offsetY * resFactor),
+    setCulling: module._setCulling,
+    setGlbCulling: module._setGlbCulling,
+    // Culling default for animated GLBs (Model.load): only once the wasm carries the export — an older
+    // binary leaves the SDK on the always-draw default (see bridges.d.ts).
+    skinnedCullingSupported: module._skinnedCullingSupported ? () => !!module._skinnedCullingSupported() : undefined,
+    // Model.lod / Animator.lod (docs/lod-plan.md) — only once the wasm carries the LOD pass.
+    setLod: module._setLod ? (entityId: number, mesh: number, anim: number) => module._setLod(entityId, mesh, anim) : undefined,
+    // Shadow flags across a whole GLB instance (glb.cpp setGlbShadows). Only present once the wasm
+    // carries the export — the SDK feature-detects it, so an older binary just leaves models casting.
+    setGlbShadows: module._setGlbShadows,
+    hasMesh: module._hasMesh,
+    cloneEntity: module._cloneEntity,
+    setMaterialGlobalParameter: module._setMaterialGlobalParameter,
+
+    setParent: module._setParent as (entityId: number, parentEntityId: number, worldPositionStays: boolean) => void,
+    setParentNull: module._setParentNull,
+    // Batch setParent; children keep their LOCAL transform (worldPositionStays = false) — the same
+    // semantics as the lite scene core and the creator-pkg binding.
+    addChildren: (parentEntityId: number, entityIds: number[]) => {
+      for (const id of entityIds) module._setParent(id, parentEntityId, false)
+    },
+    getParent: module._getParent,
+    getChildCount: module._getChildCount,
+    getChild: module._getChild,
+    getMaterial: module._getMaterial,
+    createARPlane: module._createARPlane,
+    updateProjectionMatrixAR: module._updateProjectionMatrixAR,
+    getCameraFov: module._getCameraFov,
+    // Stored per scene natively and re-applied on every _setViewport — nothing to re-send on resize.
+    setCameraProjection: module._setCameraProjection,
+
+    // Particle systems — 3 methods; all config crosses as one tagged Float32Array
+    createParticleSystem: module._createParticleSystem,
+    spawnParticles: module._spawnParticles,
+    setParticleSystemConfig(entityId: number, data: Float32Array) {
+      const ptr: number = module._malloc(data.length * 4)
+      module.HEAPF32.set(data, ptr / 4)
+      module._setParticleSystemConfig(entityId, ptr, data.length)
+      module._free(ptr)
+    },
+    createNoise: module._createNoise,
+    setNoiseFrequency: module._setNoiseFrequency,
+    setNoiseOctaves: module._setNoiseOctaves,
+    setNoiseFractalLunacrity: module._setNoiseFractalLunacrity,
+    setNoiseFractalGain: module._setNoiseFractalGain,
+    getNoise2D: module._getNoise2D,
+    getNoise3D: module._getNoise3D,
+
+    createARController(sceneId: number, cameraId: number, mode: string, onTrack: (entityId: number, track: boolean) => void): void {
+      throw new Error("createARController is not implemented")
+    },
+    launchAR(sceneId: number, onComplete: () => void, onReject: () => void): void {
+      throw new Error("launchAR is not implemented")
+    },
+    stopAR(): void {
+      throw new Error("stopAR is not implemented")
+    },
+    createRootAnchor(sceneId: number): number {
+      throw new Error("createRootAnchor is not implemented")
+    },
+    createAnchor(sceneId: number, physicalWidth: number, sourceId: number): number {
+      throw new Error("createAnchor is not implemented")
+    },
+    getSceneMaterial(sceneId: number): number {
+      throw new Error("getSceneMaterial is not implemented")
+    },
+    getName(entityId: number) {
+      const namePtr = module._getName(entityId)
+      if (namePtr === 0) {
+        return ""
+      }
+      return module.UTF8ToString(namePtr)
+    },
+    findNode(entityId: number, name: string): number {
+      const maxLen = name.length * 4 + 1
+      const ptr = module._malloc(maxLen)
+      module.stringToUTF8(name, ptr, maxLen)
+      const found = module._findNode(entityId, ptr) as number
+      module._free(ptr)
+      return found
+    },
+
+    setName(entityId: number, name: string) {
+      const maxLen = name.length + 1;
+      const uniformPtr = module._malloc(maxLen);
+      module.stringToUTF8(name, uniformPtr, maxLen);
+      module._setName(entityId, uniformPtr)
+      module._free(uniformPtr)
+    },
+
+    createMediaPlayerTexture,
+
+    // Per-frame aspect update(dt) dispatch, fired from inside render(): early = before the physics step,
+    // late = after animations/particles, just before draw. Single-slot (the SDK registers one dispatcher
+    // per phase that iterates its own updater list). See init.cpp / lib.js.
+    setEarlyUpdate: (callback: (dt: number) => void) => module.onEarlyUpdate = callback,
+    setLateUpdate: (callback: (dt: number) => void) => module.onLateUpdate = callback,
+    // Fixed phase (once per physics substep, dt = 1/60): bound only when the wasm exports the gate, so a
+    // wasm predating it leaves the SDK on its own accumulator instead of a phase that never fires.
+    ...((module as any)._setFixedUpdateEnabled ? {
+      setFixedUpdate: (callback: ((dt: number) => void) | null) => {
+        (module as any).onFixedUpdate = callback ?? undefined
+        ;(module as any)._setFixedUpdateEnabled(callback ? 1 : 0)
+      },
+    } : {}),
+    // Engine clock multiplier (SDK Time.scale / Time.paused → physics, animators, particles). Bound
+    // only when the wasm exports it — the SDK feature-detects and a wasm predating it just keeps its
+    // sims at wall-clock speed instead of pretending to scale.
+    ...((module as any)._setTimeScale ? { setTimeScale: (scale: number) => (module as any)._setTimeScale(scale) } : {}),
+    // Camera exposure (aperture / shutter / ISO) — bound when the wasm exports it.
+    ...((module as any)._setCameraExposure ? { setCameraExposure: (sceneId: number, aperture: number, shutterSpeed: number, sensitivity: number) => (module as any)._setCameraExposure(sceneId, aperture, shutterSpeed, sensitivity) } : {}),
+    // Display output range / HDR look (creator-gl setDisplayHeadroom & co, filament patch 0018) —
+    // bound when the wasm exports them. No web host asks the canvas for an extended-range surface
+    // yet (float16 canvas + rec2100 colour spaces are behind flags), so the headroom reads SDR and
+    // device.hdr's setters are stored, not seen.
+    ...((module as any)._getDisplayHeadroom ? {
+      getDisplayHeadroom: () => (module as any)._getDisplayHeadroom(),
+      getDisplayMaxHeadroom: () => Math.max(1, (module as any)._getDisplayHeadroom()),
+      setHdrStrength: (strength: number) => (module as any)._setHdrStrength(strength),
+      getHdrStrength: () => (module as any)._getHdrStrength(),
+      setHdrPaperWhite: (paperWhite: number) => (module as any)._setHdrPaperWhite(paperWhite),
+      getHdrPaperWhite: () => (module as any)._getHdrPaperWhite(),
+    } : {}),
+    // Physics contact/sensor events (drained after each step): a/b = entity ids, type 0 enter / 1 exit.
+    setOnPhysicsEvent: (callback: (a: number, b: number, type: number) => void) => module.onPhysicsEvent = callback,
+    setDefaultIbl(sceneId: number, intensity: number) {
+      const ptr = module._malloc(iblBuffer.byteLength);
+      module.HEAPU8.set(new Uint8Array(iblBuffer), ptr)
+      module._createIblLight(sceneId, ptr, iblBuffer.byteLength, intensity)
+    },
+    setBloomOptions: module._setBloomOptions,
+    setUniformColor(materialId: number, uniform: string, color: number) {
+      call("_setUniformRgb", materialId, uniform, color)
+    },
+    setUniformRgb(materialId: number, uniform: string, color: number) {
+      call("_setUniformRgb", materialId, uniform, color)
+    },
+    setUniformRgba(materialId: number, uniform: string, color: number) {
+      call("_setUniformRgba", materialId, uniform, color)
+    },
+    setUniformFloat(materialId: number, uniform: string, value: number) {
+      call("_setUniformFloat", materialId, uniform, value)
+    },
+    setUniformBoolean(materialId: number, uniform: string, value: boolean) {
+      call("_setUniformBoolean", materialId, uniform, value)
+    },
+    setUniformTexture(materialId: number, uniform: string, systemId: number, wrapS: number, wrapT: number) {
+      call("_setUniformTexture", materialId, uniform, systemId, wrapS, wrapT)
+    },
+    setUniformArray(materialId: number, uniform: string, value: Float32Array) {
+      const uniformPtr = module._malloc(value.byteLength);
+      module.HEAPF32.set(value, uniformPtr/4)
+      call("_setUniformArray", materialId, uniform, uniformPtr, value.length)
+    },
+    setUniformNull(materialId: number, uniform: string) {
+      // material.set(key, null): a SAMPLER_2D uniform resets to the engine's white 1x1 (see
+      // creator-gl setUniformNull). Guarded so a stale creator-gl.wasm (built before the export
+      // existed) degrades to a no-op instead of a crash.
+      if (!module._setUniformNull) return
+      const maxLen = uniform.length + 1
+      const uniformPtr = module._malloc(maxLen)
+      module.stringToUTF8(uniform, uniformPtr, maxLen)
+      module._setUniformNull(materialId, uniformPtr)
+      module._free(uniformPtr)
+    },
+    // A built-in material by shader NAME, resolved through the same local-resource path the SDK
+    // factories use (Material.lit → fetchLocal("lit.filamat")). The shader must have been
+    // preloaded (ViewerOptions.preloads / putLocalBuffer) — same requirement as the factories.
+    createMaterialS: (name: string): number => {
+      const systemId = _fetchLocal(`${name}.filamat`)
+      if (systemId < 0) throw new Error(`createMaterialS: material "${name}.filamat" is not preloaded on this host`)
+      return module._createMaterialInstance(compileMaterial(systemId))
+    },
+    createMaterial: (systemId: number) => {
+      return module._createMaterialInstance(compileMaterial(systemId))
+    },
+    setMesh(entityId: number, materialId: number, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, meshType: number, uv1?: Float32Array) {
+      const ptrVertices = module._malloc(vertices.byteLength)
+      const ptrNormals = module._malloc(normals.byteLength)
+      const ptrIndices = module._malloc(indices.byteLength)
+      const ptrUv = module._malloc(uv.byteLength)
+      module.HEAPF32.set(vertices, ptrVertices/4)
+      module.HEAPF32.set(normals, ptrNormals/4)
+      module.HEAPU16.set(indices, ptrIndices/2)
+      module.HEAPF32.set(uv, ptrUv/4)
+
+      // the lightmap UV set rides the newer export; a wasm without it duplicates uv into UV1
+      if (uv1 && module._createMeshEx) {
+        const ptrUv1 = module._malloc(uv1.byteLength)
+        module.HEAPF32.set(uv1, ptrUv1/4)
+        module._createMeshEx(entityId, materialId, ptrVertices, ptrNormals, ptrIndices, ptrUv, vertices.length/3, indices.length, meshType, ptrUv1)
+        return
+      }
+      module._createMesh(entityId, materialId, ptrVertices, ptrNormals, ptrIndices, ptrUv, vertices.length/3, indices.length, meshType)
+    },
+    attachCameraToAR(sceneId: number, cameraId: number, onProjectChange: () => void) {
+      module._attachCameraToScene(sceneId, cameraId)
+    },
+    createGLView() {},
+    openScene(sceneId: number) {
+      if (!sceneOpened) {
+        requestAnimationFrame(render)
+        canvas.style.display = "block"
+      }
+      sceneOpened = true
+      module._openScene(sceneId)
+      module._setViewport(canvas.width, canvas.height)
+    },
+    _onResize(width: number, height: number, factor = 1) {
+      resFactor = factor
+      logicalW = width
+      logicalH = height
+      // Backing store in device px, CSS box pinned to logical px (host-shared crispness pattern).
+      canvas.width = Math.max(1, Math.round(width * factor))
+      canvas.height = Math.max(1, Math.round(height * factor))
+      canvas.style.width = width + "px"
+      canvas.style.height = height + "px"
+      module._setViewport(canvas.width, canvas.height)
+    },
+    closeScene() {
+      canvas.style.display = "none"
+      sceneOpened = false
+    },
+    traverse(entityId: number, callback: (entityId: number) => void) {
+      module.traverseCallback = callback
+      module._traverseEm(entityId)
+    },
+    setMatrix(entityId: number, matrix: Float32Array) {
+      const ptrMatrix = module._malloc(matrix.byteLength)
+      module.HEAPF32.set(matrix, ptrMatrix/4)
+      module._setMatrix(entityId, ptrMatrix)
+      module._free(ptrMatrix)
+    },
+    setWorldMatrix(entityId: number, matrix: Float32Array) {
+      const ptrMatrix = module._malloc(matrix.byteLength)
+      module.HEAPF32.set(matrix, ptrMatrix/4)
+      module._setWorldMatrix(entityId, ptrMatrix)
+      module._free(ptrMatrix)
+    },
+    getMatrix(entityId: number, matrix: Float32Array) {
+      readInto(matrix, 16, ptr => module._getMatrix(entityId, ptr))
+    },
+    getWorldMatrix(entityId: number, matrix: Float32Array) {
+      readInto(matrix, 16, ptr => module._getWorldMatrix(entityId, ptr))
+    },
+    getWorldPosition(entityId: number, matrix: Float32Array) {
+      readInto(matrix, 3, ptr => module._getWorldPosition(entityId, ptr))
+    },
+    getWorldDirection(entityId: number, mode: number, matrix: Float32Array) {
+      readInto(matrix, 3, ptr => module._getWorldDirection(entityId, mode, ptr))
+    },
+    getWorldMatrixInverse(entityId: number, matrix: Float32Array) {
+      readInto(matrix, 16, ptr => module._getWOrldMatrixInverse(entityId, ptr))
+    },
+    getCameraViewDirection(sceneId: number, screenX: number, screenY: number, outVec: Float32Array) {
+      // Screen inputs are logical px; the native viewport is backing px → scale up by the factor.
+      readInto(outVec, 3, ptr => module._getCameraViewDirection(sceneId, screenX * resFactor, screenY * resFactor, ptr))
+    },
+    getDisplaySize() {
+      // Logical (CSS-px) viewport — device.pixelRatio carries the density separately.
+      return [ logicalW || canvas.width, logicalH || canvas.height ]
+    },
+    getChildren(entityId: number) {
+
+      const childrenIds = []
+      const chunk_size = 32
+
+      for (let i = 0; i < 256; i++) {
+        const ptr = module._malloc(chunk_size * 4)/4
+        const childCount = module._getChildrenIter(entityId, ptr*4, i * chunk_size, chunk_size)
+  
+        for (let i = 0; i < childCount; i++) {
+          childrenIds.push(module.HEAPU32[ptr + i])
+        }
+        module._free(ptr*4)
+        if (childCount < chunk_size) {
+          break
+        }
+      }
+
+      return childrenIds
+    },
+    createTexture(systemId: number, onComplete: (textureId: number, width: number, height: number) => void, onReject: any) {
+      const blob = getBlob(systemId)
+      // KTX2 (Basis Universal): createImageBitmap can't decode it — the wasm core transcodes it
+      // (BC3 via WEBGL_compressed_texture_s3tc, else RGBA8) and keeps the file's mip chain.
+      blob.slice(0, 12).arrayBuffer().then((head) => {
+        if (!isKtx2Bytes(new Uint8Array(head))) return false
+        return blob.arrayBuffer().then((buf) => {
+          const bytes = new Uint8Array(buf)
+          const ptr = module._malloc(bytes.length)
+          module.HEAPU8.set(bytes, ptr)
+          const texId = module._createTextureFromKtx2(ptr, bytes.length) >>> 0
+          module._free(ptr)
+          if (texId === 0xFFFFFFFF) throw new Error('KTX2 transcode failed')
+          onComplete(texId, module._getTextureWidth(texId), module._getTextureHeight(texId))
+          return true
+        })
+      }).then((handled) => { if (!handled) createBitmapTexture(blob, onComplete, onReject) }, onReject)
+    },
+    // --- textures from a _creatorCanvas surface (straight sRGB RGBA8 → Filament texture; no decode) ---
+    // Same registry as createTexture, so setUniformTexture(matId, uniform, texId, …) consumes it as-is.
+    createTextureFromCanvas(surfaceId: number): number {
+      const surf = options.canvasHost?.readSurface(surfaceId)
+      if (!surf) return 0
+      const bytes = new Uint8Array(surf.data.buffer, surf.data.byteOffset, surf.data.byteLength)
+      const ptr = module._malloc(bytes.length)
+      module.HEAPU8.set(bytes, ptr)
+      const texId = module._createTextureFromRGBA(ptr, surf.width, surf.height)
+      module._free(ptr)
+      return texId
+    },
+    updateTextureFromCanvas(texId: number, surfaceId: number): void {
+      const surf = options.canvasHost?.readSurface(surfaceId)
+      if (!surf) return
+      const bytes = new Uint8Array(surf.data.buffer, surf.data.byteOffset, surf.data.byteLength)
+      const ptr = module._malloc(bytes.length)
+      module.HEAPU8.set(bytes, ptr)
+      module._updateTextureFromRGBA(texId, ptr, surf.width, surf.height)
+      module._free(ptr)
+    },
+    async createGlb(systemId: number, onComplete: (resp: number) => void, onReject: (err: any) => void) {
+      let glbBuffer = 0
+      try {
+        const buf = getBuffer(systemId)
+        glbBuffer = module._malloc(buf.byteLength)
+        module.HEAPU8.set(new Uint8Array(buf), glbBuffer)
+        
+        const entityId = module._loadGlb(glbBuffer, buf.byteLength)
+        // KTX2/Basis textures transcode asynchronously over several frames. Poll until fully loaded
+        // (progress >= 1) instead of a fixed ~100ms window — otherwise slower KTX2 transcodes don't
+        // finish in time and those textures render black. Generous cap (~5s) as a safety net.
+        for (let i = 0; i < 500; i++) {
+          if (module._glbLoadingUpdate() >= 1) break
+          await new Promise(res => setTimeout(res, 10))
+        }
+        
+        onComplete(entityId)
+      } catch(e) {
+        // onReject hands the error to app code, so the global handler never sees it.
+        symbolizeWasmError(e)
+        onReject(e)
+      } finally {
+        if (glbBuffer !== 0) {
+          module._free(glbBuffer)
+        }
+      }
+    },
+    // ---- Animation system (docs/animation-plan.md): clip sets + animators ----
+    loadClips(systemId: number, onComplete: (clipSetId: number) => void, onReject: (err: unknown) => void) {
+      let ptr = 0
+      try {
+        const buf = getBuffer(systemId)
+        ptr = module._malloc(buf.byteLength)
+        module.HEAPU8.set(new Uint8Array(buf), ptr)
+        onComplete(module._loadClips(ptr, buf.byteLength))
+      } catch (e) {
+        symbolizeWasmError(e)
+        onReject(e)
+      } finally {
+        if (ptr !== 0) module._free(ptr)
+      }
+    },
+    createClipFromTracks(names: string, data: Float32Array) {
+      const nameLen = names.length * 3 + 1
+      const namePtr = module._malloc(nameLen)
+      module.stringToUTF8(names, namePtr, nameLen)
+      const dataPtr = module._malloc(data.byteLength)
+      module.HEAPF32.set(data, dataPtr / 4)
+      const id = module._createClipFromTracks(namePtr, dataPtr, data.length)
+      module._free(dataPtr)
+      module._free(namePtr)
+      return id
+    },
+    getClipSetInfo(clipSetId: number) {
+      const count = module._getClipSetCount(clipSetId)
+      if (count === 0) return []
+      const size = count * (4 + 1 + 200 + 2)
+      const ptr = module._malloc(size)
+      module._getClipSetInfo(clipSetId, ptr)
+      const view = new DataView(module.HEAPU8.buffer.slice(ptr, ptr + size))
+      module._free(ptr)
+      const out: { name: string, duration: number, trackCount: number }[] = []
+      let index = 0
+      for (let i = 0; i < count; i++) { out.push({ name: "", duration: view.getFloat32(index, true), trackCount: 0 }); index += 4 }
+      for (let i = 0; i < count; i++) {
+        const len = view.getUint8(index); index += 1
+        out[i].name = decoder.decode(new Uint8Array(view.buffer, index, len)); index += len
+      }
+      for (let i = 0; i < count; i++) { out[i].trackCount = view.getUint16(index, true); index += 2 }
+      return out
+    },
+    getGlbClipSet: (entityId: number) => module._getGlbClipSet(entityId),
+    sliceClip: (clipSetId: number, clip: number, start: number, end: number) => module._sliceClip(clipSetId, clip, start, end),
+    destroyClipSet: (clipSetId: number) => module._destroyClipSet(clipSetId),
+    animatorCreate: (entityId: number) => module._animatorCreate(entityId),
+    animatorDestroy: (animatorId: number) => module._animatorDestroy(animatorId),
+    setClipEvents(clipSetId: number, clip: number, times: Float32Array) {
+      const ptr = module._malloc(Math.max(4, times.length * 4))
+      module.HEAPF32.set(times, ptr / 4)
+      module._setClipEvents(clipSetId, clip, ptr, times.length)
+      module._free(ptr)
+    },
+    animatorBind: (animatorId: number, clipSetId: number, clipIndex: number, layer: number) =>
+      module._animatorBind(animatorId, clipSetId, clipIndex, layer),
+    animatorBoundTracks: (animatorId: number, slot: number) => module._animatorBoundTracks(animatorId, slot),
+    animatorSetBlend(animatorId: number, layer: number, dims: number, slots: Uint16Array, positions: Float32Array, fade: number, speed: number) {
+      const n = Math.min(slots.length, Math.floor(positions.length / dims))
+      const sp = module._malloc(Math.max(2, n * 2)), pp = module._malloc(Math.max(4, n * dims * 4))
+      module.HEAPU16.set(slots.subarray(0, n), sp / 2)
+      module.HEAPF32.set(positions.subarray(0, n * dims), pp / 4)
+      module._animatorSetBlend(animatorId, layer, dims, sp, pp, n, fade, speed)
+      module._free(sp); module._free(pp)
+    },
+    animatorSetBlendValue: (animatorId: number, layer: number, x: number, y: number) => module._animatorSetBlendValue(animatorId, layer, x, y),
+    animatorPlay: (animatorId: number, slot: number, loop: boolean, speed: number, fadeIn: number, fadeOut: number, restart: boolean) =>
+      module._animatorPlay(animatorId, slot, loop, speed, fadeIn, fadeOut, restart),
+    animatorStop: (animatorId: number, layer: number, slot: number, fade: number) => module._animatorStop(animatorId, layer, slot, fade),
+    animatorSeek: (animatorId: number, slot: number, time: number) => module._animatorSeek(animatorId, slot, time),
+    animatorGetSlotTime: (animatorId: number, slot: number) => module._animatorGetSlotTime(animatorId, slot),
+    animatorGetSlotWeight: (animatorId: number, slot: number) => module._animatorGetSlotWeight(animatorId, slot),
+    animatorSetLayer(animatorId: number, layer: number, weight: number, additive: boolean, maskRoot: string) {
+      const len = maskRoot.length * 3 + 1
+      const ptr = module._malloc(len)
+      module.stringToUTF8(maskRoot, ptr, len)
+      module._animatorSetLayer(animatorId, layer, weight, additive, ptr)
+      module._free(ptr)
+    },
+    animatorSetGlobal: (animatorId: number, speed: number, paused: boolean) => module._animatorSetGlobal(animatorId, speed, paused),
+    animatorSetRootMotion(animatorId: number, bone: string, apply: number) {
+      const len = bone.length * 3 + 1
+      const ptr = module._malloc(len)
+      module.stringToUTF8(bone, ptr, len)
+      module._animatorSetRootMotion(animatorId, ptr, apply)
+      module._free(ptr)
+    },
+    animatorGetRootMotion(animatorId: number, out: Float32Array) {
+      const ptr = module._malloc(12)
+      module._animatorGetRootMotion(animatorId, ptr)
+      out.set(module.HEAPF32.subarray(ptr / 4, ptr / 4 + 3))
+      module._free(ptr)
+    },
+    setOnAnimatorEvent: (callback: (animatorId: number, slot: number, type: number) => void) => module.onAnimatorEvent = callback,
+    async loadGlb(systemId: number, onComplete: (resp: ArrayBuffer) => void, onReject: (err: any) => void) {
+      let glbBuffer = -1
+      let buffer = -1
+      try {
+        const buf = getBuffer(systemId)
+        glbBuffer = module._malloc(buf.byteLength)
+        module.HEAPU8.set(new Uint8Array(buf), glbBuffer)
+
+        const entityId = module._loadGlb(glbBuffer, buf.byteLength)
+        
+        // KTX2/Basis textures transcode asynchronously over several frames. Poll until fully loaded
+        // (progress >= 1) instead of a fixed ~100ms window — otherwise slower KTX2 transcodes don't
+        // finish in time and those textures render black. Generous cap (~5s) as a safety net.
+        for (let i = 0; i < 500; i++) {
+          if (module._glbLoadingUpdate() >= 1) break
+          await new Promise(res => setTimeout(res, 10))
+        }
+
+        buffer = module._malloc(8192*4)
+        const bufferSize = module._getGlbStructure(entityId, buffer)
+        const targetBuffer = module.HEAPU8.buffer.slice(buffer, buffer+bufferSize)
+  
+        onComplete(targetBuffer as ArrayBuffer)
+      } catch (e) {
+        // onReject hands the error to app code, so the global handler never sees it.
+        symbolizeWasmError(e)
+        onReject(e)
+      } finally {
+        if (glbBuffer !== 0) {
+          module._free(glbBuffer)
+        }
+        if (buffer !== 0) {
+          module._free(buffer)
+        }
+      }
+    },
+    stopAllPlayers() {
+      removePlayers()
+    },
+    async createEngine() {},
+    async warmRender(sceneId: number, onComplete: () => void) {
+      module._setVisibleAll(sceneId, true)
+
+      for (let i = 0; i < 10; i++) {
+        if (module._renderScene(sceneId)) {
+          break
+        }
+        await new Promise(res => setTimeout(res, 10))
+      }
+
+      module._setVisibleAll(sceneId, false)
+      onComplete()
+    },
+    async captureImage(sceneId: number, onComplete: (bufferId: number, name: string, size: number) => void, onReject: () => void) {
+      const temp = new OffscreenCanvas(canvas.width, canvas.height)
+      const ctx = temp.getContext("2d")!
+      ctx.drawImage(canvas, 0, 0,)
+      const blob = await temp.convertToBlob({ type: "image/png" })
+      const buffer = await blob.arrayBuffer()
+      const bufferId = putBuffer(buffer)
+      onComplete(bufferId, "image.png", blob.size)
+    },
+    /** Draw one frame synchronously; true when a frame was actually drawn. Hosts call this
+     *  immediately before reading the canvas (the simulator's "Save image") — without it the
+     *  drawing buffer is already discarded and the 3D layer reads back empty. Filament may DECLINE
+     *  a frame, so callers retry until it returns true (same shape as warmRender).  */
+    _renderNow: renderOnce,
+    _fetch,   // Здесь функция для внутреннего использования (в Simulator.vue)
+    _getPlayer: getPlayer,
+    _setARController(newARController: any) {
+      arController = newARController
+    },
+    _raycastView(offsetX: number, offsetY: number) {
+      return module._raycastView(offsetX * resFactor, offsetY * resFactor)
+    },
+    _createGLTexture(canvas: HTMLCanvasElement | OffscreenCanvas) {
+      const glTextureId = module.GL.getNewId(module.GL.textures)
+      const glTexture = gl.createTexture()
+      module.GL.textures[glTextureId] = glTexture
+
+      gl.bindTexture(gl.TEXTURE_2D, glTexture)
+      gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+      gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+      gl.pixelStorei(gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE );
+      gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA8, canvas.width, canvas.height)
+
+      const textureId = module._importTexture(glTextureId, canvas.width, canvas.height)
+
+      return { gl, glTexture, textureId }
+    },
+    _dispose() {
+      this.closeScene()
+      this.stopAllPlayers()
+
+      // Release filament's headless swapchain while the context is still valid, then force the
+      // WebGL2 context to be freed now. Without loseContext the context lingers until the module is
+      // GC'd, and the browser caps live contexts (~16) — so reloads eventually drop the oldest.
+      try { module._destroySwapChain?.() } catch {}
+      gl.getExtension("WEBGL_lose_context")?.loseContext()
+
+      // These globals hold the context (and its canvas) alive process-wide; drop them so nothing
+      // outlives this run. Guard so a newer run's context (already swapped in) is never cleared.
+      if ((window as any).filament_glContext === gl) {
+        ;(window as any).filament_glContext = null
+        ;(window as any).filament_glOptions = null
+      }
+    }
+  }
+}