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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// 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;
}