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): a duty says which differential holds it, or says nobody does

yhhbd2087fb127a
diff --git a/fixtures/aot-conformance/src/main.ts b/fixtures/aot-conformance/src/main.ts
index ff66d4bc6..8de858708 100644
--- a/fixtures/aot-conformance/src/main.ts
+++ b/fixtures/aot-conformance/src/main.ts
@@ -2,7 +2,7 @@
// The reporting is game code on purpose — a host-side dump would be a second
// path nobody ships.
import {
- addStartupSystem, addSystemToSchedule, Commands, defineSystem,
+ addStartupSystem, addSystemToSchedule, Changed, Commands, defineSystem,
Query, Res, Schedule, Time,
} from 'esengine';
@@ -19,6 +19,17 @@ const spawnSystem = defineSystem(
);
let frame = 0;
+let ticked = 0;
+
+/** What a `Changed` filter matched this frame: the one duty no value shows. */
+const watchSystem = defineSystem(
+ [Query(Changed(Mover))],
+ (query) => {
+ ticked = 0;
+ for (const _row of query) ticked++;
+ },
+ { name: 'ConfWatch' },
+);
/** Last in the schedule, and not `@compiled`: it reads what the two above left.
* The delta goes out with the rows because a road that stepped by another one
@@ -29,7 +40,7 @@ const reportSystem = defineSystem(
const rows: number[][] = [];
for (const [, m] of query) rows.push([m.x, m.speed, m.bounces]);
console.log(`CONF ${frame} ${time.delta} ${JSON.stringify(rows)} `
- + `${JSON.stringify([tally.bounces, tally.frames])}`);
+ + `${JSON.stringify([tally.bounces, tally.frames])} ${ticked}`);
frame++;
},
{ name: 'ConfReport' },
@@ -39,4 +50,5 @@ addStartupSystem(spawnSystem);
addSystemToSchedule(Schedule.Update, driftSystem);
addSystemToSchedule(Schedule.Update, clampSystem);
addSystemToSchedule(Schedule.Update, tallySystem);
+addSystemToSchedule(Schedule.Update, watchSystem);
addSystemToSchedule(Schedule.Update, reportSystem);
diff --git a/sdk/tests/aot-conformance.test.ts b/sdk/tests/aot-conformance.test.ts
index 8951b2873..4e7b9984d 100644
--- a/sdk/tests/aot-conformance.test.ts
+++ b/sdk/tests/aot-conformance.test.ts
@@ -31,7 +31,8 @@ import { setEditorMode, setPlayMode } from '../src/ecs/env';
import { createMockModule } from './mocks/wasm';
import { FakeEngine } from './fakeEngine';
import { buildAotModule, useBytesPlatform } from './helpers/aotFade';
-import { Schedule } from '../src/ecs/system';
+import { Schedule, defineSystem } from '../src/ecs/system';
+import { Query, Changed } from '../src/ecs/query';
import { Time } from '../src/ecs/resource';
import type { AotManifest } from '../src/ecs/aot/AotSystems';
import type { Entity } from '../src/types';
@@ -83,9 +84,11 @@ function compileFixture(emcc: string): { wasm: Uint8Array; manifest: AotManifest
type Trace = number[][][];
/** The resource one of them WRITES, after each frame: [bounces, frames]. */
type ResTrace = number[][];
+/** How many rows a `Changed(Mover)` watcher matched, after each frame. */
+type TickTrace = number[];
async function play(compiled: { wasm: Uint8Array; manifest: AotManifest } | null): Promise<{
- trace: Trace; resource: ResTrace; calls: number; delta: number;
+ trace: Trace; resource: ResTrace; ticks: TickTrace; calls: number; delta: number;
}> {
// One context for both roads on purpose: the fixture's `defineComponent`
// runs once, at import, and a road that reset the registry under it would
@@ -98,6 +101,16 @@ async function play(compiled: { wasm: Uint8Array; manifest: AotManifest } | null
app.addSystemToSchedule(Schedule.Update, fixture.driftSystem);
app.addSystemToSchedule(Schedule.Update, fixture.clampSystem);
app.addSystemToSchedule(Schedule.Update, fixture.tallySystem);
+ // Interpreted, and last: the Changed ticks a twin leaves are the one duty
+ // no value in the trace can show. A watcher counts what a filter matched,
+ // which is the same question a game asks of change detection.
+ const ticks: TickTrace = [];
+ app.addSystemToSchedule(Schedule.Update, defineSystem([Query(Changed(fixture.Mover))],
+ (query) => {
+ let n = 0;
+ for (const _row of query) n++;
+ ticks.push(n);
+ }, { name: 'ConfWatch' }));
// NOT inserted: a project resource nothing has touched yet is exactly the
// case a shipped game boots in, and the handshake has to find it by the name
// the manifest carries or refuse the module over a resource that is there.
@@ -136,7 +149,7 @@ async function play(compiled: { wasm: Uint8Array; manifest: AotManifest } | null
// would be a second opinion about the frame rather than a reading of it.
const time = (app as unknown as { resources_: { get: (r: unknown) => { delta: number } } })
.resources_.get(Time);
- return { trace, resource, calls: runtime?.systems.calls ?? 0, delta: time.delta };
+ return { trace, resource, ticks, calls: runtime?.systems.calls ?? 0, delta: time.delta };
}
describe.skipIf(!EMCC)('one source, interpreted and compiled', () => {
@@ -162,10 +175,16 @@ describe.skipIf(!EMCC)('one source, interpreted and compiled', () => {
// that never copied the mirror back would leave it at its default
// while every row above still agreed.
expect([f, twins.resource[f]]).toEqual([f, interpreted.resource[f]]);
+ // The ticks the compiled code could not leave, which the host has
+ // to mark instead. Nothing in the world's VALUES shows them.
+ expect([f, twins.ticks[f]]).toEqual([f, interpreted.ticks[f]]);
}
// And the run went somewhere: a fixture whose systems do nothing agrees
// on every road.
expect(interpreted.trace[FRAMES - 1]).not.toEqual(interpreted.trace[0]);
+ // A watcher that matched nothing agrees on every road: the tick
+ // comparison above is only worth running if something was ticked.
+ expect(interpreted.ticks.some((n) => n > 0)).toBe(true);
});
});
@@ -347,6 +366,10 @@ describe('the inputs a loading host builds against', () => {
// row above still agrees, which is why it is traced separately.
resourceFields: ['bounces', 'frames'],
resource: run.resource,
+ // What a `Changed(Mover)` filter matched after each frame. Nothing
+ // in the values above shows a tick, and a road that stopped marking
+ // them agrees with every other column.
+ ticks: run.ticks,
}, null, 2)}\n`);
});
diff --git a/tests/aot/generated/conformance/trace.json b/tests/aot/generated/conformance/trace.json
index db8222dee..0730e3e29 100644
--- a/tests/aot/generated/conformance/trace.json
+++ b/tests/aot/generated/conformance/trace.json
@@ -346,5 +346,19 @@
46,
12
]
+ ],
+ "ticks": [
+ 0,
+ 4,
+ 4,
+ 4,
+ 4,
+ 4,
+ 4,
+ 4,
+ 4,
+ 4,
+ 4,
+ 4
]
}
diff --git a/tools/check-aot-duties.mjs b/tools/check-aot-duties.mjs
index 4acf21724..030bec714 100644
--- a/tools/check-aot-duties.mjs
+++ b/tools/check-aot-duties.mjs
@@ -111,6 +111,37 @@ for (const duty of DUTIES) {
}
}
+/**
+ * The other half: is what a road performs held against the INTERPRETER anywhere?
+ *
+ * `resource-write-back` was implemented on both roads and accounted for here
+ * while no source form existed that both lowered the same way. An expectation
+ * test agrees with whatever the road happens to do; only a differential does not.
+ */
+for (const duty of DUTIES) {
+ const held = duty.differential ?? [];
+ if (held.length === 0) {
+ if (!duty.owed) {
+ findings.push(`${duty.id}: no differential holds it against the interpreter, and no `
+ + '`owed` says so. A duty checked only for presence is a duty nothing verifies.');
+ }
+ continue;
+ }
+ if (duty.owed) {
+ findings.push(`${duty.id}: \`owed\` says nothing holds it, and ${held.length} `
+ + 'differential(s) are named. One of the two has stopped being true.');
+ }
+ for (const at of held) {
+ let src = null;
+ try { src = read(at.path); } catch { src = null; }
+ if (src === null) findings.push(`${duty.id}: ${at.path} is gone, and it is named as holding it.`);
+ else if (!at.probe.test(src)) {
+ findings.push(`${duty.id}: ${at.path} no longer matches ${at.probe} — the differential `
+ + 'this list points at has moved or been dropped.');
+ }
+ }
+}
+
// 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) {
@@ -149,6 +180,10 @@ if (findings.length > 0) {
process.exit(1);
}
const skipped = DUTIES.filter((d) => ROADS.some((r) => d[r.id] === null)).length;
+const owed = DUTIES.filter((d) => (d.differential ?? []).length === 0);
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.`);
+console.log(` ${DUTIES.length - owed.length} held against the interpreter by a differential; `
+ + `${owed.length} owed one:`);
+for (const d of owed) console.log(` ${d.id}: ${d.owed}`);
diff --git a/tools/lib/aotDuties.mjs b/tools/lib/aotDuties.mjs
index 885202132..ab9e4c45f 100644
--- a/tools/lib/aotDuties.mjs
+++ b/tools/lib/aotDuties.mjs
@@ -39,42 +39,65 @@ export const DUTIES = [
// and is told where the script pools are.
web: ['runtime.addresses.componentNamed', 'runtime.ctx.build'],
native: ['world.scriptSpanOf', 'bindings.scriptRows'],
+ differential: [
+ { path: 'sdk/tests/aot-conformance.test.ts', probe: /twins\.trace\[f\]/ },
+ { path: 'tools/verify-native-conformance.mjs', probe: /disagrees at frame/ },
+ ],
},
{
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'],
+ // The fixture seeds a world and never moves a row in it, so the cached
+ // table is never invalidated on any road. Nothing holds the REUSE.
+ owed: 'a differential whose world gains and loses rows mid-run',
},
{
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'],
+ // Jointly with the rows: `Res(Time)` is what moves them, so a resource
+ // at the wrong address is a row that disagrees on frame 0.
+ differential: [{ path: 'sdk/tests/aot-conformance.test.ts', probe: /twins\.trace\[f\]/ }],
},
{
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'],
+ differential: [
+ { path: 'sdk/tests/aot-conformance.test.ts', probe: /twins\.resource\[f\]/ },
+ { path: 'tools/verify-native-conformance.mjs', probe: /about the resource/ },
+ ],
},
{
id: 'call',
what: 'the compiled function runs',
web: ['twin.call'],
native: ['bindings.run'],
+ differential: [{ path: 'sdk/tests/aot-conformance.test.ts', probe: /twins\.trace\[f\]/ }],
},
{
id: 'call-counted',
what: 'App.compiledSystems can tell a module that loaded from one that ran',
web: ['runtime.systems.noteCall'],
native: ['systems.noteCall'],
+ differential: [
+ { path: 'sdk/tests/aot-conformance.test.ts', probe: /twins\.calls/ },
+ { path: 'tools/verify-native-conformance.mjs', probe: /were dispatched to/ },
+ ],
},
{
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'],
+ differential: [
+ { path: 'sdk/tests/aot-conformance.test.ts', probe: /twins\.ticks\[f\]/ },
+ { path: 'tools/verify-native-conformance.mjs', probe: /changed row\(s\) at frame/ },
+ ],
},
{
id: 'event-payloads-in',
@@ -82,6 +105,7 @@ export const DUTIES = [
web: ['runtime.addresses.payloadRows'],
native: null,
excusedBy: 'eventRead',
+ owed: 'the fixture has no events and no despawn, so nothing holds the WEB road here',
},
{
id: 'event-payloads-released',
@@ -89,6 +113,7 @@ export const DUTIES = [
web: ['runtime.addresses.releasePayloads'],
native: null,
excusedBy: 'eventRead',
+ owed: 'the fixture has no events and no despawn, so nothing holds the WEB road here',
},
{
id: 'event-records-sized',
@@ -96,6 +121,7 @@ export const DUTIES = [
web: ['runtime.ctx.setRecordLengths'],
native: null,
excusedBy: 'eventWrite',
+ owed: 'the fixture has no events and no despawn, so nothing holds the WEB road here',
},
{
id: 'events-out',
@@ -103,6 +129,7 @@ export const DUTIES = [
web: ['runtime.ctx.events', 'runtime.addresses.sendEvent'],
native: null,
excusedBy: 'eventWrite',
+ owed: 'the fixture has no events and no despawn, so nothing holds the WEB road here',
},
{
id: 'commands-out',
@@ -110,6 +137,7 @@ export const DUTIES = [
web: ['runtime.ctx.commands', 'world.despawn'],
native: null,
excusedBy: 'commands',
+ owed: 'the fixture has no events and no despawn, so nothing holds the WEB road here',
},
];
diff --git a/tools/verify-native-conformance.mjs b/tools/verify-native-conformance.mjs
index cfe527be7..b8603b248 100644
--- a/tools/verify-native-conformance.mjs
+++ b/tools/verify-native-conformance.mjs
@@ -101,14 +101,14 @@ function play(compiled) {
}
}
-/** `CONF <frame> <delta> <rows> <resource>` — what the fixture's reporter says. */
+/** `CONF <frame> <delta> <rows> <resource> <ticks>` — what the reporter says. */
function framesIn(log) {
const out = [];
for (const line of log.split('\n')) {
- const m = /CONF (\d+) (\S+) (\[.*\]) (\[[^\]]*\])\s*$/.exec(line);
+ const m = /CONF (\d+) (\S+) (\[.*\]) (\[[^\]]*\]) (\d+)\s*$/.exec(line);
if (m !== null) {
out.push({ at: Number(m[1]), delta: Number(m[2]), rows: JSON.parse(m[3]),
- resource: JSON.parse(m[4]) });
+ resource: JSON.parse(m[4]), ticks: Number(m[5]) });
}
}
return out;
@@ -147,6 +147,11 @@ function compare(road, got) {
host ${frame.resource[k]}`);
}
}
+ // The Changed ticks a twin could not leave, which the host marks instead.
+ if (frame.ticks !== want.ticks[f]) {
+ fail(`${road} matched ${frame.ticks} changed row(s) at frame ${f}, and the `
+ + `interpreter matched ${want.ticks[f]}`);
+ }
for (let i = 0; i < wantRows.length; i++) {
for (let k = 0; k < wantRows[i].length; k++) {
if (frame.rows[i][k] !== wantRows[i][k]) {