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): 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.tsindex 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.tsindex 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<strconst 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<strif (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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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,