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
docs(render): lock in frameCapture memory-safety contract
esengine47bd8c979554
diff --git a/sdk/src/frameCapture.ts b/sdk/src/frameCapture.tsindex 9f8453ce1..fd489eb61 100644--- a/sdk/src/frameCapture.ts+++ b/sdk/src/frameCapture.ts@@ -1,5 +1,28 @@import type { ESEngineModule } from './wasm';+/**+ * 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.+ */+export enum FlushReason {BatchFull = 0,TextureSlotsFull = 1,diff --git a/sdk/tests/frame-capture.test.ts b/sdk/tests/frame-capture.test.tsnew file mode 100644index 000000000..4a7ee35a1--- /dev/null+++ b/sdk/tests/frame-capture.test.ts@@ -0,0 +1,148 @@+/**+ * @file frame-capture.test.ts+ * @brief Pin down the memory-safety contract of frameCapture.ts: the+ * returned data must be a JS-owned copy that survives subsequent+ * mutation or reuse of the WASM-backed source buffer.+ */+import { describe, expect, it } from 'vitest';+import { decodeFrameCapture, getSnapshotImageData, RenderType, FlushReason } from '../src/frameCapture';+import type { ESEngineModule } from '../src/wasm';++// Minimal ImageData shim for headless test runs. Mirrors the parts of the+// DOM API that getSnapshotImageData uses.+if (typeof (globalThis as { ImageData?: unknown }).ImageData === 'undefined') {+ class ImageDataShim {+ readonly data: Uint8ClampedArray;+ readonly width: number;+ readonly height: number;+ constructor(data: Uint8ClampedArray, width: number, height: number) {+ this.data = data;+ this.width = width;+ this.height = height;+ }+ }+ (globalThis as { ImageData: unknown }).ImageData = ImageDataShim;+}++/** Build a fake ESEngineModule exposing just the capture surface. */+function buildModule(opts: {+ width: number;+ height: number;+ drawCallCount?: number;+ entities?: number[];+}): { module: ESEngineModule; heap: Uint8Array; dataPtr: number; entitiesPtr: number; snapshotPtr: number } {+ const { width, height, drawCallCount = 0, entities = [] } = opts;+ const RECORD_SIZE = 76;+ const snapshotSize = width * height * 4;+ const entitiesSize = entities.length * 4;+ const drawCallsSize = drawCallCount * RECORD_SIZE;++ // Layout: [snapshot | entities | drawCalls]+ const totalSize = snapshotSize + entitiesSize + drawCallsSize + 16;+ const buffer = new ArrayBuffer(totalSize);+ const heap = new Uint8Array(buffer);++ const snapshotPtr = 0;+ const entitiesPtr = snapshotSize;+ const dataPtr = snapshotSize + entitiesSize;++ // Fill snapshot with a recognizable pattern: each pixel is (i % 256).+ for (let i = 0; i < snapshotSize; i++) {+ heap[snapshotPtr + i] = i & 0xFF;+ }++ // Fill entities+ const u32 = new Uint32Array(buffer);+ for (let i = 0; i < entities.length; i++) {+ u32[(entitiesPtr >> 2) + i] = entities[i];+ }++ // Fill draw-call records with placeholder values (all zeroes is fine;+ // the decode function just reads the structure).+ const module: ESEngineModule = {+ HEAPU8: heap,+ renderer_hasCapturedData: () => drawCallCount > 0,+ renderer_getCapturedFrameSize: () => drawCallCount,+ renderer_getCapturedFrameData: () => dataPtr,+ renderer_getCapturedEntities: () => entitiesPtr,+ renderer_getCapturedEntityCount: () => entities.length,+ renderer_getCapturedCameraCount: () => 1,+ renderer_getSnapshotSize: () => snapshotSize,+ renderer_getSnapshotWidth: () => width,+ renderer_getSnapshotHeight: () => height,+ renderer_getSnapshotPtr: () => snapshotPtr,+ } as unknown as ESEngineModule;++ return { module, heap, dataPtr, entitiesPtr, snapshotPtr };+}++describe('getSnapshotImageData', () => {+ it('returns a JS-owned buffer independent from the WASM heap', () => {+ const { module, heap, snapshotPtr } = buildModule({ width: 4, height: 2 });+ const img = getSnapshotImageData(module);+ expect(img).not.toBeNull();++ const snapshotBefore = Array.from(img!.data);++ // Aggressively scramble the heap region the snapshot came from. If+ // the returned data still aliased HEAPU8 we'd see the new bytes.+ for (let i = snapshotPtr; i < snapshotPtr + snapshotBefore.length; i++) heap[i] = 0xAB;++ const snapshotAfter = Array.from(img!.data);+ expect(snapshotAfter).toEqual(snapshotBefore);+ });++ it('returns null when the renderer has no snapshot available', () => {+ const zero = buildModule({ width: 0, height: 0 });+ expect(getSnapshotImageData(zero.module)).toBeNull();+ });++ it('applies vertical flip so row 0 of output is the last source row', () => {+ const w = 2, h = 3;+ const { module } = buildModule({ width: w, height: h });+ const img = getSnapshotImageData(module)!;+ expect(img.width).toBe(w);+ expect(img.height).toBe(h);++ // Source pattern: byte at (y*rowBytes + x) = (y*rowBytes + x) & 0xFF.+ // Flipped output: dst row 0 = src row (h-1). First byte of dst row 0+ // should equal (h-1)*w*4 & 0xFF.+ const rowBytes = w * 4;+ expect(img.data[0]).toBe(((h - 1) * rowBytes) & 0xFF);+ });+});++describe('decodeFrameCapture', () => {+ it('returns null when no data has been captured', () => {+ const { module } = buildModule({ width: 1, height: 1 });+ expect(decodeFrameCapture(module)).toBeNull();+ });++ it('copies entity indices as numbers, not as views over WASM memory', () => {+ const { module, heap, entitiesPtr, dataPtr } = buildModule({+ width: 1, height: 1, drawCallCount: 1, entities: [101, 202, 303],+ });++ // Populate draw-call record to reference the entity range.+ const u32 = new Uint32Array(heap.buffer);+ u32[(dataPtr >> 2) + 8] = 3; // entityCount at offset 32+ u32[(dataPtr >> 2) + 9] = 0; // entityOffset at offset 36++ const capture = decodeFrameCapture(module)!;+ expect(capture.drawCalls).toHaveLength(1);+ expect(capture.drawCalls[0].entities).toEqual([101, 202, 303]);++ // Scramble the entity region in WASM memory.+ u32[entitiesPtr >> 2] = 999;+ u32[(entitiesPtr >> 2) + 1] = 999;+ u32[(entitiesPtr >> 2) + 2] = 999;++ // Captured entities remain unchanged (primitive numbers were copied).+ expect(capture.drawCalls[0].entities).toEqual([101, 202, 303]);+ });++ it('surfaces enum values with the typed names (smoke)', () => {+ expect(RenderType.Sprite).toBe(0);+ expect(FlushReason.BatchFull).toBe(0);+ });+});