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 author can write down that a system must compile
yhh0ebe34a1a477
diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.tsindex 340e63482..49756b117 100644--- a/compiler/src/frontend.ts+++ b/compiler/src/frontend.ts@@ -39,6 +39,12 @@ export interface Diagnostic {readonly line: number;readonly message: string;readonly kind: RefusalKind;+ /**+ * Whether the author PROMISED this would compile. `@compiled` on a system+ * makes its refusal an error: without the marker a system that quietly stops+ * compiling just gets slower, and nothing anywhere goes red.+ */+ readonly severity: 'error' | 'note';/** The system this killed, when the failure happened inside one. */readonly system?: string;}@@ -54,6 +60,49 @@ export interface LowerResult {* system runs per frame or once at startup.*/readonly systemBindings: ReadonlyMap<string, string>;+ /**+ * Systems the author marked `@compiled`. Compiling these is a PROMISE, and+ * `brokenPromises` is what a build asks whether it was kept.+ */+ readonly required: readonly string[];+}++/**+ * A `@compiled` tag, read straight off the parse tree. `ts.getJSDocTags` walks+ * parent pointers, which this file may not touch (see the header); `node.jsDoc`+ * is what the parser attached and needs nothing bound.+ */+interface WithJsDoc {+ readonly jsDoc?: readonly ts.JSDoc[];+}++function marksCompiled(node: ts.Node): boolean {+ const doc = (node as WithJsDoc).jsDoc;+ if (!doc) return false;+ return doc.some((d) => d.tags?.some((t) => t.tagName.text === 'compiled') ?? false);+}++/**+ * The promises this program did not keep: every marked system that refused, plus+ * any that vanished without a diagnostic. A build fails on this list; an unmarked+ * refusal stays a note, because §3.2's fallback is a design and not a defect.+ */+export function brokenPromises(result: LowerResult): readonly Diagnostic[] {+ const compiled = new Set(result.module.systems.map((s) => s.name));+ const spoken = new Set<string>();+ const out = result.diagnostics.filter((d) => {+ if (d.severity !== 'error') return false;+ if (d.system) spoken.add(d.system);+ return true;+ });+ for (const name of result.required) {+ if (compiled.has(name) || spoken.has(name)) continue;+ out.push({+ file: '', line: 0, kind: 'pending', severity: 'error', system: name,+ message: `'${name}' is marked @compiled but the compiler never produced it`,+ });+ }+ return out;}const BIN_OPS: ReadonlyMap<ts.SyntaxKind, BinOp> = new Map([@@ -698,6 +747,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<strconst diagnostics: Diagnostic[] = [];const seen: string[] = [];const systemBindings = new Map<string, string>();+ const required: 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.@@ -708,17 +758,20 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str// Both scans carry the enclosing `const` name down instead of reading// node.parent: parent pointers exist only once the program has bound, which// is a side effect of getTypeChecker() and not a thing to depend on.- type Visit = (node: ts.Node, binding: string | null) => void;+ /** `marked` is the `@compiled` tag from the enclosing statement, carried down+ * to the `defineSystem` call the same way `binding` is. */+ type Visit = (node: ts.Node, binding: string | null, marked: boolean) => void;const walkTop = (sf: ts.SourceFile, visit: Visit): void => {- const go = (node: ts.Node, binding: string | null): void => {- visit(node, binding);+ const go = (node: ts.Node, binding: string | null, marked: boolean): void => {+ const here = marked || marksCompiled(node);+ visit(node, binding, here);if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {- go(node.initializer, node.name.text);+ go(node.initializer, node.name.text, here);return;}- ts.forEachChild(node, (c) => go(c, null));+ ts.forEachChild(node, (c) => go(c, null, here));};- ts.forEachChild(sf, (c) => go(c, null));+ ts.forEachChild(sf, (c) => go(c, null, false));};// Constants and components first: a system in one file names both from another.@@ -739,7 +792,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<strif (!shape) {diagnostics.push({file: sf.fileName, line: lineOf(sf, node),- kind: 'permanent',+ kind: 'permanent', severity: 'note',message: 'defineComponent needs a string literal name and an object literal of literal defaults',});return;@@ -747,7 +800,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<strconst existing = comps.get(shape.name);if (existing && !sameShape(existing, shape)) {diagnostics.push({- file: sf.fileName, line: lineOf(sf, node), kind: 'permanent',+ file: sf.fileName, line: lineOf(sf, node), kind: 'permanent', severity: 'note',message: `component '${shape.name}' is already declared with a different shape`+ ` — one program cannot hold two`,});@@ -786,12 +839,13 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str}for (const sf of sources) {- walkTop(sf, (node, binding) => {+ walkTop(sf, (node, binding, marked) => {if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return;if (node.expression.text !== 'defineSystem') return;const name = systemName(node, binding);seen.push(name);if (binding) systemBindings.set(binding, name);+ if (marked) required.push(name);try {const [params, fn] = node.arguments;if (!params || !fn || !ts.isArrowFunction(fn)) {@@ -801,13 +855,17 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str} catch (e) {if (!(e instanceof NotInSubset)) throw e;diagnostics.push({- file: sf.fileName, line: lineOf(sf, e.node), message: e.message, kind: e.kind, system: name,+ file: sf.fileName, line: lineOf(sf, e.node), message: e.message, kind: e.kind,+ // The marker does not change WHY a system was refused, only+ // whether anybody has to act on it.+ severity: marked ? 'error' : 'note',+ system: name,});}});}- return { module: { systems, comps, fns }, diagnostics, seen, systemBindings };+ return { module: { systems, comps, fns }, diagnostics, seen, systemBindings, required };}/** `{ name: 'MoveSystem' }` if given, else the const it is assigned to. */diff --git a/compiler/src/index.ts b/compiler/src/index.tsindex ed48fec9e..00964ac58 100644--- a/compiler/src/index.ts+++ b/compiler/src/index.ts@@ -5,7 +5,7 @@* @brief Estella AOT compiler — public surface (docs/REARCH_AOT.md Stages 1-2).*/export * from './eir';-export { lowerProgram, type Diagnostic, type LowerResult } from './frontend';+export { brokenPromises, lowerProgram, type Diagnostic, type LowerResult } from './frontend';export { verifySystem, type VerifyError } from './verify';export { runSystem, type EirWorld, type Fns, type Row } from './interp';export { inlineModule, inlineSystem } from './inline';diff --git a/compiler/tests/coverage.test.ts b/compiler/tests/coverage.test.tsindex 8bdb7bbbc..9ae8adf34 100644--- a/compiler/tests/coverage.test.ts+++ b/compiler/tests/coverage.test.ts@@ -30,7 +30,7 @@ import { describe, it, expect } from 'vitest';import { readFileSync, readdirSync, statSync } from 'node:fs';import { join, resolve, sep } from 'node:path';import { fileURLToPath } from 'node:url';-import { lowerProgram } from '../src/frontend';+import { brokenPromises, lowerProgram } from '../src/frontend';import { verifySystem } from '../src/verify';import { builtinShapes } from '../src/builtins';@@ -183,3 +183,28 @@ describe('AOT coverage over examples/', () => {expect(unverified).toEqual([]);});});++/**+ * The coverage number above measures a corpus nobody promised anything about.+ * This one measures the promises: a system carrying `@compiled` must compile and+ * verify, and a refusal against one is an error rather than a quiet fallback.+ * It is the number that can be 100% and STAY 100%.+ */+describe('systems the corpus promises to compile', () => {+ const promised = results.flatMap((r) => r.required);++ it('finds the marker in the corpus at all', () => {+ // At zero this whole block asserts nothing, which is the failure a gate+ // is least able to notice about itself.+ expect(promised.length).toBeGreaterThan(0);+ console.log(`@compiled promises: ${promised.length} — ${promised.join(', ')}`);+ });++ it('keeps every one of them', () => {+ expect(results.flatMap((r) => brokenPromises(r))).toEqual([]);+ });++ it('and each also verifies, not merely lowers', () => {+ expect(promised.filter((n) => !verifiedNames.has(n))).toEqual([]);+ });+});diff --git a/compiler/tests/fixtures/outside-subset.ts b/compiler/tests/fixtures/outside-subset.tsindex 5d334b807..ced581587 100644--- a/compiler/tests/fixtures/outside-subset.ts+++ b/compiler/tests/fixtures/outside-subset.ts@@ -91,3 +91,35 @@ export const writesConst = defineSystem(},{ name: 'FixtureWritesConst' },);++/**+ * The same refusal as `FixtureTrig`, but PROMISED.+ *+ * @compiled+ * Without the marker a system that stops compiling just gets slower and nothing+ * goes red; with it, the refusal is an error naming this line.+ */+export const promised = defineSystem(+ [Query(Mut(Transform), Speed), Res(Time)],+ (query, time) => {+ for (const [_e, t, s] of query) {+ t.position.x += Math.cos(s.value * time.delta);+ }+ },+ { name: 'FixturePromised' },+);++/**+ * Marked, and inside the subset: the promise is kept.+ *+ * @compiled+ */+export const promiseKept = defineSystem(+ [Query(Mut(Transform), Speed), Res(Time)],+ (query, time) => {+ for (const [_e, t, s] of query) {+ t.position.x += s.value * time.delta;+ }+ },+ { name: 'FixturePromiseKept' },+);diff --git a/compiler/tests/subset.test.ts b/compiler/tests/subset.test.tsindex d1142ea32..65332a740 100644--- a/compiler/tests/subset.test.ts+++ b/compiler/tests/subset.test.ts@@ -11,7 +11,7 @@import { describe, it, expect } from 'vitest';import { resolve } from 'node:path';import { fileURLToPath } from 'node:url';-import { lowerProgram } from '../src/frontend';+import { brokenPromises, lowerProgram } from '../src/frontend';import { verifySystem } from '../src/verify';import { builtinShapes } from '../src/builtins';@@ -28,6 +28,7 @@ describe('the subset refuses, and says why', () => {expect(result.seen).toEqual(['FixtureLooping', 'FixtureTypo', 'FixtureTrig', 'FixtureCalling','FixtureWritesReadOnly', 'FixtureWritesConst',+ 'FixturePromised', 'FixturePromiseKept',]);});@@ -67,3 +68,29 @@ describe('the subset refuses, and says why', () => {expect(dyn.diagnostics[0]!.message).toMatch(/object literal of literal defaults/);});});++/**+ * `@compiled` does not change what the subset takes; it changes who has to act.+ * An unmarked refusal is §3.2's design. A marked one is a build error.+ */+describe('a promise the author wrote down', () => {+ it('sees the marker, and only where it was written', () => {+ expect(result.required).toEqual(['FixturePromised', 'FixturePromiseKept']);+ });++ it('makes the same refusal an error, with the same reason and line', () => {+ const promised = diagOf('FixturePromised')!;+ const unmarked = diagOf('FixtureTrig')!;+ expect(promised.severity).toBe('error');+ expect(unmarked.severity).toBe('note');+ // The marker is not a second rule: both are refused for the same reason.+ expect(promised.message).toMatch(/Math\.cos is not exactly specified/);+ expect(promised.kind).toBe(unmarked.kind);+ expect(promised.line).toBeGreaterThan(0);+ });++ it('a kept promise is not a broken one', () => {+ expect(compiled('FixturePromiseKept')).toBe(true);+ expect(brokenPromises(result).map((d) => d.system)).toEqual(['FixturePromised']);+ });+});diff --git a/examples/ecs-basics/src/systems/move.ts b/examples/ecs-basics/src/systems/move.tsindex 61fce6e98..2b87f63d7 100644--- a/examples/ecs-basics/src/systems/move.ts+++ b/examples/ecs-basics/src/systems/move.ts@@ -3,6 +3,13 @@ import {} from 'esengine';import { Mover } from '../components';+/**+ * Moves every entity by its direction and speed, once per frame.+ *+ * @compiled+ * A promise, not a hint: anything the subset cannot lower is a build error here+ * rather than a silent fall back to the interpreter (REARCH_AOT_ABI.md §4.1).+ */export const moveSystem = defineSystem([Query(Mut(Transform), Mover), Res(Time)],(query, time) => {