Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

52.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    wasm.ts
 * @brief   WASM module type definitions
 */

import { Entity } from './types';
import type { Registry as GeneratedRegistry } from './wasm/wasm.generated';

// =============================================================================
// C++ Registry Interface
// =============================================================================

/**
 * A JS-owned C++ EstellaContext instance. Created
 * via `new module.EstellaContext()`, destroyed via `.delete()` — like Registry.
 * Owns one engine's GPU + logic subsystems; `setActiveContext` selects which one
 * the bindings route through.
 */
export interface CppEngineContext {
    /** Initialize GPU subsystems against a WebGL context handle. Returns success. */
    init(webglContextHandle: number): boolean;
    /** Tear down all subsystems + the WebGL context. */
    shutdown(): void;
    isInitialized(): boolean;
    /** Free the underlying C++ instance (embind ownership). */
    delete(): void;
}

export interface CppRegistry extends GeneratedRegistry {
    delete(): void;
    removeParent(entity: Entity): void;
    /** Every pool's version in one number, where the core binds it on the
     *  registry itself. The web module answers the same question as a free
     *  function; absent on a core built before either existed. */
    layoutEpoch?(): number;

    [key: string]: Function | undefined;
}

// =============================================================================
// C++ Resource Manager
// =============================================================================

/**
 * Who refills a texture after a device loss, stated by whoever creates it —
 * mirroring the engine's `resource::ResourceContent`.
 */
export const TextureContent = {
    /** Rewritten before every use (a decoded video frame). */
    Transient: 0,
    /** The engine keeps the bytes (a tile collection composed at load). */
    Retained: 1,
    /** The asset layer loads it again from its path. */
    Asset: 2,
    /** Redrawn from the canvas it mirrors. */
    Canvas: 3,
    /** Refilled by the video it shows. */
    Video: 4,
    /** Repainted from the glyphs placed on it. */
    GlyphPage: 6,
    /** A skeleton's atlas page, decoded again from its image. */
    AtlasPage: 7,
    /** Composed again by its creator from its sources (a terrain's layer arrays). */
    Composed: 8,
} as const;
export type TextureContent = typeof TextureContent[keyof typeof TextureContent];

/** A content code's name, for a log that says what could not be refilled. */
export function textureContentName(content: TextureContent): string {
    const entry = Object.entries(TextureContent).find(([, code]) => code === content);
    return entry ? entry[0] : `content ${content}`;
}

export interface CppResourceManager {
    /** `content` is a {@link TextureContent}: who refills the texture after a device loss. */
    createTexture(width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, content: TextureContent): number;
    /** `filterMode`: bit 0 is linear over nearest, bit 1 a mip chain (see `textureFilterCode`). */
    createTextureEx(width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number, content: TextureContent): number;
    /**
     * A 2D texture array of `layers` RGBA8 layers, `pixelsLen` bytes back to back; `filterMode` and `wrapMode` are
     * {@link createTextureEx}'s codes. Absent on an older wasm build.
     */
    createTextureArray?(width: number, height: number, layers: number, pixels: number, pixelsLen: number, format: number, filterMode: number, wrapMode: number, content: TextureContent): number;
    /**
     * Module-free texture upload: take the RGBA bytes directly instead of a wasm
     * heap pointer. Present ONLY on the native ResourceManager (embedded Dawn, no
     * wasm heap to marshal into); the wasm embind object does not implement it, so
     * the upload helpers fall through to the heap path and web stays byte-identical.
     * `filterMode`/`wrapMode` mirror {@link createTextureEx}'s codes (optional). */
    /** {@link createTextureArray} without a wasm heap: the layers back to back as bytes. Present only on the native ResourceManager. */
    createTextureArrayFromBytes?(width: number, height: number, layers: number, pixels: Uint8Array, format: number, filterMode: number, wrapMode: number, content: TextureContent): number;
    createTextureFromBytes?(width: number, height: number, pixels: Uint8Array, format: number, flipY: boolean, content: TextureContent, filterMode?: number, wrapMode?: number): number;
    /** Transcode + upload a KTX2/Basis container to a device-supported compressed
     *  format (or RGBA32). Native only (the basis transcoder lives in the host);
     *  the web KTX2 path is WebGL2 + the wasm transcoder instead. */
    /** Transcode + upload a KTX2 natively. `format` is the GfxCompressedFormat
     *  ordinal uploaded, negative when it decoded to RGBA; `blockRefused` says a
     *  supported format existed and the image was not whole blocks of it. Both
     *  optional — an absent answer must not read as a compressed one. */
    createTextureFromKTX2?(bytes: Uint8Array, srgb: boolean): {
        handle: number; width: number; height: number;
        format?: number; blockRefused?: boolean;
    } | null;
    /** Whether the ACTIVE backend samples this compressed format (the C++
     *  `GfxCompressedFormat` ordinal). Absent on an older wasm build. */
    supportsCompressedFormat?(format: number): boolean;
    /** Uploads pre-transcoded blocks (level 0 first) as one compressed texture,
     *  whichever backend is running. Absent on an older wasm build. */
    createCompressedTexture?(width: number, height: number, format: number,
                             dataPtr: number, dataLen: number, mipLevels: number,
                             content: TextureContent): number;
    /** Module-free {@link updateTextureSubregion} — native byte upload for the
     *  glyph atlas, symmetric with {@link createTextureFromBytes}. */
    updateTextureSubregionFromBytes?(handle: number, x: number, y: number, width: number, height: number, pixels: Uint8Array): void;
    createShader(vertSrc: string, fragSrc: string): number;
    registerExternalTexture(glTextureId: number, width: number, height: number, content: TextureContent): number;
    /** Like registerExternalTexture, but with the actual GPU byte size for the
     *  eviction budget (compressed textures are 4–8× smaller than the RGBA8
     *  estimate the plain variant books). */
    registerExternalTextureSized(glTextureId: number, width: number, height: number, bytes: number, content: TextureContent): number;
    /** A resource handle for a device texture another owner keeps (a render target's colour). */
    wrapDeviceTexture?(textureId: number, width: number, height: number): number;
    /**
     * The textures the device is waiting for content for, one
     * `handle|content|path` per line; `content` is the {@link TextureContent}
     * that refills it. Optional: absent on an older wasm build.
     */
    texturesAwaitingReupload?(): string;
    /** Give up on an owed texture's content: it keeps blank storage. */
    forgoTextureContent?(handle: number): void;
    /** Its provider wrote the pixels itself (the JS upload bridge); the debt is paid. */
    restoreTextureContent?(handle: number): void;
    /**
     * Move a freshly loaded texture's pixels behind an owed handle; the source
     * is left empty for its release. Optional: absent on an older wasm build.
     */
    adoptTextureContent?(target: number, source: number): boolean;
    /**
     * Replayable meshes still owed their geometry, as comma-separated handle
     * ids. No path travels with them: the asset layer holds the provenance.
     * Optional: absent on an older wasm build.
     */
    meshesAwaitingRemat?(): string;
    /** Every live mesh as `handle:realized`. Optional: absent on an older wasm build. */
    meshRealizations?(): string;
    getTextureGLId(handle: number): number;
    /** The backend's own name for the texture's object (an emscripten GL texture id),
     *  valid until the next device loss; 0 where the backend has none. */
    getTextureNativeId?(handle: number): number;
    getTextureDimensions(handle: number): { width: number; height: number } | null;
    releaseTexture(handle: number): void;
    getTextureRefCount(handle: number): number;
    releaseShader(handle: number): void;
    getShaderRefCount(handle: number): number;
    setTextureMetadata(handle: number, left: number, right: number, top: number, bottom: number): void;
    updateTextureSubregion(handle: number, x: number, y: number, width: number, height: number, pixels: number, pixelsLen: number): void;
    registerTextureWithPath(handle: number, path: string): void;
    setTextureBudget(bytes: number): void;
    /** Optional: the native core does not wire it. */
    setRetainedBudget?(bytes: number): void;
    acquireTextureByPath(path: string): number;
    invalidateTexturePath(path: string): boolean;
    trimTextureCache(): number;
    getResourceStats(): {
        shaderCount: number;
        textureCount: number;
        vertexBufferCount: number;
        indexBufferCount: number;
        cacheHits: number;
        cacheMisses: number;
        textureBytes: number;
        textureBudget: number;
        textureEvictableCount: number;
        retainedBytes: number;
    };
    loadBitmapFont(fntContent: string, textureHandle: number, texWidth: number, texHeight: number): number;
    createLabelAtlasFont(textureHandle: number, texWidth: number, texHeight: number, chars: string, charWidth: number, charHeight: number): number;
    releaseBitmapFont(handle: number): void;
    getBitmapFontRefCount(handle: number): number;
    measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number };
}

/**
 * GPU objects the graphics device is holding, as {@link ESEngineModule.renderer_getLiveObjects}
 * reports them. The C++ side documents which of these obey a conservation law
 * and which are caches (renderer/rhi/GfxDevice.hpp).
 */
export interface GfxLiveObjects {
    buffers: number;
    textures: number;
    programs: number;
    layouts: number;
    pipelines: number;
    renderTargets: number;
    readbacks: number;
}

// =============================================================================
// WASM Module Interface
// =============================================================================

export interface EmscriptenFS {
    writeFile(path: string, data: string | Uint8Array): void;
    readFile(path: string, opts?: { encoding?: string }): string | Uint8Array;
    mkdir(path: string): void;
    mkdirTree(path: string): void;
    unlink(path: string): void;
    stat(path: string): { mode: number; size: number };
    isFile(mode: number): boolean;
    isDir(mode: number): boolean;
    analyzePath(path: string): { exists: boolean; parentExists: boolean };
}

export interface ESEngineModule {
    Registry: new () => CppRegistry;
    /** JS-newable engine context. */
    EstellaContext: new () => CppEngineContext;
    HEAPU8: Uint8Array;
    HEAPU32: Uint32Array;
    HEAPF32: Float32Array;
    /**
     * The module's own linear memory, which a compiled system module IMPORTS
     * rather than owning a second (docs/REARCH_AOT.md §6.1) — and only a
     * `Memory` can be imported, a heap view's `buffer` cannot become one again.
     * Optional because an artifact built before the link flag carries none.
     */
    wasmMemory?: WebAssembly.Memory;

    FS: EmscriptenFS;

    initRenderer(): boolean;
    initRendererWithContext(contextHandle: number): boolean;
    /**
     * Boot on the WebGPU backend. The host must acquire a GPUDevice and pass it
     * as `preinitializedWebGPUDevice` in the module factory arg BEFORE
     * instantiation; '#canvas' resolves to the module's canvas. Returns false
     * when the build carries no WebGPU backend or no device was provided.
     */
    initRendererWebGPU(canvasSelector: string, width: number, height: number,
                       readback: boolean, preferBGRA: boolean): boolean;
    shutdownRenderer(): void;
    /**
     * Select which EstellaContext the bindings route through. Pass null to clear.
     * Existing initRenderer paths still set it implicitly; this lets the editor
     * own contexts explicitly.
     */
    setActiveContext(ctx: CppEngineContext | null): void;

    GL: {
        registerContext(ctx: WebGLRenderingContext | WebGL2RenderingContext, options: {
            majorVersion: number;
            minorVersion: number;
            enableExtensionsByDefault?: boolean;
        }): number;
        /** Emscripten-internal: active GL context record (populated after registerContext). */
        currentContext?: { GLctx: WebGLRenderingContext | WebGL2RenderingContext };
        /** Emscripten-internal: every registered context record, indexed by handle (holes possible). */
        contexts?: ({ GLctx: WebGLRenderingContext | WebGL2RenderingContext } | null)[];
        /** Emscripten-internal: allocate a new handle id into the given object pool. */
        getNewId(pool: Record<number, unknown>): number;
        /** Emscripten-internal: texture object pool keyed by handle id. */
        textures: Record<number, WebGLTexture>;
    };
    getResourceManager(): CppResourceManager;
    /**
     * Convert a Canvas2D-rasterized alpha bitmap to a signed distance field for
     * the runtime glyph atlas. `alphaPtr`/`outPtr` are HEAPU8
     * pointers to width*height byte buffers; the SDF is written into `outPtr`.
     */
    sdfFromAlpha?(alphaPtr: number, outPtr: number, width: number, height: number, spread: number): void;
    /**
     * Whether the GPU device can still be drawn to: 0 live, 1 lost, 2 recovering,
     * 3 dead. Reports live before a renderer exists — there is nothing to lose yet.
     * Optional: an older wasm build does not carry it.
     */
    deviceStatus?(): number;
    /** One-line loss report naming backend, GPU, driver and reason; empty while live. */
    deviceLostReport?(): string;
    /** `backend|vendor|renderer|version`, or empty before a device exists. */
    deviceIdentity?(): string;
    /**
     * Report a loss the page observed (`webglcontextlost`, a rejected GPUDevice
     * `lost` promise) so the engine stops submitting on this frame rather than
     * on its own next poll. Reason codes match GfxDeviceLostReason.
     */
    notifyDeviceLost?(reason: number, message: string): void;
    /**
     * Upload geometry described by an .esmesh channel table — 8 bytes per channel
     * (semantic, components, type, normalized, offset) in the file's own layout,
     * so the format stays the asset layer's and the vertex layout stays the
     * engine's. A channel's semantic is its shader attribute location.
     */
    mesh_createFromChannels?(channelsPtr: number, channelCount: number, vertexStride: number,
                             vertexPtr: number, vertexBytes: number,
                             indexPtr: number, indexCount: number,
                             minX: number, minY: number, minZ: number,
                             maxX: number, maxY: number, maxZ: number,
                             bindPtr: number, bindFloats: number,
                             morphPtr: number, morphFloats: number,
                             morphTargets: number, morphNormals: number): number;
    /**
     * Put replayed geometry behind an EXISTING mesh handle after a device loss.
     * Returns the handle it was given, or 0 if the engine refused — never a new
     * handle, which is why this is not a second mesh_createFromChannels: every
     * component in the world still names the mesh by the handle it already has.
     */
    mesh_rematerializeFromChannels?(targetHandle: number,
                                    channelsPtr: number, channelCount: number,
                                    vertexStride: number,
                                    vertexPtr: number, vertexBytes: number,
                                    indexPtr: number, indexCount: number,
                                    minX: number, minY: number, minZ: number,
                                    maxX: number, maxY: number, maxZ: number,
                                    bindPtr: number, bindFloats: number,
                                    morphPtr: number, morphFloats: number,
                                    morphTargets: number, morphNormals: number): number;
    /**
     * The renderer's program-readiness epoch. Advanced whenever programs that
     * WERE ready go cold, so a readiness record carrying an older one is naming
     * programs that may no longer exist and has to be re-derived.
     * Optional: absent on an older wasm build.
     */
    renderer_programEpoch?(): number;
    /**
     * Which generation of the GPU device is current, advanced by every successful
     * rebuild. Never part of a readiness claim — the guard that says the claim
     * was derived and readied on ONE device.
     * Optional: absent on an older wasm build.
     */
    renderer_deviceGeneration?(): number;
    /**
     * Ready the mesh programs a prepared cell requires, from its decoded document
     * — no entity of it need exist, which is what preparing means. Eleven words
     * out: claim-valid, four counts, the requirement digest, its epoch, and the
     * device generation that witnessed it. Optional: absent on an older wasm.
     */
    engine_prepareMeshPrograms?(rowsPtr: number, count: number, outPtr: number): void;
    /** Release a mesh and the buffers it owns. */
    mesh_release?(meshHandle: number): void;
    /**
     * Register a baked environment: 27 floats of irradiance (nine RGB spherical-
     * harmonic coefficients, convolved and over pi) plus the prefiltered atlas an
     * ambient light reflects; 0 is diffuse-only. `columns` is the pyramids in that
     * atlas — one for a sky, several for a bake whose column 0 IS the sky.
     */
    environment_create?(shPtr: number, specularHandle: number, faceSize: number,
                        mipCount: number, maxRange: number, columns: number): number;
    /** Release an environment; its atlas is an ordinary texture and outlives it. */
    environment_release?(environmentHandle: number): void;
    environment_setSky?(environmentHandle: number, skyHandle: number): void;
    /** The environment the sky lights the scene with, 0 for none (postprocess/skyEnvironment). */
    renderer_setSkyEnvironment?(environmentHandle: number): void;
    /**
     * Give an environment the sun its importer separated from the sky: 27 floats of
     * irradiance without it, the direction toward it (panorama frame) and its
     * irradiance over pi — what a Light following it casts.
     */
    environment_setSun?(environmentHandle: number, skyShPtr: number, dx: number, dy: number,
                        dz: number, r: number, g: number, b: number): void;
    /**
     * Register a grid of baked irradiance: `resX*resY*resZ*27` floats, nine RGB
     * coefficients per probe with x varying fastest. The same nine an environment
     * carries, at points instead of once — which is what lights a thing that moves.
     */
    probe_volume_create?(resX: number, resY: number, resZ: number, shPtr: number): number;
    /** Release a probe volume. */
    probe_volume_release?(volumeHandle: number): void;
    /** Nine floats per probe of how much of the sky each sees (a bake with sky occlusion). */
    probe_volume_setSkyVisibility?(volumeHandle: number, visibilityPtr: number): void;
    /** The same for every MeshRenderer in the world; returns how many were frozen. */
    meshRenderer_makeAllResident?(registry: CppRegistry): number;
    /**
     * Point every MeshRenderer in the world at one resident mesh, clearing their
     * inline payloads. Returns how many were pointed.
     */
    meshRenderer_setMeshAll?(registry: CppRegistry, meshHandle: number): number;
    /** Local XY bounds of what a MeshRenderer draws — resident geometry, else its
     *  inline payload. Null when it draws nothing. */
    meshRenderer_localBounds?(registry: CppRegistry, entity: number):
        { minX: number; minY: number; maxX: number; maxY: number } | null;
    /** Point every MeshRenderer in the world at one material; returns how many. */
    meshRenderer_setMaterialAll?(registry: CppRegistry, materialId: number): number;
    recoverDevice?(): boolean;
    /**
     * Take up the replacement device left on `Module.pendingWebGPUDevice`. A
     * WebGPU device belongs to whoever created it, so the page has to supply
     * one; the next {@link recoverDevice} adopts it. WebGL2 answers false.
     */
    provideReplacementDevice?(): boolean;
    /**
     * UI draw order of an entity (its UIVisual.uiOrder, assigned by the UI
     * render-order pass), so SDF text quads interleave with UI quads. -1 if the
     * entity is not a UI render node.
     */
    ui_getRenderOrder?(registry: CppRegistry, entity: number): number;
    ui_getCullBit?(registry: CppRegistry, entity: number): number;
    /** Whether an entity belongs to the screen rather than the world — the same
     *  answer the renderer partitions its collects by (UISystem::screenDomain). */
    ui_isScreenDomain?(registry: CppRegistry, entity: number): boolean;

    /**
     * Geometry posed by a skeletal runtime (Spine, DragonBones): x,y,u,v,r,g,b,a per
     * vertex, drawn as `entity`'s, with `materialId` resolved as a Sprite's is.
     */
    /**
     * Whether the camera being rendered right now would draw this entity's
     * geometry at the local extent it promises to stay inside. The frame's own
     * frustum and culling mask — a fact, not a permission.
     */
    renderer_entityVisibleToCamera?(
        registry: CppRegistry, entity: number, layer: number,
        minX: number, minY: number, maxX: number, maxY: number, outVisiblePtr: number): void;

    renderer_submitSkeletalBatchByEntity?(
        registry: CppRegistry,
        verticesPtr: number, vertexCount: number,
        indicesPtr: number, indexCount: number,
        textureId: number, blendMode: number,
        entity: number, skelScale: number, flipX: boolean, flipY: boolean,
        layer: number, depth: number, materialId: number
    ): void;
    renderer_submitSkeletalBatchByEntityEx?(
        registry: CppRegistry,
        verticesPtr: number, vertexCount: number,
        indicesPtr: number, indexCount: number,
        textureId: number, blendMode: number,
        entity: number, skelScale: number, flipX: boolean, flipY: boolean,
        layer: number, depth: number, materialId: number, premultipliedColor: boolean
    ): void;
    /**
     * Submit pre-laid-out glyph quads. Vertex format x,y,u,v,r,g,b,a,sdfBias; `glyphMode` (TextGlyphMode) says how the page's
     * pixels become coverage: 0 the plain textured batch (device bitmap atlas), 1 the SDF variant, 2 and 3 a baked-outline page's
     * silhouette and fill.
     */
    renderer_submitTextBatch?(
        verticesPtr: number, vertexCount: number,
        indicesPtr: number, indexCount: number,
        textureId: number, transformPtr: number,
        entity: number, layer: number, depth: number, glyphMode: number, cullBit: number
    ): void;
    /**
     * Retained text: glyph quads handed over once and submitted by the engine every frame (RetainedText.hpp). `Begin` starts or replaces an
     * entity's label (its domain, box and layer), `Batch` adds one atlas page's quads to it, `Clear` forgets it, `Stale` lists the entities whose
     * domain or box no longer matches what they were laid out for, and `Submit` draws one domain's labels into the open list.
     */
    renderer_retainedTextBegin?(
        entity: number, sdf: number, screen: number, hasBox: number, layer: number, boxWidth: number, boxHeight: number, autoKind: number
    ): void;
    renderer_retainedTextBatch?(
        entity: number, verticesPtr: number, vertexCount: number,
        indicesPtr: number, indexCount: number, pageId: number, glyphMode: number
    ): void;
    renderer_retainedTextClear?(entity: number): void;
    renderer_retainedTextStale?(registry: CppRegistry, outPtr: number, capacity: number): number;
    renderer_retainedTextSubmit?(registry: CppRegistry, screen: number, projectionPtr: number): void;
    /**
     * Upload a MeshRenderer component's geometry: interleaved f32 [x,y,u,v] per vertex,
     * optional RGBA8 colors (colorsPtr 0 = all white), u32 triangle-list indices.
     * Validated engine-side: out-of-range indices reject the whole upload.
     */
    meshRenderer_setGeometry?(
        registry: CppRegistry, entity: number,
        posUvPtr: number, vertexCount: number,
        colorsPtr: number,
        indicesPtr: number, indexCount: number
    ): void;

    /**
     * The placements of a MeshInstances component: sixteen f32 an instance (the model's three rows, then a tint). Empty clears the set.
     * Reached through the generated engine surface (see foliage/plantGrowth.ts); declared here because embind registers it by hand for the web.
     */
    meshInstances_set?(registry: CppRegistry, entity: number, dataPtr: number, count: number): void;

    // Material API. Materials are engine-side data: the SDK compiles a shader
    // here, then pushes the resolved render state (flags pack depthTest bit 0,
    // depthWrite bit 1, CullMode bits 2-3) and the param values. Reached through
    // the generated engine surface rather than this interface (see material.ts),
    // which is what makes them work on a device too; declared here because embind
    // registers them by hand for the web.
    material_compileEsshader(source: string, featuresCsv: string): number;
    material_define(materialId: number, shaderHandle: number, blendMode: number, flags: number, depthBias: number): void;
    material_setUniform(materialId: number, name: string, arity: number,
                        v0: number, v1: number, v2: number, v3: number): void;
    material_setTexture(materialId: number, name: string, textureHandle: number): void;
    material_undefine(materialId: number): void;

    // ImmediateDraw API
    draw_begin(matrixPtr: number, viewportWidth: number, viewportHeight: number): void;
    draw_end(): void;
    draw_deferEnd(): void;
    draw_line(fromX: number, fromY: number, toX: number, toY: number,
              r: number, g: number, b: number, a: number, thickness: number): void;
    draw_line3D(fromX: number, fromY: number, fromZ: number,
                toX: number, toY: number, toZ: number,
                r: number, g: number, b: number, a: number, thickness: number): void;
    draw_line3DScreen(fromX: number, fromY: number, fromZ: number,
                      toX: number, toY: number, toZ: number,
                      r: number, g: number, b: number, a: number, thickness: number): void;
    draw_line3DScreenOffset(anchorX: number, anchorY: number, anchorZ: number,
                            fromX: number, fromY: number, toX: number, toY: number,
                            r: number, g: number, b: number, a: number, thickness: number): void;
    draw_rect(x: number, y: number, width: number, height: number,
              r: number, g: number, b: number, a: number, filled: boolean): void;
    draw_rectOutline(x: number, y: number, width: number, height: number,
                     r: number, g: number, b: number, a: number, thickness: number): void;
    draw_circle(centerX: number, centerY: number, radius: number,
                r: number, g: number, b: number, a: number, filled: boolean, segments: number): void;
    draw_circleOutline(centerX: number, centerY: number, radius: number,
                       r: number, g: number, b: number, a: number, thickness: number, segments: number): void;
    draw_texture(x: number, y: number, width: number, height: number, textureId: number,
                 r: number, g: number, b: number, a: number): void;
    draw_textureRotated(x: number, y: number, width: number, height: number, rotation: number,
                        textureId: number, r: number, g: number, b: number, a: number): void;
    draw_setLayer(layer: number): void;
    draw_setDepth(depth: number): void;
    draw_getDrawCallCount(): number;
    draw_getPrimitiveCount(): number;
    draw_setBlendMode(mode: number): void;
    draw_setDepthTest(enabled: boolean): void;
    draw_getDepthState?(): number;
    draw_setDepthState?(flags: number): void;
    draw_deferBegin?(): void;
    draw_mesh(geometryHandle: number, shaderHandle: number, transformPtr: number): void;
    draw_meshWithUniforms(geometryHandle: number, shaderHandle: number, transformPtr: number,
                          uniformsPtr: number, uniformCount: number): void;
    /** Reflected-material mesh draw (MaterialConstants UBO); false = shader has no
     *  #pragma-param layout, caller falls back to the loose uniform stream. */
    draw_meshWithMaterial(geometryHandle: number, materialId: number): boolean;
    /** Cook-time introspection (tools/gen-shader-twins.mjs): assembles both GLSL
     *  stages exactly as the runtime + the texture-unit reflection a GLSL→WGSL
     *  converter needs. Not called by the SDK itself. */
    esshader_cookInfo(source: string, featuresCsv: string): {
        valid: boolean; error?: string; name: string; domain: string;
        hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean;
        vertGlsl: string; fragGlsl: string;
        textures: Array<{ name: string; unit: number }>;
    };

    // Geometry API
    geometry_create(): number;
    geometry_init(handle: number, verticesPtr: number, vertexCount: number,
                  layoutPtr: number, layoutCount: number, dynamic: boolean): void;
    geometry_setIndices16(handle: number, indicesPtr: number, indexCount: number): void;
    geometry_setIndices32(handle: number, indicesPtr: number, indexCount: number): void;
    geometry_updateVertices(handle: number, verticesPtr: number, vertexCount: number, offset: number): void;
    geometry_release(handle: number): void;
    geometry_isValid(handle: number): boolean;

    // PostProcess API
    postprocess_init(width: number, height: number): boolean;
    postprocess_shutdown(): void;
    postprocess_resize(width: number, height: number): void;
    postprocess_addPass(name: string, shaderHandle: number): number;
    postprocess_addComputePass?(name: string, wgsl: string, params: string, workgroupX: number, workgroupY: number): number;
    postprocess_supportsCompute?(): boolean;
    postprocess_addNativePass?(name: string, kind: string): number;
    postprocess_updateGIField?(headerPtr: number, headerCount: number, sdfPtr: number, sdfOffset: number, sdfCount: number): boolean;
    postprocess_setGIScene?(headerPtr: number, headerCount: number, sdfPtr: number, sdfCount: number, instancesPtr: number, instanceCount: number, pixelsPtr: number, pixelCount: number): boolean;
    postprocess_setPassScale(name: string, scale: number): void;
    postprocess_setPassContinuesEffect(name: string): void;
    postprocess_requestSkyCapture?(passName: string, width: number, height: number): void;
    renderer_setWorldUnitsPerMeter?(units: number): void;
    renderer_requestProbeCapture?(x: number, y: number, z: number, face: number): void;
    renderer_pollProbeCapture?(): number;
    renderer_takeProbeCapture?(dst: number, bytes: number): boolean;
    renderer_setProbeVolumeOverride?(entity: number, volumeHandle: number): void;
    renderer_setProbeVolumeReflection?(entity: number, environmentHandle: number, slot: number): void;
    postprocess_pollSkyCapture?(): number;
    postprocess_takeSkyCapture?(dst: number, bytes: number): boolean;
    postprocess_giStats?(dst: number, capacity: number): number;
    postprocess_setMsaaSamples(samples: number): void;
    postprocess_effectiveMsaaSamples?(): number;
    postprocess_maxMsaaSamples?(): number;
    postprocess_hdrFormat?(outPtr: number): number;
    postprocess_hdrFormatNames?(): string;
    postprocess_setUniformFloat(passName: string, uniform: string, value: number): void;
    postprocess_setPassTexture(passName: string, uniform: string, textureHandle: number): void;
    postprocess_setUniformVec4(passName: string, uniform: string, x: number, y: number, z: number, w: number): void;
    postprocess_begin(): void;
    postprocess_end(): void;
    postprocess_isInitialized(): boolean;
    postprocess_setBypass(bypass: boolean): void;
    /** The curve the chain applies on the way out: 0 = none, 1 = ACES filmic.
     *  Absent on an engine built before the output transform existed. */
    postprocess_setOutputTransform?(transform: number): void;
    postprocess_setViewExposure?(ev: number): void;
    /** A graded look the last pass applies to the picture as the display shows it. Absent on an engine built before there was one. */
    postprocess_setDisplayLut?(textureHandle: number, amount: number): void;
    postprocess_clearPasses(): void;
    postprocess_setOutputViewport(x: number, y: number, w: number, h: number): void;
    /** Say a present is needed when the rects cannot: see PostProcessPipeline. */
    postprocess_setPresentRequired?(required: boolean): void;
    postprocess_beginScreenCapture(): void;
    postprocess_endScreenCapture(): void;
    postprocess_executeScreenPasses(): void;
    postprocess_addScreenPass(name: string, shaderHandle: number): number;
    postprocess_clearScreenPasses(): void;
    postprocess_setScreenUniformFloat(passName: string, uniform: string, value: number): void;
    postprocess_setScreenUniformVec4(passName: string, uniform: string, x: number, y: number, z: number, w: number): void;

    // Renderer API (RenderFrame)
    renderer_init(width: number, height: number): void;
    renderer_resize(width: number, height: number): void;
    renderer_beginFrame(elapsedSec: number): void;
    renderer_setOrigin?(x: number, y: number, z: number): void;
    renderer_updateTransforms(registry: CppRegistry): void;
    /** Address of the transform composition's staleness counter, so a producer
     *  stores into linear memory rather than calling across it. */
    transform_epochAddress?(): number;
    /** Compose world transforms if a producer said the inputs moved; O(1) if not. */
    transform_ensureComposed?(registry: CppRegistry): void;
    /** Whether composition also records which entities' output moved. Off by
     *  default: only a consumer maintaining an incremental structure needs it. */
    transform_setChangeTracking?(on: boolean): void;
    /** What every composition since the last acknowledgement changed: `count`
     *  raw entity ids at `ptr`, valid until the next composition. */
    transform_compositionChanges?(): {
        serial: number; tracking: boolean; overflowed: boolean;
        count: number; visited: number; ptr: number;
    };
    /** Acknowledge that set: it starts again. */
    transform_takeChanges?(): void;
    /** Permute component storage to the given entity order — see World.applyEntityOrder.
     *  Optional: an older core still answers every other renderer entry point. */
    renderer_setEntityDrawOrder?(registry: CppRegistry, entitiesPtr: number, count: number): void;
    renderer_begin(matrixPtr: number, targetHandle: number, clearFlags: number,
                   r: number, g: number, b: number, a: number,
                   clearX: number, clearY: number, clearW: number, clearH: number): void;
    renderer_flush(): void;
    renderer_end(): void;
    /** Closes the frame — per FRAME, not per camera. Optional: an older core
     *  released the surface at every camera's end and answers nothing here. */
    renderer_endFrame?(): void;
    /** The frame's screen-space overlay. Optional as a set: a core without them
     *  has no screen pass, and screen UI stays world content. */
    renderer_beginScreenOverlay?(projectionPtr: number, vpX: number, vpY: number,
                                 vpW: number, vpH: number): void;
    renderer_submitScreenOverlay?(registry: CppRegistry): void;
    renderer_endScreenOverlay?(targetHandle: number): void;
    renderer_submitAll(registry: CppRegistry, vpX: number, vpY: number, vpW: number, vpH: number): void;
    particle_update?(registry: CppRegistry, dt: number): void;
    particle_collisionQueryCount?(): number;
    particle_collisionQueries?(): number;
    particle_collisionEventCount?(): number;
    particle_collisionEvents?(): number;
    particle_collisionStatsCount?(): number;
    particle_collisionStats?(): number;
    particle_collisionResolve?(registry: CppRegistry, ptr: number, count: number): void;
    particle_collisionSetBudget?(queries: number, events: number, debug: boolean): void;
    particle_play?(registry: CppRegistry, entity: number): void;
    particle_emitAt?(registry: CppRegistry, entity: number, count: number, px: number, py: number, pz: number,
                     nx: number, ny: number, nz: number, vx: number, vy: number, vz: number): number;
    particle_stop?(registry: CppRegistry, entity: number): void;
    particle_reset?(registry: CppRegistry, entity: number): void;
    particle_getAliveCount?(entity: number): number;
    /** Upload (count = LUT size) or clear (count = 0) an entity's baked color-over-life LUT. */
    particle_set_color_lut?(entity: number, ptr: number, count: number): void;
    /** Upload/clear an entity's baked size-over-life multiplier LUT. */
    particle_set_size_lut?(entity: number, ptr: number, count: number): void;
    particle_set_speed_lut?(entity: number, ptr: number, count: number): void;
    particle_set_bursts?(entity: number, ptr: number, count: number): void;
    trail_update?(registry: CppRegistry, dt: number): void;
    trail_clear?(registry: CppRegistry, entity: number): void;
    springbone_update?(registry: CppRegistry, dt: number): void;
    springbone_reset?(registry: CppRegistry, entity: number): void;
    springbone_release?(registry: CppRegistry, entity: number): void;
    springbone_snapshot?(registry: CppRegistry, entity: number): number;
    springbone_snapshotCount?(): number;
    springbone_snapshotData?(): number;

    // Tilemap API
    tilemap_initLayer?(entity: number, width: number, height: number,
                       tileWidth: number, tileHeight: number): void;
    tilemap_initInfinite?(entity: number, tileWidth: number, tileHeight: number): void;
    tilemap_destroyLayer?(entity: number): void;
    tilemap_setTile?(entity: number, x: number, y: number, tileId: number): void;
    tilemap_getTile?(entity: number, x: number, y: number): number;
    tilemap_fillRect?(entity: number, x: number, y: number,
                      w: number, h: number, tileId: number): void;
    tilemap_setTiles?(entity: number, tilesPtr: number, count: number): void;
    tilemap_hasLayer?(entity: number): boolean;
    tilemap_getEditRevision?(entity: number): number;
    tilemap_getGeneration?(entity: number): number;
    tilemap_readChunkIndex?(entity: number, rowsPtr: number, capacity: number): number;
    tilemap_readChunkTiles?(entity: number, chunkX: number, chunkY: number, tilesPtr: number, capacity: number): boolean;
    tilemap_exportChunks?(entity: number): string;
    tilemap_importChunks?(entity: number, encoded: string): boolean;
    renderer_setStage(stage: number): void;
    renderer_createTarget(width: number, height: number, flags: number): number;
    renderer_releaseTarget(handle: number): void;
    renderer_getTargetTexture(handle: number): number;
    renderer_queueMaterialBake(material: number, shader: number, target: number, x: number, y: number, w: number, h: number,
                               a0: number, a1: number, a2: number, a3: number, b0: number, b1: number, b2: number, b3: number): number;
    renderer_materialBakeState(ticket: number): number;
    renderer_getTargetDepthTexture(handle: number): number;
    /**
     * Bytes malloc has handed out and not got back — the exact C++ leak signal
     * for the resource census. Optional: older engine builds do not carry it.
     */
    es_getMallocBytes?(): number;
    renderer_getDrawCalls(): number;
    /** Every draw the GPU was asked for in the last frame, every pass included. Optional: older engine builds do not carry it. */
    renderer_getGpuDrawCalls?(): number;
    /** Hand an entity's Impostor the atlas it draws from (0 takes it away). Optional: older engine builds do not carry it. */
    renderer_setImpostorAtlas?(entity: number, texture: number, frames: number): void;
    /** What size each texture was asked for since the last call, as `handle:side` pairs; texture streaming reads it. */
    renderer_takeTextureWants?(): string;
    /**
     * GPU objects the device has created and not destroyed, for the resource
     * census. Null when no device is initialized — a census must record those
     * counters as ABSENT, since zero would read as "everything was freed".
     * Optional: older engine builds do not carry it.
     */
    renderer_getLiveObjects?(): GfxLiveObjects | null;
    renderer_getTriangles(): number;
    renderer_getSprites(): number;
    renderer_getText(): number;
    renderer_getSkeletal?(): number;
    renderer_getMeshes(): number;
    renderer_getCulled(): number;
    /** Last frame's GPU time (ms) via EXT_disjoint_timer_query, or -1 if unavailable. */
    renderer_getGpuTimeMs?(): number;
    /** Enable/disable per-frame CPU scope profiling (FrameProfiler). */
    engine_setCpuProfiling?(on: boolean): void;
    /** Last frame's CPU scopes as a JSON object {"render.submit": ms, …}. */
    engine_getCpuScopes?(): string;
    /** Last frame's named counters as a JSON object {"render.culled": n, …}. */
    engine_getCounters?(): string;
    /** Last frame's per-pass GPU times as a JSON object {"graph": ms, …}. */
    engine_getGpuScopes?(): string;
    /** Resident texture VRAM (RGBA8 estimate, bytes) for the profiler's memory pillar. */
    renderer_getTextureBytes?(): number;
    /** Nominal live GPU buffer/texture storage, including target attachments; excludes driver overhead. */
    renderer_getEstimatedGpuBytes?(): number;
    renderer_setClearColor(r: number, g: number, b: number, a: number): void;
    renderer_setViewport(x: number, y: number, w: number, h: number): void;
    /** Bitmask of layers 0..31 that y-sort within the layer (top-down occlusion). */
    renderer_setYSortLayers?(mask: number): void;
    renderer_setDepthLayers?(mask: number): void;
    renderer_setTreeSortLayers?(mask: number): void;
    renderer_setQualityBudgets?(atlasSize: number, cellSize: number,
        cascades: number, particleLimit: number): void;
    renderer_setShadowDistance?(distance: number): void;
    /** How many samples across a light source a soft 2D shadow is drawn with (1 to 32). */
    renderer_setShadow2DSoftSamples?(samples: number): void;
    /** Draw the opaque scene twice, depth alone first, so a pixel is shaded for the surface in front of it. */
    renderer_setDepthPrepass?(on: boolean): void;
    renderer_setLightingDirect?(on: boolean): void;
    renderer_setAsyncShaderCompile?(on: boolean): void;
    renderer_getPendingShaders?(): number;
    renderer_setPlanarReflectionQuality?(scale: number, maxSize: number, updatesPerSecond: number): void;
    renderer_getPlanarReflectionStatus?(view: number, entity: number): string;
    renderer_setViewLighting?(mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean): void;
    renderer_setCullingMask?(mask: number): void;
    renderer_setViewId?(view: number): void;
    renderer_lodInspect?(view: number, entity: number, outPtr: number): number;
    renderer_setLodPreview?(view: number, entity: number, level: number): void;
    renderer_setViewShading?(view: number, mode: number): void;
    renderer_setMeshEdgeBuffers?(enabled: boolean): void;
    renderer_setViewSkinWeights?(view: number, entity: number, joint: number): void;
    renderer_lightStatus?(entity: number, outPtr: number): number;
    renderer_shadowStatus?(entity: number, outPtr: number): number;
    renderer_setColorSpace?(linear: number): void;
    /** Reseed the engine's randomness so a run reproduces (core/RandomSource.hpp). */
    engine_setRandomSeed?(seed: number): void;
    renderer_setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;



    // ECS Query API
    registry_getCanvasEntity(registry: CppRegistry): number;
    registry_getCanvasEntities?(registry: CppRegistry): number[];
    registry_getCameraEntities(registry: CppRegistry): number[];
    getChildEntities(registry: CppRegistry, entity: number): number[];
    registry_getGeneration(registry: CppRegistry, entity: number): number;
    registry_watchEntityChanges?(registry: CppRegistry): number;
    registry_unwatchEntityChanges?(registry: CppRegistry, reader: number): void;
    registry_entityChangeSequence?(registry: CppRegistry): number;
    registry_entityChangeResetEpoch?(registry: CppRegistry): number;
    registry_componentMutationRevision?(registry: CppRegistry, component: number, topology: boolean): number;
    registry_readEntityChanges?(registry: CppRegistry, after: number, outputPtr: number, capacity: number): number;
    registry_markComponentsChanged?(registry: CppRegistry, pairsPtr: number, count: number): void;
    registry_batchSyncPhysicsTransforms(registry: CppRegistry, bufferPtr: number, count: number, ppu: number): void;
    registry_readWorldPoses2D?(registry: CppRegistry, entitiesPtr: number, count: number, outputPtr: number): number;

    // GL Debug API
    gl_enableErrorCheck(enabled: boolean): void;
    gl_checkErrors(context: string): number;
    renderer_diagnose(): void;

    // Frame Capture API
    renderer_captureNextFrame(): void;
    /** Books the next completed frame for readback; poll + take it (frameCapture.ts). */
    renderer_captureFrame?(w: number, h: number): number;
    renderer_pollFrameCapture?(handle: number): number;
    renderer_takeFrameCapture?(handle: number, dest: number, destSize: number): boolean;
    renderer_getCapturedFrameSize(): number;
    renderer_getCapturedFrameData(): number;
    renderer_getCapturedEntities(): number;
    renderer_getCapturedEntityCount(): number;
    renderer_getCapturedTextures(): number;
    renderer_getCapturedTextureCount(): number;
    renderer_getCapturedPassCount(): number;
    renderer_hasCapturedData(): boolean;

    /** Replays on a later frame, after the pass that drew the call; the snapshot
     *  poll reports pending until then. */
    renderer_replayToDrawCall(drawCallIndex: number): void;
    renderer_snapshotMatchesCapture(): boolean;
    /** Lands the snapshot's async readback: 0 = pending (yield, poll again),
     *  1 = getSnapshot* serve the pixels, 2 = none/failed. GL reports 1 on the
     *  first poll; WebGPU resolves on a later event-loop turn. */
    renderer_pollSnapshotReadback(): number;
    renderer_getSnapshotPtr(): number;
    renderer_getSnapshotSize(): number;
    renderer_getSnapshotWidth(): number;
    renderer_getSnapshotHeight(): number;
    renderer_renderMaterialPreview(materialId: number, w: number, h: number, meshId: number, textureId: number): void;
    /** A skeletal preview, owned by its handle: every call names one, so two of
     *  them cannot reach each other and there is no "current" preview. */
    renderer_createSkeletalPreview(w: number, h: number): number;
    renderer_submitSkeletalPreviewBatch(
        preview: number, verticesPtr: number, vertexCount: number,
        indicesPtr: number, indexCount: number, textureId: number, blendMode: number,
        transformPtr: number, layer: number, depth: number, materialId: number): number;
    renderer_submitSkeletalPreviewBatchEx(
        preview: number, verticesPtr: number, vertexCount: number,
        indicesPtr: number, indexCount: number, textureId: number, blendMode: number,
        transformPtr: number, layer: number, depth: number, materialId: number, premultipliedColor: boolean): number;
    renderer_renderSkeletalPreview(preview: number, viewProjectionPtr: number): number;
    renderer_pollSkeletalPreview(preview: number): number;
    renderer_getSkeletalPreviewPtr(preview: number): number;
    renderer_getSkeletalPreviewSize(preview: number): number;
    renderer_getSkeletalPreviewWidth(preview: number): number;
    renderer_getSkeletalPreviewHeight(preview: number): number;
    renderer_destroySkeletalPreview(preview: number): void;
    renderer_renderMeshPreview(meshId: number, w: number, h: number): void;
    /** Same 0/1/2 readback contract as renderer_pollSnapshotReadback. */
    renderer_pollPreviewReadback(): number;
    renderer_getPreviewPtr(): number;
    renderer_getPreviewSize(): number;
    renderer_getPreviewWidth(): number;
    renderer_getPreviewHeight(): number;

    // UI Systems
    uiLayout_update(registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean): void;
    uiHitTest_update(registry: CppRegistry,
                     originX: number, originY: number, originZ: number,
                     dirX: number, dirY: number, dirZ: number): void;
    /** The hit test with a ray per domain: world content answers the first,
     *  screen UI the second. Optional — an older core has one domain. */
    uiHitTest_updateDomains?(registry: CppRegistry,
                             worldOriginX: number, worldOriginY: number, worldOriginZ: number,
                             worldDirX: number, worldDirY: number, worldDirZ: number,
                             screenOriginX: number, screenOriginY: number, screenOriginZ: number,
                             screenDirX: number, screenDirY: number, screenDirZ: number): void;
    uiHitTest_getHitEntity(): number;
    uiHitTest_pick?(registry: CppRegistry, worldX: number, worldY: number): number;
    uiHitTest_pickAll?(registry: CppRegistry, worldX: number, worldY: number): number;
    uiHitTest_pickResult?(index: number): number;
    uiNode_computedWidth(registry: CppRegistry, entity: number): number;
    uiNode_computedHeight(registry: CppRegistry, entity: number): number;
    uiRenderOrder_update(registry: CppRegistry): void;
    getUINodeComputedWidth?(registry: CppRegistry, entity: number): number;
    getUINodeComputedHeight?(registry: CppRegistry, entity: number): number;
    getUINodeHiddenInTree?(registry: CppRegistry, entity: number): boolean;
    /** Subtree opacity resolved by the layout pass (UINode.opacity multiplied down). */
    getUINodeAlphaInTree?(registry: CppRegistry, entity: number): number;
    transform_update(registry: CppRegistry): void;
    transform_copyFlatRenderMatrix?(registry: CppRegistry, entity: number, outputPtr: number): boolean;

    // Animation (Tween) API
    anim_createTween(registry: CppRegistry, entity: number, targetProp: number,
                      from: number, to: number, duration: number,
                      easing: number, delay: number,
                      loopMode: number, loopCount: number): number;
    anim_cancelTween(registry: CppRegistry, tweenEntity: number): void;
    anim_cancelAllTweens(registry: CppRegistry, targetEntity: number): void;
    anim_pauseTween(registry: CppRegistry, tweenEntity: number): void;
    anim_resumeTween(registry: CppRegistry, tweenEntity: number): void;
    anim_setTweenBezier(registry: CppRegistry, tweenEntity: number,
                         p1x: number, p1y: number, p2x: number, p2y: number): void;
    anim_setSequenceNext(registry: CppRegistry, tweenEntity: number, nextEntity: number): void;
    anim_updateTweens(registry: CppRegistry, deltaTime: number): void;
    anim_getTweenState(registry: CppRegistry, tweenEntity: number): number;

    /**
     * Every component pool's version, summed (`Registry::layoutEpoch`). Equal
     * across two reads means no stored component changed address between them —
     * which is what a holder of raw addresses (the AOT row table) asks before
     * trusting them for another frame.
     */
    registryLayoutEpoch(registry: CppRegistry): number;

    // Pointer-based component access
    getTransformPtr(registry: CppRegistry, entity: number): number;
    getSpritePtr(registry: CppRegistry, entity: number): number;
    /** Optional fast access; older Web cores retain the component-getter fallback. */
    getUINodePtr?(registry: CppRegistry, entity: number): number;
    getVelocityPtr(registry: CppRegistry, entity: number): number;
    getCameraPtr(registry: CppRegistry, entity: number): number;
    getRigidBody2DPtr(registry: CppRegistry, entity: number): number;
    getBoxCollider2DPtr(registry: CppRegistry, entity: number): number;
    getCircleCollider2DPtr(registry: CppRegistry, entity: number): number;

    _malloc(size: number): number;
    _free(ptr: number): void;

}