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(compiler): the ABI, and the test that asks whether it is sufficient
yhh13726d14d48d
diff --git a/compiler/src/abi.ts b/compiler/src/abi.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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, ureturn { 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.tsindex 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.tsnew file mode 100644index 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.+});