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
feat(ecs): a pool's rows can live where compiled code can reach them
yhh9581c180083e
diff --git a/sdk/src/ecs/ScriptPool.ts b/sdk/src/ecs/ScriptPool.tsindex 93d99d266..cf8ab80d1 100644--- a/sdk/src/ecs/ScriptPool.ts+++ b/sdk/src/ecs/ScriptPool.ts@@ -34,6 +34,25 @@ export interface PoolField {/** One f64 per field: what the ABI gives a host record (REARCH_AOT_ABI §2.4). */export const POOL_SLOT_BYTES = 8;+/**+ * Where a pool's rows are allocated FROM. The default is a plain array, which+ * suits a native host: same process, real address. A wasm host must pass one+ * carved out of linear memory, because compiled code inside the module cannot+ * reach a JS-heap array — and unreachable is what rows exist to stop being.+ */+export interface PoolMemory {+ /** A view of `slots` doubles the pool may keep. */+ alloc(slots: number): Float64Array;+ /** A view the pool has finished with. */+ release(view: Float64Array): void;+}++/** Rows on the JS heap: right for native, useless to a wasm module. */+export const HEAP_MEMORY: PoolMemory = {+ alloc: (slots) => new Float64Array(slots),+ release: () => { /* the collector owns it */ },+};+/*** The fields a pool can back, or null when the defaults are not all scalars.* Anything else — a string, an asset ref, a nested object, an array — has no@@ -68,11 +87,15 @@ export class ScriptPool {private readonly free_: number[] = [];private next_ = 0;- constructor(fields: readonly PoolField[], capacity = 64) {+ constructor(+ fields: readonly PoolField[],+ capacity = 64,+ private readonly memory_: PoolMemory = HEAP_MEMORY,+ ) {this.fields = fields;this.stride = fields.length * POOL_SLOT_BYTES;this.capacity_ = Math.max(1, capacity);- this.slots_ = new Float64Array(this.capacity_ * fields.length);+ this.slots_ = memory_.alloc(this.capacity_ * fields.length);}/** The backing store. Its byteOffset moves when the pool grows, so an@@ -85,12 +108,23 @@ export class ScriptPool {return this.slotOf_.size;}- /** Byte offset of `entity`'s row inside `buffer`, for a host to hand over. */+ /** Byte offset of `entity`'s row inside `buffer`. */baseOf(entity: Entity): number | undefined {const slot = this.slotOf_.get(entity);return slot === undefined ? undefined : slot * this.stride;}+ /**+ * The address a host hands to compiled code: the row's offset in the memory+ * the pool allocated from, not in the pool's own view. The two differ by+ * `byteOffset` once the rows are carved out of a larger block. Valid until+ * the next growth, which §2.2 requires anyway.+ */+ address(entity: Entity): number | undefined {+ const base = this.baseOf(entity);+ return base === undefined ? undefined : this.slots_.byteOffset + base;+ }+has(entity: Entity): boolean {return this.slotOf_.has(entity);}@@ -145,9 +179,11 @@ export class ScriptPool {private grow_(): void {this.capacity_ *= 2;- const wider = new Float64Array(this.capacity_ * this.fields.length);+ const wider = this.memory_.alloc(this.capacity_ * this.fields.length);wider.set(this.slots_);+ const old = this.slots_;this.slots_ = wider;+ this.memory_.release(old);// Views hold a slot index, not a reference into the old array, so they// survive this. An ADDRESS taken before it does not, which is why// `baseOf` says so.diff --git a/sdk/src/ecs/ScriptStorage.ts b/sdk/src/ecs/ScriptStorage.tsindex 6e3ad22a3..8de05dcd1 100644--- a/sdk/src/ecs/ScriptStorage.ts+++ b/sdk/src/ecs/ScriptStorage.ts@@ -10,7 +10,7 @@ import { ComponentDef } from './component';import { validateComponentData, formatValidationErrors, assetFieldNames } from '../util/validation';import { log } from '../util/logger';import { reorderMapByRank, type RankOf } from './entityOrder';-import { ScriptPool, poolShape } from './ScriptPool';+import { ScriptPool, poolShape, HEAP_MEMORY, type PoolMemory } from './ScriptPool';export interface InsertResult<T> {value: T;@@ -27,6 +27,19 @@ export class ScriptStorage {* object has no address (docs/REARCH_AOT_ABI.md §2.4).*/private pools_ = new Map<symbol, ScriptPool>();+ private poolMemory_: PoolMemory = HEAP_MEMORY;++ /**+ * @internal Where pools allocate from. A wasm runtime installs one backed by+ * linear memory before any component is added, because compiled code cannot+ * reach a JS-heap array; a native one leaves the default.+ */+ usePoolMemory(memory: PoolMemory): void {+ if (this.pools_.size > 0) {+ throw new Error('ScriptPool memory must be chosen before the first pooled component');+ }+ this.poolMemory_ = memory;+ }/** @internal The rows behind `component`, or undefined if it has none. */poolFor(id: symbol): ScriptPool | undefined {@@ -44,7 +57,7 @@ export class ScriptStorage {if (this.notPooled_.has(component._id)) return null;const fields = poolShape(component._default);if (!fields) { this.notPooled_.add(component._id); return null; }- const pool = new ScriptPool(fields);+ const pool = new ScriptPool(fields, 64, this.poolMemory_);this.pools_.set(component._id, pool);return pool;}diff --git a/sdk/tests/script-pool.test.ts b/sdk/tests/script-pool.test.tsindex dd297e841..c25da5bf1 100644--- a/sdk/tests/script-pool.test.ts+++ b/sdk/tests/script-pool.test.ts@@ -11,7 +11,7 @@* component still reads and writes as an object.*/import { describe, it, expect } from 'vitest';-import { ScriptPool, poolShape, POOL_SLOT_BYTES } from '../src/ecs/ScriptPool';+import { ScriptPool, poolShape, POOL_SLOT_BYTES, HEAP_MEMORY, type PoolMemory } from '../src/ecs/ScriptPool';import type { Entity } from '../src/types';const e = (n: number): Entity => n as unknown as Entity;@@ -128,3 +128,67 @@ describe('a row, and the view onto it', () => {expect(pool.baseOf(e(3))! - pool.baseOf(e(2))!).toBe(pool.stride);});});++/**+ * A wasm host cannot let a pool allocate on the JS heap: compiled code inside+ * the module has no way to reach it. So the rows come out of one block the host+ * owns, and an address is an offset into THAT.+ */+describe('rows carved out of a host-owned block', () => {+ /** Stands in for the wasm heap: one buffer, a bump pointer, nothing freed. */+ function heapOf(bytes: number): { memory: PoolMemory; all: Float64Array; used: () => number } {+ const all = new Float64Array(bytes / POOL_SLOT_BYTES);+ let at = 8; // a nonzero start, so an address that forgot byteOffset is wrong+ return {+ all,+ used: () => at,+ memory: {+ alloc(slots) {+ const view = new Float64Array(all.buffer, at * POOL_SLOT_BYTES, slots);+ at += slots;+ return view;+ },+ release: () => { /* a bump allocator frees nothing */ },+ },+ };+ }++ it('an address is an offset into the block, not into the pool', () => {+ const heap = heapOf(1 << 16);+ const pool = new ScriptPool(poolShape(DEFAULTS)!, 8, heap.memory);+ pool.put(e(1), DEFAULTS, { speed: 11 });+ pool.put(e(2), DEFAULTS, { speed: 22 });++ // baseOf is where the row is inside the pool; address is where it is in+ // the memory a host would hand to compiled code.+ expect(pool.baseOf(e(2))).toBe(pool.stride);+ expect(pool.address(e(2))).toBe(pool.buffer.byteOffset + pool.stride);+ expect(pool.address(e(2))).toBeGreaterThan(pool.baseOf(e(2))!);++ // Read the field back through the BLOCK at that address, which is what+ // the compiled code does.+ for (const [entity, want] of [[1, 11], [2, 22]] as const) {+ const at = pool.address(e(entity))! / POOL_SLOT_BYTES;+ expect(heap.all[at], `entity ${entity} speed`).toBe(want);+ }+ });++ it('growing moves the rows, and the addresses move with them', () => {+ const heap = heapOf(1 << 16);+ const pool = new ScriptPool(poolShape(DEFAULTS)!, 2, heap.memory);+ for (let i = 1; i <= 12; i++) pool.put(e(i), DEFAULTS, { speed: i });+ expect(heap.used()).toBeGreaterThan(8);++ for (let i = 1; i <= 12; i++) {+ const at = pool.address(e(i))! / POOL_SLOT_BYTES;+ expect(heap.all[at], `entity ${i} after growth`).toBe(i);+ }+ });++ it('the default keeps the rows on the JS heap, where native wants them', () => {+ const pool = new ScriptPool(poolShape(DEFAULTS)!, 4, HEAP_MEMORY);+ pool.put(e(1), DEFAULTS);+ expect(pool.buffer.byteOffset).toBe(0);+ expect(pool.address(e(1))).toBe(pool.baseOf(e(1)));+ });+});