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.

fix(aot): the two roads are clocked against each other, duty by duty

yhh81d5702eedd7
diff --git a/sdk/src/ecs/aot/installNativeAot.ts b/sdk/src/ecs/aot/installNativeAot.ts
index b2575f5b9..ce7b42f50 100644
--- a/sdk/src/ecs/aot/installNativeAot.ts
+++ b/sdk/src/ecs/aot/installNativeAot.ts
@@ -179,7 +179,7 @@ export function installNativeAot(opts: InstallNativeAotOptions): AotRuntime | nu
} as unknown as AotRuntime['addresses'],
ctx: null as unknown as AotRuntime['ctx'],
dispatcherFor: (world) =>
- new NativeAotDispatch(world, bindings, byName, pooled, resources),
+ new NativeAotDispatch(world, bindings, byName, pooled, resources, systems),
};
opts.runner.useAot(runtime);
return runtime;
@@ -204,6 +204,7 @@ class NativeAotDispatch implements AotDispatcher {
private readonly indexByName: ReadonlyMap<string, number>,
private readonly pooled: ReadonlySet<string>,
private readonly resources: AotResources,
+ private readonly systems: AotSystems,
) {}
run(twin: AotTwin): boolean {
@@ -219,6 +220,10 @@ class NativeAotDispatch implements AotDispatcher {
// reads — a pool with no rows yet, a resource nothing has written.
// The interpreter keeps it this frame and it is asked again next.
if (this.bindings.run(at, this.world.scriptLayoutEpoch()) < 0) return false;
+ // The counter `App.compiledSystems` reports to say installed is not RAN.
+ // It was web-only, so on the road whose fallback is by design the
+ // instrument for spotting one answered 0 every frame.
+ this.systems.noteCall();
// Once, the first time the host takes it. "Installed" says a module
// loaded; this says a system is actually running as machine code, and
// the two are different frames when a pool has to exist first.
diff --git a/sdk/tests/aot-native-install.test.ts b/sdk/tests/aot-native-install.test.ts
index d5073c069..521b8802c 100644
--- a/sdk/tests/aot-native-install.test.ts
+++ b/sdk/tests/aot-native-install.test.ts
@@ -341,6 +341,20 @@ describe('a capability a loading host cannot hand compiled code', () => {
expect(f.world.valid(entity)).toBe(false);
});
+ it('counts the calls it took, which is what says installed is not ran', () => {
+ const f = eventFixture();
+ const plain = defineSystem([Query(Mut(f.Drift))], () => {}, { name: 'PlainSystem' });
+ const entity = f.world.spawn();
+ f.world.insert(entity, f.Drift, { x: 0 });
+ f.runner.run(plain);
+ f.runner.run(plain);
+
+ // `App.compiledSystems` reports this to answer one question: a module
+ // that loaded and was never dispatched to. Counted on the wasm road
+ // only, so on the road whose fallback is by DESIGN it read 0 forever.
+ expect(f.runtime!.systems.calls).toBe(2);
+ });
+
it('and takes the system that needs none of it', () => {
const f = eventFixture();
const plain = defineSystem([Query(Mut(f.Drift))], () => {
diff --git a/tools/check-aot-duties.mjs b/tools/check-aot-duties.mjs
new file mode 100644
index 000000000..4acf21724
--- /dev/null
+++ b/tools/check-aot-duties.mjs
@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-aot-duties — every road performs each duty, or refuses the
+ * systems that need it. There is no third answer.
+ *
+ * Holds `tools/lib/aotDuties.mjs` against what the two dispatchers actually
+ * call, so the ledger cannot claim a duty the code stopped doing and a call it
+ * has never heard of is a finding.
+ *
+ * The excuse is checked too: a duty a road skips must name a capability
+ * `executorCapabilities.ts` really turns OFF, or the systems it was supposed to
+ * keep away are being taken.
+ *
+ * node tools/check-aot-duties.mjs
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DUTIES, BOOKKEEPING, ROADS, CAPABILITIES_AT } from './lib/aotDuties.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
+const findings = [];
+
+/**
+ * Every effectful call a class body makes, as `receiver.method`.
+ *
+ * `this.thing_(...)` is an own helper, and its body is in this same slice so
+ * whatever IT calls is already counted. Anything else that looks like one is
+ * REPORTED: the convention is what makes this scan complete.
+ */
+function callsIn(rel, className) {
+ const src = read(rel);
+ const at = src.indexOf(`class ${className}`);
+ if (at < 0) return null;
+ const body = src.slice(at);
+ const out = new Set();
+ for (const m of body.matchAll(/\bthis\.([A-Za-z_][\w]*)((?:\.[A-Za-z_][\w]*)*)\s*\(/g)) {
+ if (m[2] === '') {
+ if (!m[1].endsWith('_')) {
+ findings.push(`${rel}: this.${m[1]}() is neither a field call nor a `
+ + 'trailing-underscore helper — this scan cannot classify it.');
+ }
+ continue;
+ }
+ out.add(m[1] + m[2]);
+ }
+ // The twin is handed in rather than held, and calling it is the duty this
+ // whole file is about.
+ for (const m of body.matchAll(/\btwin\.([A-Za-z_][\w]*)\s*\(/g)) out.add(`twin.${m[1]}`);
+ return out;
+}
+
+/** The capability set a road declares, read out of the model it is declared in. */
+function capabilitiesOf(name) {
+ const src = read(CAPABILITIES_AT);
+ const block = new RegExp(`export const ${name}[^=]*=\\s*\\{([^}]*)\\}`).exec(src);
+ if (block === null) return null;
+ const out = {};
+ for (const m of block[1].matchAll(/([A-Za-z_][\w]*)\s*:\s*(true|false)/g)) out[m[1]] = m[2] === 'true';
+ return out;
+}
+
+const made = new Map();
+for (const road of ROADS) {
+ const calls = callsIn(road.path, road.className);
+ if (calls === null) {
+ findings.push(`${road.path} no longer declares class ${road.className} — this gate reads it.`);
+ continue;
+ }
+ made.set(road.id, calls);
+}
+
+const claimed = new Set(Object.keys(BOOKKEEPING));
+for (const duty of DUTIES) {
+ for (const road of ROADS) {
+ const performs = duty[road.id];
+ const calls = made.get(road.id);
+ if (calls === undefined) continue;
+
+ if (performs === null || performs === undefined) {
+ // The whole point: not performing is only allowed with a reason the
+ // model actually enforces.
+ if (!duty.excusedBy) {
+ findings.push(`${duty.id}: the ${road.id} road does not perform it and names no `
+ + 'capability that keeps such a system off this road.');
+ continue;
+ }
+ const caps = capabilitiesOf(road.capabilities);
+ if (caps === null) {
+ findings.push(`${CAPABILITIES_AT} no longer declares ${road.capabilities} as a `
+ + 'literal this gate can read.');
+ } else if (caps[duty.excusedBy] === undefined) {
+ findings.push(`${duty.id}: excused by '${duty.excusedBy}', which ${road.capabilities} `
+ + 'does not declare.');
+ } else if (caps[duty.excusedBy] !== false) {
+ findings.push(`${duty.id}: excused by '${duty.excusedBy}', but ${road.capabilities} has `
+ + 'it ON — the systems this duty serves are being taken by a road that skips it.');
+ }
+ continue;
+ }
+
+ for (const call of performs) {
+ claimed.add(call);
+ if (!calls.has(call)) {
+ findings.push(`${duty.id}: the ${road.id} road is said to perform it with `
+ + `\`${call}\`, which ${road.className} no longer calls.`);
+ }
+ }
+ }
+}
+
+// A call nothing accounts for. This is the direction all three known bugs came
+// from — one road grew a step and the other did not.
+for (const road of ROADS) {
+ for (const call of made.get(road.id) ?? []) {
+ if (!claimed.has(call)) {
+ findings.push(`${road.className} calls \`${call}\`, and no duty names it — either it is a `
+ + 'duty this list owes an entry, or bookkeeping that has to say so.');
+ }
+ }
+}
+
+// An excuse nobody uses stops being true.
+const everyCall = new Set([...made.values()].flatMap((s) => [...s]));
+for (const [call, why] of Object.entries(BOOKKEEPING)) {
+ if (!everyCall.has(call)) {
+ findings.push(`BOOKKEEPING names \`${call}\` (${why}), which no road makes any more.`);
+ }
+}
+
+// And a capability that gates nothing is a capability that means nothing: it
+// would read as a promise while refusing systems for no duty at all.
+for (const road of ROADS) {
+ const caps = capabilitiesOf(road.capabilities) ?? {};
+ for (const [name, on] of Object.entries(caps)) {
+ if (on) continue;
+ if (!DUTIES.some((d) => d.excusedBy === name)) {
+ findings.push(`${road.capabilities}.${name} is off, and no duty is excused by it — it `
+ + 'refuses systems for a step nothing says this road skips.');
+ }
+ }
+}
+
+if (findings.length > 0) {
+ console.error(`check-aot-duties: ${findings.length} finding(s).`);
+ for (const f of findings) console.error(` ${f}`);
+ process.exit(1);
+}
+const skipped = DUTIES.filter((d) => ROADS.some((r) => d[r.id] === null)).length;
+console.log(`check-aot-duties: ${DUTIES.length} duties across ${ROADS.length} roads — `
+ + `${DUTIES.length - skipped} performed by both, ${skipped} refused by capability, `
+ + `${everyCall.size} call(s) accounted for.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index b72fa1377..1ee0b4422 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -226,6 +226,10 @@ export const GATES = [
// authority claims, or a cross-language pin no fact names, is a compatibility
// fact outside the compatibility system — the state EsEventOut was in.
{ id: 'contract-inventory', run: 'node tools/contract-inventory.mjs' },
+ // The two AOT roads share no code, so a step one grows and the other does not
+ // is invisible to a reader. Three were: events, commands, and the counter that
+ // exists to say a twin ran at all.
+ { id: 'aot-duties', run: 'node tools/check-aot-duties.mjs' },
// Windows deletes asynchronously: the rmdir races the unlink it just did, and
// the temp tree a test made comes back ENOTEMPTY at random. Node's retry loop
// is right there and defaults to OFF.
diff --git a/tools/lib/aotDuties.mjs b/tools/lib/aotDuties.mjs
new file mode 100644
index 000000000..885202132
--- /dev/null
+++ b/tools/lib/aotDuties.mjs
@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file aotDuties.mjs — what a road owes around one compiled call, declared.
+ *
+ * A twin replaces a closure, so everything the closure would have done to the
+ * world has to be done by the road that took it. There are two roads and they
+ * do not overlap in code at all — one packs rows into the engine's own memory,
+ * the other tells a host in another process where they are — so a duty present
+ * on one and absent on the other is not something a reader notices.
+ *
+ * Three were absent, and each was found by hand, months apart:
+ * - events, which faulted;
+ * - commands, where a despawn reached the C++ Registry and never the World,
+ * so the entity stayed in every query and its children kept rendering;
+ * - the CALL COUNTER, which `App.compiledSystems` publishes to answer "did a
+ * twin ever actually run" — and which the loading road never incremented,
+ * so the instrument for spotting a silent fallback read 0 on the road whose
+ * fallback is by design.
+ *
+ * So the roads are clocked rather than read. Every effectful call each one makes
+ * is named here, as a duty both perform or as one a CAPABILITY keeps off the
+ * road that cannot (`sdk/src/ecs/aot/executorCapabilities.ts`). There is no
+ * third answer: a duty a road neither performs nor refuses systems for is the
+ * shape all three bugs had.
+ */
+
+/**
+ * `web` and `native` list the calls that PERFORM the duty on that road, or null
+ * where the road does not perform it — and then `excusedBy` names the capability
+ * that keeps such a system off it, which the checker holds against the model.
+ */
+export const DUTIES = [
+ {
+ id: 'row-addresses',
+ what: 'the rows a query walks are reachable by the call',
+ // Different owners, same duty: the wasm module shares the engine's
+ // memory so this side writes the table, and a loading host packs its own
+ // and is told where the script pools are.
+ web: ['runtime.addresses.componentNamed', 'runtime.ctx.build'],
+ native: ['world.scriptSpanOf', 'bindings.scriptRows'],
+ },
+ {
+ id: 'layout-vouched',
+ what: 'an address is reused only while something says the rows have not moved',
+ web: ['world.layoutEpoch'],
+ native: ['world.layoutEpoch', 'world.scriptLayoutEpoch'],
+ },
+ {
+ id: 'resource-in',
+ what: 'a declared resource is at an address for exactly this call',
+ web: ['runtime.addresses.resourceAt'],
+ native: ['resources.addressOf', 'resources.bytesOf', 'bindings.resource'],
+ },
+ {
+ id: 'resource-write-back',
+ what: 'a ResMut the call wrote lands in the world, not only in the mirror',
+ web: ['runtime.addresses.resourceWriteBack'],
+ native: ['resources.writeBack'],
+ },
+ {
+ id: 'call',
+ what: 'the compiled function runs',
+ web: ['twin.call'],
+ native: ['bindings.run'],
+ },
+ {
+ id: 'call-counted',
+ what: 'App.compiledSystems can tell a module that loaded from one that ran',
+ web: ['runtime.systems.noteCall'],
+ native: ['systems.noteCall'],
+ },
+ {
+ id: 'changed-ticks',
+ what: 'the Changed ticks the compiled code could not leave',
+ web: ['world.isChangeTracked', 'world.markChanged', 'world.queryEntities'],
+ native: ['world.isChangeTracked', 'world.markChanged', 'world.queryEntities'],
+ },
+ {
+ id: 'event-payloads-in',
+ what: "this frame's payloads reach a reader as rows",
+ web: ['runtime.addresses.payloadRows'],
+ native: null,
+ excusedBy: 'eventRead',
+ },
+ {
+ id: 'event-payloads-released',
+ what: 'the payload blocks a call was given are handed back after it',
+ web: ['runtime.addresses.releasePayloads'],
+ native: null,
+ excusedBy: 'eventRead',
+ },
+ {
+ id: 'event-records-sized',
+ what: 'the record area is sized for the payloads a writer may append',
+ web: ['runtime.ctx.setRecordLengths'],
+ native: null,
+ excusedBy: 'eventWrite',
+ },
+ {
+ id: 'events-out',
+ what: 'what the call appended is delivered as an event',
+ web: ['runtime.ctx.events', 'runtime.addresses.sendEvent'],
+ native: null,
+ excusedBy: 'eventWrite',
+ },
+ {
+ id: 'commands-out',
+ what: 'a command record reaches the world the interpreter would have used',
+ web: ['runtime.ctx.commands', 'world.despawn'],
+ native: null,
+ excusedBy: 'commands',
+ },
+];
+
+/**
+ * Calls that are a road's own bookkeeping rather than a duty to the world.
+ *
+ * Named one by one, not matched by a pattern: "it looked internal" is how a duty
+ * hides. An entry nobody makes any more is a finding, the same way a stale
+ * excuse is.
+ */
+export const BOOKKEEPING = {
+ 'plans.get': 'the per-system plan cache, which only this road has',
+ 'plans.set': 'the per-system plan cache, which only this road has',
+ 'plans.clear': 'dropping the plans on reset',
+ 'indexByName.get': "the host's index for a system name, resolved at install",
+ 'running_.has': 'so the "running compiled" line is said once per system',
+ 'running_.add': 'so the "running compiled" line is said once per system',
+};
+
+/** The two roads, and where each one's dispatcher lives. */
+export const ROADS = [
+ {
+ id: 'web',
+ path: 'sdk/src/ecs/aot/AotDispatch.ts',
+ className: 'AotDispatch',
+ capabilities: 'WEB_AOT',
+ },
+ {
+ id: 'native',
+ path: 'sdk/src/ecs/aot/installNativeAot.ts',
+ className: 'NativeAotDispatch',
+ capabilities: 'NATIVE_AOT',
+ },
+];
+
+export const CAPABILITIES_AT = 'sdk/src/ecs/aot/executorCapabilities.ts';