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
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.tsindex 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.tsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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';