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(compiler): the ABI, and the test that asks whether it is sufficient

yhh13726d14d48d
diff --git a/compiler/src/abi.ts b/compiler/src/abi.ts
new file mode 100644
index 000000000..3b79c91ec
--- /dev/null
+++ b/compiler/src/abi.ts
@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file abi.ts
+ * @brief The Estella ABI, as an EirHost (docs/REARCH_AOT_ABI.md).
+ *
+ * @details Runs a system with nothing but what SysCtx provides: a packed row
+ * array, resource pointers, a command buffer, and shared linear memory
+ * at EHT offsets. It calls the engine ZERO times, because the contract
+ * has no calls to make.
+ *
+ * Its job is not speed — it is proof. Running the SAME interpreter over
+ * this host and over the JS-object one, and requiring both to match
+ * node, is what shows the contract is SUFFICIENT. A system that cannot
+ * run here names something SysCtx is missing, and that is the only
+ * legitimate reason to add a field to it.
+ *
+ * Field offsets come from PTR_LAYOUTS via builtins.ts — the same EHT
+ * table the engine and the SDK's accessors already agree on.
+ */
+import type { CompShape, EirType, QueryArg } from './eir';
+import type { EirHost } from './interp';
+
+/** One command record: 16 bytes, four u32 (docs/REARCH_AOT_ABI.md §2.3). */
+export const CMD_WORDS = 4;
+export const CMD_DESPAWN = 1;
+export const CMD_REMOVE = 2;
+
+/**
+ * Where a field lives, and HOW WIDE it is. Component bytes are f32 because EHT
+ * says the C++ structs are; a resource is a host-side record and `Time.delta` is
+ * an f64 — packing it as f32 makes one side multiply by a rounded 1/30 and the
+ * two drift apart. Width is part of the contract, not an implementation detail.
+ */
+export interface Leaf {
+ readonly byteOffset: number;
+ readonly bits: 32 | 64;
+ readonly type: EirType;
+}
+
+export interface FieldOffsets {
+ /** `position.x` -> its leaf. */
+ readonly leaves: ReadonlyMap<string, Leaf>;
+ /** Bytes per row. */
+ readonly stride: number;
+}
+
+export interface AbiLayout {
+ readonly comps: ReadonlyMap<string, FieldOffsets>;
+ readonly resources: ReadonlyMap<string, FieldOffsets>;
+}
+
+/**
+ * A flat image of a world, laid out the way the host would lay it out. Test
+ * scaffolding: the real host is C++, and this stands in for it so the contract
+ * can be exercised before the engine implements it.
+ */
+export class AbiMemory {
+ readonly buffer: ArrayBuffer;
+ readonly f32: Float32Array;
+ readonly f64: Float64Array;
+ readonly u32: Uint32Array;
+ private next = 64;
+ private readonly compBase = new Map<string, Map<number, number>>();
+ private readonly resBase = new Map<string, number>();
+ /** Entities in world order, as the host would materialise them. */
+ readonly entities: number[] = [];
+ readonly cmdBuf: number;
+ readonly cmdCap = 256;
+ cmdCount = 0;
+
+ constructor(private readonly layout: AbiLayout, bytes = 1 << 20) {
+ this.buffer = new ArrayBuffer(bytes);
+ this.f32 = new Float32Array(this.buffer);
+ this.f64 = new Float64Array(this.buffer);
+ this.u32 = new Uint32Array(this.buffer);
+ this.cmdBuf = this.alloc(this.cmdCap * CMD_WORDS * 4);
+ }
+
+ private alloc(size: number): number {
+ const at = this.next;
+ this.next += (size + 15) & ~15;
+ if (this.next > this.buffer.byteLength) throw new Error('ABI image out of memory');
+ return at;
+ }
+
+ /** Give `entity` a row of `comp`, returning its base address. */
+ addComponent(comp: string, entity: number, fields: Record<string, number | boolean>): number {
+ const shape = this.layout.comps.get(comp);
+ if (!shape) throw new Error(`ABI: no layout for component '${comp}'`);
+ if (!this.entities.includes(entity)) this.entities.push(entity);
+ const base = this.alloc(shape.stride);
+ let rows = this.compBase.get(comp);
+ if (!rows) { rows = new Map(); this.compBase.set(comp, rows); }
+ rows.set(entity, base);
+ for (const [path, v] of Object.entries(fields)) this.writeLeaf(shape, base, path, v);
+ return base;
+ }
+
+ addResource(name: string, fields: Record<string, number | boolean>): number {
+ const shape = this.layout.resources.get(name);
+ if (!shape) throw new Error(`ABI: no layout for resource '${name}'`);
+ const base = this.alloc(shape.stride);
+ this.resBase.set(name, base);
+ for (const [path, v] of Object.entries(fields)) this.writeLeaf(shape, base, path, v);
+ return base;
+ }
+
+ private writeLeaf(shape: FieldOffsets, base: number, path: string, v: number | boolean): void {
+ const leaf = shape.leaves.get(path);
+ if (!leaf) throw new Error(`ABI: no field '${path}'`);
+ store(this, base + leaf.byteOffset, leaf.bits, v);
+ }
+
+ baseOf(comp: string, entity: number): number | undefined {
+ return this.compBase.get(comp)?.get(entity);
+ }
+
+ resourceBase(name: string): number {
+ const at = this.resBase.get(name);
+ if (at === undefined) throw new Error(`ABI: no resource '${name}'`);
+ return at;
+ }
+
+ /** Read a leaf back, for a test to check what the run produced. */
+ read(comp: string, entity: number, path: string): number {
+ const shape = this.layout.comps.get(comp)!;
+ const leaf = shape.leaves.get(path)!;
+ return load(this, this.baseOf(comp, entity)! + leaf.byteOffset, leaf.bits);
+ }
+
+ /** Drop an entity, as the host's flush would. */
+ despawn(entity: number): void {
+ const at = this.entities.indexOf(entity);
+ if (at >= 0) this.entities.splice(at, 1);
+ for (const rows of this.compBase.values()) rows.delete(entity);
+ }
+}
+
+/** One load / one store, chosen by the width the contract declares. */
+function load(mem: AbiMemory, at: number, bits: 32 | 64): number {
+ return bits === 64 ? mem.f64[at >> 3]! : mem.f32[at >> 2]!;
+}
+function store(mem: AbiMemory, at: number, bits: 32 | 64, v: number | boolean): void {
+ const n = typeof v === 'boolean' ? (v ? 1 : 0) : v;
+ if (bits === 64) mem.f64[at >> 3] = n; else mem.f32[at >> 2] = n;
+}
+
+/**
+ * The host a compiled system would see. `rows` is the packed array SysCtx
+ * carries; every field access below is a load or store at a declared offset,
+ * and nothing here calls the engine.
+ */
+export function abiHost(mem: AbiMemory, layout: AbiLayout): EirHost {
+ const leafAt = (owner: string, path: readonly string[]): Leaf => {
+ const shape = layout.comps.get(owner) ?? layout.resources.get(owner);
+ const leaf = shape?.leaves.get(path.join('.'));
+ if (!leaf) throw new Error(`ABI: '${owner}' has no field '${path.join('.')}'`);
+ return leaf;
+ };
+ return {
+ *rows(args: readonly QueryArg[]) {
+ // What the host materialises: [entity, base0, base1, …] per row.
+ for (const e of mem.entities) {
+ const binds = args.map((a) => mem.baseOf(a.comp, e));
+ if (binds.some((b) => b === undefined)) continue;
+ yield { entity: e, binds: binds as number[] };
+ }
+ },
+ readField(base, owner, path) {
+ const leaf = leafAt(owner, path);
+ return load(mem, (base as number) + leaf.byteOffset, leaf.bits);
+ },
+ writeField(base, owner, path, v) {
+ const leaf = leafAt(owner, path);
+ store(mem, (base as number) + leaf.byteOffset, leaf.bits, v);
+ },
+ resource(name) {
+ return mem.resourceBase(name);
+ },
+ emit(record, args) {
+ if (mem.cmdCount >= mem.cmdCap) throw new Error('ABI: command buffer overflow');
+ const at = (mem.cmdBuf >> 2) + mem.cmdCount * CMD_WORDS;
+ mem.u32[at] = record === 'despawn' ? CMD_DESPAWN : CMD_REMOVE;
+ mem.u32[at + 1] = args[0] as number;
+ mem.cmdCount++;
+ },
+ flush() {
+ const at = mem.cmdBuf >> 2;
+ for (let i = 0; i < mem.cmdCount; i++) {
+ const kind = mem.u32[at + i * CMD_WORDS]!;
+ if (kind === CMD_DESPAWN) mem.despawn(mem.u32[at + i * CMD_WORDS + 1]!);
+ }
+ mem.cmdCount = 0;
+ },
+ };
+}
+
+/**
+ * Byte offsets for every shape: leaves in declaration order, at the width the
+ * SHAPE declares. Nothing here asks what a name means — `engine` shapes are the
+ * C++ pools and `host` shapes are JS-side records, and both say so themselves.
+ */
+export function packLayout(shapes: ReadonlyMap<string, CompShape>): AbiLayout {
+ const comps = new Map<string, FieldOffsets>();
+ const resources = new Map<string, FieldOffsets>();
+ for (const [name, shape] of shapes) {
+ const leaves = new Map<string, Leaf>();
+ let at = 0;
+ for (const [path, spec] of shape.fields) {
+ const width = spec.bits >> 3;
+ at = (at + width - 1) & ~(width - 1);
+ leaves.set(path, { byteOffset: at, bits: spec.bits, type: spec.type });
+ at += width;
+ }
+ const packed: FieldOffsets = { leaves, stride: Math.max(8, at) };
+ // A resource is addressed by field exactly as a component is, so the two
+ // tables differ only in which one a `Res(...)` parameter looks in.
+ (shape.storage === 'host' && RESOURCES.has(name) ? resources : comps).set(name, packed);
+ }
+ return { comps, resources };
+}
+
+/**
+ * Which host-stored shapes are RESOURCES rather than components. This is the one
+ * thing the shape cannot yet say, because resources have no generator — see the
+ * note in builtins.ts. It goes away when they get one.
+ */
+const RESOURCES = new Set(['Time', 'Input']);
diff --git a/compiler/src/builtins.ts b/compiler/src/builtins.ts
index ad5ef6210..68821b6e0 100644
--- a/compiler/src/builtins.ts
+++ b/compiler/src/builtins.ts
@@ -14,7 +14,7 @@
* file exists to avoid.
*/
import { PTR_LAYOUTS } from '../../sdk/src/wasm/ptrLayouts.generated';
-import { BOOL, F64, type CompShape, type EirType } from './eir';
+import { BOOL, F64, storageBits, type CompShape, type EirType, type FieldSpec, type Storage } from './eir';
/** Leaf member names per composite field, in memory order. */
const MEMBERS: Record<string, readonly string[]> = {
@@ -25,8 +25,8 @@ const MEMBERS: Record<string, readonly string[]> = {
color: ['r', 'g', 'b', 'a'],
};
-function leafType(t: string): EirType {
- return t === 'bool' ? BOOL : F64;
+function leafSpec(t: string, storage: Storage): FieldSpec {
+ return { type: t === 'bool' ? BOOL : F64, bits: storageBits(storage) };
}
/**
@@ -37,18 +37,20 @@ function leafType(t: string): EirType {
export function builtinShapes(): Map<string, CompShape> {
const out = new Map<string, CompShape>();
for (const [name, layout] of Object.entries(PTR_LAYOUTS)) {
- const fields = new Map<string, EirType>();
+ const fields = new Map<string, FieldSpec>();
for (const f of layout.fields) {
const members = MEMBERS[f.type];
if (members) {
- for (const m of members) fields.set(`${f.name}.${m}`, F64);
+ for (const m of members) fields.set(`${f.name}.${m}`, leafSpec('f32', 'engine'));
} else if (f.type === 'struct') {
- for (const m of f.members ?? []) fields.set(`${f.name}.${m.name}`, leafType(m.type));
+ for (const m of f.members ?? []) fields.set(`${f.name}.${m.name}`, leafSpec(m.type, 'engine'));
} else {
- fields.set(f.name, leafType(f.type));
+ fields.set(f.name, leafSpec(f.type, 'engine'));
}
}
- out.set(name, { name, fields });
+ // EHT's table IS the engine's flat pools, so everything from it is
+ // engine-stored. Nothing downstream has to ask by name.
+ out.set(name, { name, storage: 'engine', fields });
}
out.set('Time', TIME);
return out;
@@ -59,9 +61,8 @@ export function builtinShapes(): Map<string, CompShape> {
// compiler reads any resource beyond this one.
const TIME: CompShape = {
name: 'Time',
- fields: new Map<string, EirType>([
- ['delta', F64], ['elapsed', F64], ['frameCount', F64],
- ['fixedDelta', F64], ['fixedAlpha', F64], ['fixedTick', F64],
- ['scale', F64], ['unscaledDelta', F64],
- ]),
+ storage: 'host',
+ fields: new Map<string, FieldSpec>(
+ ['delta', 'elapsed', 'frameCount', 'fixedDelta', 'fixedAlpha', 'fixedTick', 'scale', 'unscaledDelta']
+ .map((k) => [k, { type: F64, bits: 64 }] as const)),
};
diff --git a/compiler/src/eir.ts b/compiler/src/eir.ts
index d1162f023..3cd920cd4 100644
--- a/compiler/src/eir.ts
+++ b/compiler/src/eir.ts
@@ -148,11 +148,31 @@ export interface EirSystem {
readonly body: readonly Stmt[];
}
+/**
+ * Where a shape's bytes live: `engine` is a C++ flat pool at EHT offsets with
+ * 32-bit fields, `host` a JS-side record (ScriptStorage, resources) with 64.
+ * Carried on the SHAPE so no consumer has to ask by name, which is how a table
+ * grows one entry per surprise.
+ */
+export type Storage = 'engine' | 'host';
+
+/** One leaf field: what it computes as, and how wide it is stored. */
+export interface FieldSpec {
+ readonly type: EirType;
+ readonly bits: 32 | 64;
+}
+
/** A component's field shape, flattened to leaf paths of one scalar each. */
export interface CompShape {
readonly name: string;
- /** `position.x` -> f64. Order is the declaration order EHT would give. */
- readonly fields: ReadonlyMap<string, EirType>;
+ readonly storage: Storage;
+ /** `position.x` -> its spec. Order is the declaration order EHT would give. */
+ readonly fields: ReadonlyMap<string, FieldSpec>;
+}
+
+/** Bits every field of a shape in this storage is stored at. */
+export function storageBits(storage: Storage): 32 | 64 {
+ return storage === 'engine' ? 32 : 64;
}
export interface EirModule {
diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.ts
index f02515880..033bffd96 100644
--- a/compiler/src/frontend.ts
+++ b/compiler/src/frontend.ts
@@ -30,7 +30,7 @@ import {
BOOL, ENTITY, F64,
type CompShape, type EirModule, type EirSystem, type EirType,
MATH_FNS,
- type EirFn, type Expr, type Local, type Place, type QueryArg, type Stmt, type BinOp, type LogicOp,
+ type FieldSpec, type EirFn, type Expr, type Local, type Place, type QueryArg, type Stmt, type BinOp, type LogicOp,
type MathFn,
} from './eir';
@@ -448,15 +448,15 @@ class SystemLowerer {
if (base.type.k === 'comp') {
const shape = this.comps.get(base.type.name);
if (!shape) throw new NotInSubset(node, `no declared shape for component '${base.type.name}'`);
- const t = shape.fields.get(key);
- if (!t) throw new NotInSubset(node, `'${base.type.name}' has no field '${key}'`);
- return t;
+ const f = shape.fields.get(key);
+ if (!f) throw new NotInSubset(node, `'${base.type.name}' has no field '${key}'`);
+ return f.type;
}
if (base.type.k === 'res') {
const shape = this.comps.get(base.type.name);
- const t = shape?.fields.get(key);
- if (!t) throw new NotInSubset(node, `resource '${base.type.name}' has no field '${key}'`);
- return t;
+ const f = shape?.fields.get(key);
+ if (!f) throw new NotInSubset(node, `resource '${base.type.name}' has no field '${key}'`);
+ return f.type;
}
throw new NotInSubset(node, `'${base.name}' has no fields to read`);
}
@@ -580,7 +580,7 @@ function componentShape(call: ts.CallExpression): CompShape | null {
const [nameArg, defaults] = call.arguments;
if (!nameArg || !ts.isStringLiteral(nameArg)) return null;
if (!defaults || !ts.isObjectLiteralExpression(defaults)) return null;
- const fields = new Map<string, EirType>();
+ const fields = new Map<string, FieldSpec>();
for (const prop of defaults.properties) {
if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) return null;
// `-50` parses as a prefix expression, not a numeric literal. A default
@@ -590,19 +590,22 @@ function componentShape(call: ts.CallExpression): CompShape | null {
&& prop.initializer.operator === ts.SyntaxKind.MinusToken
? prop.initializer.operand
: prop.initializer;
- if (ts.isNumericLiteral(init)) fields.set(prop.name.text, F64);
+ if (ts.isNumericLiteral(init)) fields.set(prop.name.text, { type: F64, bits: 64 });
else if (init.kind === ts.SyntaxKind.TrueKeyword || init.kind === ts.SyntaxKind.FalseKeyword) {
- fields.set(prop.name.text, BOOL);
+ fields.set(prop.name.text, { type: BOOL, bits: 64 });
} else return null;
}
- return { name: nameArg.text, fields };
+ // defineComponent lands in ScriptStorage — a Map of JS objects — so its
+ // numbers are f64, unlike an engine component's f32 pool.
+ return { name: nameArg.text, storage: 'host', fields };
}
/** Two declarations of one name are the same component only if every field matches. */
function sameShape(a: CompShape, b: CompShape): boolean {
if (a.fields.size !== b.fields.size) return false;
- for (const [k, t] of a.fields) {
- if (b.fields.get(k)?.k !== t.k) return false;
+ for (const [k, f] of a.fields) {
+ const other = b.fields.get(k);
+ if (other?.type.k !== f.type.k || other.bits !== f.bits) return false;
}
return true;
}
diff --git a/compiler/src/interp.ts b/compiler/src/interp.ts
index e761256ee..8ed31fd03 100644
--- a/compiler/src/interp.ts
+++ b/compiler/src/interp.ts
@@ -21,6 +21,24 @@ export type Fns = ReadonlyMap<string, EirFn>;
/** One component instance, nested exactly as a system reads it. */
export type Row = Record<string, unknown>;
+/**
+ * How a system reaches the world. Two implementations: the JS-object host below,
+ * and the ABI host (abi.ts) that reads flat memory through a SysCtx. One
+ * interpreter over both is what proves the ABI is sufficient — a second
+ * evaluator would only prove the two evaluators agree.
+ */
+export interface EirHost {
+ /** Rows the query matches, each binding one opaque base per component. */
+ rows(args: readonly QueryArg[]): Iterable<{ entity: number; binds: readonly unknown[] }>;
+ readField(base: unknown, comp: string, path: readonly string[]): number | boolean;
+ writeField(base: unknown, comp: string, path: readonly string[], v: number | boolean): void;
+ /** An opaque base for a resource, addressed by field like a component. */
+ resource(name: string): unknown;
+ emit(record: string, args: readonly (number | boolean)[]): void;
+ /** Called once after the body, where the SDK's runner flushes. */
+ flush(): void;
+}
+
export interface EirWorld {
/** Entity ids in the order a query walks them. Mutable: a flush removes from it. */
entities: number[];
@@ -56,33 +74,34 @@ function walk(root: unknown, path: readonly string[]): { owner: Record<string, u
return { owner: cur, key: path[path.length - 1]! };
}
-function readPlace(p: Place, frame: Frame): unknown {
+/** The component or resource a local holds, for the host to resolve fields on. */
+type Owners = ReadonlyMap<number, string>;
+
+function readPlace(p: Place, frame: Frame, host: EirHost, owners: Owners): unknown {
if (p.p === 'local') return frame.get(p.id);
- const base = readPlace(p.base, frame);
- const { owner, key } = walk(base, p.path);
- return owner[key];
+ const base = readPlace(p.base, frame, host, owners);
+ const id = p.base.p === 'local' ? p.base.id : -1;
+ return host.readField(base, owners.get(id) ?? '', p.path);
}
-function writePlace(p: Place, frame: Frame, value: unknown): void {
+function writePlace(p: Place, frame: Frame, host: EirHost, owners: Owners, value: unknown): void {
if (p.p === 'local') { frame.set(p.id, value); return; }
- const base = readPlace(p.base, frame);
- const { owner, key } = walk(base, p.path);
- owner[key] = value;
+ const base = readPlace(p.base, frame, host, owners);
+ const id = p.base.p === 'local' ? p.base.id : -1;
+ host.writeField(base, owners.get(id) ?? '', p.path, value as number | boolean);
}
/** A pure function cannot see the world, so calling one needs only its own frame. */
-const EMPTY_WORLD: EirWorld = { entities: [], comps: new Map(), resources: new Map() };
-
-function evalExpr(e: Expr, frame: Frame, fns: Fns): number | boolean {
+function evalExpr(e: Expr, frame: Frame, fns: Fns, host: EirHost, owners: Owners): number | boolean {
switch (e.e) {
case 'const': return e.value;
- case 'read': return readPlace(e.place, frame) as number | boolean;
- case 'neg': return -(evalExpr(e.v, frame, fns) as number);
- case 'not': return !(evalExpr(e.v, frame, fns) as boolean);
+ case 'read': return readPlace(e.place, frame, host, owners) as number | boolean;
+ case 'neg': return -(evalExpr(e.v, frame, fns, host, owners) as number);
+ case 'not': return !(evalExpr(e.v, frame, fns, host, owners) as boolean);
case 'select':
- return evalExpr(e.cond, frame, fns) ? evalExpr(e.then, frame, fns) : evalExpr(e.otherwise, frame, fns);
+ return evalExpr(e.cond, frame, fns, host, owners) ? evalExpr(e.then, frame, fns, host, owners) : evalExpr(e.otherwise, frame, fns, host, owners);
case 'call': {
- const a = e.args.map((x) => evalExpr(x, frame, fns));
+ const a = e.args.map((x) => evalExpr(x, frame, fns, host, owners));
if (e.target.k === 'math') {
// The frontend admits only the exactly-specified operations, so
// deferring to the host's Math is the same answer everywhere.
@@ -93,20 +112,20 @@ function evalExpr(e: Expr, frame: Frame, fns: Fns): number | boolean {
if (!def) throw new Error(`EIR: no function '${e.target.name}'`);
const inner = new Frame();
def.params.forEach((p, i) => inner.set(p.id, a[i]));
- const out = exec(def.body, inner, EMPTY_WORLD, fns);
+ const out = exec(def.body, inner, fns, host, owners);
if (out === undefined) throw new Error(`EIR: '${def.name}' returned nothing`);
return out;
}
case 'logic': {
// Short-circuit, which is why this is not a `bin`: `a && b(…)` must
// not evaluate b when a is false.
- const l = evalExpr(e.l, frame, fns) as boolean;
- if (e.op === '&&') return l ? (evalExpr(e.r, frame, fns) as boolean) : false;
- return l ? true : (evalExpr(e.r, frame, fns) as boolean);
+ const l = evalExpr(e.l, frame, fns, host, owners) as boolean;
+ if (e.op === '&&') return l ? (evalExpr(e.r, frame, fns, host, owners) as boolean) : false;
+ return l ? true : (evalExpr(e.r, frame, fns, host, owners) as boolean);
}
case 'bin': {
- const l = evalExpr(e.l, frame, fns) as number;
- const r = evalExpr(e.r, frame, fns) as number;
+ const l = evalExpr(e.l, frame, fns, host, owners) as number;
+ const r = evalExpr(e.r, frame, fns, host, owners) as number;
switch (e.op) {
case '+': return l + r;
case '-': return l - r;
@@ -125,90 +144,116 @@ function evalExpr(e: Expr, frame: Frame, fns: Fns): number | boolean {
}
/** Entities carrying every component the query names, in world order. */
-function matching(world: EirWorld, args: readonly QueryArg[]): number[] {
- return world.entities.filter((e) => args.every((a) => world.comps.get(a.comp)?.has(e)));
-}
-
-/** Returns the value a `return` produced, or undefined if control ran off the end. */
-function exec(stmts: readonly Stmt[], frame: Frame, world: EirWorld, fns: Fns): number | boolean | undefined {
+/** Rows the query matches, from the host. */
+function exec(
+ stmts: readonly Stmt[], frame: Frame, fns: Fns, host: EirHost, owners: Owners,
+): number | boolean | undefined {
for (const s of stmts) {
switch (s.s) {
case 'return':
- return evalExpr(s.value, frame, fns);
+ return evalExpr(s.value, frame, fns, host, owners);
case 'let':
- frame.set(s.id, evalExpr(s.value, frame, fns));
+ frame.set(s.id, evalExpr(s.value, frame, fns, host, owners));
break;
case 'assign':
- writePlace(s.target, frame, evalExpr(s.value, frame, fns));
+ writePlace(s.target, frame, host, owners, evalExpr(s.value, frame, fns, host, owners));
break;
- case 'emit': {
- const queue = readPlace(s.channel, frame) as Command[];
- queue.push({ record: s.record, args: s.args.map((a) => evalExpr(a, frame, fns)) });
+ case 'emit':
+ host.emit(s.record, s.args.map((a) => evalExpr(a, frame, fns, host, owners)));
break;
- }
case 'if': {
- const out = evalExpr(s.cond, frame, fns)
- ? exec(s.then, frame, world, fns)
- : exec(s.otherwise, frame, world, fns);
+ const out = evalExpr(s.cond, frame, fns, host, owners)
+ ? exec(s.then, frame, fns, host, owners)
+ : exec(s.otherwise, frame, fns, host, owners);
if (out !== undefined) return out;
break;
}
case 'rowLoop': {
- const q = readPlace(s.query, frame) as { args: readonly QueryArg[] };
- for (const entity of matching(world, q.args)) {
- if (s.entity !== null) frame.set(s.entity, entity);
- s.binds.forEach((id, i) => {
- frame.set(id, world.comps.get(q.args[i]!.comp)!.get(entity)!);
- });
- exec(s.body, frame, world, fns);
+ const q = readPlace(s.query, frame, host, owners) as { args: readonly QueryArg[] };
+ for (const row of host.rows(q.args)) {
+ if (s.entity !== null) frame.set(s.entity, row.entity);
+ s.binds.forEach((id, i) => frame.set(id, row.binds[i]));
+ const out = exec(s.body, frame, fns, host, owners);
+ if (out !== undefined) return out;
}
break;
}
}
}
+ return undefined;
+}
+
+/** Which component or resource each local names, so the host can resolve fields. */
+function ownersOf(sys: EirSystem): Map<number, string> {
+ const out = new Map<number, string>();
+ for (const l of [...sys.params, ...sys.locals]) {
+ if (l.type.k === 'comp' || l.type.k === 'res') out.set(l.id, l.type.name);
+ }
+ return out;
}
/**
- * Run `sys` against `world`, mutating it in place. Parameters are bound from
- * their declared types: a query becomes its own argument list, a resource its
- * row — the same two things the SDK's runner resolves.
+ * Run `sys` against `host`. Parameters are bound from their declared types, the
+ * two things the SDK's runner also resolves, and the host flushes at the end
+ * because that is where flushSystem_ does.
*/
-export function runSystem(sys: EirSystem, world: EirWorld, fns: Fns = new Map()): void {
+export function runSystemOn(sys: EirSystem, host: EirHost, fns: Fns = new Map()): void {
const frame = new Frame();
- const queues: Command[][] = [];
+ const owners = ownersOf(sys);
for (const p of sys.params) {
- const q = bindParam(p, frame, world);
- if (q) queues.push(q);
+ if (p.type.k === 'query') frame.set(p.id, { args: p.type.args });
+ else if (p.type.k === 'res') frame.set(p.id, host.resource(p.type.name));
+ else if (p.type.k === 'channel') frame.set(p.id, null);
+ else throw new Error(`EIR: '${p.name}' has no parameter binding for ${p.type.k}`);
}
- exec(sys.body, frame, world, fns);
- // At system end, not at the call: the SDK's runner flushes in flushSystem_,
- // and a despawn taking effect mid-row would change what the row loop walks.
- for (const q of queues) flush(q, world);
+ exec(sys.body, frame, fns, host, owners);
+ host.flush();
}
-function flush(queue: Command[], world: EirWorld): void {
- for (const c of queue) {
- if (c.record !== 'despawn') throw new Error(`EIR: no flush for '${c.record}'`);
- const e = c.args[0] as number;
- const at = world.entities.indexOf(e);
- if (at >= 0) world.entities.splice(at, 1);
- for (const rows of world.comps.values()) rows.delete(e);
- }
- queue.length = 0;
+/**
+ * The JS-object host: components are nested records, as a test builds them.
+ * Kept because it is what makes the differential readable; the ABI host in
+ * abi.ts is the one that proves the contract.
+ */
+export function jsHost(world: EirWorld): EirHost {
+ const queued: Command[] = [];
+ return {
+ *rows(args) {
+ for (const e of world.entities) {
+ if (!args.every((a) => world.comps.get(a.comp)?.has(e))) continue;
+ yield { entity: e, binds: args.map((a) => world.comps.get(a.comp)!.get(e)!) };
+ }
+ },
+ readField(base, _comp, path) {
+ const { owner, key } = walk(base, path);
+ return owner[key] as number | boolean;
+ },
+ writeField(base, _comp, path, v) {
+ const { owner, key } = walk(base, path);
+ owner[key] = v;
+ },
+ resource(name) {
+ const row = world.resources.get(name);
+ if (!row) throw new Error(`EIR: no resource '${name}' in the world`);
+ return row;
+ },
+ emit(record, args) {
+ queued.push({ record, args });
+ },
+ flush() {
+ for (const c of queued) {
+ if (c.record !== 'despawn') throw new Error(`EIR: no flush for '${c.record}'`);
+ const e = c.args[0] as number;
+ const at = world.entities.indexOf(e);
+ if (at >= 0) world.entities.splice(at, 1);
+ for (const rows of world.comps.values()) rows.delete(e);
+ }
+ queued.length = 0;
+ },
+ };
}
-function bindParam(p: Local, frame: Frame, world: EirWorld): Command[] | null {
- if (p.type.k === 'query') { frame.set(p.id, { args: p.type.args }); return null; }
- if (p.type.k === 'res') {
- const row = world.resources.get(p.type.name);
- if (!row) throw new Error(`EIR: no resource '${p.type.name}' in the world`);
- frame.set(p.id, row);
- return null;
- }
- if (p.type.k === 'channel') {
- const q: Command[] = [];
- frame.set(p.id, q);
- return q;
- }
- throw new Error(`EIR: '${p.name}' has no parameter binding for ${p.type.k}`);
+/** Run against a JS-object world. Shorthand for runSystemOn(sys, jsHost(world)). */
+export function runSystem(sys: EirSystem, world: EirWorld, fns: Fns = new Map()): void {
+ runSystemOn(sys, jsHost(world), fns);
}
diff --git a/compiler/src/verify.ts b/compiler/src/verify.ts
index 3ee2e29f4..ee363f8b8 100644
--- a/compiler/src/verify.ts
+++ b/compiler/src/verify.ts
@@ -61,9 +61,9 @@ class Verifier {
}
const shape = this.comps.get(base.name);
if (!shape) { this.fail(`no declared shape for '${base.name}'`); return null; }
- const t = shape.fields.get(p.path.join('.'));
- if (!t) { this.fail(`'${base.name}' has no field '${p.path.join('.')}'`); return null; }
- return t;
+ const f = shape.fields.get(p.path.join('.'));
+ if (!f) { this.fail(`'${base.name}' has no field '${p.path.join('.')}'`); return null; }
+ return f.type;
}
exprType(e: Expr): EirType | null {
diff --git a/compiler/tests/abi.test.ts b/compiler/tests/abi.test.ts
new file mode 100644
index 000000000..c465918c0
--- /dev/null
+++ b/compiler/tests/abi.test.ts
@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file abi.test.ts
+ * @brief Is the ABI SUFFICIENT? (docs/REARCH_AOT_ABI.md)
+ *
+ * @details The same interpreter runs the same system twice: once over JS objects
+ * and once over flat memory reached only through what SysCtx carries.
+ * Both must match node.
+ *
+ * That is the question this file exists to answer. A system that runs
+ * in the first and not the second names something the contract is
+ * missing — which is the only legitimate reason to add a field to it.
+ */
+import { describe, it, expect } from 'vitest';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { lowerProgram } from '../src/frontend';
+import { verifySystem } from '../src/verify';
+import { runSystem, runSystemOn, type EirWorld, type Row } from '../src/interp';
+import { builtinShapes } from '../src/builtins';
+import { AbiMemory, abiHost, packLayout } from '../src/abi';
+
+import { moveSystem } from '../../examples/ecs-basics/src/systems/move';
+import { lifetimeSystem } from '../../examples/ecs-basics/src/systems/lifetime';
+import type { StubSystem } from './stubs/esengine';
+
+const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));
+const FILES = [
+ resolve(ROOT, 'examples/ecs-basics/src/systems/move.ts'),
+ resolve(ROOT, 'examples/ecs-basics/src/systems/lifetime.ts'),
+ resolve(ROOT, 'examples/ecs-basics/src/components.ts'),
+];
+
+const { module } = lowerProgram(FILES, builtinShapes());
+const layout = packLayout(module.comps);
+const N = 24;
+
+/** The same starting world, in each of the two shapes. */
+function seed(i: number): { tx: number; ty: number; dx: number; dy: number; speed: number; life: number } {
+ return {
+ tx: (i % 7) * 13 - 40, ty: (i % 5) * 9 - 20,
+ dx: ((i % 3) - 1), dy: ((i % 4) - 2) / 2,
+ speed: 40 + (i % 6) * 15, life: 0.05 * i,
+ };
+}
+
+/**
+ * Rounds every store the way that shape's storage does — f32 for an engine pool,
+ * f64 for a ScriptStorage record. Asking the SHAPE, not the name: a JS-object
+ * world that rounded everything the same way would drift from the ABI image and
+ * flip `remaining <= 0` a frame early.
+ */
+function rowOf(comp: string, fields: Record<string, unknown>): Row {
+ return module.comps.get(comp)!.storage === 'engine' ? f32Row(fields) : (fields as Row);
+}
+
+function f32Row(fields: Record<string, unknown>): Row {
+ const out: Record<string, unknown> = {};
+ for (const [k, v] of Object.entries(fields)) {
+ if (v !== null && typeof v === 'object') { out[k] = f32Row(v as Record<string, unknown>); continue; }
+ let held = Math.fround(v as number);
+ Object.defineProperty(out, k, {
+ enumerable: true,
+ get: () => held,
+ set: (n: number) => { held = Math.fround(n); },
+ });
+ }
+ return out;
+}
+
+function jsWorld(): EirWorld {
+ const transforms = new Map<number, Row>();
+ const movers = new Map<number, Row>();
+ const lifetimes = new Map<number, Row>();
+ const sprites = new Map<number, Row>();
+ const entities: number[] = [];
+ for (let i = 1; i <= N; i++) {
+ const s = seed(i);
+ entities.push(i);
+ transforms.set(i, rowOf('Transform', {
+ position: { x: s.tx, y: s.ty, z: 0 },
+ rotation: { x: 0, y: 0, z: 0, w: 1 }, scale: { x: 1, y: 1, z: 1 },
+ worldPosition: { x: 0, y: 0, z: 0 },
+ worldRotation: { x: 0, y: 0, z: 0, w: 1 }, worldScale: { x: 1, y: 1, z: 1 },
+ }));
+ movers.set(i, rowOf('Mover', { speed: s.speed, directionX: s.dx, directionY: s.dy }));
+ lifetimes.set(i, rowOf('Lifetime', { remaining: s.life }));
+ sprites.set(i, rowOf('Sprite', { color: { r: 1, g: 1, b: 1, a: 1 }, size: { x: 8, y: 8 } }));
+ }
+ return {
+ entities,
+ comps: new Map([['Transform', transforms], ['Mover', movers],
+ ['Lifetime', lifetimes], ['Sprite', sprites]]),
+ resources: new Map<string, Row>([['Time', { delta: 1 / 30 }]]),
+ };
+}
+
+function abiWorld(): AbiMemory {
+ const mem = new AbiMemory(layout);
+ mem.addResource('Time', { delta: 1 / 30 });
+ for (let i = 1; i <= N; i++) {
+ const s = seed(i);
+ mem.addComponent('Transform', i, { 'position.x': s.tx, 'position.y': s.ty });
+ mem.addComponent('Mover', i, { speed: s.speed, directionX: s.dx, directionY: s.dy });
+ mem.addComponent('Lifetime', i, { remaining: s.life });
+ mem.addComponent('Sprite', i, { 'color.a': 1 });
+ }
+ return mem;
+}
+
+describe('the ABI is sufficient for the systems the subset compiles', () => {
+ const move = module.systems.find((s) => s.name === 'MoveSystem')!;
+ const life = module.systems.find((s) => s.name === 'LifetimeSystem')!;
+
+ it('lowered both, and both verify', () => {
+ expect(move).toBeDefined();
+ expect(life).toBeDefined();
+ expect(verifySystem(move, module.comps, module.fns)).toEqual([]);
+ expect(verifySystem(life, module.comps, module.fns)).toEqual([]);
+ });
+
+ it('MoveSystem: flat memory agrees with JS objects, and both with node', () => {
+ const byNode = jsWorld();
+ const byJs = jsWorld();
+ const mem = abiWorld();
+ const host = abiHost(mem, layout);
+
+ const sys = moveSystem as unknown as StubSystem;
+ for (let f = 0; f < 30; f++) {
+ const tf = byNode.comps.get('Transform')!;
+ const mv = byNode.comps.get('Mover')!;
+ (sys.fn as unknown as (q: unknown, t: unknown) => void)({
+ *[Symbol.iterator]() {
+ for (const e of byNode.entities) yield [e, tf.get(e)!, mv.get(e)!];
+ },
+ }, byNode.resources.get('Time'));
+ runSystem(move, byJs, module.fns);
+ runSystemOn(move, host, module.fns);
+ }
+
+ for (let i = 1; i <= N; i++) {
+ const want = (byNode.comps.get('Transform')!.get(i)!['position'] as Record<string, number>);
+ const js = (byJs.comps.get('Transform')!.get(i)!['position'] as Record<string, number>);
+ // Both sides round through f32 on every store, so this is exact.
+ expect(js['x'], `js entity ${i}`).toBe(want['x']);
+ expect(mem.read('Transform', i, 'position.x'), `abi entity ${i}`).toBe(want['x']);
+ expect(mem.read('Transform', i, 'position.y'), `abi entity ${i}`).toBe(want['y']);
+ }
+ });
+
+ it('LifetimeSystem: despawn through the command buffer removes the same entities', () => {
+ const byJs = jsWorld();
+ const mem = abiWorld();
+ const host = abiHost(mem, layout);
+ for (let f = 0; f < 30; f++) {
+ runSystem(life, byJs, module.fns);
+ runSystemOn(life, host, module.fns);
+ expect(mem.entities, `frame ${f}`).toEqual(byJs.entities);
+ }
+ expect(byJs.entities.length).toBeLessThan(N);
+ expect(byJs.entities.length).toBeGreaterThan(0);
+ });
+
+ // "Zero calls into the engine" is not asserted here: it is a property of the
+ // shipped artifact (an empty wasm import section) that the build checks,
+ // per docs/REARCH_AOT_ABI.md §6.5.
+});