lecodes-sdk 1.1.0 → 2.0.0

package/src/bridges/gl.d.ts

@@ -0,0 +1,1133 @@
+// The 3D engine bridge (`_creator`): engines/gl (Filament) + anim, physics (Jolt), particles, bake.
+// Part of the host contract: every runtime implements this global (runtime/native in C++, the web
+// runtimes in TS). Types are the PRECISE ones the native side reads (see ./types.d.ts); the SDK
+// only sees numbers. The ABI checker (scripts/check-pkg-bridges.mjs) reads this folder.
+import type { bytes, f32, f64, handle, i32, u32, u8 } from "./types"
+
+// Object types of the contract (the generator's struct rule: the engine fills a C struct of the same
+// name and fields, the bridge converts it field by field — see scripts/gen-bridges.ts).
+/** One clip of a clip set. */
+export type ClipInfo = { name: string, duration: f32, trackCount: u32 }
+/** One weighted joint of a picked vertex (`pickTriangle`): the joint's name, "#<index>" when it has none. */
+export type PickBone = { name: string, weight: f32 }
+/** One vertex of the picked triangle: `bind` = its position in mesh space, `world` = skinned this frame,
+ *  `bones` = its JOINTS_0 / WEIGHTS_0 pairs with weight > 0 (empty = unweighted). */
+export type PickVertex = { index: u32, bind: [f32, f32, f32], world: [f32, f32, f32], bones: PickBone[] }
+/** The closest triangle under a screen point (`pickTriangle`). `node` = the mesh node's own entity (0
+ *  when the host has none), `lightmapGroup` / `uv1` only when the node / primitive carry them. */
+export type TrianglePick = {
+  entity: u32, node: u32, nodeName: string, lightmapGroup?: i32,
+  mesh: string, primitive: u32, material: string,
+  triangle: u32, backface: boolean, distance: f32,
+  point: [f32, f32, f32], bary: [f32, f32, f32], uv1?: [f32, f32],
+  skin: string, vertices: PickVertex[],
+}
+
+declare global {
+  // ---- 3D engine (Filament / creator-gl) -------------------------------------------------------
+  /** @engine gl */
+  var _creator: {
+    backend: string
+    /** Bring the engine up (or rebuild it) — the deferred start of a bundle whose header says
+     *  `// gl: defer`; throws when the GPU refuses the shared context. A no-op on a host whose
+     *  engine is always up. @custom */
+    createEngine(): void
+
+    createScene(): u32
+    createOverlayScene(sceneId: u32): u32
+    /** @custom */
+    createGLView(): void
+    /** @custom */
+    openScene(sceneId: u32): void
+    /** @custom */
+    closeScene(): void
+    /** @custom */
+    launchAR(sceneId: u32, onComplete: () => void, onReject: () => void): void
+    /** @custom */
+    stopAR(): void
+    /** @custom */
+    launchVR(sceneId: u32, onComplete: () => void, onReject: (err?: unknown) => void): void
+    /** @custom */
+    stopVR(): void
+    addEntityToScene(sceneId: u32, entityId: u32): void
+    removeEntityFromScene(sceneId: u32, entityId: u32): void
+    /** @custom */
+    warmRender(sceneId: u32, onComplete: () => void): void
+    /** Compile every shader variant the scene's materials can need — sun / shadows / fog / skinning
+     *  and the dynamic-light key — on the backend's compiler threads, then call back. Materials
+     *  loaded later are queued in the background as they are created. Optional: a host without it
+     *  resolves at once (the SDK feature-detects). @custom */
+    precompileShaders?(sceneId: u32, onComplete: () => void): void
+
+    /** An OWNED root (owned.h): loose and dropped → its whole subtree goes. @owned GlEntity */
+    createEntity(): Handle
+    /** @owned GlEntity */
+    cloneEntity(entityId: u32): Handle
+    /** The subtree, its records, and the SDK hears the ids (the freed channel). @custom */
+    destroyEntity(entityId: u32): void
+    /** True while the engine holds the entity (a parent, a scene); the SDK unpins a node this says no to. */
+    entityIsOwned(entityId: u32): boolean
+
+    setMatrix(entityId: u32, mat: Float32Array): void
+    setWorldMatrix(entityId: u32, mat: Float32Array): void
+    getChildCount(entityId: u32): u32
+    getChild(entityId: u32, index: i32): u32
+
+    setPosition(entityId: u32, x: f32, y: f32, z: f32): void
+    setQuaternion(entityId: u32, x: f32, y: f32, z: f32, w: f32): void
+    setEulerAngles(entityId: u32, x: f32, y: f32, z: f32, order: u8): void
+    setScale(entityId: u32, x: f32, y: f32, z: f32): void
+
+    setParent(entityId: u32, parentEntityId: u32, worldPositionStays: boolean): void
+    setParentNull(entityId: u32, worldPositionStays: boolean): void
+    getParent(entityId: u32): u32
+    /** @custom */
+    traverse(entityId: u32, callback: (entityId: number) => void): void
+    /** Descendant of `entityId` by name, with the Animator's binding rule: exact name first, then the
+     *  short name (after the last `:` / `|` — Mixamo `mixamorig:Hips`); a skin joint beats a plain node
+     *  of the same name (merged GLBs carrying a leftover skeleton copy), otherwise first in tree order.
+     *  0 when absent. Optional: hosts that predate it fall back to the SDK's traverse walk (node.bone). */
+    findNode?(entityId: u32, name: string): u32
+
+    /** shadowCascades (2026-09-23, optional 9th arg): 1-4 shadow-map cascades over shadowDistance; a host that predates it
+     *  renders one. */
+    createSunLight(entityId: u32, x: f64, y: f64, z: f64, intensity: f64, color: u32, shadowsQuality: i32, shadowDistance: f64, shadowCascades?: i32): void
+    /** Punctual light. `intensity` is luminous POWER in lumens; `falloff` is the metres of
+     *  influence (filament's own default is 1 m, i.e. invisible, so it is always passed). */
+    createPointLight?(entityId: u32, intensity: f64, color: u32, falloff: f64, castShadows: boolean): void
+    /** The lightmap bake takes this point light as a RECTANGLE of `width` x `height` metres (an area light: a ceiling
+     *  panel) in the light's local XZ plane, emitting along its local -Y with the same lumens; 0, 0 = a point again. */
+    setLightBakeArea?(entityId: u32, width: f32, height: f32): void
+    /** Live intensity for any light (sun: lux, point: lumens) — a flash animates instead of rebuilding. */
+    setLightIntensity?(entityId: u32, intensity: f64): void
+    setLightColor?(entityId: u32, color: u32): void
+    /** `iblFetchId` (optional, -1 = none) names the scene's own probe; without it the host looks for a project-wide `ibl.ktx`. @custom */
+    setDefaultIbl(sceneId: u32, intensity: f64, iblFetchId?: i32): void
+    /** The environment's intensity in lux, live (`scene.environmentIntensity`) — `setDefaultIbl` is
+     *  the only other way to change it and it rebuilds the cubemap and the IndirectLight from the
+     *  ktx every call, so it can never carry a slider. No-op until the scene has an IBL. Optional:
+     *  hosts that predate it keep whatever `setDefaultIbl` set at open. */
+    setEnvironmentIntensity?(sceneId: u32, intensity: f32): void
+    setBloomOptions(sceneId: u32, enabled: boolean, strength: f32, quality: u8): void
+    setToneMapping?(sceneId: u32, mode: u8): void
+    /** Exposure of the scene's camera — filament's physical model: `aperture` f-stops,
+     *  `shutterSpeed` seconds, `sensitivity` ISO (default f/16, 1/125 s, ISO 100 = EV100 15, bright
+     *  sunlight). ISO ×2 = one stop brighter. Scene-referred light follows it; particle emission is
+     *  post-exposure and does not. Optional: hosts that predate it keep the fixed default. */
+    setCameraExposure?(sceneId: u32, aperture: f32, shutterSpeed: f32, sensitivity: f32): void
+    /** Display output range (macOS/iOS EDR, `device.hdr`). `getDisplayHeadroom` is what the engine
+     *  renders to right now: the screen's peak as a multiple of SDR white, quantised to half-stops;
+     *  0 or 1 = SDR. Live — it ramps up from 1 over the first seconds, follows brightness and the
+     *  screen under the window. `getDisplayMaxHeadroom` is the peak the surface can reach at all
+     *  (1 = SDR), constant once the surface exists: the value to branch content on. Optional: hosts
+     *  that predate it, or render 8-bit, are SDR. */
+    getDisplayHeadroom?(): f64
+    /** @c getDisplayHeadroom */
+    getDisplayMaxHeadroom?(): f64
+    /** HDR look, engine-wide (creator.h `setHdrStrength` / `setHdrPaperWhite`): `strength` 0..1 =
+     *  how much of the picture reaches for the headroom (0 only what SDR clipped, 1 nearly
+     *  everything), `paperWhite` 1..8 = where the operator's white lands as a multiple of SDR white
+     *  (the "HDR brightness" of a console calibration screen; clamped to the headroom). A host may
+     *  pin either from its environment — the getters report what is in force. Optional. */
+    setHdrStrength?(strength: f32): void
+    getHdrStrength?(): f64
+    setHdrPaperWhite?(paperWhite: f32): void
+    getHdrPaperWhite?(): f64
+    /** Screen-space ambient occlusion: the contact darkening in creases and where objects meet the
+     *  ground. `radius` is world-space metres, `power` the falloff contrast, `quality` 0 LOW … 3
+     *  ULTRA (sample count — not the buffer resolution, which stays half-res).
+     *  Optional: hosts that predate it render without AO and the SDK skips the call. */
+    setAmbientOcclusionOptions?(sceneId: u32, enabled: boolean, intensity: f32, radius: f32, power: f32, quality: u8): void
+    /** Distance fog / aerial perspective. `color` is packed 0xRRGGBB used as a TINT on the
+     *  in-scattered ambient — the engine multiplies it by the environment luminance, so white means
+     *  "as bright as the ambient" and it is NOT the absolute-radiance convention `setSkybox` uses.
+     *  `density` = extinction per metre at `height`, `heightFalloff` 1/m (0 = uniform),
+     *  `cutOff` <= 0 = apply at every distance (the skybox included — that is what blends the
+     *  horizon), `fromIbl` = take the colour from the environment in the view direction and tint
+     *  it by `color`.
+     *  Optional: hosts that predate it render without fog and the SDK skips the call. */
+    setFogOptions?(sceneId: u32, enabled: boolean, color: u32, distance: f32, density: f32, height: f32, heightFalloff: f32, maxOpacity: f32, cutOff: f32, fromIbl: boolean): void
+    setSkybox(sceneId: u32, color: u32): void
+    /** Draw the scene's IBL environment as the sky instead of a flat colour. No-op until the IBL
+     *  exists (setDefaultIbl runs first). Optional: hosts that predate it keep the flat skybox. */
+    setSkyboxFromEnvironment?(sceneId: u32): void
+    /** The sky from its own KTX1 cubemap. `fetchId` is a local-resource id (`_creatorFetch.local`
+     *  / an `asset()` handle), pointing at cmgen's `<name>_skybox.ktx` — the sharp single-mip file,
+     *  not the roughness-prefiltered `_ibl.ktx` beside it. Optional: hosts that predate it keep the
+     *  flat skybox. */
+    setSkyboxTexture?(sceneId: u32, fetchId: bytes): void
+    /** Temporal anti-aliasing (Filament's TAA) for the scene and its overlays: on, MSAA and FXAA are off for the
+     *  view; `feedback` = the history's share (0.12 default, higher = less ghosting, less smoothing), `sharpness` =
+     *  the post-TAA sharpen (0–1), `upscale` = the fraction the 3D is rendered at and TAA-upscaled from (0.5–1,
+     *  1 = none; below 1 Filament's dynamic resolution is off), `nearLimit` = the band in front of the camera (m,
+     *  0 = off) whose pixels keep their screen position instead of the camera's reprojection — a first-person
+     *  viewmodel, which would trail on every turn otherwise. Off restores the scene's MSAA state. Optional: a
+     *  host without it keeps MSAA. @c setTemporalAntiAliasing */
+    setTemporalAntiAliasing?(sceneId: u32, enabled: boolean, feedback: f32, sharpness: f32, upscale: f32, nearLimit: f32): void
+    /** @c setMultiSampleAntiAliasing */
+    setSceneMultiSampleAntiAliasing(sceneId: u32, enabled: boolean, scale: u8): void
+    /** Filament View::setStencilBufferEnabled (Scene.stencil). Optional. */
+    setSceneStencil?(sceneId: u32, enabled: boolean): void
+    /** Render resolution: `renderScale` (0.25–1) = fixed 3D-buffer scale vs the viewport (the UI is
+     *  untouched; a host that owns the 3D texture resizes it, one rendering into the swapchain may
+     *  ignore it), `dynamicResolution` = engine-adaptive scaling under that down to `minScale`.
+     *  Optional: older hosts predate it and the SDK skips the call. */
+    setSceneRenderOptions?(sceneId: u32, renderScale: f32, dynamicResolution: boolean, minScale: f32): void
+    /** Anisotropic filtering for every texture bound FROM HERE ON (1 = off, 2 = the engine default,
+     *  16 = max; clamped). Engine-wide rather than per scene, because a sampler is baked when its
+     *  texture is bound — a glTF binds during `Model.load`, and two scenes cannot disagree about a
+     *  texture they share. Call it before loading the assets it should apply to; `SceneOptions.
+     *  anisotropy` does that automatically (a scene's env runs before its nodes build). Optional:
+     *  hosts that predate it keep isotropic filtering and the SDK skips the call. */
+    setTextureAnisotropy?(level: f32): void
+    /** Engine-wide cap on texture size (`Texture.maxSize` / `SceneOptions.maxTextureSize`): a
+     *  KTX2 wider or taller than `size` loses its top mip levels on load, a glTF PNG/JPEG is
+     *  downsampled; 0 = no cap. Reaches textures created AFTER the call — a loaded level keeps
+     *  its textures, so a settings menu applies it on the next level load. `createTexture` flag
+     *  2 (FULL_SIZE) exempts one texture (lightmap pages). Optional: hosts that predate it load
+     *  full-size textures and the SDK skips the call. */
+    setTextureMaxSize?(size: u32): void
+    /** Depth-reading effects on / off (`scene.setDepthEffects`): soft particles (`depthFade`) and
+     *  projected decals read the scene depth, which costs a half-res depth pre-pass of every opaque
+     *  draw. Off = no pre-pass, hard-edged particles, decal sets draw nothing. Engine-wide, live.
+     *  Optional: hosts that predate it keep the effects and the SDK skips the call. */
+    setDepthEffects?(enabled: boolean): void
+    /** LOD distance (`scene.setLodBias`): the LOD pass' screen-size thresholds × `bias` — 2 = every
+     *  level switches at half the distance, 0.5 = full detail twice as far; 1 = the defaults
+     *  (0.30 / 0.12 / 0.05 of the viewport height). Engine-wide, live, clamped 0.25..8. Optional:
+     *  hosts without the LOD pass ignore it and the SDK skips the call. */
+    setLodBias?(bias: f64): void
+    setMaterialGlobalParameter(sceneId: u32, i: u32, x: f32, y: f32, z: f32, w: f32): void
+    getCameraFov(sceneId: u32, fovType: u8): f64
+    /** The scene camera's projection: VERTICAL fov in degrees + near/far clip distances (defaults
+     *  60 / 0.01 / 1000). Aspect stays host-owned — the host STORES these per scene and re-applies
+     *  them whenever the viewport changes, so one call outlives every resize. Optional: hosts that
+     *  predate it keep the fixed defaults and the SDK feature-detects (Camera.setProjection). */
+    setCameraProjection?(sceneId: u32, fov: f32, near: f32, far: f32): void
+
+    /** @into mat 16 */
+    getMatrix(entityId: u32, mat: Float32Array): void
+    /** @into mat 16 */
+    getWorldMatrix(entityId: u32, mat: Float32Array): void
+    /** @into mat 3 */
+    getWorldPosition(entityId: u32, mat: Float32Array): void
+    /** @into mat 3 */
+    getWorldDirection(entityId: u32, mode: u8, mat: Float32Array): void
+
+    /** @into mat 16 */
+    getWorldMatrixInverse(entityId: u32, mat: Float32Array): void
+    /** Screen inputs are LOGICAL px: the web host scales them to its backing store by hand. @into mat 3 @custom web */
+    getCameraViewDirection(sceneId: u32, screenX: f32, screenY: f32, mat: Float32Array): void
+
+    /** `uv1` (optional, 2 floats per vertex) is the lightmap UV set (Geometry.uv1); absent → the
+     *  host duplicates `uv` into UV1. Hosts that predate the argument ignore it. */
+    /** `colors` (Geometry.colors) is 4 bytes RGBA per vertex for a `requires: [color]` material;
+     *  a host that predates it draws the mesh white. @c createMeshC @count verticesCount=vertices/3 indicesCount=indices */
+    setMesh(entityId: u32, materialId: u32, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, meshType: i32, uv1?: Float32Array, colors?: Uint8Array): void
+    // Terrain (gl/Terrain.ts ↔ creator-gl/src/terrain.cpp, docs/terrain-plan.md §1.4): a heightmap grid of
+    // sizeX × sizeZ samples `cellSize` apart (+X across columns, +Z across rows, height on +Y, sample 0 at
+    // the node origin), drawn as one renderable per `chunk`×`chunk` cells on internal children of the
+    // entity (u16 indices → chunk ≤ 255). `holes` = one byte per sample, 1 = hole (a triangle exists only
+    // when its three samples are valid — the same rule as the Jolt height field), null = none. UV0 = local
+    // XZ in metres, UV1 = the terrain's unit square. Returns the chunk count (0 = refused). terrainUpdate
+    // re-reads the FULL arrays and rebuilds the chunks the sample rectangle touches. All optional: a host
+    // without them gets the SDK's own chunk meshes through setMesh (gl/terrainMesh.ts).
+    terrainCreate?(entityId: u32, materialId: u32, heights: Float32Array, sizeX: u32, sizeZ: u32, cellSize: f32, chunk: u32, holes: Uint8Array | null): u32
+    terrainUpdate?(entityId: u32, heights: Float32Array, holes: Uint8Array | null, x0: u32, z0: u32, w: u32, h: u32): void
+    terrainSetMaterial?(entityId: u32, materialId: u32): void
+    terrainSetShadows?(entityId: u32, cast: boolean, receive: boolean): void
+    // Instanced mesh (gl/InstancedMesh.ts ↔ creator-gl/src/instanced.cpp): `count` transforms,
+    // column-major 4×4 local to the node, all-zero = hidden. setInstanceTransforms writes
+    // matrices.length / 16 of them starting at `first` (a subarray view is fine — consumed synchronously).
+    /** @count verticesCount=vertices/3 indicesCount=indices */
+    createInstancedMesh(entityId: u32, materialId: u32, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, count: u32): void
+    /** @count count=matrices/16 */
+    setInstanceTransforms(entityId: u32, matrices: Float32Array, first: u32): void
+    setInstancedMeshMaterial(entityId: u32, materialId: u32): void
+    setInstancedMeshShadows(entityId: u32, cast: boolean, receive: boolean): void
+    setCulling(entityId: u32, culling: boolean): void
+    /** Filament RenderableManager::setPriority — the coarse draw order, 0..7 (Mesh.renderPriority).
+     *  Optional: an older host leaves everything at the default 4. */
+    setRenderPriority?(entityId: u32, priority: u32): void
+    /** Filament MaterialInstance::setDepthCulling / setDepthWrite — per-instance overrides of the
+     *  depth state baked into the shader package (Material.depthTest / depthWrite). Optional. */
+    setMaterialDepthTest?(materialInstanceId: u32, enable: boolean): void
+    setMaterialDepthWrite?(materialInstanceId: u32, enable: boolean): void
+    /** Filament MaterialInstance::setCullingMode: 0 none (double-sided), 1 front, 2 back. Optional. */
+    setMaterialCulling?(materialInstanceId: u32, mode: u8): void
+    /** Filament MaterialInstance stencil state in one call (Material.stencil): `test` 0 always, 1 never,
+     *  2 less, 3 lessEqual, 4 greater, 5 greaterEqual, 6 equal, 7 notEqual; the ops 0 keep, 1 zero,
+     *  2 replace, 3 increment, 4 decrement, 5 invert. Optional. */
+    setMaterialStencil?(materialInstanceId: u32, write: boolean, test: u8, ref: u8, onPass: u8, onFail: u8, onDepthFail: u8, readMask: u8, writeMask: u8): void
+    setCastShadows(entityId: u32, culling: boolean): void
+    setReceiveShadows(entityId: u32, culling: boolean): void
+
+    /** Decode a fetched image into a texture. `flags` (optional, Texture.load): bit 1 = LINEAR data
+     *  (a normal map — store RGBA8, not sRGB); unset / absent = colour, sRGB. A host that ignores
+     *  it loads colour correctly and normal maps wrongly. KTX2 decides by its own header. @custom */
+    createTexture(systemId: bytes, onComplete: (texture: Handle, width: number, height: number) => void, onReject: () => void, flags?: u32): void
+    // Texture from a baked _creatorCanvas surface (RGBA8, already rasterized — synchronous, no decode).
+    /** @custom */
+    createTextureFromCanvas(surfaceId: i32): u32
+    /** @custom */
+    updateTextureFromCanvas(texId: u32, surfaceId: i32): void
+    /** A texture from raw UBYTE pixels — `channels` 1–4, row-major, `width*height*channels` bytes, no
+     *  mips; `srgb` selects the sRGB internal format for 3/4 channels (colour) vs linear (data — a
+     *  terrain's control map). The bytes are copied. Returns 0xFFFFFFFF on failure. `updateTexturePixels`
+     *  re-uploads a sub-rectangle with the creation channel count. Optional (Texture.fromPixels throws). @args data width height channels srgb @count pixelBytes=data @owned GlTexture */
+    createTexturePixels?(width: u32, height: u32, channels: u32, data: Uint8Array, srgb: boolean): Handle
+    updateTexturePixels?(textureId: u32, x: u32, y: u32, width: u32, height: u32, data: Uint8Array): void
+
+    /** A material INSTANCE of these .filamat bytes (an app's own shader, fetched); the material itself is deduplicated by content in the engine. @c createMaterialInstanceFromBytes @owned GlMaterial @throw createMaterial: no .filamat bytes behind this fetch id */
+    createMaterial(systemId: bytes): Handle
+    /** A material INSTANCE of a BUILT-IN material by name — `"lit"`, `"unlit-transparent"`, `"lightmap-masked"` …:
+     *  the sources of engines/gl/materials — or null when this host carries none of that name. The engine's
+     *  materials are the runtime's to find, like the ubershader archive: in the materials archive the host
+     *  hands over (`HostFetch.systemBuffer(3)`), on every host; one material per name is kept. The names a
+     *  bundle asks for with a string literal are in its `// preload:` header (`material:<name>`) — what a
+     *  host that fetches its archives by need goes by. @custom */
+    builtinMaterial(name: string): Handle | null
+    setMaterial(entityId: u32, materialId: u32, index: i32): void
+    getMaterial(entityId: u32, index: i32): u32
+
+    setUniformRgb(materialId: u32, uniform: string, color: u32): void
+    setUniformRgba(materialId: u32, uniform: string, color: u32): void
+    setUniformFloat(materialId: u32, uniform: string, value: f64): void
+    setUniformBoolean(materialId: u32, uniform: string, value: boolean): void
+    setUniformTexture(materialId: u32, uniform: string, systemId: u32, wrapS: u8, wrapT: u8): void
+    setUniformArray(materialId: u32, uniform: string, value: Float32Array): void
+    setUniformNull(materialId: u32, uniform: string): void
+
+    /** @custom */
+    attachCameraToAR(sceneId: u32, cameraEntityId: u32, onProjectionChange: (mat: Float32Array, fov: number) => void): void
+    /** @custom */
+    getDisplaySize(): Float32Array
+
+    setVisible(entityId: u32, visible: boolean): void
+    isVisible(entityId: u32): boolean
+
+    /** @custom */
+    createGlb(systemId: bytes, onComplete: (root: Handle | null) => void, onReject: () => void): void
+    setGlbCulling(entityId: u32, culling: boolean): void
+    /** Optional. True when the host refits a skinned model's frustum-culling bounds to its joints every
+     *  frame (creator-gl animation/skinning.cpp), i.e. culling is safe for animated GLBs. Model.load
+     *  defaults culling ON only where this returns true; absent / false = the always-draw default. */
+    skinnedCullingSupported?(): boolean
+    /** Optional. Level-of-detail override for a GLB instance (docs/lod-plan.md): `mesh` / `anim` are -1 for
+     *  automatic (the engine picks by screen size and visibility) or a forced level 0..3. Backs Model.lod
+     *  and Animator.lod; a host without it (no LOD pass) leaves everything at full detail. */
+    setLod?(entityId: u32, mesh: f32, anim: f32): void
+
+    // Render-synced aspect update(dt) dispatch, called from inside render(). Early = before the physics
+    // step; late = after animations/particles, just before draw. Single-slot per phase (the SDK's Aspect
+    // dispatcher registers one callback per phase that iterates its ordered updater list).
+    /** @custom */
+    setEarlyUpdate(cb: (dt: number) => void): void
+    /** @custom */
+    setLateUpdate(cb: (dt: number) => void): void
+    /** FIXED phase - the SDK's `updateFixed`: once per physics substep with dt = 1/60 exactly, BEFORE
+     *  that substep's Jolt step (move commands / velocities written here feed the same step). Under
+     *  `setTimeScale` the NUMBER of substeps changes, never the dt; at most 4 per frame. `null` clears it -
+     *  registered lazily, only once an aspect declares the phase (one flag check per substep otherwise).
+     *  Optional: a host without it gets the SDK's own 1/60 accumulator inside the early phase. @custom */
+    setFixedUpdate?(cb: ((dt: number) => void) | null): void
+    /** The engine's clock multiplier for physics / animators / particles (1 normal, 0 frozen) — the
+     *  SDK's `Time.scale` / `Time.paused` pushed down so the sims stay in step with game code. The
+     *  two aspect phases still receive the RAW wall-clock dt (the SDK scales it itself). Optional:
+     *  a host without it keeps its sims at wall-clock speed. */
+    setTimeScale?(scale: f64): void
+    // Physics contact/sensor events (drained after each step): a/b = entity ids, type 0 enter / 1 exit.
+    /** @custom */
+    setOnPhysicsEvent(cb: (a: number, b: number, type: number) => void): void
+
+    // ---- Animation system (docs/animation-v2-plan.md): AnimationClip + Animator — THE skeletal animation
+    // path, evaluated by creator-anim on every host. A clip set is parsed straight from GLB bytes (tracks
+    // target bone NAMES, no entities); a model's embedded clips are registered by createGlb (getGlbClipSet,
+    // 0 = none). An Animator binds clips to one node hierarchy by name; the native evaluator runs the WHOLE
+    // per-frame loop (sources, transitions, blend spaces, one-shot hand-over, root motion) — the SDK only
+    // issues play/stop/blend calls and has no tick. Skinning is flushed AFTER the late phase so IK /
+    // procedural joint writes land in the skin.
+    // TRANSITIONS ARE INERTIAL, NOT CROSSFADES: a layer evaluates exactly ONE source (its one-shot, its
+    // loop, or nothing); a switch records the difference between the pose the layer SHOWED and the pose the
+    // new source shows and decays it away over `fade` seconds (halflife = 0.4 × fade). A replaced source is
+    // silent from that moment — it costs nothing, its weight is 0 at once, and it may be replaced again
+    // mid-transition (the offset is re-recorded from the displayed pose). `fade` 0 = cut.
+    /** @custom */
+    loadClips(systemId: bytes, onComplete: (clipSetId: number) => void, onReject: (err: unknown) => void): void
+    // names = newline-joined track targets; data = [trackCount, duration (<=0 → max key time), (path 0 T/1 R/2 S,
+    // interp 0 linear/1 step/2 cubic, comps, keyCount, times…, values…)*]. Returns a one-clip set id (0 = bad).
+    createClipFromTracks(names: string, data: Float32Array): u32
+    /** @c getClipInfos */
+    getClipSetInfo(clipSetId: u32): ClipInfo[]
+    // A clip DERIVED from one of the set as a NEW single-clip set (index 0) — AnimationClip.from(clip, { mirror,
+    // from, to }): the mirror (left ↔ right on the set's own rig, the GLB's node tree: contacts swapped, heading
+    // negated), then the [start, end] window re-timed to 0 (start < 0 = whole, end < 0 = the clip's end; boundary
+    // values interpolated in, events re-timed). 0 = bad id / range, or a mirror asked of a set without a rig.
+    deriveClip(clipSetId: u32, clip: u32, mirror: boolean, start: f32, end: f32): u32
+    // Clip events on the CLIP: normalized times (sorted ascending). Every slot bound to the clip, in every
+    // animator, fires slot event type 4 + i on crossing event i. Empty = clear.
+    setClipEvents(clipSetId: u32, clip: u32, times: Float32Array): void
+    getGlbClipSet(entityId: u32): u32
+    destroyClipSet(clipSetId: u32): void
+    animatorCreate(entityId: u32): u32                     // 0 = not a transform node
+    animatorDestroy(animatorId: u32): void                    // leaves the skeleton in rest pose
+    // One (clip, layer) slot, silent until played / made a blend member. slot index or -1.
+    animatorBind(animatorId: u32, clipSetId: u32, clipIndex: u32, layer: u8): i32
+    animatorBoundTracks(animatorId: u32, slot: u32): u32
+    // The layer's LOOP: member slots + positions (dims 1: x per member, 2: x,y; one member = a plain looping
+    // clip). The members share ONE cycle clock, each placed on it LINEARLY by `phases` — two floats per member,
+    // (offset, cycles): φ(t) = offset + cycles · t / duration, 0 at a left-foot-down (measured offline
+    // from the clip's foot marks). An empty array, or cycles <= 0 for a member = normalized time (0, 1) and no
+    // cycle to phase-match to — the clock never reads the clip's marks. animatorSetBlendValue picks the mix (1D linear between neighbours /
+    // 2D gradient band). Setting it takes the layer over from whatever it shows — the previous loop and any
+    // one-shot on it go silent — with a transition of `fade`. Empty = no loop. speed = the members' rate.
+    /** @args animatorId layer dims slots positions phases fade speed */
+    animatorSetBlend(animatorId: u32, layer: u8, dims: 1 | 2, slots: Uint16Array, positions: Float32Array, fade: f32, speed: f32, phases: Float32Array): void
+    animatorSetBlendValue(animatorId: u32, layer: u8, x: f32, y: f32): void
+    // Play a slot as the layer's one-shot, transitioned in over fadeIn (0 = cut) from whatever the layer
+    // showed (playing a blend MEMBER brings the whole blend back instead). A non-looping one-shot plays to its
+    // end and hands the layer back to the loop THERE, the return transition taking fadeOut from its last pose
+    // (0 = cut back; on a loopless layer hold the last frame).
+    // restart = rewind even if already playing (a restart is a new source: it transitions from the pose shown).
+    animatorPlay(animatorId: u32, slot: u32, loop: boolean, speed: f32, fadeIn: f32, fadeOut: f32, restart: boolean): void
+    // TURN WARP for the slot's current play (right after animatorPlay): the node's turn from the clip's baked heading is
+    // scaled to `radians` total; the pose keeps its own turn, the extra pivots about the planted foot. enabled false =
+    // the clip's own turn. Optional: older hosts lack it.
+    animatorSlotSetTurn?(animatorId: u32, slot: u32, radians: f32, enabled: boolean): void
+    // WINDOW of the slot's current play (right after animatorPlay): the one-shot runs [start, end] clip seconds — enters
+    // at start (at end when backwards) if the play rewound, completes + hands over at end, clip events outside never fire.
+    // end < 0 = the clip's end. Loops ignore it. Optional: older hosts lack it (the whole clip plays).
+    animatorSlotSetWindow?(animatorId: u32, slot: u32, start: f32, end: f32): void
+    // Release over `fade` (a transition toward what is left — the loop, or the rest pose): one slot; a
+    // layer's one-shot + loop (slot -1); everything (layer -1).
+    animatorStop(animatorId: u32, layer: i32, slot: i32, fade: f32): void
+    animatorSeek(animatorId: u32, slot: u32, time: f32): void   // seeking a blend member moves the blend
+    animatorGetSlotTime(animatorId: u32, slot: u32): f64
+    animatorGetSlotWeight(animatorId: u32, slot: u32): f64     // 1 = the layer's source, a loop member = its share, else 0
+    // Layer config: weight 0–1; additive = each slot's DELTA vs its clip's first frame on top of the layers
+    // below; maskRoot = bone name(s, '\n'-separated) whose subtrees the layer drives ("" = all).
+    animatorSetLayer(animatorId: u32, layer: u8, weight: f32, additive: boolean, maskRoot: string): void
+    // ANTICIPATION for the layer's next source change: the transition starts with -amount x the new source's
+    // joint velocity (a wind-up against the coming motion), consumed by that switch. Optional: older hosts lack it.
+    animatorSetLayerAnticipation?(animatorId: u32, layer: u8, amount: f32): void
+    animatorSetGlobal(animatorId: u32, speed: f32, paused: boolean): void
+    // Root motion: "" off, "*" auto (the shallowest joint a base-layer clip translates), else a bone name. The
+    // root's horizontal travel (animator-node frame) is stripped from the pose and, per apply: 0 accumulated
+    // only (animatorGetRootMotion copies + clears out[3]), 1 added to the node's transform, 2 fed to the
+    // CharacterController on the node or an ancestor as a world velocity (falls back to 1 without one).
+    /** `apply` bits 0–1: 0 accumulate only / 1 move the node / 2 feed the CharacterController; bit 2 (+4): the
+     *  root joint's yaw about the node's up is root motion too (off the pose, onto the node the travel lands on). */
+    animatorSetRootMotion(animatorId: u32, bone: string, apply: u8): void
+    /** @into out 3 */
+    animatorGetRootMotion(animatorId: u32, out: Float32Array): void
+    // Slot events: 0 completed (non-loop end) / 1 loop wrapped / 2 settled (no longer a source, after a stop
+    // or a replacement) / 3 HAND-OVER (a one-shot's return starts — for the SDK the clip is over; what the app
+    // starts in response takes the layer over instead) / 4+i clip event i. Single-slot (routed by animatorId).
+    /** @custom */
+    setOnAnimatorEvent(callback: (animatorId: number, slot: number, type: number) => void): void
+    // ---- contacts, phase, root curves (docs/animation-v2-plan.md §2.5–2.6) ----
+    // Every clip bound to a skeleton is baked once against it: when each foot is planted, the gait phase
+    // φ(t) (0 at a left-foot-down, 0.5 at a right-foot-down, unwrapped over the clip; absent for a clip
+    // with no gait cycle) and the root's cumulative travel / yaw / speed. A controller asks these instead
+    // of shipping measured tables of its own.
+    // The feet: '\n'-joined bone names per side (foot[, toe/ball]); both "" = classify by name. Re-bakes.
+    animatorSetFeet(animatorId: u32, left: string, right: string): void
+    // One curve of a slot's clip at `time` seconds (< 0 = the slot's clock now): which 0 φ (-1 = no gait)
+    // / 1 travel (m) / 2 yaw (rad, + = left) / 3 speed (m/s) / 4-5 unit travel direction x / z
+    // (model space, held through stills — integrate dir × d(travel) for the root's 2D path).
+    animatorSlotCurveAt(animatorId: u32, slot: u32, which: 0 | 1 | 2 | 3 | 4 | 5 | 6, time: f32): f64
+    // out ← [curve sample dt, total travel (m), mean speed (m/s), in-place flag]. False = unbound slot.
+    animatorSlotCurveInfo(animatorId: u32, slot: u32, out: Float32Array): boolean
+    animatorSlotTurn(animatorId: u32, slot: u32): f64          // the clip's total root yaw, rad
+    // The first time the clip has turned `yaw` radians — where a turn is entered by a body already
+    // that far into the same turn, so the two read as one move.
+    animatorSlotTimeAtTurn(animatorId: u32, slot: u32, yaw: f32): f64
+    // What the LAYER shows, as a cycle phase in [0, 1) — its loop's clock, or its one-shot's φ; -1 = none.
+    animatorLayerPhase(animatorId: u32, layer: u8): f64
+    // Seek the slot to the first time whose φ ≡ phase (mod 1); a blend member moves its whole group.
+    animatorSeekPhase(animatorId: u32, slot: u32, phase: f32): void
+    // How far the slot's pose is from `target`'s at the same cycle phase, metres (joint distance +
+    // the velocity difference over 0.1 s, the planted foot weighted most) — what handing over to that
+    // clip would hand the inertializer. Fills `out` at the curve rate, returns the sample count.
+    // align: 0 = compare at the same cycle phase, 1 = at the same time (two clips that both begin
+    // from standing have no shared cycle to line up on).
+    animatorSlotFit(animatorId: u32, slot: u32, target: u32, align: 0 | 1, out: Float32Array): u32
+    // The earliest time in the slot where that hand-over costs no more than `tolerance` metres;
+    // atContact snaps to the next foot-down at or after it. -1 = never that close.
+    animatorSlotExit(animatorId: u32, slot: u32, target: u32, tolerance: f32, atContact: boolean, align: 0 | 1): f64
+    // CYCLE ALIGNMENT by pose, no marks: given slot a's cycle (offA, cyclesA), the (offset, cycles) of slot b
+    // under which the two loops show the same pose at the same gait phase — b's cycle count searched over
+    // cyclesA × {1/3 … 3}, its offset on a fine grid. out = [offset, cycles, score (metres), margin (runner-up
+    // ≥ 0.2 cycle away minus the best; ~0 = ambiguous)]. Returns 1, or 0 when there is nothing to compare.
+    animatorSlotAlign(animatorId: u32, a: u32, b: u32, offA: f32, cyclesA: f32, out: Float32Array): i32
+    // Contact spans as (side 0 left / 1 right, from, to, atX, atY, atZ) sextuplets (seconds, model space);
+    // returns the span count, filling `out` up to its capacity.
+    /** @count maxSpans=out/8 */
+    animatorSlotContacts(animatorId: u32, slot: u32, out: Float32Array): u32
+    // A CLIMBING clip's tread levels (model-space plant heights, sorted ascending): out[0] = the
+    // riser (median level spacing), out[1..] = the levels, filled up to out's capacity. Returns the
+    // level count — 0 for a flat clip.
+    animatorSlotTreads(animatorId: u32, slot: u32, out: Float32Array): u32
+    // The clip's baked physics at `time` seconds (< 0 = the slot's current time), unit body mass,
+    // model space: out11 = COM position xyz, COM velocity xyz (= linear momentum per kg), angular
+    // momentum about the COM xyz, then per-foot support left/right (contact-gated, seesaw split,
+    // scaled by the vertical force proxy — > 1 on a landing, 0 in flight). 0 = no body segments
+    // classified on this skeleton.
+    animatorSlotPhysics(animatorId: u32, slot: u32, time: f32, out: Float32Array): i32
+    // The clip's MATCHING FEATURE ROW at `time` (37 floats, the clip's heading frame at that time —
+    // x lateral (+ left), y up, z forward): 0–5 feet positions (relative to the pelvis' ground
+    // point), 6–11 feet velocities, 12–14 pelvis velocity, 15 pelvis height, 16–18 COM velocity,
+    // 19–20 support L/R, 21–22 contact phase L/R, 23 yaw angular momentum, 24–31 the clip's own
+    // path 0.3/0.6/1.0/1.5 s ahead as (lateral, forward) pairs, 32–35 facing change at those
+    // horizons (rad, + = left), 36 cyclic flag. Returns 37, or 0 without a leg chain.
+    animatorSlotFeatures(animatorId: u32, slot: u32, time: f32, out: Float32Array): i32
+    // The calibrated knee HINGE AXIS of a side (0 left / 1 right): a unit vector in the thigh's local
+    // frame — a skeleton property, measured over every bound clip's knee rotation track. out8 = axis
+    // xyz, spread mean (rad), spread max (rad), measurement count, 0, 0. 0 = no leg / no knee motion.
+    animatorKneeAxis(animatorId: u32, side: u32, out: Float32Array): i32
+    // The knee's bend plane of a slot's clip at `time` seconds (< 0 = the slot's current time),
+    // predicted from the hinge axis + the clip's own thigh rotation — continuous even where the leg
+    // is straight. out6 = pole xyz (unit, model space, toward the knee — a two-bone solver's bend
+    // direction), then the plane normal xyz. 0 = uncalibrated / no leg.
+    animatorSlotKneePole(animatorId: u32, slot: u32, side: u32, time: f32, out: Float32Array): i32
+    // Step warp v2: stride scales the feet's travel-direction offsets from the hips (uniform through
+    // stance and swing), lift = metres ADDED to their height (swing-gated by the contact marks;
+    // 0 = neutral, negative = a shuffle; half of what it adds raises the pelvis, capped by the
+    // planted legs' remaining extension), pitchDeg rotates each foot about its lateral axis
+    // (+ = toes up), slopeDeg the invisible staircase (+ = ascending: foot heights follow the
+    // incline + the feet auto-pitch; the HOST climbs the body at tan(slope) × the stride-scaled
+    // travel, which holds each planted foot's world height constant on its tread). Solved in the
+    // calibrated knee hinge plane with a soft reach; the pelvis lowers by any leg's overreach
+    // (marks-weighted, spring-followed, zero when nothing overreaches). 1/0/0/0 = identity;
+    // on false = off.
+    animatorSetStepWarp(animatorId: u32, on: boolean, stride: f32, lift: f32, pitchDeg: f32, slopeDeg: f32): void
+    // Footsteps: a contact that BEGAN this evaluation on what the base layer shows — side 0 left / 1 right,
+    // x/y/z = the foot's WORLD position at the plant. Fired after the frame's transform commit.
+    /** @custom */
+    setOnAnimatorStep(callback: (animatorId: number, side: number, x: number, y: number, z: number) => void): void
+
+    // ---- drives + warping ----
+    // The character's world velocity this frame: the speed the stride warp fits the stride to and the
+    // direction the orientation warp turns the lower body toward.
+    animatorSetMotion(animatorId: u32, vx: f32, vy: f32, vz: f32): void
+    // Cumulative capsule travel (m) and yaw (rad, + = left) — what a slot's distance / angle drive reads.
+    animatorSetDriveInput(animatorId: u32, distance: f32, angle: f32): void
+    // Drive a slot's clock by a quantity instead of time: 0 time / 1 distance / 2 angle. `entry` is the
+    // curve value that corresponds to NOW (a start 0; a stop with D metres left: total travel − D), so
+    // the clip is entered where it already agrees with the body. Stalls fall back to time.
+    animatorSetSlotDrive(animatorId: u32, slot: u32, mode: 0 | 1 | 2, entry: f32): void
+    // [stride on, stride min, stride max, orient on, orient max°, orient time, min speed, pelvis drop]
+    animatorSetWarpParams(animatorId: u32, params: Float32Array): void
+
+    // ---- feet: foot lock + ground IK (docs/animation-v2-plan.md §2.9) ----
+    // The feet stage runs in WORLD space inside the evaluation, after the clips are composited: a foot
+    // the shown clip calls planted is pinned where it landed and the leg re-solved to keep it there
+    // while the body moves on (the lock), and each foot is put on the ground the ENGINE probed under it,
+    // the pelvis lowered so the leg reaches (ground IK). The engine casts the probe rays itself against
+    // what a character can stand on (static + moving solids; never the character's own bodies, debris
+    // or sensors) and reads the CharacterController's ground state — nothing per frame from the SDK.
+    // [ik on, lock on, pelvis drop m, unlock distance m, lock-in s, lock-out s, pelvis spring s,
+    //  align to ground normal 0..1, probe half-length m, detector max speed m/s, detector max height m]
+    // Optional: a host without it has no feet stage (the legs stay as animated).
+    animatorSetFeetParams?(animatorId: u32, params: Float32Array): void
+    // One foot after this frame's evaluation, side 0 left / 1 right: out ← [locked, lock weight,
+    // anchor xyz, target xyz] (world) — a debug overlay's beam under the foot. False = no such foot.
+    animatorFootState?(animatorId: u32, side: i32, out: Float32Array): boolean
+
+    // ---- IK chains + sockets (creator-anim anchors.cpp: the gun-master rig's hands) ----
+    // The chains are solved in the engine's LATE pass — after the app's update(dt) phase, before the
+    // dynamic bones and the skin flush — on the joints as the app left them: a world-target chain reaches
+    // the point / rotation given (or its target NODES, read by the engine then), an ANCHORED chain rides
+    // a live socket, keeping the animated end bone's pose relative to the same socket on the take's
+    // donor and following the playing clips' anchor spans between sockets. Nothing per frame from the
+    // SDK. Optional: a host without them has inert IK (the SDK warns once).
+    // kind 0 two-bone (the chain = the end entity, its parent, its grandparent) / 1 look-at. 0 = the
+    // entity is no joint of the animator.
+    animatorIkCreate?(animatorId: u32, kind: 0 | 1, endEntityId: u32): u32
+    animatorIkDestroy?(animatorId: u32, ik: u32): void
+    // CANIM_IK_* order: [target xyz, pole xyz, has pole, weight, rotation xyzw, rotation weight, look-at
+    // axis xyz, look-at limit°, enabled, anchor time s].
+    animatorIkSet?(animatorId: u32, ik: u32, params: Float32Array): void
+    // Nodes the engine reads every late pass (0 = none): the target's world position, the pole's, the
+    // rotation node's world rotation — in place of the fixed floats above.
+    animatorIkNodes?(animatorId: u32, ik: u32, targetEntity: u32, poleEntity: u32, rotationEntity: u32): void
+    // Anchor the chain to the live socket ('' = a world-target chain).
+    animatorIkAnchor?(animatorId: u32, ik: u32, socket: string): void
+    // out ← [reach error m, anchor delta m, anchor delta rad, applied weight]. False = no such chain.
+    animatorIkState?(animatorId: u32, ik: u32, out: Float32Array): boolean
+    // A socket: set '' = live, else a donor's name; on joint `jointEntityId` (a bone of the animator). A
+    // NODE socket (nodeEntityId != 0) is that entity, read every late pass (its world → the joint's
+    // space); else trs = [t.xyz, r.xyzw] fixed in the joint's space. No node and null trs = remove.
+    animatorSetSocket?(animatorId: u32, set: string, name: string, jointEntityId: u32, nodeEntityId: u32, trs: Float32Array | null): void
+    /** A clip's anchor spans for one bone: the donor set, one '\n'-joined socket name per span ('' = the
+     *  joint itself), spans = (from, to, rotation 0..1, pin 0..1) per span in NORMALIZED time — FOUR floats
+     *  a span, the engine's count is the span count. Empty spans + donor '' = remove; a clip without data
+     *  takes no part in the anchor blend. @count count=spans/4 */
+    setClipAnchors?(clipSetId: u32, clip: u32, bone: string, donor: string, sockets: string, spans: Float32Array): void
+
+    // ---- locomotion: the movement model + the clip selector, both engine-side ----
+    // The intent (`locoSetInput`) becomes a desired velocity; the simulated velocity springs toward it
+    // one fixed substep at a time (`locoStep`, given the capsule's place), and `locoUpdate` — called
+    // before the animators are evaluated — picks and drives what the base layer shows. The host moves
+    // the character with the velocity and facing it reads back: in displacement `code` the animation
+    // never moves the body, so "how fast am I" is an input to the animation, not an output of it.
+    locoCreate(animatorId: u32): u32
+    locoDestroy(loco: u32): void
+    // [halflife walk, halflife run, halflife facing, speed walk, speed run, speed sprint, deadzone,
+    //  turn min°, turn big°, blend, stop blend, start tap, resume, predict, displacement (0 code /
+    //  1 data / 2 hybrid), mode (0 rules / 1 matching), match interval, match blend, spin min°, turn
+    //  rate cap (deg/s, 0 = uncapped), halflife braking, hybrid adjustment clamp (m/s)]
+    locoSetParams(loco: u32, params: Float32Array): void
+    /** @into out 64 */
+    locoDefaults(out: Float32Array): void
+    // Register a bound slot: kind 0 idle / 1 gait / 2 start / 3 stop / 4 turn / 5 match / 6 spin
+    // (a turn on the spot); `angle` degrees (+ = left) for the starts / turns / spins, `speed` m/s for
+    // a gait (0 = the clip's own measured speed), `gait` the gait a transition belongs to (0 walk /
+    // 1 run / 2 sprint, -1 = any) — a walking body plays the walking starts, stops and turns.
+    locoSetEntry(loco: u32, slot: u32, kind: i32, angle: f32, speed: f32, gait: i32): void
+    locoClearSet(loco: u32): void
+    // [dir x, dir z, magnitude 0–1, face x, face z, gait 0 walk / 1 run / 2 sprint] — the facing is
+    // independent of the movement: a released key with a heading still owed turns the body on the spot.
+    locoSetInput(loco: u32, input: Float32Array): void
+    // One simulation step at the capsule's world place — from the fixed substep loop.
+    locoStep(loco: u32, dt: f32, px: f32, py: f32, pz: f32): void
+    // Run the selector for this frame — before the animators are evaluated.
+    locoUpdate(loco: u32, dt: f32): void
+    // out ← [state (0 idle / 1 start / 2 move / 3 turn / 4 stop / 5 spin), speed, vel x/y/z, yaw (rad,
+    // 0 = +Z, + = toward +X), yaw rate, phase, state sequence, then 3 × (x, z, dir x, dir z) predicted
+    // at +0.2 / +0.4 / +0.7 s].
+    locoRead(loco: u32, out: Float32Array): void
+    // Why the last STOP was the one played: one row of 9 floats per candidate weighed — [slot, entry
+    // time, metres it still travels, metres the body needs, seconds to its next foot-down, foot-downs
+    // left, flags (1 = its phase matched, 2 = at/after its first foot-down, 4 = played, 8 = entered
+    // ahead of that foot-down by its pose), score, pose distance from what showed (m, -1 = not
+    // measured)]. Returns the rows written. A debug read; absent on hosts predating it.
+    /** @count maxRows=out/10 */
+    locoStopReport?(loco: u32, out: Float32Array): i32
+    // Build the motion-matching database over the registered set (selector mode 1); returns frames.
+    locoBuildDatabase(loco: u32): i32
+
+    /** Subtree AABB in the entity's OWN local space (its own transform excluded) as
+     *  [minX,minY,minZ, maxX,maxY,maxZ] — zeros for an empty / not-yet-loaded subtree. What
+     *  `Shape.fit()` measures. Optional: absent on hosts predating the binding. @out 6 */
+    computeBoundingBox?(entityId: u32): Float32Array
+    /** DEBUG pick: the closest TRIANGLE under a screen point (logical px) among the loaded GLB instances —
+     *  entityId = one Model's root, 0 = every instance — CPU-skinned with the joints' CURRENT pose, both
+     *  faces. null on a miss. One full CPU skin per call — click-rate only. Optional: a debug tool, hosts
+     *  may lack it. */
+    pickTriangle?(entityId: u32, screenX: f32, screenY: f32): TrianglePick | null
+    setColliderFromMesh(entityId: u32, meshEntityId: u32, form: i32): void
+    setColliderBox(entityId: u32, centerX: f64, centerY: f64, centerZ: f64, sizeX: f64, sizeY: f64, sizeZ: f64): void
+    setColliderSphere(entityId: u32, centerX: f64, centerY: f64, centerZ: f64, radius: f64): void
+
+    // JoltPhysics. motionType: 0 static / 1 kinematic / 2 dynamic.
+    /** @c creatorHasPhysics */
+    physicsHasSupport(): boolean
+    /** Lightmap bake (engines/bake) — a dev-time tool compiled into the desktop host only; `lightmapBake` exists
+     *  only where `lightmapHasSupport()` is true. Describes the given static instances (GLB roots / Mesh entities;
+     *  `keysJoined` = one key per id, '
+'-joined), the scene's brightest sun, its point lights (spherical emitters of
+     *  `lightRadius` metres) and its IBL to the bake, which traces them on the NVIDIA card — direct light plus
+     *  `bounceRays` Lambertian paths of `bounces` vertices per texel (0 / 0 = direct only) with `patchSamples` next-event
+     *  samples over the bright patches of a first direct pass — and writes
+     *  `<outDir>/<stem>.bake` + `<stem>-light[_n].ktx2` (irradiance in lux / lightScale, BC6H) + `<stem>-aux[_n].ktx2`
+     *  (sun / sky visibility + light direction); `split` adds `<stem>-direct[_n]` / `-indirect[_n]` page sets for the
+     *  SDK's two views; `denoise` runs OptiX's AI denoiser over 0 nothing, 1 the indirect part, 2 + the sky and the lamps, 3 + the sun; `filter` = the texel's reconstruction filter radius in texels (1 = ±1 texel tent, 0.5 = within the texel, 0 = the centre alone);
+     *  `probeSpacing` > 0 places REFLECTION PROBES on a grid of that many metres and writes `<stem>-probes.ktx2` (a BC6H atlas of octahedral
+     *  maps: one column of roughness-level tiles per probe, captured with `probeSize`² cube faces and `probeRays` paths per texel; the scene's
+     *  IBL cubemap is what an escaping ray sees; `probeIndoor` keeps only the probes under a roof (an open share of the sphere of at most 15 %) — the
+     *  outdoors reflects the sky through the texel's baked sky visibility instead; `volumeSpacing` (metres, 0 = none) bakes THE LIGHT GRID for movers — `<name>.lgrid`, named in the .bake's `volume`: per cell
+     *  in free space an ambient cube without the direct sun, links between neighbours a ray connects (what `setAmbientCube`
+     *  is fed from); `minSize` (metres, 0 = off) leaves every instance smaller than that along every axis out of the atlas — an occluder
+     *  only, `"small": true` + its `light` (an ambient cube baked where it stands) in the .bake, applied by lightmapObjectApply; `probeLayout` 0 = ROOMS (indoor points slide to their
+     *  room's middle and merge: one probe per room), 1 = GRID; `probeBox` = 6 floats, min xyz + max xyz, keeps the grid inside that box — null = the
+     *  receivers' bounds) and the grid into the .bake; `debugDir` (optional) gets the float layers per page. Synchronous; progress on stdout as
+     *  "[lightmap] …" lines, "[lightmap] done" on success. @c creatorHasLightmapBake */
+    lightmapHasSupport?(): boolean
+    /** @custom */
+    lightmapBake?(outDir: string, stem: string, entityIds: Uint32Array, keysJoined: string, size: u32, texel: f32, pages: u32,
+                  sunRays: u32, skyRays: u32, lightRays: u32, lightRadius: f32, sunAngleDeg: f32, bias: f32, seed: u32,
+                  bounceRays: u32, bounces: u32, patchSamples: u32, split: boolean, denoise: u32, filter: f32,
+                  probeSpacing: f32, probeSize: u32, probeRays: u32, probeIndoor: boolean, probeLayout: u32, probeBox: Float32Array | null, minSize: f32, volumeSpacing: f32, emissiveNits: f32, detailTexels: u32, debugDir?: string,
+                  transmit?: string): boolean
+    /** Lightmap consumption: the next createGlb takes lightmap.filamat (the material behind that instance id) for its
+     *  OPAQUE materials and the masked twin for its MASK materials instead of the ubershader, and keeps TEXCOORD_1;
+     *  BLEND (glass) materials always keep the ubershader. 0xFFFFFFFF clears. The same call arms the foliage tier. @custom */
+    setNextGlbLightmapped?(materialInstanceId: u32, maskedMaterialInstanceId?: u32): void
+    /** The level-wide scale every lightmap-material instance shares (present and future): lux per encoded 1.0 of the
+     *  light atlas — the .bake's `lightScale` times whatever multiplier a debug knob wants. `emissiveNits` = the bake's
+     *  radiance of emission 1.0 (the .bake's `emissiveNits`): over 0 the statics' glow is drawn scene-referred with it -
+     *  a panel looks as bright as the light it gives; 0 = screen-referred. */
+    lightmapSetOptions?(lightScale: f32, emissiveNits?: f32): void
+    /** A MOVER'S SUN SHADOW ON THE BAKED STATICS: (dx, dy, dz) = TO the sun, (r, g, b) = its illuminance in lux, `on` =
+     *  the level's aux pages end in the bake's SUN MAP (the .bake's `sunMap`; never true without it). The lightmap
+     *  material takes the sun's part out of the baked light where the real-time shadow map says "in shadow". */
+    lightmapSunSet?(dx: f32, dy: f32, dz: f32, r: f32, g: f32, b: f32, on: boolean, levels?: i32): void
+    /** The lightmap material's DATA views, level-wide: 0 = the picture, 1 lighting only (a white diffuse material under the camera's exposure), 2 albedo, 3 geometric normal,
+     *  4 shading normal, 5 sun visibility, 6 sky visibility, 7 the atlas texel checker (tinted per instance), 8 light
+     *  direction, 9 false-colour log10 lux over [p1, p2], 10 relief (E on the shading normal / E), 13 what the specular
+     *  reflects (the probe along the reflection, or the sky + baked light without one), 14 the probe map (grey = the probes' share of the reflection, tinted by the texel's pair), 15 the sky's path of the reflection alone, 16 the probes' path alone. */
+    lightmapDebug?(mode: u32, p0?: f32, p1?: f32, p2?: f32, p3?: f32): void
+    /** The level's reflection probes, level-wide (every lightmap-material instance, present and future): the octahedral
+     *  atlas as a loaded texture (`<stem>-probes.ktx2`, `Texture.load` like a page), its layout (`oct` = level 0's tile edge,
+     *  `levels`, `perRow`), the probe count and the range the probe maps' records decode with (the .bake's `probes.encode`:
+     *  lo xyz, size xyz). WHICH probes a pixel reflects is baked into the pages: every aux page carries its probe map
+     *  under the page (per 4 x 4 block of texels the two probes those texels SEE — rays at bake time — and their weight).
+     *  Returns the probe count; an invalid texture id clears. */
+    lightmapProbesSet?(atlasTextureId: u32, oct: u32, levels: u32, perRow: u32, count: u32,
+                       lox: f32, loy: f32, loz: f32, sx: f32, sy: f32, sz: f32): u32
+    /** Bind the light page + the aux page + this instance's rect (uv1 * [sx, sy] + [ox, oy]) on every lightmap-material
+     *  instance of the entity (a GLB instance's renderables, or a Mesh entity's own) and move those renderables to light
+     *  channel 1 alone — a baked static takes nothing from the real-time sun and lamps (channel 0). Returns how many
+     *  material instances took it (0 = not loaded lightmapped). */
+    lightmapApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, sx: f32, sy: f32, ox: f32, oy: f32, group?: i32): u32
+    /** A SMALL STATIC the atlas left out (the bake's `minSize`: `small` + `light` in the .bake): no rect — the light
+     *  baked where it stands goes into its material parameters. `data` = 27 floats: the ambient cube — per side of its
+     *  bounds (+x -x +y -y +z -z) the irradiance rgb in lux and the sky visibility — then probe a, probe b, a's weight
+     *  (65535 = no probe, 65534 = the sky). The textures = any page of the level (the probes' records sit under every
+     *  aux page). Returns the material instances that took it (0 = not loaded lightmapped). @count count=data */
+    lightmapObjectApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, data: Float32Array, group?: i32): u32
+    /** BAKED AMBIENT LIGHT for a mover, or anything on a standard or custom LIT shader: every renderable of the GLB
+     *  instance (or the Mesh entity) takes its diffuse indirect light from `data`'s ambient cube instead of the scene's
+     *  IBL, and the IBL's reflections through the sky visibility. `data` = 25 or 26 floats: six sides (+x -x +y -y +z -z) of
+     *  irradiance rgb in lux + one unused float each, the sky visibility (0 a room .. 1 the open sky), then optionally the
+     *  baked SUN visibility (1 when absent): the real-time directional light on it is multiplied by it — the baked
+     *  statics' shadow, they cast none in real time while a light grid is loaded. Lamps stay as they are. Cheap per frame. `null` = back to the IBL. Returns the renderables touched. @c ambientCubeSet */
+    setAmbientCube?(entityId: u32, data: Float32Array | null): u32
+    /** THE LIGHT GRID for movers (`lecodes lightmap bake` writes `<name>.lgrid`, the .bake's `volume` names it):
+     *  `lightVolumeLoad(fetchId)` hands the engine the fetched file (false = not a grid); `lightVolumeTrack(entityId, on)`
+     *  marks a GLB instance root or a Mesh entity as a MOVER — every frame the engine gives it the ambient cube of the
+     *  place it is at (`setAmbientCube`), blended from the reachable cells around it and eased over ~0.06 s;
+     *  `fixed` = a STATIC the atlas left out (glass, a material the lightmap shader declines): sampled once a grid, and
+     *  ignored when every primitive of it is baked;
+     *  `lightVolumeSample(x, y, z)` = that cube at a point (26 floats, null = no grid or no valid cell near), for tools;
+     *  `lightVolumeClear()` drops the grid and every mover's cube. */
+    lightVolumeLoad?(fetchId: bytes): boolean
+    lightVolumeTrack?(entityId: u32, on: boolean, fixed?: boolean): void
+    lightVolumeClear?(): void
+    /** @out 26 @out 26 */
+    lightVolumeSample?(x: f32, y: f32, z: f32): Float32Array | null
+    /** A light's channels (Filament's, 0..7). Every light is on channel 0 at creation; one that must reach BAKED statics
+     *  too (an unbaked lamp, a muzzle flash) is added to channel 1. */
+    setLightChannel?(entityId: u32, channel: u32, enable: boolean): void
+    /** Shadow flags on every renderable of a GLB instance (Mesh has setCastShadows/setReceiveShadows). */
+    setGlbShadows?(entityId: u32, cast: boolean, receive: boolean): void
+    /** Foliage — the vegetation tier (`foliage.filamat` / `foliage-masked.filamat`, armed per model
+     *  through setNextGlbLightmapped; the engine knows the tier by its `benders` parameter). Level-wide WIND FIELD (the
+     *  model of Unity HDRP's Wind.hlsl, 2026-09-23): direction on the ground (normalised by the host), speed m/s,
+     *  turbulence 0..2 = the random share of the speed, gust 0..1 = the gust field's strength, gustSpeed m/s = how fast
+     *  the gust pattern travels. The per-material drag / stiffness / lean / shiver profile comes from the GLB's material
+     *  extras (`lecodes.wind`) or from the plant's size. Applies to every foliage instance, present and future. */
+    foliageSetWind?(dirX: f32, dirZ: f32, speed: f32, turbulence: f32, gust: f32, gustSpeed: f32): void
+    /** Level-wide options: touchStrength = metres a bender pushes, variation 0..1 = per-copy tint, sunWrap 0..1 =
+     *  wrapped Lambert. */
+    foliageSetOptions?(touchStrength: f32, variation: f32, sunWrap: f32): void
+    /** The leaves themselves: shiver = a multiplier on every material's shiver drag (1 = as authored, 0 = none),
+     *  translucency 0..1 = the sun through a thin leaf lit from behind, leafShadow 0..1 = how much of a light's shadow a
+     *  leaf card takes (bark always all of it), skyAo 0..1 = how far the baked sky visibility darkens the ambient.
+     *  Level-wide, present and future instances. */
+    foliageSetLeaf?(shiver: f32, translucency: f32, leafShadow: f32, skyAo: f32): void
+    /** The look of the cards (2026-09-23): canopy 0..1 = the card's shading normal from its own plane to the crown's hull
+     *  normal (hides the flat quads), normalMap = the cards' normal-map strength, edgeFade = a card seen edge-on dissolves
+     *  over this much of |N·V|, coverage = alpha × (1 + coverage × mip level) so a distant crown keeps its density. */
+    foliageSetLook?(canopy: f32, normalMap: f32, edgeFade: f32, coverage: f32): void
+    /** An entity whose live world position bends the vegetation within `radius` metres; <= 0 removes it. The host
+     *  writes the 8 benders nearest the camera to the shader each frame. */
+    foliageSetBender?(entityId: u32, radius: f32): void
+    /** Distance fade for every instance of the entity's ASSET (present and future): the cards thin out between `start`
+     *  and `end` metres from the camera and past `end` the LOD pass takes the instance out of the scene. end 0 = none. */
+    foliageSetFade?(entityId: u32, start: f32, end: f32): void
+    physicsConfigure(gx: f32, gy: f32, gz: f32, maxBodies: u32): void
+    /** @c setPhysicsInterpolation */
+    setInterpolation(enabled: boolean): void
+    // Shape/Physics/Trigger aspects: build a shape once, create bodies from it.
+    physicsBuildBox(hx: f32, hy: f32, hz: f32): u32
+    physicsBuildSphere(radius: f32): u32
+    physicsBuildCylinder(halfHeight: f32, radius: f32): u32
+    physicsBuildCapsule(halfHeight: f32, radius: f32): u32
+    /** Mesh shape from node-local triangles. convex=false → triangle mesh (static/kinematic/pick/character
+     *  only; physicsCreateBody returns 0 for a dynamic one), convex=true → convex hull (any motion).
+     *  (sx,sy,sz) = world scale, applied natively. Returns 0 if the shape can't be built. @count vertexCount=vertices/3 */
+    physicsBuildMesh(vertices: Float32Array, indices: Uint32Array, convex: boolean, sx: f32, sy: f32, sz: f32): u32
+    /** Same from a loaded GLB root (non-skinned primitives, bind pose, baked sub-node transforms; cached per asset). */
+    physicsBuildMeshFromEntity(entityId: u32, convex: boolean, sx: f32, sy: f32, sz: f32): u32
+    /** Terrain collider (Shape { heightfield: true }, docs/terrain-plan.md §1.4): a Jolt HeightFieldShape over
+     *  the grid `terrainCreate` draws (same arrays, same hole rule). Static / kinematic / pick / character
+     *  ground only. (sx,sy,sz) = world scale. `physicsUpdateHeightField` rewrites a sample rectangle in
+     *  place from the FULL arrays (live bodies keep the shape); heights beyond the range chosen at build
+     *  time (25 % headroom) clamp — the SDK rebuilds the shape when an edit leaves that range. Optional. */
+    physicsBuildHeightField?(heights: Float32Array, sizeX: u32, sizeZ: u32, cellSize: f32, holes: Uint8Array | null, sx: f32, sy: f32, sz: f32): u32
+    physicsUpdateHeightField?(shapeId: u32, heights: Float32Array, sizeX: u32, sizeZ: u32, x0: u32, z0: u32, w: u32, h: u32, holes: Uint8Array | null): void
+    /** A loaded GLB root's triangle soup — the one `physicsBuildMeshFromEntity` collides — as 9 floats per
+     *  triangle in the asset root's space (empty when the entity is not a GLB). `Terrain.conform` stamps a
+     *  road model into the ground with it. Optional. @custom */
+    glbTriangles?(entityId: u32): Float32Array
+    /** Offset a built shape's centre from the node's origin (Shape `origin`) — world units in the
+     *  body's rotated, UNSCALED frame, sitting outside a mesh shape's scale wrapper. Sets rather
+     *  than accumulates; (0,0,0) clears it. Optional: an older host just centres on the node. */
+    physicsSetShapeOrigin?(shapeId: u32, x: f32, y: f32, z: f32): void
+    /** Swap a live body's shape, keeping its id, velocity and transform (Shape.fit / a re-attach).
+     *  updateMass recomputes the inertia tensor. Refuses a triangle mesh on a dynamic body. */
+    physicsSetBodyShape?(bodyId: u32, shapeId: u32, updateMass: boolean): void
+    physicsDestroyShape(shapeId: u32): void
+    /** sensor = trigger (overlap events, no response); pickOnly = raycast-only, non-colliding body. */
+    physicsCreateBody(entityId: u32, shapeId: u32, motion: i32, mass: f32, sensor: boolean, pickOnly: boolean): u32
+    physicsSetPickable(bodyId: u32, pickable: boolean): void
+    /** Surface friction of one body (0 = ice, ~1 = grippy asphalt). Values COMBINE as sqrt(a * b), so
+     *  a low value on either side dominates. New bodies start at 0.6 — a neutral solid surface.
+     *  The vehicle wheel cast reads the GROUND body's value — this is what caps a car's cornering. */
+    physicsSetFriction(bodyId: u32, friction: f32): void
+    physicsGetFriction(bodyId: u32): f64
+    /** Ray vs pickable bodies → hit entity id (0 = miss); fills `out` = [px,py,pz,nx,ny,nz,fraction]. @into out 7 */
+    physicsRaycast(ox: f32, oy: f32, oz: f32, dx: f32, dy: f32, dz: f32, maxDist: f32, out?: Float32Array): u32
+    /** Dev-time dump of the static collision geometry (docs/navmesh-plan.md §4) — the input of
+     *  `lecodes navmesh bake`: every STATIC solid body's triangles in world space, as an NGEO file at
+     *  `outPath`. `entityIds`/`areas` are per-entity overrides (area 0..15, 255 unwalkable, 254 skip).
+     *  Returns the triangle count (-1 = failed). Desktop hosts with physics only. */
+    physicsStaticGeometry?(outPath: string, entityIds: Uint32Array, areas: Uint8Array): i32
+    // CharacterController (Jolt CharacterVirtual). The character steps on the engine's FIXED clock like
+    // every body (frame-rate independent) and is render-interpolated; the engine owns its gravity, so
+    // the SDK never ticks it. Both velocity halves are LATCHED STATE, never one-shot events — JS runs
+    // once per frame while the sim runs 0..4 sub-steps, so a one-shot would double-apply or vanish.
+    // groundState: 0 OnGround / 1 OnSteepGround / 2 NotSupported / 3 InAir.
+    characterCreate(entityId: u32, shapeId: u32, maxSlopeDeg: f32): u32
+    characterDestroy(charId: u32): void
+    /** This frame's HORIZONTAL command (world units/s), cleared once a step consumes it — no command
+     *  means standing still, not coasting. Held across the frame's sub-steps, and it takes the axis
+     *  back from a latched velocity: the last writer owns X/Z. */
+    characterMove(charId: u32, x: f32, z: f32): void
+    /** The same command including the vertical — free mode (gravityScale 0): swimming / flying. */
+    characterMoveFree(charId: u32, x: f32, y: f32, z: f32): void
+    /** Seed the LATCHED ballistic vertical (jump / dash). No ground check. */
+    characterSetVerticalVelocity(charId: u32, vy: f32): void
+    /** Latch the whole velocity — it persists until a characterMove takes the axis back (knockback,
+     *  wall jump, launch pad, weightless flight). Gravity still acts on the vertical. */
+    characterSetVelocity(charId: u32, x: f32, y: f32, z: f32): void
+    /** Multiplier over the world gravity; 0 = free mode, which ALSO disables stick-to-floor + stairs. */
+    characterSetGravityScale(charId: u32, scale: f32): void
+    characterSetMaxSlope(charId: u32, maxSlopeDeg: f32): void
+    /** Swap the collider live (crouch / stand up), keeping the FEET planted. Returns false when the new
+     *  shape doesn't fit where the character stands — nothing changed, so the caller retries later and
+     *  that retry is an exact headroom test. Optional: a host without it can't resize a character. */
+    characterSetShape?(charId: u32, shapeId: u32): boolean
+    /** The velocity the solver ENDED UP with after the last step (post-collision), not the command. @into out 3 */
+    characterGetVelocity(charId: u32, out: Float32Array): void
+    characterGetGroundState(charId: u32): i32
+    /** Discontinuous move (spawn / respawn / teleport) — also resets the interpolation pair. */
+    characterSetPosition(charId: u32, x: f32, y: f32, z: f32): void
+    // Vehicle (Jolt VehicleConstraint + WheeledVehicleController). One settings BLOB, so tuning knobs
+    // never grow this ABI — layout (floats):
+    //   header[34]: version(15), mass, comAuto, comY,
+    //               engTorque, engMaxRpm, engIdleRpm (0 = no floor: the engine can stall, the game
+    //                 holds idle and cranks it), engInertia, engBraking, clutchStrength,
+    //               diffRatio (<= 0 = a fully OPEN differential),
+    //               antiRoll (the bar's stiffness as a FRACTION of the wheel spring; 0 = no bars),
+    //               maxTiltDeg,
+    //               aeroDownforce, aeroDrag (each a fraction of the car's own WEIGHT at 30 m/s, scaled
+    //                 by v² from there; 0/0 = no aero, Jolt's own behaviour),
+    //               steerMode (0 = `steer` is the wheel angle as a fraction of the lock; 1 = `steer`
+    //                 is where the driver's HANDS aim a steering column the engine integrates every
+    //                 sub-step: I·θ̈ = T_hand + T_align·(1 − assist) + T_stop − damping·θ̇ − friction,
+    //                 T_hand = clamp(handStiffness·(steer·lock − θ), ±handTorque·steerForce),
+    //                 steerForce = the input's per-frame hold — the game's policy on when the hands let go,
+    //                 T_align = the steered tires' lateral force × (pneumatic trail collapsing to
+    //                 trailFloor × trail at the curve's peak + caster) — heavy at speed, light past
+    //                 the peak, self-centring, counter-steering in a slide),
+    //               colInertia, colDamping, colFriction (the patch's dry friction, fades out by 1.5 m/s),
+    //               colCaster, colTrail, colTrailFloor (the aligning torque's arms — read in BOTH
+    //                 modes; steerTorque is reported either way, the force-feedback signal),
+    //               colHandTorque, colHandStiffness, colAssist (power steering),
+    //               colRateDeg (the HANDS' top turning speed, deg/s — they cannot push a wheel that
+    //                 outruns them, they can still hold it; the free column is uncapped; 0 = none),
+    //               colStopDeg, colStopTorque, colStopDamping (the end stop: over the last colStopDeg
+    //                 before the lock the rack pushes back colStopTorque × depth² N·m and damps by
+    //                 colStopDamping × depth N·m·s/rad — progressive, viscous rubber; 0 band = the
+    //                 hard clamp only),
+    //               colBearing (the column's own dry friction, N·m, at any speed — rack and bearings),
+    //               colHandRamp (seconds the hands' torque builds to colHandTorque over; 0 = instant),
+    //               clutchCapacity (N·m the clutch passes before it slips, × the clutch scalar; 0 = Jolt's
+    //                 viscous clutch alone),
+    //               wheelCount, curveCount
+    //   + curveCount * 2: the engine's normalized torque curve (x = rpm/maxRpm, y = torque/maxTorque);
+    //                     0 points keeps Jolt's default
+    //   + per wheel, VARIABLE length: 15 fixed floats — px, py, pz, radius, width, maxSteerDeg,
+    //                      driven (the wheel's SHARE of the engine's torque: an axle's share is the sum
+    //                      of its two, the left/right split their ratio; every wheel 0 = no drive at
+    //                      all), axle, travel, stiffness, damping,
+    //                      traction (the longitudinal impulse clamp as a multiple of friction × load;
+    //                      1 = the physical tire, Jolt's sample runs 10), circle (friction circle 0..1:
+    //                      the share of lateral capacity the longitudinal impulse in use takes away;
+    //                      0 = the two axes independent), sideCount, forwardCount — then
+    //                      sideCount × (slip angle °, friction) and forwardCount × (slip ratio,
+    //                      friction). Tire curves are POINTS the SDK sends (its presets are SDK-side);
+    //                      0 points keeps Jolt's own curve.
+    // In steerMode 0 the steering input is RAW: `steer` × each wheel's maxSteerDeg, per fixed step —
+    // any taper / rate limit is the game's. In mode 1 `steer` is where the hands aim the wheel.
+    // NO gear list, no pedals and no wheel node ids: the gearbox is the game's (a ratio + clutch in
+    // the input vector), the brakes are a torque per wheel in the same vector, and the game poses its
+    // wheel models itself from the state. Chassis space is forward -Z / up +Y (matching node.forward);
+    // wheel positions are suspension attachment points in unscaled chassis space; `axle` pairs wheels
+    // for the differentials + anti-roll bars.
+    vehicleCreate(entityId: u32, shapeId: u32, settings: Float32Array): u32
+    vehicleDestroy(vehicleId: u32): void
+    /** ONE input vector, latched and applied once per fixed step: [throttle 0..1, steer −1..1 (a
+     *  fraction of the wheels' maxSteerDeg, applied as is; with a column, where the hands aim),
+     *  steerForce 0..1 (with a column: how firmly the hands hold the wheel — the game's per-frame
+     *  policy on letting go; without one, ignored), ratio (the ONE gear ratio the car runs: 0 =
+     *  neutral, negative = reverse — the engine never sees a gear list), clutch 0..1 (scales the clutch
+     *  in the coupled engine/wheel solve), brake_0 … brake_n (N·m of brake torque per wheel, this
+     *  step)]. A shorter vector leaves the rest as it was. Sticky; a non-zero throttle, steer or brake
+     *  wakes a sleeping car. */
+    vehicleSetInput(vehicleId: u32, input: Float32Array): void
+    /** Re-apply the TUNABLE half of the blob (same layout) to a live car — differential, per-wheel tire
+     *  curves / traction / circle, engine torque/RPM/curve, clutch strength + capacity, steer lock, the
+     *  column, anti-roll stiffness, tilt limit. Structural values (mass, centre of mass, wheel geometry,
+     *  the driven shares, suspension, whether an axle has a bar) are ignored: those need a re-create. */
+    vehicleSetTuning?(vehicleId: u32, settings: Float32Array): void
+    /** out = [speed, rpm, wheelsInContact, vx, vy, vz, wx, wy, wz, steerDeg, steerTorque] (w = chassis
+     *  angular velocity, rad/s; steerDeg = where the road wheels are, right-positive; steerTorque = the
+     *  tires' self-aligning torque on the steering, N·m, + = pulls right — the force-feedback signal,
+     *  reported in both steering modes)
+     *  + per wheel [contact, slipLong, slipAngleDeg, suspensionLength, steerDeg, spin, fLat, fLong, vLat, vSlip, load]
+     *  (fLat/fLong = the tire's forces, N, + = to its right / pushing the car forward; vLat/vSlip = the
+     *  patch's sliding speeds, m/s, + = to the right / tread spinning up — force × speed is heat; load =
+     *  the suspension's force on the wheel, N). slipLong is SIGNED (+ spinning up, − locking) and so is
+     *  slipAngleDeg (+ the patch sliding to the tire's right). suspensionLength, steerDeg and spin are
+     *  what a wheel model's pose is built from — by the game, the SDK only exposes them. */
+    vehicleGetState(vehicleId: u32, out: Float32Array): void
+    /** Teleport upright and clear all motion (velocities, engine RPM, wheel spin); the input vector is
+     *  zeroed — the SDK re-sends its own on the next early pass. */
+    vehicleReset(vehicleId: u32, x: f32, y: f32, z: f32, qx: f32, qy: f32, qz: f32, qw: f32): void
+    /** The chassis rigid body, for the plain body calls (physicsApplyImpulse, …). 0 if unknown. */
+    vehicleBodyId(vehicleId: u32): u32
+    // Ragdoll (Jolt Ragdoll): a Model's skeleton handed to physics — one dynamic body per listed bone
+    // (a capsule from the bone's origin to the next joint) joined to its parent part by a swing-twist
+    // constraint that carries a swing + twist MOTOR. Built ONCE from the pose the bones are in (that
+    // pose is the joints' neutral for the limits) and kept out of the world until ragdollActivate,
+    // which takes the bones' CURRENT pose and adds the bodies moving as the engine measured each bone
+    // over the last two frames (a swinging arm keeps swinging) plus a launch; from then on the engine
+    // writes the bodies' poses onto the bone entities every frame AFTER the animator, until
+    // ragdollDeactivate. POWERED (ragdollSetDrive): the motors pull every joint toward the relative
+    // rotation the ANIMATED pose shows (the engine hands the animator's pose to physics every frame,
+    // right after the animator wrote it and before the bodies overwrite it), and the root can be
+    // ANCHORED — the hips body kinematic on the animated hips — so a standing character stays in its
+    // animation while a hit jolts a limb and the motors bring it back; strength 0 with no anchor =
+    // limp. The skin joints under the hips that carry no part (the spine bones between two parts, the
+    // neck, the clavicles, fingers, toes) follow the animation while driven and HOLD their pose as the
+    // strength goes to 0 — a limp body never breathes with the loop playing underneath. Deactivating
+    // with a blend seeds the model's animator with the fallen pose, so whatever plays next
+    // transitions out of it (canimAnimatorSeedPose). Every body carries its bone entity as user
+    // data, so physicsRaycast / contact events name the bone. Optional: a host without it has no
+    // ragdolls.
+    //   bones[partCount * 2]: bone entity, `to` entity (0 = a leaf: `length` along the parent's line;
+    //                         a leaf ROOT points along the model's up)
+    //   settings — header[16]: version(3), partCount, stride(12), friction, linearDamping,
+    //              angularDamping (0 = Jolt's own), collide (0 = everything, 1 = the STATIC world and
+    //              other such ragdolls only: dynamic bodies, character controllers and vehicles pass
+    //              through — Jolt's DEBRIS object/broadphase layer), freeze (1 = once every part of a
+    //              LIMP body is asleep the bodies turn STATIC where they lie: the last pose keeps being
+    //              written onto the bones, raycasts still hit, nothing wakes them, the solver skips
+    //              them; ragdollActive reads false, ragdollDeactivate / ragdollActivate still work —
+    //              activate makes the parts dynamic again), freezeAfter (seconds LIMP after which the
+    //              freeze happens regardless; 0 = no cap), driveFrequency (Hz: the motors' position
+    //              spring), driveDamping (ratio, 1 = critical), driveTorque (N·m per kg of the part:
+    //              the motors' limit at strength 1), jointFriction (N·m per kg of the part: a torque
+    //              that resists any joint motion, motor or not), limits (0 = the part cones below;
+    //              1 = LEARNED: at the first activation that finds clips bound to the model's
+    //              animator the engine measures, per joint, how far the clips swing and twist it in
+    //              its constraint frame and rebuilds the joints to those ranges — the motors never
+    //              target a pose the limits forbid; no clips yet = the cones, measured at a later
+    //              activation), limitsMargin (degrees added on each side of a learned range),
+    //              reserved x1
+    //   + partCount * 12: parentIndex (-1 = the root; always < the part's own index), radius, length
+    //              (0 = up to the `to` bone), mass (kg; 0 = from the volume), swingDeg (cone
+    //              half-angle), twistDeg (half-angle), hinge (0/1), hingeAxisX/Y/Z (in the MODEL
+    //              node's space), hingeMinDeg, hingeMaxDeg — a hinge is a swing-twist whose cone is
+    //              flat (2°) across the axis and [min, max] about it (a knee, an elbow)
+    ragdollCreate?(rootEntityId: u32, bones: Uint32Array, settings: Float32Array): u32
+    ragdollDestroy?(ragdollId: u32): void
+    /** Pose the bodies from the bones' current transforms and add them to the world, each moving as
+     *  its bone was measured over the last two frames, plus the launch (vx, vy, vz) on every body.
+     *  Already active = re-wake + the launch. false = unknown id / no world. */
+    ragdollActivate?(ragdollId: u32, vx: f32, vy: f32, vz: f32): boolean
+    /** Take the bodies out of the world. The bones get the bodies' last pose written against the
+     *  parents' CURRENT worlds (move the model node under the hips first), and with `blend` > 0 the
+     *  model's animator is seeded with it: whatever plays next transitions from the fallen pose over
+     *  `blend` seconds. */
+    ragdollDeactivate?(ragdollId: u32, blend: f32): void
+    /** In the world AND at least one body still awake (a settled ragdoll reads false). */
+    ragdollActive?(ragdollId: u32): boolean
+    /** The rigid body of part `index` (for physicsApplyImpulseAt / velocities). 0 if unknown. */
+    ragdollBodyId?(ragdollId: u32, index: u32): u32
+    /** The joint motors' strength (0..1 = the share of driveTorque; 0 = off = limp) and the root
+     *  anchor (the hips body kinematic on the animated hips). Kept across activations; a driven or
+     *  anchored body never freezes. */
+    ragdollSetDrive?(ragdollId: u32, strength: f32, anchor: boolean): void
+    // Dynamic bones (the SDK's DynamicBone; creator-anim canimDyn* behind creator-gl): secondary motion
+    // for tails, ears, hair and cloaks — a bone tree under one root simulated as Verlet particle chains
+    // (gravity, wind, drag, stiffness toward the animated shape, an angle cone, capsule / sphere
+    // colliders, a floor plane, bone length, neighbour links) in an engine stage AFTER the late phase
+    // and BEFORE the skin flush: the animator, an active ragdoll and late-phase JS bone writes are the
+    // input, the simulated local rotations the output. Bones the animator does not drive keep their
+    // bind pose as the target; driven ones follow their clip. Optional: a host without it shows the
+    // animation alone.
+    //   bones[boneCount]: entity ids — the root first, every other bone a child of an earlier one.
+    //   settings — header[28]: version(1), boneCount, boneStride(7), then the chain params: weight
+    //              (0..1 animation → simulation; 0 = off, re-arms on the animated pose), follow (0..1 of
+    //              the root's travel carried onto the particles; 0 = full whip), wind xyz (m/s², world),
+    //              link (0..1 neighbour-link strength), rate (substep Hz, ≤ 4 substeps per frame),
+    //              teleport (a root jump past this many metres resets the chain), floor (0/1), floor
+    //              point xyz, floor normal xyz (the floor slots are overridden by dynamicBoneSetFloor),
+    //              floorFriction (a Coulomb coefficient: a resting particle's slide loses up to friction · g · dt of
+    //              speed per substep), iterations
+    //              (constraint passes per substep, 1..8, default 4; a long rope may want 8), side (the
+    //              cloth's outside, one-sided colliders: 0 none, 1 away from the root bone's axis, 2 the
+    //              next xyz in the root bone's frame), side xyz, guideHold (0..1: guides re-applied after
+    //              every constraint pass with this fraction of their weight; 0 = once before the passes),
+    //              edges (1 = the bone segments and links collide with the capsules too, not only the particles),
+    //              spin (> 0: the chain in the parent bone's rotating frame + its centrifugal / Euler forces × spin;
+    //              0 = the translational frame, no turn forces), spinInertia (s: the cloth's own rotation follows the body's with this time constant — behind on a start, past the back on a stop; 0 = glued)
+    //   + boneCount × 7: radius (m), stiffness (0..1 per 1/60 s toward the animated shape), damping
+    //              (0..1 velocity lost per 1/60 s), gravity (m/s² along world −Y), angleLimit (degrees off
+    //              the animated direction, 0 = none), mass (relative, 0 = 1: a bone-length constraint
+    //              moves its two ends in inverse proportion; the root is kinematic; < 0 = PINNED, the bone
+    //              rides the animation), give (m, pinned bones: a soft pin — a collider may push the bone
+    //              this far off its animated place, its local translation is written back too; 0 = hard)
+    //   links: (a, b) bone index pairs held at their rest distance (a cloak's columns; two linked leaves
+    //          link their virtual tips too, so a hem stays a hem); optional.
+    /** @count linkCount=links/2 */
+    dynamicBoneCreate?(modelRootId: u32, bones: Uint32Array, settings: Float32Array, links?: Uint16Array): u32
+    dynamicBoneDestroy?(id: u32): void
+    /** Retune a live chain: the same blob as create (the bone rows too when the count matches). */
+    dynamicBoneSet?(id: u32, settings: Float32Array): void
+    /** The floor the particles stay above: mode 0 none / 1 the plane (point, normal) / 2 probe — the
+     *  engine casts a ray from the chain root down every frame (the ground probe, the model root
+     *  excluded) and uses the hit; no hit / no physics world = no floor that frame. */
+    dynamicBoneSetFloor?(id: u32, mode: 0 | 1 | 2, x: f32, y: f32, z: f32, nx: f32, ny: f32, nz: f32): void
+    /** The next frame snaps the chain onto the animated pose (a teleport, a cut). */
+    dynamicBoneReset?(id: u32): void
+    /** The colliders this chain collides with (dynamicBoneColliderCreate ids); replaces the list. */
+    dynamicBoneSetColliders?(id: u32, colliderIds: Uint32Array): void
+    /** The particles' world positions (bones first, then the leaves' virtual tips), 3 floats each into
+     *  `out`; returns the count written — a debug overlay. @count max=out/3 */
+    dynamicBoneParticles?(id: u32, out: Float32Array): u32
+    // guides: rows × 5 — bone index (in the chain's bone order), world x y z, weight — world points the
+    // bones' particles are drawn to before the constraints; null / empty clears; refreshed every frame
+    /** @count count=rows/5 */
+    dynamicBoneTargets?(id: u32, rows: Float32Array | null): void
+    /** A capsule a → b in the entity's local space (a == b = a sphere) that rides the entity — a bone
+     *  of the body the chains must not pass through. Returns a collider id (0 on failure). */
+    /** `sided` 1 = one-sided: while the capsule moves away from the chain's `side` it puts a bone it has run into over to that side instead of carrying it (an arm under a cape); 0 = pushes to the nearest surface. */
+    dynamicBoneColliderCreate?(entityId: u32, ax: f32, ay: f32, az: f32, bx: f32, by: f32, bz: f32, radius: f32, sided: f32): u32
+    dynamicBoneColliderSet?(colliderId: u32, ax: f32, ay: f32, az: f32, bx: f32, by: f32, bz: f32, radius: f32, sided: f32): void
+    dynamicBoneColliderDestroy?(colliderId: u32): void
+    // Legacy coupled shape+body (still used by the worker RigidBody).
+    physicsCreateBox(entityId: u32, hx: f32, hy: f32, hz: f32, motionType: i32, mass: f32): u32
+    physicsCreateSphere(entityId: u32, radius: f32, motionType: i32, mass: f32): u32
+    physicsCreateCylinder(entityId: u32, halfHeight: f32, radius: f32, motionType: i32, mass: f32): u32
+    physicsSetLinearVelocity(bodyId: u32, x: f32, y: f32, z: f32): void
+    /** @into out 3 */
+    physicsGetLinearVelocity(bodyId: u32, out: Float32Array): void
+    /** Angular velocity about each world axis, RADIANS/second — Jolt's unit; the SDK exposes degrees.
+     *  The only way to stop a spin: a position write leaves both velocities untouched. */
+    physicsSetAngularVelocity?(bodyId: u32, x: f32, y: f32, z: f32): void
+    /** @into out 3 */
+    physicsGetAngularVelocity?(bodyId: u32, out: Float32Array): void
+    physicsApplyImpulse(bodyId: u32, x: f32, y: f32, z: f32): void
+    physicsApplyImpulseAt?(bodyId: u32, x: f32, y: f32, z: f32, px: f32, py: f32, pz: f32): void
+    physicsSetBodyPosition(bodyId: u32, x: f32, y: f32, z: f32): void
+    /** The rotation twin (normalized host-side). Both snap the body's render-interpolation pair, so a
+     *  discontinuous move is drawn as one rather than as a one-frame slide/spin across the gap. */
+    physicsSetBodyRotation?(bodyId: u32, qx: f32, qy: f32, qz: f32, qw: f32): void
+    physicsRemoveBody(bodyId: u32): void
+
+    /** @custom */
+    createMediaPlayerTexture(id: i32): i32
+
+    getName(entityId: u32): string
+    setName(entityId: u32, name: string): void
+
+    hasMesh(entityId: u32): boolean
+
+    /** @custom */
+    createARController(sceneId: u32, cameraId: u32, mode: string, onTrack: (entityId: number, track: boolean) => void): void
+    /** @custom */
+    createRootAnchor(sceneId: u32): u32
+    /** @custom */
+    createAnchor(sceneId: u32, physicalWidth: f64, systemId: bytes): u32
+
+    // Particles. All emitter/curve config crosses as ONE Float32Array of [tag, payloadLen,
+    // ...payload] records, parsed once in creator-particles (CPART_TAG_* in creator-particles.h; the
+    // SDK mirror is in gl/Particles.ts, guarded by sdk/tests/gl/particles-tags.test.ts). Unknown
+    // tags skip by length. maxParticles 0 = default (1000).
+    createParticleSystem(entityId: u32, materialInstanceId: u32, maxParticles: u32): void
+    spawnParticles(entityId: u32, count: f32): void
+    setParticleSystemConfig(entityId: u32, data: Float32Array): void
+
+    // Projected decals (creator-gl src/decals.h; SDK gl/DecalSet.ts). A set on an entity = one
+    // renderable of `capacity` (0 = 256) unit boxes drawn with the material instance (decal.filamat)
+    // — each box projects its atlas cell onto the opaque scene behind it through the scene depth
+    // buffer. A record is 27 floats in the SET entity's space: X Y Z axes scaled by the box's
+    // width / height / depth (Z = out of the surface), centre, atlas rect u0 v0 u1 v1, tint rgba,
+    // life (s, 0 = forever), fadeIn (s), fadeOut (s), capStart, capEnd (tilt of the image's bottom /
+    // top edge in unit space — mitred trail joints, 0 = square), alphaStart, alphaEnd (opacity
+    // multipliers at the bottom / top edge — a gradient along the image). addDecal returns the slot (0xFFFFFFFF = no
+    // set; a full set recycles its oldest); updateDecal keeps the slot's birth time. Optional:
+    // a host without them draws no decals (the SDK warns once).
+    createDecalSet?(entityId: u32, materialInstanceId: u32, capacity: u32): void
+    addDecal?(entityId: u32, record: Float32Array): u32
+    updateDecal?(entityId: u32, slot: u32, record: Float32Array): void
+    removeDecal?(entityId: u32, slot: u32): void
+    clearDecals?(entityId: u32): void
+    decalCount?(entityId: u32): u32
+
+    createNoise(): u32
+    setNoiseFrequency(noiseId: u32, frequency: f32): void
+    setNoiseOctaves(noiseId: u32, octaves: f32): void
+    setNoiseFractalLunacrity(noiseId: u32, lunacrity: f32): void
+    setNoiseFractalGain(noiseId: u32, fractalGain: f32): void
+    getNoise2D(noiseId: u32, x: f32, y: f32): f64
+    getNoise3D(noiseId: u32, x: f32, y: f32, z: f32): f64
+
+    /** @custom */
+    captureImage(sceneId: number, onComplete: (bufferId: number, name: string, size: number) => void, onReject: () => void): void
+  }
+}
+
+/** The 3D HOST's side of the contract — what the engine needs from the platform around Filament
+ *  (`HostGL` of creator-pkg/host.gen.h): the GL context to share, the scene view's lifecycle, image
+ *  decoding into textures, AR / VR sessions. OPTIONAL as a whole (a UI-only build has no 3D); every
+ *  slot but `createTexture` is optional — the runtime skips what a host does not fill.
+ *  @host gl HostGL @optional */
+export interface HostGL {
+  /** The host's GL context Filament shares with (a desktop master context, the XR context on Quest);
+   *  absent = the engine creates its own. */
+  getGLContext?(): handle
+  /** Fired on the JS thread right after createEngine built (or rebuilt) the engine, success or not — a
+   *  host that released its own context for the share re-binds it here. */
+  engineCreated?(): void
+  /** The legacy first scene.open(): create the scene view / swap chain lazily. */
+  createGLView?(): void
+  /** The scene closed for good: drop the scene view, stop compositing. */
+  closeScene?(): void
+  /** Decode host buffer `systemId` (PNG / JPEG / KTX2) into an engine texture (`flags` = Texture.load's
+   *  options bitmask, 1 = linear data); settle `onComplete(textureId, width, height)` or `onReject`
+   *  through the dispatch bridge. */
+  createTexture(systemId: bytes, flags: u32, onComplete: (textureId: u32, width: i32, height: i32) => void, onReject: (err: string) => void): void
+  /** Import a media player's frames as an engine texture (`_creator.createMediaPlayerTexture`); 0 = none. */
+  createMediaPlayerTexture?(playerId: i32): i32
+  /** Start an AR session for the scene; settle one callback through the dispatch bridge. */
+  launchAR?(sceneId: u32, onComplete: () => void, onReject: (err: string) => void): void
+  stopAR?(): void
+  /** Start a VR (OpenXR) session for the scene; absent = "VR is not supported on this device". */
+  launchVR?(sceneId: u32, onComplete: () => void, onReject: (err: string) => void): void
+  stopVR?(): void
+  /** Bind the AR camera of `sceneId` to `cameraId` in `mode` ("world" / "face" / …). */
+  createARController?(sceneId: u32, cameraId: u32, mode: string): void
+  /** The AR root anchor entity of a scene. */
+  createRootAnchor?(sceneId: u32, entityId: u32): void
+  /** An image anchor: track the image in host buffer `systemId` (`physicalWidth` in metres) on `entityId`. */
+  createAnchor?(sceneId: u32, entityId: u32, physicalWidth: f32, systemId: bytes): void
+}
+
+export {}