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 WasmPoolMemory.ts
* @brief Component rows on the engine's wasm heap, where compiled code is.
*
* @details A compiled system runs inside the engine's module and reads memory by
* offset. Rows on the JS heap are as unreachable to it as the objects
* they replaced, so on web they come from `_malloc` instead — one
* linear memory, one set of offsets, and `ScriptPool.address` is
* already the address the compiled code wants.
*
* The trap is growth: `_malloc` may grow the heap, and growing DETACHES
* every ArrayBuffer view of it. The bytes survive at the same offsets —
* it is the same linear memory — but a held `Float64Array` stops
* working, silently returning undefined rather than throwing. So a
* block is identified by its OFFSET and the buffer is fetched fresh,
* which is the same thing emscripten does for its own HEAP views.
*/
import type { PoolBlock, PoolMemory } from './ScriptPool';
/** What this needs of the engine module: an allocator and its heap. */
export interface WasmHeap {
readonly allocatorIdentity?: object;
_malloc(size: number): number;
_free(ptr: number): void;
/** The live view. Emscripten replaces this object when the heap grows. */
readonly HEAPU8: Uint8Array;
}
/**
* Rows on the engine's heap. `byteOffset` is a wasm address, which is what makes
* a pool's `span()` directly usable by compiled code.
*/
export class WasmPoolMemory implements PoolMemory {
readonly allocatorIdentity: object;
constructor(private readonly heap: WasmHeap) {
this.allocatorIdentity = heap.allocatorIdentity ?? heap;
}
alloc(bytes: number): PoolBlock {
// Eight-aligned because a row's fields are f64 and an unaligned typed
// array view is a range error rather than a slow read.
const size = (bytes + 7) & ~7;
const at = this.heap._malloc(size);
if (at === 0) throw new Error(`ScriptPool: the wasm heap refused ${size} bytes`);
return { buffer: this.heap.HEAPU8.buffer, byteOffset: at, byteLength: size };
}
release(block: PoolBlock): void {
this.heap._free(block.byteOffset);
}
/**
* The block's buffer as it is NOW. After a growth the one handed out at
* `alloc` is detached and this is a different object holding the same bytes
* at the same offset.
*/
current(block: PoolBlock): ArrayBufferLike {
void block;
return this.heap.HEAPU8.buffer;
}
}