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): pure helpers become calls in EIR, and a pass makes them bodies

yhh67d8db007721
diff --git a/compiler/src/eir.ts b/compiler/src/eir.ts
index 46da2879f..d1162f023 100644
--- a/compiler/src/eir.ts
+++ b/compiler/src/eir.ts
@@ -71,8 +71,13 @@ export type Expr =
readonly otherwise: Expr;
readonly type: EirType;
}
- /** An intrinsic call. Only the exactly-specified Math operations (§3.3). */
- | { readonly e: 'call'; readonly fn: MathFn; readonly args: readonly Expr[]; readonly type: EirType };
+ /** A call. One node, parameterised by target — as `emit` is by record. */
+ | { readonly e: 'call'; readonly target: CallTarget; readonly args: readonly Expr[]; readonly type: EirType };
+
+export type CallTarget =
+ /** Only the exactly-specified Math operations (§3.3). */
+ | { readonly k: 'math'; readonly fn: MathFn }
+ | { readonly k: 'fn'; readonly name: string };
/**
* The Math operations ECMAScript specifies EXACTLY, so a backend can compute
@@ -99,6 +104,7 @@ export type Stmt =
readonly body: readonly Stmt[];
}
| { readonly s: 'assign'; readonly target: Place; readonly value: Expr }
+ | { readonly s: 'return'; 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
@@ -125,6 +131,15 @@ export interface Local {
readonly type: EirType;
}
+/** A module-level pure function over numbers and booleans. */
+export interface EirFn {
+ readonly name: string;
+ readonly params: readonly Local[];
+ readonly locals: readonly Local[];
+ readonly body: readonly Stmt[];
+ readonly ret: EirType;
+}
+
export interface EirSystem {
readonly name: string;
/** Locals bound to the system's declared parameters, in declaration order. */
@@ -143,6 +158,7 @@ export interface CompShape {
export interface EirModule {
readonly systems: readonly EirSystem[];
readonly comps: ReadonlyMap<string, CompShape>;
+ readonly fns: ReadonlyMap<string, EirFn>;
}
// =============================================================================
@@ -174,8 +190,10 @@ function exprText(e: Expr, locals: ReadonlyMap<number, Local>): string {
case 'not': return `!${exprText(e.v, locals)}`;
case 'select':
return `(${exprText(e.cond, locals)} ? ${exprText(e.then, locals)} : ${exprText(e.otherwise, locals)})`;
- case 'call':
- return `${e.fn}(${e.args.map((a) => exprText(a, locals)).join(', ')})`;
+ case 'call': {
+ const name = e.target.k === 'math' ? e.target.fn : e.target.name;
+ return `${name}(${e.args.map((a) => exprText(a, locals)).join(', ')})`;
+ }
}
}
@@ -192,6 +210,8 @@ 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 'return':
+ return [`${indent}return ${exprText(s.value, locals)}`];
case 'emit':
return [`${indent}emit ${placeName(s.channel, locals)}.${s.record}(`
+ `${s.args.map((a) => exprText(a, locals)).join(', ')})`];
@@ -208,6 +228,17 @@ function stmtText(s: Stmt, locals: ReadonlyMap<number, Local>, indent: string):
}
}
+export function printFn(fn: EirFn): string {
+ const byId = new Map<number, Local>();
+ for (const l of [...fn.params, ...fn.locals]) byId.set(l.id, l);
+ const params = fn.params.map((p) => `${p.name}: ${typeName(p.type)}`).join(', ');
+ return [
+ `fn ${fn.name}(${params}) -> ${typeName(fn.ret)} {`,
+ ...fn.body.flatMap((s) => stmtText(s, byId, ' ')),
+ '}',
+ ].join('\n');
+}
+
export function printSystem(sys: EirSystem): string {
const byId = new Map<number, Local>();
for (const l of [...sys.params, ...sys.locals]) byId.set(l.id, l);
diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.ts
index 054c873f9..f02515880 100644
--- a/compiler/src/frontend.ts
+++ b/compiler/src/frontend.ts
@@ -13,6 +13,12 @@
* declaration — so both arguments must be literals or the file falls
* back to the interpreter.
*
+ * NOTHING in this file may call `getText()`, `getSourceFile()` or read
+ * `.parent`. Those need the program to have BOUND, which only happens
+ * as a side effect of getTypeChecker(); they have already broken line
+ * numbers, binding resolution, operator text and parameter names here.
+ * Use `.text` on an identifier and `ts.tokenToString(kind)` on a token.
+ *
* Nothing here throws on code it cannot handle. Anything outside the
* subset produces a Diagnostic naming the line and the reason, and its
* system is simply not compiled — §3.2's no-cliff rule, which is what
@@ -24,7 +30,7 @@ import {
BOOL, ENTITY, F64,
type CompShape, type EirModule, type EirSystem, type EirType,
MATH_FNS,
- type Expr, type Local, type Place, type QueryArg, type Stmt, type BinOp, type LogicOp,
+ type EirFn, type Expr, type Local, type Place, type QueryArg, type Stmt, type BinOp, type LogicOp,
type MathFn,
} from './eir';
@@ -113,6 +119,13 @@ function constValue(node: ts.Expression): ConstValue | null {
return null;
}
+/** `number` / `boolean` written as an annotation; nothing else is a subset type. */
+function annotatedType(node: ts.TypeNode): EirType | null {
+ if (node.kind === ts.SyntaxKind.NumberKeyword) return F64;
+ if (node.kind === ts.SyntaxKind.BooleanKeyword) return BOOL;
+ return null;
+}
+
/** Thrown internally to abandon one system; never escapes lowerProgram. */
class NotInSubset extends Error {
constructor(readonly node: ts.Node, message: string) { super(message); }
@@ -131,8 +144,45 @@ class SystemLowerer {
private readonly bindings: ReadonlyMap<string, string>,
/** Module-level literals, folded where they are read. */
private readonly consts: ReadonlyMap<string, ConstValue>,
+ /** Module-level pure functions, callable from a system or from each other. */
+ private readonly fns: ReadonlyMap<string, EirFn>,
+ /** Why a function is absent, so the call site can say more than "no". */
+ private readonly fnFailures: ReadonlyMap<string, string> = new Map(),
) {}
+ /** Lower a module-level function; `lower` does the same for a system body. */
+ lowerFn(name: string, params: readonly ts.ParameterDeclaration[], body: ts.ConciseBody): EirFn {
+ const bound = params.map((p) => {
+ if (!ts.isIdentifier(p.name)) throw new NotInSubset(p, 'a parameter must be a plain name');
+ if (!p.type) {
+ throw new NotInSubset(p, `parameter '${p.name.text}' needs a type annotation`);
+ }
+ const t = annotatedType(p.type);
+ if (!t) throw new NotInSubset(p.type, 'a parameter must be annotated number or boolean');
+ return this.define(p.name.text, t);
+ });
+ // One `return <expr>` and nothing else: that is what makes inlining a
+ // substitution rather than a control-flow splice, and it covers the
+ // numeric helpers the corpus writes.
+ const value = ts.isBlock(body)
+ ? (() => {
+ const only = body.statements.length === 1 ? body.statements[0] : undefined;
+ if (!only || !ts.isReturnStatement(only) || !only.expression) {
+ throw new NotInSubset(body, 'a function body must be a single return of an expression');
+ }
+ return this.expr(only.expression);
+ })()
+ : this.expr(body);
+ const paramIds = new Set(bound.map((b) => b.id));
+ return {
+ name,
+ params: bound,
+ locals: this.locals.filter((l) => !paramIds.has(l.id)),
+ body: [{ s: 'return', value }],
+ ret: value.type,
+ };
+ }
+
/** The constant a dotted path names, or null when the root is not one. */
private constAt(root: string, path: readonly string[]): ConstValue | null {
let cur = this.consts.get(root);
@@ -419,6 +469,29 @@ class SystemLowerer {
*/
private mathCall(node: ts.CallExpression): Expr {
const callee = node.expression;
+ // A module-level pure function, called by name.
+ if (ts.isIdentifier(callee)) {
+ const target = this.fns.get(callee.text);
+ if (!target) {
+ const why = this.fnFailures.get(callee.text);
+ throw new NotInSubset(node, why
+ ? `'${callee.text}' cannot be lowered: ${why}`
+ : `'${callee.text}' is not a function this subset lowers`);
+ }
+ if (node.arguments.length !== target.params.length) {
+ throw new NotInSubset(node,
+ `${target.name} takes ${target.params.length} argument(s), not ${node.arguments.length}`);
+ }
+ const args = node.arguments.map((a) => this.expr(a));
+ args.forEach((a, i) => {
+ const want = target.params[i]!.type;
+ if (a.type.k !== want.k) {
+ throw new NotInSubset(node.arguments[i]!,
+ `${target.name} takes a ${want.k} here, not a ${a.type.k}`);
+ }
+ });
+ return { e: 'call', target: { k: 'fn', name: target.name }, args, type: target.ret };
+ }
if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression)
|| callee.expression.text !== 'Math') {
throw new NotInSubset(node, 'CallExpression is not an expression this subset lowers');
@@ -436,7 +509,7 @@ class SystemLowerer {
for (const a of args) {
if (a.type.k !== 'f64') throw new NotInSubset(node, `Math.${fn} takes numbers, not a ${a.type.k}`);
}
- return { e: 'call', fn, args, type: F64 };
+ return { e: 'call', target: { k: 'math', fn }, args, type: F64 };
}
/** A read of a module-level constant becomes the value, not a load. */
@@ -567,6 +640,11 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
// missing until a fixture used two.
const bindings = new Map<string, string>();
const consts = new Map<string, ConstValue>();
+ const fns = new Map<string, EirFn>();
+ // Why a function could not be lowered, reported at the CALL SITE rather than
+ // where it was declared: a helper nothing calls has blocked nothing, and a
+ // diagnostic for it is noise that buries the list of real blockers.
+ const fnFailures = new Map<string, string>();
const systems: EirSystem[] = [];
const diagnostics: Diagnostic[] = [];
const seen: string[] = [];
@@ -630,6 +708,33 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
});
}
+ // Functions before systems, and in dependency order by repeated passes: a
+ // helper may call a helper declared later in the file.
+ for (let pass = 0; pass < 2; pass++) {
+ for (const sf of sources) {
+ walkTop(sf, (node, binding) => {
+ let name: string | null = null;
+ let params: readonly ts.ParameterDeclaration[] | null = null;
+ let body: ts.ConciseBody | null = null;
+ if (ts.isFunctionDeclaration(node) && node.name && node.body) {
+ name = node.name.text; params = node.parameters; body = node.body;
+ } else if (binding && ts.isArrowFunction(node)) {
+ name = binding; params = node.parameters; body = node.body;
+ }
+ if (!name || !params || !body || fns.has(name)) return;
+ try {
+ fns.set(name, new SystemLowerer(comps, bindings, consts, fns, fnFailures)
+ .lowerFn(name, params, body));
+ } catch (e) {
+ if (!(e instanceof NotInSubset)) throw e;
+ // Recorded on the last pass only: an earlier failure may just
+ // be a helper whose own callee is not lowered yet.
+ if (pass === 1) fnFailures.set(name, e.message);
+ }
+ });
+ }
+ }
+
for (const sf of sources) {
walkTop(sf, (node, binding) => {
if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return;
@@ -642,7 +747,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
if (!params || !fn || !ts.isArrowFunction(fn)) {
throw new NotInSubset(node, 'defineSystem takes a parameter array and an arrow function');
}
- systems.push(new SystemLowerer(comps, bindings, consts).lower(name, params, fn));
+ systems.push(new SystemLowerer(comps, bindings, consts, fns, fnFailures).lower(name, params, fn));
} catch (e) {
if (!(e instanceof NotInSubset)) throw e;
diagnostics.push({
@@ -652,7 +757,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
});
}
- return { module: { systems, comps }, diagnostics, seen, systemBindings };
+ return { module: { systems, comps, fns }, diagnostics, seen, systemBindings };
}
/** `{ name: 'MoveSystem' }` if given, else the const it is assigned to. */
diff --git a/compiler/src/index.ts b/compiler/src/index.ts
index d7ccd8a52..3a8bfbe61 100644
--- a/compiler/src/index.ts
+++ b/compiler/src/index.ts
@@ -7,5 +7,6 @@
export * from './eir';
export { lowerProgram, type Diagnostic, type LowerResult } from './frontend';
export { verifySystem, type VerifyError } from './verify';
-export { runSystem, type EirWorld, type Row } from './interp';
+export { runSystem, type EirWorld, type Fns, type Row } from './interp';
+export { inlineModule, inlineSystem } from './inline';
export { builtinShapes } from './builtins';
diff --git a/compiler/src/inline.ts b/compiler/src/inline.ts
new file mode 100644
index 000000000..51959d4d7
--- /dev/null
+++ b/compiler/src/inline.ts
@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file inline.ts
+ * @brief The first EIR -> EIR pass: calls to pure functions become their bodies.
+ *
+ * @details A helper called once per row must not still be a call by the time the
+ * backend sees it — §4.2's optimisations need the body visible, and a
+ * call boundary hides it.
+ *
+ * It is a PASS, not something the frontend does, and that is the point.
+ * The frontend lowers faithfully; every optimisation after it is an
+ * EIR -> EIR function whose result the differential re-checks against
+ * node. Stage 3's copy-elimination and archetype specialisation are the
+ * same shape, so this is where that discipline starts.
+ *
+ * Arguments are bound to `let` temporaries hoisted before the statement
+ * rather than substituted into the body. Substituting would duplicate an
+ * argument once per use — `clamp`'s `v` appears three times — and while
+ * that is safe here (subset expressions are pure), it is work the C
+ * compiler would then have to undo.
+ */
+import type { EirFn, EirModule, EirSystem, Expr, Local, Stmt } from './eir';
+
+/** Every function reachable from `name`, or null if the graph has a cycle. */
+function callees(fn: EirFn, fns: ReadonlyMap<string, EirFn>, seen: Set<string>): boolean {
+ if (seen.has(fn.name)) return false;
+ seen.add(fn.name);
+ let ok = true;
+ walkExprs(fn.body, (e) => {
+ if (e.e === 'call' && e.target.k === 'fn') {
+ const next = fns.get(e.target.name);
+ if (!next || !callees(next, fns, seen)) ok = false;
+ }
+ });
+ seen.delete(fn.name);
+ return ok;
+}
+
+function walkExprs(stmts: readonly Stmt[], visit: (e: Expr) => void): void {
+ const expr = (e: Expr): void => {
+ visit(e);
+ switch (e.e) {
+ case 'bin': case 'logic': expr(e.l); expr(e.r); break;
+ case 'neg': case 'not': expr(e.v); break;
+ case 'select': expr(e.cond); expr(e.then); expr(e.otherwise); break;
+ case 'call': for (const a of e.args) expr(a); break;
+ default: break;
+ }
+ };
+ for (const s of stmts) {
+ switch (s.s) {
+ case 'let': case 'return': expr(s.value); break;
+ case 'assign': expr(s.value); break;
+ case 'emit': for (const a of s.args) expr(a); break;
+ case 'if': expr(s.cond); walkExprs(s.then, visit); walkExprs(s.otherwise, visit); break;
+ case 'rowLoop': walkExprs(s.body, visit); break;
+ }
+ }
+}
+
+/** Rewrites one system, minting fresh local ids as it goes. */
+class Inliner {
+ private readonly extra: Local[] = [];
+ private next: number;
+ /** Statements to place before the one being rewritten. */
+ private hoisted: Stmt[] = [];
+
+ constructor(private readonly fns: ReadonlyMap<string, EirFn>, firstId: number) {
+ this.next = firstId;
+ }
+
+ get locals(): readonly Local[] { return this.extra; }
+
+ private mint(name: string, type: Local['type']): Local {
+ const l: Local = { id: this.next++, name: `${name}$${this.next}`, type };
+ this.extra.push(l);
+ return l;
+ }
+
+ stmts(list: readonly Stmt[]): Stmt[] {
+ const out: Stmt[] = [];
+ for (const s of list) {
+ const saved = this.hoisted;
+ this.hoisted = [];
+ const rewritten = this.stmt(s);
+ out.push(...this.hoisted, rewritten);
+ this.hoisted = saved;
+ }
+ return out;
+ }
+
+ private stmt(s: Stmt): Stmt {
+ switch (s.s) {
+ case 'let': return { ...s, value: this.expr(s.value) };
+ case 'return': return { ...s, value: this.expr(s.value) };
+ case 'assign': return { ...s, value: this.expr(s.value) };
+ case 'emit': return { ...s, args: s.args.map((a) => this.expr(a)) };
+ case 'if': return {
+ s: 'if',
+ cond: this.expr(s.cond),
+ // Each arm gets its own hoist scope: a temp for a call inside the
+ // `then` must not be evaluated when the `else` is taken.
+ then: this.stmts(s.then),
+ otherwise: this.stmts(s.otherwise),
+ };
+ case 'rowLoop': return { ...s, body: this.stmts(s.body) };
+ }
+ }
+
+ private expr(e: Expr): Expr {
+ switch (e.e) {
+ case 'const': case 'read': return e;
+ case 'neg': return { ...e, v: this.expr(e.v) };
+ case 'not': return { ...e, v: this.expr(e.v) };
+ case 'bin': return { ...e, l: this.expr(e.l), r: this.expr(e.r) };
+ case 'logic': return { ...e, l: this.expr(e.l), r: this.expr(e.r) };
+ case 'select':
+ return { ...e, cond: this.expr(e.cond), then: this.expr(e.then), otherwise: this.expr(e.otherwise) };
+ case 'call': {
+ const args = e.args.map((a) => this.expr(a));
+ if (e.target.k === 'math') return { ...e, args };
+ const def = this.fns.get(e.target.name);
+ if (!def) return { ...e, args };
+ const subst = new Map<number, Expr>();
+ def.params.forEach((p, i) => {
+ const tmp = this.mint(p.name, p.type);
+ this.hoisted.push({ s: 'let', id: tmp.id, value: args[i]! });
+ subst.set(p.id, { e: 'read', place: { p: 'local', id: tmp.id }, type: p.type });
+ });
+ const only = def.body[0];
+ if (!only || only.s !== 'return') return { ...e, args };
+ // The body is one `return <expr>`, so inlining is substitution.
+ return this.expr(substitute(only.value, subst));
+ }
+ }
+ }
+}
+
+/** Replace reads of the given locals with the expressions bound to them. */
+function substitute(e: Expr, subst: ReadonlyMap<number, Expr>): Expr {
+ switch (e.e) {
+ case 'const': return e;
+ case 'read':
+ return e.place.p === 'local' ? (subst.get(e.place.id) ?? e) : e;
+ case 'neg': return { ...e, v: substitute(e.v, subst) };
+ case 'not': return { ...e, v: substitute(e.v, subst) };
+ case 'bin': return { ...e, l: substitute(e.l, subst), r: substitute(e.r, subst) };
+ case 'logic': return { ...e, l: substitute(e.l, subst), r: substitute(e.r, subst) };
+ case 'select': return {
+ ...e,
+ cond: substitute(e.cond, subst),
+ then: substitute(e.then, subst),
+ otherwise: substitute(e.otherwise, subst),
+ };
+ case 'call': return { ...e, args: e.args.map((a) => substitute(a, subst)) };
+ }
+}
+
+function maxId(sys: EirSystem): number {
+ let n = 0;
+ for (const l of [...sys.params, ...sys.locals]) n = Math.max(n, l.id + 1);
+ return n;
+}
+
+/**
+ * Inline every call to a module function. A system whose call graph has a cycle
+ * is returned unchanged — recursion cannot be inlined, and pretending otherwise
+ * would loop rather than fail.
+ */
+export function inlineSystem(sys: EirSystem, fns: ReadonlyMap<string, EirFn>): EirSystem {
+ for (const fn of fns.values()) {
+ if (!callees(fn, fns, new Set())) return sys;
+ }
+ const inliner = new Inliner(fns, maxId(sys));
+ const body = inliner.stmts(sys.body);
+ return { ...sys, body, locals: [...sys.locals, ...inliner.locals] };
+}
+
+/** The whole module with every system inlined. Types are unchanged, so the
+ * verifier holds on the result exactly as it did on the input. */
+export function inlineModule(module: EirModule): EirModule {
+ return { ...module, systems: module.systems.map((s) => inlineSystem(s, module.fns)) };
+}
diff --git a/compiler/src/interp.ts b/compiler/src/interp.ts
index eb8ffd679..e761256ee 100644
--- a/compiler/src/interp.ts
+++ b/compiler/src/interp.ts
@@ -13,7 +13,10 @@
* obviously correct, not fast; anything clever here would be a second
* place for a bug to hide from the backend it exists to check.
*/
-import type { EirSystem, Expr, Local, Place, QueryArg, Stmt } from './eir';
+import type { EirFn, EirSystem, Expr, Local, Place, QueryArg, Stmt } from './eir';
+
+/** The module's pure functions, threaded rather than held in a module global. */
+export type Fns = ReadonlyMap<string, EirFn>;
/** One component instance, nested exactly as a system reads it. */
export type Row = Record<string, unknown>;
@@ -67,31 +70,43 @@ function writePlace(p: Place, frame: Frame, value: unknown): void {
owner[key] = value;
}
-function evalExpr(e: Expr, frame: Frame): 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 {
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) as number);
- case 'not': return !(evalExpr(e.v, frame) as boolean);
+ case 'neg': return -(evalExpr(e.v, frame, fns) as number);
+ case 'not': return !(evalExpr(e.v, frame, fns) as boolean);
case 'select':
- return evalExpr(e.cond, frame) ? evalExpr(e.then, frame) : evalExpr(e.otherwise, frame);
+ return evalExpr(e.cond, frame, fns) ? evalExpr(e.then, frame, fns) : evalExpr(e.otherwise, frame, fns);
case 'call': {
- const a = e.args.map((x) => evalExpr(x, frame) as number);
- // The frontend admits only the exactly-specified operations, so
- // deferring to the host's Math is the same answer everywhere.
- const fn = (Math as unknown as Record<string, (...xs: number[]) => number>)[e.fn]!;
- return fn(...a);
+ const a = e.args.map((x) => evalExpr(x, frame, fns));
+ 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.
+ const fn = (Math as unknown as Record<string, (...xs: number[]) => number>)[e.target.fn]!;
+ return fn(...(a as number[]));
+ }
+ const def = fns.get(e.target.name);
+ 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);
+ 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) as boolean;
- if (e.op === '&&') return l ? (evalExpr(e.r, frame) as boolean) : false;
- return l ? true : (evalExpr(e.r, frame) as boolean);
+ 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);
}
case 'bin': {
- const l = evalExpr(e.l, frame) as number;
- const r = evalExpr(e.r, frame) as number;
+ const l = evalExpr(e.l, frame, fns) as number;
+ const r = evalExpr(e.r, frame, fns) as number;
switch (e.op) {
case '+': return l + r;
case '-': return l - r;
@@ -114,24 +129,30 @@ function matching(world: EirWorld, args: readonly QueryArg[]): number[] {
return world.entities.filter((e) => args.every((a) => world.comps.get(a.comp)?.has(e)));
}
-function exec(stmts: readonly Stmt[], frame: Frame, world: EirWorld): void {
+/** 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 {
for (const s of stmts) {
switch (s.s) {
+ case 'return':
+ return evalExpr(s.value, frame, fns);
case 'let':
- frame.set(s.id, evalExpr(s.value, frame));
+ frame.set(s.id, evalExpr(s.value, frame, fns));
break;
case 'assign':
- writePlace(s.target, frame, evalExpr(s.value, frame));
+ writePlace(s.target, frame, evalExpr(s.value, frame, fns));
break;
case 'emit': {
const queue = readPlace(s.channel, frame) as Command[];
- queue.push({ record: s.record, args: s.args.map((a) => evalExpr(a, frame)) });
+ queue.push({ record: s.record, args: s.args.map((a) => evalExpr(a, frame, fns)) });
break;
}
- case 'if':
- if (evalExpr(s.cond, frame)) exec(s.then, frame, world);
- else exec(s.otherwise, frame, world);
+ case 'if': {
+ const out = evalExpr(s.cond, frame, fns)
+ ? exec(s.then, frame, world, fns)
+ : exec(s.otherwise, frame, world, fns);
+ 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)) {
@@ -139,7 +160,7 @@ function exec(stmts: readonly Stmt[], frame: Frame, world: EirWorld): void {
s.binds.forEach((id, i) => {
frame.set(id, world.comps.get(q.args[i]!.comp)!.get(entity)!);
});
- exec(s.body, frame, world);
+ exec(s.body, frame, world, fns);
}
break;
}
@@ -152,14 +173,14 @@ function exec(stmts: readonly Stmt[], frame: Frame, world: EirWorld): void {
* their declared types: a query becomes its own argument list, a resource its
* row — the same two things the SDK's runner resolves.
*/
-export function runSystem(sys: EirSystem, world: EirWorld): void {
+export function runSystem(sys: EirSystem, world: EirWorld, fns: Fns = new Map()): void {
const frame = new Frame();
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);
+ 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);
diff --git a/compiler/src/verify.ts b/compiler/src/verify.ts
index 2876a6e8b..3ee2e29f4 100644
--- a/compiler/src/verify.ts
+++ b/compiler/src/verify.ts
@@ -16,7 +16,7 @@
*/
import {
MATH_FNS,
- type CompShape, type EirSystem, type EirType, type Expr, type Local, type Place, type Stmt,
+ type CompShape, type EirFn, type EirSystem, type EirType, type Expr, type Local, type Place, type Stmt,
typeName,
} from './eir';
@@ -32,6 +32,7 @@ class Verifier {
constructor(
private readonly sys: EirSystem,
private readonly comps: ReadonlyMap<string, CompShape>,
+ private readonly fns: ReadonlyMap<string, EirFn>,
) {
for (const l of [...sys.params, ...sys.locals]) {
if (this.byId.has(l.id)) this.fail(`local %${l.id} ('${l.name}') is declared twice`);
@@ -95,6 +96,12 @@ class Verifier {
}
return e.type;
}
+ case 'bin': {
+ for (const t of [this.exprType(e.l), this.exprType(e.r)]) {
+ if (t && t.k !== 'f64') this.fail(`operator '${e.op}' applied to a ${typeName(t)}`);
+ }
+ return e.type;
+ }
case 'select': {
const c = this.exprType(e.cond);
if (c && c.k !== 'bool') this.fail(`a ternary condition is a ${typeName(c)}`);
@@ -104,23 +111,31 @@ class Verifier {
return e.type;
}
case 'call': {
- const arity = (MATH_FNS as Record<string, number | undefined>)[e.fn];
- if (arity === undefined) this.fail(`'${e.fn}' is not an intrinsic`);
- else if (arity !== e.args.length) {
- this.fail(`${e.fn} called with ${e.args.length} argument(s), not ${arity}`);
- }
- for (const a of e.args) {
- const t = this.exprType(a);
- if (t && t.k !== 'f64') this.fail(`${e.fn} applied to a ${typeName(t)}`);
+ if (e.target.k === 'math') {
+ const arity = (MATH_FNS as Record<string, number | undefined>)[e.target.fn];
+ if (arity === undefined) this.fail(`'${e.target.fn}' is not an intrinsic`);
+ else if (arity !== e.args.length) {
+ this.fail(`${e.target.fn} called with ${e.args.length} argument(s), not ${arity}`);
+ }
+ for (const a of e.args) {
+ const t = this.exprType(a);
+ if (t && t.k !== 'f64') this.fail(`${e.target.fn} applied to a ${typeName(t)}`);
+ }
+ return e.type;
}
- return e.type;
- }
- case 'bin': {
- const l = this.exprType(e.l);
- const r = this.exprType(e.r);
- for (const t of [l, r]) {
- if (t && t.k !== 'f64') this.fail(`operator '${e.op}' applied to a ${typeName(t)}`);
+ const def = this.fns.get(e.target.name);
+ if (!def) { this.fail(`no function '${e.target.name}'`); return e.type; }
+ if (def.params.length !== e.args.length) {
+ this.fail(`${def.name} called with ${e.args.length} argument(s), not ${def.params.length}`);
}
+ e.args.forEach((a, i) => {
+ const t = this.exprType(a);
+ const want = def.params[i]?.type;
+ if (t && want && t.k !== want.k) {
+ this.fail(`${def.name} argument ${i} is ${typeName(t)}, not ${typeName(want)}`);
+ }
+ });
+ if (def.ret.k !== e.type.k) this.fail(`${def.name} returns ${typeName(def.ret)}, read as ${typeName(e.type)}`);
return e.type;
}
}
@@ -205,8 +220,12 @@ class Verifier {
}
/** Every type claim in `sys`, re-proved. An empty array means it holds. */
-export function verifySystem(sys: EirSystem, comps: ReadonlyMap<string, CompShape>): VerifyError[] {
- const v = new Verifier(sys, comps);
+export function verifySystem(
+ sys: EirSystem,
+ comps: ReadonlyMap<string, CompShape>,
+ fns: ReadonlyMap<string, EirFn> = new Map(),
+): VerifyError[] {
+ const v = new Verifier(sys, comps, fns);
for (const s of sys.body) v.stmt(s);
return v.errors;
}
diff --git a/compiler/tests/commands.test.ts b/compiler/tests/commands.test.ts
index 000edf8c3..861663d29 100644
--- a/compiler/tests/commands.test.ts
+++ b/compiler/tests/commands.test.ts
@@ -77,7 +77,7 @@ 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([]);
+ expect(verifySystem(eir!, module.comps, module.fns)).toEqual([]);
});
it('keeps the despawn as an emit on the channel', () => {
diff --git a/compiler/tests/conformance.test.ts b/compiler/tests/conformance.test.ts
index e43e06d60..86dc6b91d 100644
--- a/compiler/tests/conformance.test.ts
+++ b/compiler/tests/conformance.test.ts
@@ -18,10 +18,11 @@ 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 { inlineSystem } from '../src/inline';
import { builtinShapes } from '../src/builtins';
import { printSystem } from '../src/eir';
-import { driftSystem, clampSystem, tunedSystem } from './fixtures/in-subset';
+import { driftSystem, clampSystem, tunedSystem, helperSystem } from './fixtures/in-subset';
import type { StubSystem } from './stubs/esengine';
const FIXTURE = resolve(fileURLToPath(new URL('./fixtures/in-subset.ts', import.meta.url)));
@@ -80,7 +81,7 @@ describe('conformance — locals, branches, logic', () => {
it('compiles', () => {
expect(diagnostics.filter((d) => d.system === 'FixtureDrift')).toEqual([]);
expect(drift).toBeDefined();
- expect(verifySystem(drift!, module.comps)).toEqual([]);
+ expect(verifySystem(drift!, module.comps, module.fns)).toEqual([]);
});
it('reads back with its locals and branches intact', () => {
@@ -176,7 +177,7 @@ describe('conformance — ternaries and exact Math', () => {
it('compiles and verifies', () => {
expect(diagnostics.filter((d) => d.system === 'FixtureClampSys').map((d) => d.message)).toEqual([]);
expect(clamp).toBeDefined();
- expect(verifySystem(clamp!, module.comps)).toEqual([]);
+ expect(verifySystem(clamp!, module.comps, module.fns)).toEqual([]);
});
it('keeps the ternary and the intrinsics in the IR', () => {
@@ -216,7 +217,7 @@ describe('conformance — module constants', () => {
it('compiles and verifies', () => {
expect(diagnostics.filter((d) => d.system === 'FixtureTuned').map((d) => d.message)).toEqual([]);
expect(tuned).toBeDefined();
- expect(verifySystem(tuned!, module.comps)).toEqual([]);
+ expect(verifySystem(tuned!, module.comps, module.fns)).toEqual([]);
});
it('folds the constants rather than loading them', () => {
@@ -245,3 +246,53 @@ describe('conformance — module constants', () => {
expect(byEir.comps.get('Transform')).toEqual(byNode.comps.get('Transform'));
});
});
+
+describe('conformance — pure helpers, called and inlined', () => {
+ const helpers = module.systems.find((s) => s.name === 'FixtureHelpers');
+ const inlined = helpers ? inlineSystem(helpers, module.fns) : undefined;
+
+ function runHelperNative(world: EirWorld): void {
+ const sys = helperSystem as unknown as StubSystem;
+ const transforms = world.comps.get('Transform')!;
+ const drifts = world.comps.get('FixtureDrift')!;
+ const query = {
+ *[Symbol.iterator]() {
+ for (const e of world.entities) {
+ if (transforms.has(e) && drifts.has(e)) yield [e, transforms.get(e)!, drifts.get(e)!];
+ }
+ },
+ };
+ (sys.fn as unknown as (q: unknown, t: unknown) => void)(query, world.resources.get('Time'));
+ }
+
+ it('compiles, and both forms verify', () => {
+ expect(diagnostics.filter((d) => d.system === 'FixtureHelpers').map((d) => d.message)).toEqual([]);
+ expect(helpers).toBeDefined();
+ expect(verifySystem(helpers!, module.comps, module.fns)).toEqual([]);
+ // The pass must not invalidate the IR it rewrote.
+ expect(verifySystem(inlined!, module.comps, module.fns)).toEqual([]);
+ });
+
+ it('leaves no call to a module function after inlining', () => {
+ expect(printSystem(helpers!)).toContain('clamp(');
+ expect(printSystem(helpers!)).toContain('boost(');
+ const after = printSystem(inlined!);
+ expect(after).not.toContain('clamp(');
+ expect(after).not.toContain('boost(');
+ // Arguments are bound once, not duplicated per use.
+ expect(after).toContain('let v$');
+ });
+
+ it('node, the IR, and the inlined IR all agree over 40 frames', () => {
+ const byNode = makeWorld();
+ const byEir = makeWorld();
+ const byInlined = makeWorld();
+ for (let f = 0; f < 40; f++) {
+ runHelperNative(byNode);
+ runSystem(helpers!, byEir, module.fns);
+ runSystem(inlined!, byInlined, module.fns);
+ }
+ expect(byEir.comps.get('Transform')).toEqual(byNode.comps.get('Transform'));
+ expect(byInlined.comps.get('Transform')).toEqual(byNode.comps.get('Transform'));
+ });
+});
diff --git a/compiler/tests/coverage.test.ts b/compiler/tests/coverage.test.ts
index 71f016678..f45330d43 100644
--- a/compiler/tests/coverage.test.ts
+++ b/compiler/tests/coverage.test.ts
@@ -65,9 +65,9 @@ const seen = results.flatMap((r) => r.seen);
const diagnostics = results.flatMap((r) => r.diagnostics);
const systemBindings = new Map(results.flatMap((r) => [...r.systemBindings]));
const verifiedNames = new Set(results.flatMap(
- (r) => r.module.systems.filter((s) => verifySystem(s, r.module.comps).length === 0).map((s) => s.name)));
+ (r) => r.module.systems.filter((s) => verifySystem(s, r.module.comps, r.module.fns).length === 0).map((s) => s.name)));
const unverified = results.flatMap((r) => r.module.systems
- .map((s) => ({ name: s.name, errors: verifySystem(s, r.module.comps) }))
+ .map((s) => ({ name: s.name, errors: verifySystem(s, r.module.comps, r.module.fns) }))
.filter((x) => x.errors.length > 0));
const SCHEDULED = /addSystemToSchedule\s*\(\s*Schedule\.\w+\s*,\s*(\w+)\s*\)/g;
diff --git a/compiler/tests/fixtures/in-subset.ts b/compiler/tests/fixtures/in-subset.ts
index 263250846..5b507bcf0 100644
--- a/compiler/tests/fixtures/in-subset.ts
+++ b/compiler/tests/fixtures/in-subset.ts
@@ -72,3 +72,22 @@ export const tunedSystem = defineSystem(
},
{ name: 'FixtureTuned' },
);
+
+// The shape examples/camera-follow writes: a module-level pure helper called
+// once per row. It must not still be a call after the inline pass.
+const clamp = (v: number, lo: number, hi: number) => (v < lo ? lo : v > hi ? hi : v);
+function boost(v: number, on: boolean): number {
+ return on ? v * 2 : v;
+}
+
+export const helperSystem = defineSystem(
+ [Query(Mut(Transform), Drift), Res(Time)],
+ (query, time) => {
+ for (const [, transform, drift] of query) {
+ const step = boost(drift.rate * time.delta, drift.enabled);
+ transform.position.x = clamp(transform.position.x + step, -80, 80);
+ transform.position.y = clamp(boost(step, true), -10, 10);
+ }
+ },
+ { name: 'FixtureHelpers' },
+);
diff --git a/compiler/tests/fixtures/outside-subset.ts b/compiler/tests/fixtures/outside-subset.ts
index 1adf3ff3d..5d334b807 100644
--- a/compiler/tests/fixtures/outside-subset.ts
+++ b/compiler/tests/fixtures/outside-subset.ts
@@ -50,7 +50,9 @@ export const trig = defineSystem(
{ name: 'FixtureTrig' },
);
-function damp(v: number): number {
+// No annotation: the subset takes a parameter's type from the source, and there
+// is nothing here to take.
+function damp(v): number {
return v * 0.5;
}
diff --git a/compiler/tests/move-system.test.ts b/compiler/tests/move-system.test.ts
index cbd0916cf..309eb2494 100644
--- a/compiler/tests/move-system.test.ts
+++ b/compiler/tests/move-system.test.ts
@@ -101,7 +101,7 @@ describe('Stage 1 — a real example system, end to end', () => {
});
it('re-proves its own types without looking at the TypeScript', () => {
- expect(verifySystem(moveEir!, module.comps)).toEqual([]);
+ expect(verifySystem(moveEir!, module.comps, module.fns)).toEqual([]);
});
it('picks up Mover from defineComponent as a compile-time declaration', () => {
diff --git a/compiler/tests/subset.test.ts b/compiler/tests/subset.test.ts
index e14b7afda..d1142ea32 100644
--- a/compiler/tests/subset.test.ts
+++ b/compiler/tests/subset.test.ts
@@ -35,7 +35,7 @@ describe('the subset refuses, and says why', () => {
['FixtureLooping', /WhileStatement is not a statement/],
['FixtureTypo', /has no field 'valeu'/],
['FixtureTrig', /Math\.sin is not exactly specified by ECMAScript/],
- ['FixtureCalling', /CallExpression is not an expression/],
+ ['FixtureCalling', /'damp' cannot be lowered: parameter 'v' needs a type annotation/],
['FixtureWritesConst', /'LIMIT' is a constant and cannot be assigned/],
])('refuses %s', (name, why) => {
const d = diagOf(name);
@@ -55,7 +55,7 @@ describe('the subset refuses, and says why', () => {
it('…and the verifier refuses it on the IR alone', () => {
const sys = result.module.systems.find((s) => s.name === 'FixtureWritesReadOnly')!;
- const errors = verifySystem(sys, result.module.comps);
+ const errors = verifySystem(sys, result.module.comps, result.module.fns);
expect(errors).toHaveLength(1);
expect(errors[0]!.message).toMatch(/is written but the query asks for 'Transform' without Mut/);
});