Skip to content

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.

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.ts
index 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.ts
index 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.ts
index 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)));
+ });
+});