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-pool-memory.test.ts
* @brief Component rows on a wasm heap, including the one that grows.
*
* @details Growing a wasm memory DETACHES every ArrayBuffer view of it. The
* bytes survive at the same offsets — it is the same linear memory —
* but a held view silently reads undefined instead of throwing, which
* is the worst way for storage to fail.
*
* So the heap here is a real `WebAssembly.Memory` and it is really
* grown, mid-life, with rows already in it.
*/
import { describe, it, expect } from 'vitest';
import { ScriptPool, poolShape, POOL_ABSENT } from '../src/ecs/ScriptPool';
import { WasmPoolMemory, type WasmHeap } from '../src/ecs/WasmPoolMemory';
import { entityIndex, type Entity } from '../src/types';
const e = (n: number): Entity => n as unknown as Entity;
const DEFAULTS = { speed: 100, directionX: 0, directionY: 0, enabled: true };
/**
* An emscripten module as far as a pool is concerned: a bump allocator over a
* real wasm memory, and a HEAPU8 that is replaced on growth exactly as
* emscripten's `updateMemoryViews` replaces it.
*/
class FakeModule implements WasmHeap {
readonly memory: WebAssembly.Memory;
HEAPU8: Uint8Array;
private next: number;
readonly freed: number[] = [];
/**
* `growAlways` models the allocator that is hard to be correct against: a
* real `_malloc` may grow on ANY call, and growth detaches every view. A
* bump allocator that only grows when it runs out never reaches the
* interesting ordering, which is how this file first passed a sabotage.
*/
constructor(pages = 1, private readonly growAlways = false) {
this.memory = new WebAssembly.Memory({ initial: pages });
this.HEAPU8 = new Uint8Array(this.memory.buffer);
this.next = 64; // nonzero, as a real heap's low addresses are taken
}
_malloc(size: number): number {
if (this.growAlways) this.grow();
const at = this.next;
this.next += (size + 15) & ~15;
while (this.next > this.HEAPU8.byteLength) this.grow();
return at;
}
_free(ptr: number): void {
this.freed.push(ptr);
}
/** What emscripten does: grow, then rebuild the views over the new buffer. */
grow(): void {
this.memory.grow(1);
this.HEAPU8 = new Uint8Array(this.memory.buffer);
}
}
describe('rows on the engine heap', () => {
it('held numeric and boolean fields remain live after foreign heap growth without refresh', () => {
const mod = new FakeModule(), pool = new ScriptPool(poolShape(DEFAULTS)!, 4, new WasmPoolMemory(mod));
const held = pool.put(e(1), DEFAULTS, {speed: 7, enabled: false}).view;
mod.grow();
expect(held['speed']).toBe(7);expect(held['enabled']).toBe(false);
mod.grow();held['speed'] = 42;held['enabled'] = true;
const heap = new Float64Array(mod.memory.buffer), address = pool.address(e(1))!;
expect(heap[address / 8]).toBe(42);expect(heap[address / 8 + 3]).toBe(1);
pool.dispose();
});
it('compiled addresses and sparse spans survive foreign growth before any component read', () => {
const mod = new FakeModule(), pool = new ScriptPool(poolShape(DEFAULTS)!, 4, new WasmPoolMemory(mod));
pool.put(e(1), DEFAULTS, {speed: 7});const address = pool.address(e(1)), span = pool.span();
mod.grow();
expect(pool.address(e(1))).toBe(address);expect(pool.span()).toEqual(span);
expect(pool.sparseTable[entityIndex(e(1))]).toBe(1);expect(pool.buffer[0]).toBe(7);
pool.dispose();
});
it('existing writes and new rows work after foreign growth without needing pool expansion', () => {
const mod = new FakeModule(), pool = new ScriptPool(poolShape(DEFAULTS)!, 4, new WasmPoolMemory(mod));
pool.put(e(1), DEFAULTS, {speed: 7});mod.grow();
pool.put(e(1), DEFAULTS, {speed: 42});pool.put(e(2), DEFAULTS, {speed: 9});
expect(pool.get(e(1))!['speed']).toBe(42);expect(pool.get(e(2))!['speed']).toBe(9);
expect(pool.sparseTable[entityIndex(e(2))]).toBe(2);pool.dispose();
});
it('one pool allocating on the same heap cannot detach another pool view', () => {
const mod = new FakeModule(1, true), memory = new WasmPoolMemory(mod);
const first = new ScriptPool(poolShape(DEFAULTS)!, 4, memory), held = first.put(e(1), DEFAULTS, {speed: 7}).view;
const second = new ScriptPool(poolShape(DEFAULTS)!, 4, memory);
expect(held['speed']).toBe(7);held['speed'] = 42;
expect(new Float64Array(mod.memory.buffer)[first.address(e(1))! / 8]).toBe(42);
first.dispose();second.dispose();
});
it('allocates at a wasm address, and an address is that address', () => {
const mod = new FakeModule();
const pool = new ScriptPool(poolShape(DEFAULTS)!, 4, new WasmPoolMemory(mod));
pool.put(e(1), DEFAULTS, { speed: 11 });
pool.put(e(2), DEFAULTS, { speed: 22 });
// What a compiled system is handed. Reading it out of the heap by that
// address is exactly what the compiled code does.
const heap = new Float64Array(mod.memory.buffer);
for (const [entity, want] of [[1, 11], [2, 22]] as const) {
expect(heap[pool.address(e(entity))! / 8], `entity ${entity}`).toBe(want);
}
expect(pool.address(e(1))).toBeGreaterThanOrEqual(64);
});
it('survives a growth that detaches every view of the heap', () => {
const mod = new FakeModule();
const pool = new ScriptPool(poolShape(DEFAULTS)!, 4, new WasmPoolMemory(mod));
for (let i = 1; i <= 4; i++) pool.put(e(i), DEFAULTS, { speed: i });
const held = pool.get(e(2))!;
const before = pool.address(e(2));
const wasBuffer = mod.memory.buffer;
mod.grow();
expect(mod.memory.buffer, 'the growth did not actually replace the buffer')
.not.toBe(wasBuffer);
// The pool is still holding views of a buffer that no longer exists.
pool.refresh();
expect(pool.address(e(2)), 'the bytes did not move, only the buffer did').toBe(before);
for (let i = 1; i <= 4; i++) {
expect(pool.get(e(i))!['speed'], `entity ${i} after growth`).toBe(i);
}
// The view handed out BEFORE the growth still writes to the right row,
// because it reads the pool's current storage rather than holding one.
held['speed'] = 42;
const heap = new Float64Array(mod.memory.buffer);
expect(heap[pool.address(e(2))! / 8]).toBe(42);
});
it('a growth caused BY the pool does not lose the rows it was copying', () => {
// The trap the ordering in growRows_ exists for: allocating the wider
// block grows the heap, detaching the old rows BEFORE they are copied
// out of. This allocator grows every call, so every doubling meets it.
const mod = new FakeModule(1, true);
const pool = new ScriptPool(poolShape(DEFAULTS)!, 2, new WasmPoolMemory(mod));
for (let i = 1; i <= 64; i++) pool.put(e(i), DEFAULTS, { speed: i * 2 });
expect(pool.size).toBe(64);
expect(mod.memory.buffer.byteLength, 'the heap never actually grew')
.toBeGreaterThan(65536);
const heap = new Float64Array(mod.memory.buffer);
for (let i = 1; i <= 64; i++) {
expect(pool.get(e(i))!['speed'], `entity ${i} value`).toBe(i * 2);
expect(heap[pool.address(e(i))! / 8], `entity ${i} in the heap`).toBe(i * 2);
}
expect(mod.freed.length, 'the old blocks were handed back').toBeGreaterThan(0);
});
it('the sparse table lives in the same heap, and resolves there', () => {
const mod = new FakeModule();
const pool = new ScriptPool(poolShape(DEFAULTS)!, 4, new WasmPoolMemory(mod));
for (let i = 1; i <= 5; i++) pool.put(e(i), DEFAULTS, { speed: i });
const { rows, stride, sparse, sparseCount } = pool.span();
const table = new Uint32Array(mod.memory.buffer, sparse, sparseCount);
const heap = new Float64Array(mod.memory.buffer);
// The two loads a compiled host does, straight out of wasm memory.
for (let i = 1; i <= 5; i++) {
const slot = table[entityIndex(e(i))]!;
expect(slot, `entity ${i}`).not.toBe(POOL_ABSENT);
expect(heap[(rows + (slot - 1) * stride) / 8], `entity ${i}`).toBe(i);
}
// Absent has two forms and a host must take both: a zero in the table,
// and an index past its end — the table is sized by the entity indices
// seen, not by the world's. `aot::fromRows` checks the bound first.
const absent = (id: Entity): boolean => {
const at = entityIndex(id);
return at >= sparseCount || table[at] === POOL_ABSENT;
};
expect(absent(e(6)), 'a live index the pool never saw').toBe(true);
expect(absent(e(100000)), 'an index past the table').toBe(true);
expect(absent(e(3))).toBe(false);
});
});