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): a command is a record on a queue, not an opcode per method

yhhc68a6275e065
diff --git a/compiler/src/eir.ts b/compiler/src/eir.ts
index 89319d0bd..46da2879f 100644
--- a/compiler/src/eir.ts
+++ b/compiler/src/eir.ts
@@ -28,7 +28,9 @@ export type EirType =
| { readonly k: 'comp'; readonly name: string }
/** A resource, addressed by field like a component. */
| { readonly k: 'res'; readonly name: string }
- | { readonly k: 'query'; readonly args: readonly QueryArg[] };
+ | { readonly k: 'query'; readonly args: readonly QueryArg[] }
+ /** A deferred-mutation channel: Commands, and later an EventWriter. */
+ | { readonly k: 'channel'; readonly name: string };
export const F64: EirType = { k: 'f64' };
export const BOOL: EirType = { k: 'bool' };
@@ -98,6 +100,17 @@ export type Stmt =
}
| { readonly s: 'assign'; readonly target: Place; readonly value: Expr }
| { readonly s: 'let'; readonly id: number; readonly value: Expr }
+ /**
+ * Append one record to a channel. Commands are a QUEUE the runner flushes at
+ * system end, not calls — so `despawn`, `spawn` and `EventWriter.send` are
+ * one statement with the record name as data, rather than an opcode each.
+ */
+ | {
+ readonly s: 'emit';
+ readonly channel: Place;
+ readonly record: string;
+ readonly args: readonly Expr[];
+ }
| {
readonly s: 'if';
readonly cond: Expr;
@@ -140,6 +153,7 @@ export function typeName(t: EirType): string {
switch (t.k) {
case 'comp': return `comp<${t.name}>`;
case 'res': return `res<${t.name}>`;
+ case 'channel': return `channel<${t.name}>`;
case 'query': return `query<${t.args.map((a) => (a.mut ? `mut ${a.comp}` : a.comp)).join(', ')}>`;
default: return t.k;
}
@@ -178,6 +192,9 @@ function stmtText(s: Stmt, locals: ReadonlyMap<number, Local>, indent: string):
return [`${indent}${placeName(s.target, locals)} = ${exprText(s.value, locals)}`];
case 'let':
return [`${indent}let ${locals.get(s.id)?.name ?? `%${s.id}`} = ${exprText(s.value, locals)}`];
+ case 'emit':
+ return [`${indent}emit ${placeName(s.channel, locals)}.${s.record}(`
+ + `${s.args.map((a) => exprText(a, locals)).join(', ')})`];
case 'if': {
const out = [`${indent}if ${exprText(s.cond, locals)} {`];
out.push(...s.then.flatMap((b) => stmtText(b, locals, `${indent} `)));
diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.ts
index 3fc6726e6..3485b1ec7 100644
--- a/compiler/src/frontend.ts
+++ b/compiler/src/frontend.ts
@@ -41,6 +41,12 @@ export interface LowerResult {
readonly diagnostics: readonly Diagnostic[];
/** Systems seen, whether or not they compiled — the coverage gate's denominator. */
readonly seen: readonly string[];
+ /**
+ * The `const` each system is bound to -> its declared name. Registration in
+ * main.ts names the BINDING, so this is what lets a caller ask whether a
+ * system runs per frame or once at startup.
+ */
+ readonly systemBindings: ReadonlyMap<string, string>;
}
const BIN_OPS: ReadonlyMap<ts.SyntaxKind, BinOp> = new Map([
@@ -71,6 +77,13 @@ function tokenText(kind: ts.SyntaxKind): string {
return ts.tokenToString(kind) ?? ts.SyntaxKind[kind];
}
+/**
+ * Command records this subset emits, and how many arguments each carries.
+ * `spawn` is absent on purpose: it returns a builder that the corpus chains
+ * `.insert(Component, {…})` onto, which needs component literals as values.
+ */
+const COMMAND_RECORDS: Record<string, number | undefined> = { despawn: 1 };
+
/** Thrown internally to abandon one system; never escapes lowerProgram. */
class NotInSubset extends Error {
constructor(readonly node: ts.Node, message: string) { super(message); }
@@ -128,6 +141,10 @@ class SystemLowerer {
if (!arg || !ts.isIdentifier(arg)) throw new NotInSubset(el, 'Res(...) needs a named resource');
return { k: 'res', name: this.compName(arg.text) } as EirType;
}
+ if (kind === 'Commands') {
+ if (el.arguments.length !== 0) throw new NotInSubset(el, 'Commands() takes no arguments');
+ return { k: 'channel', name: 'Commands' } as EirType;
+ }
if (kind !== 'Query') throw new NotInSubset(el, `'${kind}' is not a parameter intrinsic`);
const args: QueryArg[] = el.arguments.map((a) => this.queryArg(a));
return { k: 'query', args } as EirType;
@@ -170,7 +187,10 @@ class SystemLowerer {
private stmt(node: ts.Statement): Stmt[] {
if (ts.isForOfStatement(node)) return [this.rowLoop(node)];
- if (ts.isExpressionStatement(node)) return [this.assignment(node.expression)];
+ if (ts.isExpressionStatement(node)) {
+ if (ts.isCallExpression(node.expression)) return [this.emit(node.expression)];
+ return [this.assignment(node.expression)];
+ }
if (ts.isBlock(node)) return this.scoped(() => node.statements.flatMap((s) => this.stmt(s)));
if (ts.isVariableStatement(node)) return this.declarations(node);
if (ts.isIfStatement(node)) return [this.ifStmt(node)];
@@ -253,6 +273,32 @@ class SystemLowerer {
return { s: 'rowLoop', query: { p: 'local', id: q.id }, entity, binds, body };
}
+ /**
+ * `cmds.despawn(entity)` — a record appended to a channel, not a call. The
+ * SDK already defers these to a flush at system end, so this models what it
+ * does rather than pretending the mutation happens here.
+ */
+ private emit(node: ts.CallExpression): Stmt {
+ const callee = node.expression;
+ if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression)) {
+ throw new NotInSubset(node, 'a call statement must be a method on a declared channel');
+ }
+ const target = this.lookup(callee.expression, callee.expression.text);
+ if (target.type.k !== 'channel') {
+ throw new NotInSubset(node, `'${target.name}' is not a channel this subset can emit to`);
+ }
+ const record = callee.name.text;
+ const arity = COMMAND_RECORDS[record];
+ if (arity === undefined) {
+ throw new NotInSubset(node, `Commands.${record} is not a record this subset emits yet`);
+ }
+ if (node.arguments.length !== arity) {
+ throw new NotInSubset(node, `Commands.${record} takes ${arity} argument(s), not ${node.arguments.length}`);
+ }
+ const args = node.arguments.map((a) => this.expr(a));
+ return { s: 'emit', channel: { p: 'local', id: target.id }, record, args };
+ }
+
private assignment(node: ts.Expression): Stmt {
if (!ts.isBinaryExpression(node)) {
throw new NotInSubset(node, 'only assignments are statements in this subset');
@@ -439,6 +485,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
const systems: EirSystem[] = [];
const diagnostics: Diagnostic[] = [];
const seen: string[] = [];
+ const systemBindings = new Map<string, string>();
// ts normalises fileName to forward slashes; a caller on Windows will not
// have. Comparing them raw lowers nothing and reports no error at all.
@@ -486,6 +533,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
if (node.expression.text !== 'defineSystem') return;
const name = systemName(node, binding);
seen.push(name);
+ if (binding) systemBindings.set(binding, name);
try {
const [params, fn] = node.arguments;
if (!params || !fn || !ts.isArrowFunction(fn)) {
@@ -501,7 +549,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
});
}
- return { module: { systems, comps }, diagnostics, seen };
+ return { module: { systems, comps }, diagnostics, seen, systemBindings };
}
/** `{ name: 'MoveSystem' }` if given, else the const it is assigned to. */
diff --git a/compiler/src/interp.ts b/compiler/src/interp.ts
index 9f4ea5f8a..eb8ffd679 100644
--- a/compiler/src/interp.ts
+++ b/compiler/src/interp.ts
@@ -19,13 +19,19 @@ import type { EirSystem, Expr, Local, Place, QueryArg, Stmt } from './eir';
export type Row = Record<string, unknown>;
export interface EirWorld {
- /** Entity ids in the order a query walks them. */
- readonly entities: readonly number[];
+ /** Entity ids in the order a query walks them. Mutable: a flush removes from it. */
+ entities: number[];
/** component name -> entity -> its row. An absent entity simply has none. */
readonly comps: ReadonlyMap<string, Map<number, Row>>;
readonly resources: ReadonlyMap<string, Row>;
}
+/** One appended record, waiting for the flush at system end. */
+interface Command {
+ readonly record: string;
+ readonly args: readonly unknown[];
+}
+
class Frame {
private readonly slots = new Map<number, unknown>();
set(id: number, v: unknown): void { this.slots.set(id, v); }
@@ -117,6 +123,11 @@ function exec(stmts: readonly Stmt[], frame: Frame, world: EirWorld): void {
case 'assign':
writePlace(s.target, frame, evalExpr(s.value, frame));
break;
+ case 'emit': {
+ const queue = readPlace(s.channel, frame) as Command[];
+ queue.push({ record: s.record, args: s.args.map((a) => evalExpr(a, frame)) });
+ break;
+ }
case 'if':
if (evalExpr(s.cond, frame)) exec(s.then, frame, world);
else exec(s.otherwise, frame, world);
@@ -143,17 +154,40 @@ function exec(stmts: readonly Stmt[], frame: Frame, world: EirWorld): void {
*/
export function runSystem(sys: EirSystem, world: EirWorld): void {
const frame = new Frame();
- for (const p of sys.params) bindParam(p, frame, world);
+ const queues: Command[][] = [];
+ for (const p of sys.params) {
+ const q = bindParam(p, frame, world);
+ if (q) queues.push(q);
+ }
exec(sys.body, frame, world);
+ // 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);
}
-function bindParam(p: Local, frame: Frame, world: EirWorld): void {
- if (p.type.k === 'query') { frame.set(p.id, { args: p.type.args }); return; }
+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;
+}
+
+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;
+ 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}`);
}
diff --git a/compiler/src/verify.ts b/compiler/src/verify.ts
index 208c1010e..2876a6e8b 100644
--- a/compiler/src/verify.ts
+++ b/compiler/src/verify.ts
@@ -144,6 +144,18 @@ class Verifier {
}
break;
}
+ case 'emit': {
+ const ch = this.placeType(s.channel);
+ if (ch && ch.k !== 'channel') this.fail(`emit to a ${typeName(ch)}`);
+ if (s.record === 'despawn') {
+ const t = s.args[0] ? this.exprType(s.args[0]) : null;
+ if (s.args.length !== 1) this.fail(`despawn takes 1 argument, not ${s.args.length}`);
+ else if (t && t.k !== 'entity') this.fail(`despawn applied to a ${typeName(t)}`);
+ } else {
+ this.fail(`'${s.record}' is not a record the verifier knows`);
+ }
+ break;
+ }
case 'if': {
const c = this.exprType(s.cond);
if (c && c.k !== 'bool') this.fail(`if condition is a ${typeName(c)}`);
diff --git a/compiler/tests/commands.test.ts b/compiler/tests/commands.test.ts
new file mode 100644
index 000000000..000edf8c3
--- /dev/null
+++ b/compiler/tests/commands.test.ts
@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file commands.test.ts
+ * @brief A per-frame system that despawns, run both ways (§8.2).
+ *
+ * @details The oracle is examples/ecs-basics/src/systems/lifetime.ts — a real
+ * per-frame Commands user, which is the shape AOT is for. Most of the
+ * corpus's Commands uses are in startup systems, where compiling buys
+ * nothing; this one runs every frame and removes entities.
+ *
+ * The stub queues and flushes at system end because the SDK's runner
+ * does (flushSystem_). A despawn taking effect mid-row would change
+ * what the row loop walks, and the two sides would part company there.
+ */
+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, type EirWorld, type Row } from '../src/interp';
+import { builtinShapes } from '../src/builtins';
+import { printSystem } from '../src/eir';
+
+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/lifetime.ts'),
+ resolve(ROOT, 'examples/ecs-basics/src/components.ts'),
+];
+
+const { module, diagnostics } = lowerProgram(FILES, builtinShapes());
+const eir = module.systems.find((s) => s.name === 'LifetimeSystem');
+
+function makeWorld(): EirWorld {
+ const lifetimes = new Map<number, Row>();
+ const sprites = new Map<number, Row>();
+ const entities: number[] = [];
+ for (let e = 1; e <= 24; e++) {
+ entities.push(e);
+ // Staggered so some expire on every frame rather than all at once.
+ lifetimes.set(e, { remaining: e * 0.05 });
+ sprites.set(e, { color: { r: 1, g: 1, b: 1, a: 1 }, size: { x: 8, y: 8 } });
+ }
+ return {
+ entities,
+ comps: new Map([['Lifetime', lifetimes], ['Sprite', sprites]]),
+ resources: new Map<string, Row>([['Time', { delta: 1 / 30 }]]),
+ };
+}
+
+function runNative(world: EirWorld): void {
+ const sys = lifetimeSystem as unknown as StubSystem;
+ const lifetimes = world.comps.get('Lifetime')!;
+ const sprites = world.comps.get('Sprite')!;
+ const queued: number[] = [];
+ const cmds = { despawn: (e: number) => { queued.push(e); } };
+ const query = {
+ *[Symbol.iterator]() {
+ for (const e of world.entities) {
+ if (lifetimes.has(e) && sprites.has(e)) yield [e, lifetimes.get(e)!, sprites.get(e)!];
+ }
+ },
+ };
+ (sys.fn as unknown as (q: unknown, t: unknown, c: unknown) => void)(
+ query, world.resources.get('Time'), cmds);
+ for (const e of queued) {
+ const at = world.entities.indexOf(e);
+ if (at >= 0) world.entities.splice(at, 1);
+ for (const rows of world.comps.values()) rows.delete(e);
+ }
+}
+
+describe('commands — a per-frame despawn', () => {
+ it('compiles and verifies', () => {
+ expect(diagnostics.filter((d) => d.system === 'LifetimeSystem').map((d) => d.message)).toEqual([]);
+ expect(eir).toBeDefined();
+ expect(verifySystem(eir!, module.comps)).toEqual([]);
+ });
+
+ it('keeps the despawn as an emit on the channel', () => {
+ expect(printSystem(eir!)).toContain('emit cmds.despawn(entity)');
+ expect(printSystem(eir!)).toContain('cmds: channel<Commands>');
+ });
+
+ it('agrees with node, entity for entity, over 40 frames', () => {
+ const byNode = makeWorld();
+ const byEir = makeWorld();
+ for (let f = 0; f < 40; f++) {
+ runNative(byNode);
+ runSystem(eir!, byEir);
+ expect(byEir.entities, `frame ${f}`).toEqual(byNode.entities);
+ }
+ expect(byEir.comps.get('Lifetime')).toEqual(byNode.comps.get('Lifetime'));
+ expect(byEir.comps.get('Sprite')).toEqual(byNode.comps.get('Sprite'));
+ });
+
+ it('actually despawned, and not everything at once', () => {
+ const world = makeWorld();
+ const counts: number[] = [];
+ for (let f = 0; f < 40; f++) {
+ runSystem(eir!, world);
+ counts.push(world.entities.length);
+ }
+ expect(counts[counts.length - 1]).toBe(0);
+ // A count that only ever falls, over more than a few distinct values:
+ // an all-at-once wipe would agree with node just as well.
+ for (let i = 1; i < counts.length; i++) expect(counts[i]!).toBeLessThanOrEqual(counts[i - 1]!);
+ expect(new Set(counts).size).toBeGreaterThan(3);
+ });
+});
diff --git a/compiler/tests/coverage.test.ts b/compiler/tests/coverage.test.ts
index 9231b20f3..5471ee517 100644
--- a/compiler/tests/coverage.test.ts
+++ b/compiler/tests/coverage.test.ts
@@ -8,11 +8,16 @@
* or shrink under a refactor, and nothing says so: every other test here
* passes just as well on a compiler that lowers one system.
*
+ * It counts PER-FRAME systems. A startup system runs once, so compiling
+ * it buys no frame time, and a gate counting it would measure the wrong
+ * thing — the failure a gate is least able to notice about itself. The
+ * all-systems number is printed beside it, for information.
+ *
* The floor is committed. Raising it is the point; lowering it needs a
- * reason in the commit message, because it means the corpus lost ground.
+ * reason in the commit message, because the corpus lost ground.
*/
import { describe, it, expect } from 'vitest';
-import { readdirSync, statSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { lowerProgram } from '../src/frontend';
@@ -21,13 +26,8 @@ import { builtinShapes } from '../src/builtins';
const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));
-/**
- * Measured, not aspired to. 3 of 174 is where the subset stands: the remaining
- * blockers are semantic (Commands, GetWorld, EventReader all mutate the world),
- * not syntactic, so the next increment is real work rather than more parsing.
- * Raise this when it grows; see the file header before lowering it.
- */
-const FLOOR = 3;
+/** Per-frame systems only. See the file header before lowering this. */
+const FRAME_FLOOR = 4;
function walk(dir: string, out: string[] = []): string[] {
for (const name of readdirSync(dir)) {
@@ -38,8 +38,28 @@ function walk(dir: string, out: string[] = []): string[] {
return out;
}
-const files = walk(join(ROOT, 'examples')).filter((f) => f.includes(`${'src'}`));
-const { module, diagnostics, seen } = lowerProgram(files, builtinShapes());
+const files = walk(join(ROOT, 'examples')).filter((f) => f.includes('src'));
+const { module, diagnostics, seen, systemBindings } = lowerProgram(files, builtinShapes());
+
+const SCHEDULED = /addSystemToSchedule\s*\(\s*Schedule\.\w+\s*,\s*(\w+)\s*\)/g;
+const BARE_ADD = /\baddSystem\s*\(\s*(\w+)\s*\)/g;
+
+/**
+ * Which systems run every frame. main.ts registers by BINDING, so the binding
+ * map is what turns `addSystemToSchedule(Schedule.Update, moveSystem)` into the
+ * declared name the rest of this file counts.
+ */
+function perFrameSystems(): Set<string> {
+ const frame = new Set<string>();
+ for (const f of files.filter((p) => p.endsWith('main.ts'))) {
+ const src = readFileSync(f, 'utf8');
+ for (const re of [SCHEDULED, BARE_ADD]) {
+ for (const m of src.matchAll(re)) frame.add(systemBindings.get(m[1]!) ?? m[1]!);
+ }
+ }
+ return frame;
+}
+const perFrame = perFrameSystems();
describe('AOT coverage over examples/', () => {
it('found systems to measure', () => {
@@ -47,9 +67,17 @@ describe('AOT coverage over examples/', () => {
expect(seen.length).toBeGreaterThan(20);
});
- it(`compiles at least ${FLOOR} of the corpus's systems`, () => {
+ it('classified the corpus by schedule', () => {
+ // At zero the regexes have stopped matching, and the gate below would
+ // silently be measuring an empty set.
+ expect(perFrame.size).toBeGreaterThan(50);
+ expect(perFrame.size).toBeLessThan(seen.length);
+ });
+
+ it(`compiles at least ${FRAME_FLOOR} of the per-frame systems`, () => {
const verified = module.systems.filter((s) => verifySystem(s, module.comps).length === 0);
- const pct = ((100 * verified.length) / seen.length).toFixed(1);
+ const verifiedFrame = verified.filter((s) => perFrame.has(s.name));
+ const seenFrame = seen.filter((n) => perFrame.has(n));
// The breakdown is the point of running this: the commonest refusal is
// the next thing worth lowering.
@@ -60,10 +88,17 @@ describe('AOT coverage over examples/', () => {
reasons.set(key, (reasons.get(key) ?? 0) + 1);
}
const top = [...reasons.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8);
- console.log(`\nAOT coverage: ${verified.length}/${seen.length} systems (${pct}%) over ${files.length} files`);
- for (const [why, n] of top) console.log(` ${String(n).padStart(3)}x ${why}`);
+ const pct = (n: number, d: number) => ((100 * n) / d).toFixed(1);
+ console.log([
+ '',
+ `AOT coverage, per-frame : ${verifiedFrame.length}/${seenFrame.length}`
+ + ` (${pct(verifiedFrame.length, seenFrame.length)}%) <- what AOT is for`,
+ `AOT coverage, all : ${verified.length}/${seen.length}`
+ + ` (${pct(verified.length, seen.length)}%) over ${files.length} files`,
+ ...top.map(([why, n]) => ` ${String(n).padStart(3)}x ${why}`),
+ ].join('\n'));
- expect(verified.length).toBeGreaterThanOrEqual(FLOOR);
+ expect(verifiedFrame.length).toBeGreaterThanOrEqual(FRAME_FLOOR);
});
it('every system that compiles also verifies', () => {
diff --git a/compiler/tests/stubs/esengine.ts b/compiler/tests/stubs/esengine.ts
index c1b9739ae..c3f6d703c 100644
--- a/compiler/tests/stubs/esengine.ts
+++ b/compiler/tests/stubs/esengine.ts
@@ -31,6 +31,10 @@ export function Mut(comp: unknown): unknown {
export function Res(resource: unknown): unknown {
return { kind: 'res', resource };
}
+export function Commands(): unknown {
+ return { kind: 'commands' };
+}
+export const Sprite = { _name: 'Sprite' };
export function defineSystem(
params: readonly unknown[],
fn: (...args: any[]) => void,