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
import { awaitReadback, READBACK_READY } from './readback';
/**
* Memory-safety model for this module
* -----------------------------------
*
* Every function here reads from WASM-owned memory and returns values the
* caller may hold across later frames. To stay safe when WASM memory grows
* or the renderer reuses its capture buffer, we never return a typed array
* that views the WASM heap — we copy primitives into fresh JS objects /
* buffers before returning.
*
* - decodeFrameCapture copies every field out as plain `number`s and
* numeric arrays. The intermediate `DataView` and `Uint32Array` views
* are local and dropped as soon as the function returns.
* - getSnapshotImageData reads pixel rows from the heap view into a
* freshly-allocated `Uint8ClampedArray` ("flipped") and wraps that
* JS-owned buffer in the returned ImageData.
*
* Do NOT "optimize" either function by returning a heap-backed typed array
* directly — a subsequent WASM alloc/grow would detach it or the renderer
* would overwrite the bytes on the next capture, handing the caller silent
* corruption.
*/
/**
* Why a draw call started rather than joining the one before it. Mirrors the
* engine's BatchBreak; each member is a condition the merge itself tests.
*/
export enum BatchBreak {
None = 0,
RunStart = 1,
Instanced = 2,
Shader = 3,
Blend = 4,
Layout = 5,
Material = 6,
Depth = 7,
Cull = 8,
State = 9,
Scissor = 10,
Stencil = 11,
IndexGap = 12,
TextureSlots = 13,
}
export enum RenderType {
Sprite = 0,
Spine = 1,
Mesh = 2,
ExternalMesh = 3,
Text = 4,
Particle = 5,
Shape = 6,
UIElement = 7,
}
/** What a pass of the frame draws: a camera's scene, or the screen-space overlay. */
export enum CapturePass {
Scene = 0,
Overlay = 1,
}
export interface DrawCallInfo {
index: number;
/** Which pass of the frame drew it, in the order the passes ran. */
pass: number;
passKind: CapturePass;
stage: number;
type: RenderType;
blendMode: number;
textureId: number;
materialId: number;
shaderId: number;
indexCount: number;
/** 0 for a draw that is not instanced. */
instanceCount: number;
triangleCount: number;
layer: number;
breakReason: BatchBreak;
scissorX: number;
scissorY: number;
scissorW: number;
scissorH: number;
scissorEnabled: boolean;
stencilWrite: boolean;
stencilTest: boolean;
stencilRef: number;
textureSlotUsage: number;
/** Every texture the draw bound, slot 0 first; `textureId` is the first. */
textures: number[];
/** The entities the draw was made from, in draw order; an item with no entity
* (a glyph run, a gizmo) is not listed. */
entities: number[];
}
export interface FrameCaptureData {
drawCalls: DrawCallInfo[];
passCount: number;
}
/** sizeof(DrawCallRecord) in FrameCapture.hpp, which asserts the offsets read here. */
const RECORD_SIZE_BYTES = 84;
/**
* What capture asks of the engine: the wasm module, which hands out addresses in
* its heap, or a native host's surface, which copies into a buffer allocated in
* its heap arena — its script cannot read engine memory directly.
*/
export interface CaptureEngine {
HEAPU8: Uint8Array;
_malloc?(bytes: number): number;
_free?(offset: number): void;
renderer_captureNextFrame(): void;
renderer_hasCapturedData(): boolean;
renderer_getCapturedFrameSize(): number;
renderer_getCapturedEntityCount(): number;
renderer_getCapturedTextureCount(): number;
renderer_getCapturedPassCount(): number;
renderer_getCapturedFrameData?(): number;
renderer_getCapturedEntities?(): number;
renderer_getCapturedTextures?(): number;
renderer_copyCapturedRecords?(dest: number, destSize: number): boolean;
renderer_copyCapturedEntities?(dest: number, destSize: number): boolean;
renderer_copyCapturedTextures?(dest: number, destSize: number): boolean;
renderer_replayToDrawCall(drawCallIndex: number): void;
renderer_snapshotMatchesCapture(): boolean;
renderer_pollSnapshotReadback(): number;
renderer_getSnapshotPtr?(): number;
renderer_getSnapshotSize(): number;
renderer_getSnapshotWidth(): number;
renderer_getSnapshotHeight(): number;
renderer_copySnapshot?(dest: number, destSize: number): boolean;
}
/** @p bytes of engine data as a JS-owned copy: read at its address where the
* engine gives one, else copied through a scratch buffer in the heap. */
function readOut(
engine: CaptureEngine, bytes: number,
address: (() => number) | undefined,
copy: ((dest: number, destSize: number) => boolean) | undefined,
): Uint8Array | null {
if (bytes === 0) return new Uint8Array(0);
if (address) {
const at = address();
return at ? engine.HEAPU8.slice(at, at + bytes) : null;
}
if (!copy || !engine._malloc || !engine._free) return null;
const scratch = engine._malloc(bytes);
if (!scratch) return null;
try {
return copy(scratch, bytes) ? engine.HEAPU8.slice(scratch, scratch + bytes) : null;
} finally {
engine._free(scratch);
}
}
export function decodeFrameCapture(module: CaptureEngine): FrameCaptureData | null {
if (!module.renderer_hasCapturedData()) return null;
const count = module.renderer_getCapturedFrameSize();
if (count === 0) return null;
const entityCount = module.renderer_getCapturedEntityCount();
const passCount = module.renderer_getCapturedPassCount();
const textureCount = module.renderer_getCapturedTextureCount();
const m = module;
const records = readOut(m, count * RECORD_SIZE_BYTES,
m.renderer_getCapturedFrameData && (() => m.renderer_getCapturedFrameData!()),
m.renderer_copyCapturedRecords && ((d, n) => m.renderer_copyCapturedRecords!(d, n)));
const entityBytes = readOut(m, entityCount * 4,
m.renderer_getCapturedEntities && (() => m.renderer_getCapturedEntities!()),
m.renderer_copyCapturedEntities && ((d, n) => m.renderer_copyCapturedEntities!(d, n)));
const textureBytes = readOut(m, textureCount * 4,
m.renderer_getCapturedTextures && (() => m.renderer_getCapturedTextures!()),
m.renderer_copyCapturedTextures && ((d, n) => m.renderer_copyCapturedTextures!(d, n)));
if (!records || !entityBytes || !textureBytes) return null;
const view = new DataView(records.buffer);
const entityHeap = new Uint32Array(entityBytes.buffer);
const textureHeap = new Uint32Array(textureBytes.buffer);
const drawCalls: DrawCallInfo[] = [];
for (let i = 0; i < count; i++) {
const off = i * RECORD_SIZE_BYTES;
const listed = view.getUint32(off + 32, true);
const entityOffset = view.getUint32(off + 36, true);
const entities: number[] = [];
for (let e = 0; e < listed && entityOffset + e < entityCount; e++) {
entities.push(entityHeap[entityOffset + e]);
}
const slots = view.getUint8(off + 72);
const textureOffset = view.getUint32(off + 80, true);
const textures: number[] = [];
for (let t = 0; t < slots && textureOffset + t < textureCount; t++) textures.push(textureHeap[textureOffset + t]);
drawCalls.push({
index: view.getUint32(off, true),
pass: view.getUint32(off + 4, true),
stage: view.getUint8(off + 8),
type: view.getUint8(off + 9) as RenderType,
blendMode: view.getUint8(off + 10),
passKind: view.getUint8(off + 11) as CapturePass,
textureId: view.getUint32(off + 12, true),
materialId: view.getUint32(off + 16, true),
shaderId: view.getUint32(off + 20, true),
indexCount: view.getUint32(off + 24, true),
triangleCount: view.getUint32(off + 28, true),
layer: view.getInt32(off + 40, true),
breakReason: view.getUint8(off + 44) as BatchBreak,
scissorX: view.getInt32(off + 48, true),
scissorY: view.getInt32(off + 52, true),
scissorW: view.getInt32(off + 56, true),
scissorH: view.getInt32(off + 60, true),
scissorEnabled: view.getUint8(off + 64) !== 0,
stencilWrite: view.getUint8(off + 65) !== 0,
stencilTest: view.getUint8(off + 66) !== 0,
stencilRef: view.getInt32(off + 68, true),
textureSlotUsage: slots,
textures,
instanceCount: view.getUint32(off + 76, true),
entities,
});
}
return { drawCalls, passCount };
}
/**
* Asks for the captured frame's draws up to @p drawCallIndex. The engine replays
* them on a later frame, right after the pass that drew them, so frames have to
* keep rendering until {@link getSnapshotImageData} resolves.
*/
export function replayToDrawCall(module: CaptureEngine, drawCallIndex: number): void {
module.renderer_replayToDrawCall(drawCallIndex);
}
/** Whether the replayed pass made as many draws as the capture did; false means
* the scene changed since, and the snapshot shows the later frame. */
export function snapshotMatchesCapture(module: CaptureEngine): boolean {
return module.renderer_snapshotMatchesCapture();
}
/**
* Resolves with the replay snapshot's pixels once its readback lands (the async
* seam: immediate on GL, a later event-loop turn on WebGPU). Null when no
* snapshot is in flight or the readback failed.
*/
export async function getSnapshotImageData(module: CaptureEngine): Promise<ImageData | null> {
if (await awaitReadback(() => module.renderer_pollSnapshotReadback()) !== READBACK_READY) {
return null;
}
const size = module.renderer_getSnapshotSize();
if (size === 0) return null;
const w = module.renderer_getSnapshotWidth();
const h = module.renderer_getSnapshotHeight();
if (w === 0 || h === 0) return null;
const m = module;
const bytes = readOut(m, size,
m.renderer_getSnapshotPtr && (() => m.renderer_getSnapshotPtr!()),
m.renderer_copySnapshot && ((d, n) => m.renderer_copySnapshot!(d, n)));
if (!bytes) return null;
const pixels = new Uint8ClampedArray(bytes.buffer);
const flipped = new Uint8ClampedArray(size);
const rowBytes = w * 4;
for (let y = 0; y < h; y++) {
const srcOff = y * rowBytes;
const dstOff = (h - 1 - y) * rowBytes;
flipped.set(pixels.subarray(srcOff, srcOff + rowBytes), dstOff);
}
// A mini-game host has no ImageData; the fields every reader uses are the same.
return typeof ImageData === 'function'
? new ImageData(flipped, w, h)
: { width: w, height: h, data: flipped, colorSpace: 'srgb' } as ImageData;
}
/** A frame renders before this resolves: a live loop's next animation frame, or a driver's step. */
export type NextFrame = () => Promise<void>;
/**
* Captures the next whole frame, every pass of it. Null when @p maxFrames frames
* rendered and none of them drew anything.
*/
export async function captureFrame(
module: CaptureEngine, nextFrame: NextFrame, maxFrames = 8,
): Promise<FrameCaptureData | null> {
module.renderer_captureNextFrame();
for (let i = 0; i < maxFrames; i++) {
await nextFrame();
const data = decodeFrameCapture(module);
if (data) return data;
}
return null;
}
export interface ReplaySnapshot {
image: ImageData;
/** See {@link snapshotMatchesCapture}. */
matchesCapture: boolean;
}
/** The captured frame's pass, drawn up to and including draw @p drawCallIndex. */
export async function replayDraw(
module: CaptureEngine, drawCallIndex: number, nextFrame: NextFrame, maxFrames = 8,
): Promise<ReplaySnapshot | null> {
if (drawCallIndex < 0 || drawCallIndex >= module.renderer_getCapturedFrameSize()) return null;
module.renderer_replayToDrawCall(drawCallIndex);
for (let i = 0; i < maxFrames && module.renderer_pollSnapshotReadback() === 0; i++) {
await nextFrame();
}
const image = await getSnapshotImageData(module);
return image ? { image, matchesCapture: module.renderer_snapshotMatchesCapture() } : null;
}