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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file conformance.test.ts
* @brief Every subset feature run BOTH ways and compared.
*
* @details move-system.test.ts covers the one shape a shipped system happens to
* use. This covers what the subset gained after it — locals, if /
* else-if / else, comparisons, `&&`, `!` — because a feature the
* frontend lowers but nobody runs both ways is unchecked.
*
* The oracle is the fixture itself, imported through the stubbed
* `esengine` and called with live rows, exactly as move-system does.
*/
import { describe, it, expect } from 'vitest';
import { resolve } from 'node:path';
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, helperSystem, mathSystem, gateSystem,
pingSystem, pongSystem,
} from './fixtures/in-subset';
import { PROBE, probeRow } from './probe';
import type { StubSystem } from './stubs/esengine';
const FIXTURE = resolve(fileURLToPath(new URL('./fixtures/in-subset.ts', import.meta.url)));
const ENTITIES = 48;
/** Two keys held and one not, so both answers are exercised every frame. */
function fakeInput(): { isKeyDown(k: string): boolean; isKeyPressed(k: string): boolean } {
return {
isKeyDown: (k) => k === 'KeyW',
isKeyPressed: (k) => k === 'Space',
};
}
function makeWorld(): EirWorld {
let a = 0x51ed270b >>> 0;
const rand = (): number => {
a = (a * 1664525 + 1013904223) >>> 0;
return (a >>> 8) / 16777216;
};
const transforms = new Map<number, Row>();
const drifts = new Map<number, Row>();
const entities: number[] = [];
for (let e = 1; e <= ENTITIES; e++) {
entities.push(e);
transforms.set(e, {
position: { x: (rand() - 0.5) * 260, y: 0, z: 0 },
rotation: { x: 0, y: 0, z: 0, w: 1 },
scale: { x: 1, y: 1, z: 1 },
worldPosition: { x: 0, y: 0, z: 0 },
worldRotation: { x: 0, y: 0, z: 0, w: 1 },
worldScale: { x: 1, y: 1, z: 1 },
});
// Spread rate across the `> 50` boundary and vary `enabled`, so every
// branch of the fixture is taken by some entity in every frame.
drifts.set(e, { rate: rand() * 120, wrap: 100, enabled: e % 4 !== 0 });
}
return {
entities,
comps: new Map([['Transform', transforms], ['FixtureDrift', drifts]]),
resources: new Map<string, Row>([
['Time', { delta: 1 / 30, elapsed: 0 }],
// A service, not a record: the interpreter asks it, and a compiled
// build reads what a host mirrored the same answers into.
['Input', fakeInput() as unknown as Row],
]),
};
}
function runNative(world: EirWorld): void {
const sys = driftSystem 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'));
}
const { module, diagnostics } = lowerProgram([FIXTURE], builtinShapes());
const drift = module.systems.find((s) => s.name === 'FixtureDrift');
const clamp = module.systems.find((s) => s.name === 'FixtureClampSys');
const tuned = module.systems.find((s) => s.name === 'FixtureTuned');
const gate = module.systems.find((s) => s.name === 'FixtureGate');
const ping = module.systems.find((s) => s.name === 'FixturePing');
const pong = module.systems.find((s) => s.name === 'FixturePong');
describe('conformance — locals, branches, logic', () => {
it('compiles', () => {
expect(diagnostics.filter((d) => d.system === 'FixtureDrift')).toEqual([]);
expect(drift).toBeDefined();
expect(verifySystem(drift!, module.comps, module.fns)).toEqual([]);
});
it('reads back with its locals and branches intact', () => {
expect(printSystem(drift!)).toMatchInlineSnapshot(`
"system FixtureDrift(query: query<mut Transform, FixtureDrift>, time: res<Time>) {
rowLoop query -> (_entity, transform, drift) {
let step = (drift.rate * time.delta)
let nx = (transform.position.x + step)
let fast = (drift.rate > 50)
if (nx > drift.wrap) {
transform.position.x = (nx - (drift.wrap * 2))
} else {
if ((nx < -drift.wrap) && drift.enabled) {
transform.position.x = (nx + (drift.wrap * 2))
} else {
transform.position.x = nx
}
}
if (!fast && drift.enabled) {
transform.position.y = (transform.position.y + (step * 0.5))
}
}
}"
`);
});
it('agrees with node over 40 frames', () => {
const byNode = makeWorld();
const byEir = makeWorld();
for (let f = 0; f < 40; f++) {
runNative(byNode);
runSystem(drift!, byEir);
}
expect(byEir.comps.get('Transform')).toEqual(byNode.comps.get('Transform'));
});
it('took every branch — an agreement over dead code proves nothing', () => {
const world = makeWorld();
const wrapped = new Set<number>();
const yMoved = new Set<number>();
for (let f = 0; f < 40; f++) {
const before = new Map([...world.comps.get('Transform')!].map(
([e, r]) => [e, { ...(r['position'] as Record<string, number>) }]));
runSystem(drift!, world);
for (const [e, row] of world.comps.get('Transform')!) {
const p = row['position'] as Record<string, number>;
const b = before.get(e)!;
if (Math.abs(p['x']! - b['x']!) > 100) wrapped.add(e);
if (p['y'] !== b['y']) yMoved.add(e);
}
}
expect(wrapped.size, 'no entity ever hit the wrap branch').toBeGreaterThan(0);
expect(yMoved.size, 'the !fast && enabled branch never ran').toBeGreaterThan(0);
// And some entity must have been excluded by `enabled`.
expect(yMoved.size).toBeLessThan(ENTITIES);
});
});
describe('conformance — a service question, and the ways out of a row loop', () => {
/** The author's own system, over the same world the interpreter walks. */
const runGateNative = (world: EirWorld): void => {
const drifts = world.comps.get('FixtureDrift')!;
const query = {
*[Symbol.iterator]() {
for (const e of world.entities) if (drifts.has(e)) yield [e, drifts.get(e)!];
},
};
(gateSystem as unknown as StubSystem).fn(query, world.resources.get('Input'));
};
it('compiles, and verifies', () => {
expect(diagnostics.filter((d) => d.system === 'FixtureGate')).toEqual([]);
expect(gate).toBeDefined();
expect(verifySystem(gate!, module.comps, module.fns)).toEqual([]);
});
it('reads back as the question and the jumps, not as calls', () => {
expect(printSystem(gate!)).toMatchInlineSnapshot(`
"system FixtureGate(query: query<mut FixtureDrift>, input: res<Input>) {
if !input.isKeyDown("KeyW") {
return
}
rowLoop query -> (_, d) {
if !d.enabled {
continue
}
if (d.rate > 110) {
break
}
d.rate = (d.rate + (input.isKeyPressed("Space") ? 2 : 1))
}
}"
`);
});
it('agrees with node over 40 frames', () => {
const byNode = makeWorld();
const byEir = makeWorld();
for (let f = 0; f < 40; f++) {
runGateNative(byNode);
runSystem(gate!, byEir);
}
expect(byEir.comps.get('FixtureDrift')).toEqual(byNode.comps.get('FixtureDrift'));
});
it('took each exit — an agreement over an untaken jump proves nothing', () => {
const world = makeWorld();
const rows = [...world.comps.get('FixtureDrift')!.values()] as { rate: number; enabled: boolean }[];
// `continue`: rows with enabled false, which must never move.
const skipped = rows.filter((r) => !r.enabled).map((r) => r.rate);
// `break`: a row over the limit exists, so the loop ends early and the
// rows after it are untouched this frame.
expect(rows.some((r) => r.rate > 110)).toBe(true);
for (let f = 0; f < 40; f++) runSystem(gate!, world);
expect(rows.filter((r) => !r.enabled).map((r) => r.rate)).toEqual(skipped);
// `return`: with the key up, nothing at all moves.
const quiet = makeWorld();
(quiet.resources as Map<string, Row>).set('Input',
{ isKeyDown: () => false, isKeyPressed: () => false } as unknown as Row);
const before = JSON.stringify([...quiet.comps.get('FixtureDrift')!.values()]);
for (let f = 0; f < 4; f++) runSystem(gate!, quiet);
expect(JSON.stringify([...quiet.comps.get('FixtureDrift')!.values()])).toBe(before);
});
});
describe('conformance — an event out of memory and back into it', () => {
it('compiles both halves, and verifies them', () => {
expect(diagnostics.filter((d) => d.system === 'FixturePing' || d.system === 'FixturePong')).toEqual([]);
expect(ping).toBeDefined();
expect(pong).toBeDefined();
expect(verifySystem(ping!, module.comps, module.fns)).toEqual([]);
expect(verifySystem(pong!, module.comps, module.fns)).toEqual([]);
});
it('reads back as a send and a walk, not as calls', () => {
expect(printSystem(ping!)).toMatchInlineSnapshot(`
"system FixturePing(query: query<mut FixtureDrift>, out: channel<FixturePinged>) {
rowLoop query -> (_, d) {
if d.enabled {
emit out.send(d.rate)
}
}
}"
`);
expect(printSystem(pong!)).toMatchInlineSnapshot(`
"system FixturePong(pings: events, query: query<mut FixtureDrift>) {
let total = 0
rowLoop pings -> (_, p) {
total = (total + p.by)
}
rowLoop query -> (_, d) {
d.wrap = total
}
}"
`);
});
it('what one sends is what the other walks, and node agrees', () => {
const byNode = makeWorld();
const byEir = makeWorld();
const run = (world: EirWorld, viaNode: boolean): void => {
// A frame: send, then deliver what was sent, then read.
if (viaNode) {
const sent: { by: number }[] = [];
const drifts = world.comps.get('FixtureDrift')!;
const rows = {
*[Symbol.iterator]() { for (const e of world.entities) yield [e, drifts.get(e)!]; },
};
(pingSystem as unknown as StubSystem).fn(rows, { send: (p: { by: number }) => sent.push(p) });
(pongSystem as unknown as StubSystem).fn(sent, rows);
return;
}
runSystem(ping!, world);
const sent = (world.sent?.get('FixturePinged') ?? []) as (readonly number[])[];
(world as unknown as { events?: Map<string, Row[]> }).events =
new Map([['FixturePinged', sent.map((args) => ({ by: args[0]! }))]]);
world.sent?.clear();
runSystem(pong!, world);
};
for (let f = 0; f < 20; f++) { run(byNode, true); run(byEir, false); }
expect(byEir.comps.get('FixtureDrift')).toEqual(byNode.comps.get('FixtureDrift'));
});
it('and something was actually sent — an empty queue agrees with anything', () => {
const world = makeWorld();
runSystem(ping!, world);
expect((world.sent?.get('FixturePinged') ?? []).length).toBeGreaterThan(0);
});
});
describe('conformance — ternaries and exact Math', () => {
function clampWorld(): EirWorld {
let a = 0x9e3779b1 >>> 0;
const rand = (): number => {
a = (a * 1664525 + 1013904223) >>> 0;
return (a >>> 8) / 16777216;
};
const transforms = new Map<number, Row>();
const clamps = new Map<number, Row>();
const entities: number[] = [];
for (let e = 1; e <= 32; e++) {
entities.push(e);
transforms.set(e, { position: { x: (rand() - 0.5) * 160, y: 0, z: 0 } });
clamps.set(e, { lo: -50, hi: 50, push: 10 + rand() * 60 });
}
return {
entities,
comps: new Map([['Transform', transforms], ['FixtureClamp', clamps]]),
resources: new Map<string, Row>([['Time', { delta: 1 / 30 }]]),
};
}
function runClampNative(world: EirWorld): void {
const sys = clampSystem as unknown as StubSystem;
const transforms = world.comps.get('Transform')!;
const clamps = world.comps.get('FixtureClamp')!;
const query = {
*[Symbol.iterator]() {
for (const e of world.entities) yield [e, transforms.get(e)!, clamps.get(e)!];
},
};
(sys.fn as unknown as (q: unknown, t: unknown) => void)(query, world.resources.get('Time'));
}
it('compiles and verifies', () => {
expect(diagnostics.filter((d) => d.system === 'FixtureClampSys').map((d) => d.message)).toEqual([]);
expect(clamp).toBeDefined();
expect(verifySystem(clamp!, module.comps, module.fns)).toEqual([]);
});
it('keeps the ternary and the intrinsics in the IR', () => {
const text = printSystem(clamp!);
expect(text).toContain('? ');
expect(text).toContain('min(max(');
expect(text).toContain('sqrt(abs(');
});
it('agrees with node over 40 frames', () => {
const byNode = clampWorld();
const byEir = clampWorld();
for (let f = 0; f < 40; f++) {
runClampNative(byNode);
runSystem(clamp!, byEir);
}
expect(byEir.comps.get('Transform')).toEqual(byNode.comps.get('Transform'));
});
});
describe('conformance — module constants', () => {
function runTunedNative(world: EirWorld): void {
const sys = tunedSystem 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 verifies', () => {
expect(diagnostics.filter((d) => d.system === 'FixtureTuned').map((d) => d.message)).toEqual([]);
expect(tuned).toBeDefined();
expect(verifySystem(tuned!, module.comps, module.fns)).toEqual([]);
});
it('folds the constants rather than loading them', () => {
const text = printSystem(tuned!);
// The values, not the names: WRAP is 120 and TUNING.damping is 0.9.
expect(text).toContain('120');
expect(text).toContain('0.9');
expect(text).not.toContain('WRAP)');
expect(text).not.toContain('TUNING');
});
it('lets a local shadow a module constant', () => {
// Inside the if, WRAP is a local; folding that ignored scope would print
// the module value 120 in its place.
expect(printSystem(tuned!)).toContain('let WRAP = drift.rate');
expect(printSystem(tuned!)).toContain('(WRAP > 100)');
});
it('agrees with node over 40 frames', () => {
const byNode = makeWorld();
const byEir = makeWorld();
for (let f = 0; f < 40; f++) {
runTunedNative(byNode);
runSystem(tuned!, byEir);
}
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'));
});
});
const math = module.systems.find((s) => s.name === 'FixtureMathOps');
describe('conformance — the Math the subset admits', () => {
function probeWorld(): EirWorld {
const rows = new Map<number, Row>();
const entities: number[] = [];
PROBE.forEach((v, i) => {
entities.push(i + 1);
// defineComponent shapes are host-stored, so f64: no fround, and -0
// stays -0 all the way into the image.
rows.set(i + 1, probeRow(v));
});
return { entities, comps: new Map([['FixtureMathProbe', rows]]), resources: new Map() };
}
it('compiles, and lowers each operation to a call rather than a fallback', () => {
expect(diagnostics.filter((d) => d.system === 'FixtureMathOps')).toEqual([]);
expect(math).toBeDefined();
expect(verifySystem(math!, module.comps, module.fns)).toEqual([]);
});
it('agrees with node, including the sign of zero', () => {
const byNode = probeWorld();
const byEir = probeWorld();
const sys = mathSystem as unknown as StubSystem;
const rows = byNode.comps.get('FixtureMathProbe')!;
(sys.fn as unknown as (q: unknown) => void)({
*[Symbol.iterator]() {
for (const e of byNode.entities) yield [e, rows.get(e)!];
},
});
runSystem(math!, byEir);
for (const e of byNode.entities) {
const want = rows.get(e) as Record<string, number>;
const got = byEir.comps.get('FixtureMathProbe')!.get(e) as Record<string, number>;
for (const k of Object.keys(want)) {
// Object.is, not toBe on the number: -0 and +0 are equal and are
// not the same bytes, and the bytes are what ships.
expect(Object.is(got[k], want[k]), `entity ${e} field ${k}: ${got[k]} vs ${want[k]}`).toBe(true);
}
}
});
it('the probe actually reaches the cases the shims exist for', () => {
const w = probeWorld();
runSystem(math!, w);
const rows = [...w.comps.get('FixtureMathProbe')!.values()] as Record<string, number>[];
// A tie that rounds toward +Inf rather than away from zero.
expect(rows.some((r) => r['v'] === -2.5 && r['rounded'] === -2)).toBe(true);
// The double just below 0.5, where floor(x + 0.5) gives the wrong answer.
expect(rows.some((r) => r['v'] === 0.49999999999999994 && Object.is(r['rounded'], 0))).toBe(true);
// min picking the negative zero, which fmin is free not to do.
expect(rows.some((r) => Object.is(r['lo'], -0))).toBe(true);
expect(rows.some((r) => Object.is(r['signum'], -0))).toBe(true);
});
});