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 abi.test.ts
* @brief Is the ABI SUFFICIENT?
*
* @details The same interpreter runs the same system twice: once over JS objects
* and once over flat memory reached only through what SysCtx carries.
* Both must match node.
*
* That is the question this file exists to answer. A system that runs
* in the first and not the second names something the contract is
* missing — which is the only legitimate reason to add a field to it.
*/
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 { builtinShapes } from '../src/builtins';
import { AbiMemory, abiHandshake, packLayout, runOnAbi, type SysPlan } from '../src/abi';
import { emitC } from '../src/codegen';
import { inlineSystem } from '../src/inline';
import { moveSystem } from '../../examples/ecs-basics/src/systems/move';
import { lifetimeSystem } from '../../examples/ecs-basics/src/systems/lifetime';
import type { StubSystem } from './stubs/esengine';
const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));
const FILES = [
resolve(ROOT, 'examples/ecs-basics/src/systems/move.ts'),
resolve(ROOT, 'examples/ecs-basics/src/systems/lifetime.ts'),
resolve(ROOT, 'examples/ecs-basics/src/components.ts'),
];
const { module } = lowerProgram(FILES, builtinShapes());
const layout = packLayout(module.comps);
const N = 24;
/** The same starting world, in each of the two shapes. */
function seed(i: number): { tx: number; ty: number; dx: number; dy: number; speed: number; life: number } {
return {
tx: (i % 7) * 13 - 40, ty: (i % 5) * 9 - 20,
dx: ((i % 3) - 1), dy: ((i % 4) - 2) / 2,
speed: 40 + (i % 6) * 15, life: 0.05 * i,
};
}
/**
* Rounds every store the way that shape's storage does — f32 for an engine pool,
* f64 for a ScriptStorage record. Asking the SHAPE, not the name: a JS-object
* world that rounded everything the same way would drift from the ABI image and
* flip `remaining <= 0` a frame early.
*/
function rowOf(comp: string, fields: Record<string, unknown>): Row {
return module.comps.get(comp)!.storage === 'engine' ? f32Row(fields) : (fields as Row);
}
function f32Row(fields: Record<string, unknown>): Row {
const out: Record<string, unknown> = {};
for (const [k, v] of Object.entries(fields)) {
if (v !== null && typeof v === 'object') { out[k] = f32Row(v as Record<string, unknown>); continue; }
let held = Math.fround(v as number);
Object.defineProperty(out, k, {
enumerable: true,
get: () => held,
set: (n: number) => { held = Math.fround(n); },
});
}
return out;
}
function jsWorld(): EirWorld {
const transforms = new Map<number, Row>();
const movers = new Map<number, Row>();
const lifetimes = new Map<number, Row>();
const sprites = new Map<number, Row>();
const entities: number[] = [];
for (let i = 1; i <= N; i++) {
const s = seed(i);
entities.push(i);
transforms.set(i, rowOf('Transform', {
position: { x: s.tx, y: s.ty, 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 },
}));
movers.set(i, rowOf('Mover', { speed: s.speed, directionX: s.dx, directionY: s.dy }));
lifetimes.set(i, rowOf('Lifetime', { remaining: s.life }));
sprites.set(i, rowOf('Sprite', { color: { r: 1, g: 1, b: 1, a: 1 }, size: { x: 8, y: 8 } }));
}
return {
entities,
comps: new Map([['Transform', transforms], ['Mover', movers],
['Lifetime', lifetimes], ['Sprite', sprites]]),
resources: new Map<string, Row>([['Time', { delta: 1 / 30 }]]),
};
}
function abiWorld(): AbiMemory {
const mem = new AbiMemory(layout);
mem.addResource('Time', { delta: 1 / 30 });
for (let i = 1; i <= N; i++) {
const s = seed(i);
mem.addComponent('Transform', i, { 'position.x': s.tx, 'position.y': s.ty });
mem.addComponent('Mover', i, { speed: s.speed, directionX: s.dx, directionY: s.dy });
mem.addComponent('Lifetime', i, { remaining: s.life });
mem.addComponent('Sprite', i, { 'color.a': 1 });
}
return mem;
}
describe('the ABI is sufficient for the systems the subset compiles', () => {
const move = module.systems.find((s) => s.name === 'MoveSystem')!;
const life = module.systems.find((s) => s.name === 'LifetimeSystem')!;
it('lowered both, and both verify', () => {
expect(move).toBeDefined();
expect(life).toBeDefined();
expect(verifySystem(move, module.comps, module.fns)).toEqual([]);
expect(verifySystem(life, module.comps, module.fns)).toEqual([]);
});
it('MoveSystem: flat memory agrees with JS objects, and both with node', () => {
const byNode = jsWorld();
const byJs = jsWorld();
const mem = abiWorld();
const sys = moveSystem as unknown as StubSystem;
for (let f = 0; f < 30; f++) {
const tf = byNode.comps.get('Transform')!;
const mv = byNode.comps.get('Mover')!;
(sys.fn as unknown as (q: unknown, t: unknown) => void)({
*[Symbol.iterator]() {
for (const e of byNode.entities) yield [e, tf.get(e)!, mv.get(e)!];
},
}, byNode.resources.get('Time'));
runSystem(move, byJs, module.fns);
runOnAbi(move, mem, layout, module.fns);
}
for (let i = 1; i <= N; i++) {
const want = (byNode.comps.get('Transform')!.get(i)!['position'] as Record<string, number>);
const js = (byJs.comps.get('Transform')!.get(i)!['position'] as Record<string, number>);
// Both sides round through f32 on every store, so this is exact.
expect(js['x'], `js entity ${i}`).toBe(want['x']);
expect(mem.read('Transform', i, 'position.x'), `abi entity ${i}`).toBe(want['x']);
expect(mem.read('Transform', i, 'position.y'), `abi entity ${i}`).toBe(want['y']);
}
});
it('LifetimeSystem: despawn through the command buffer removes the same entities', () => {
const byJs = jsWorld();
const mem = abiWorld();
for (let f = 0; f < 30; f++) {
runSystem(life, byJs, module.fns);
runOnAbi(life, mem, layout, module.fns);
expect(mem.entities, `frame ${f}`).toEqual(byJs.entities);
}
expect(byJs.entities.length).toBeLessThan(N);
expect(byJs.entities.length).toBeGreaterThan(0);
});
// "Zero calls into the engine" is not asserted here: it is a property of the
// shipped artifact — an empty wasm import section — and wasm.test.ts asks it
// of the artifact itself.
});
/**
* Two builds of one engine, over one project's shapes, agree on both digests
* while declaring different queries, mut flags and event payloads — and those
* are what a runtime's bookkeeping reads out of the sidecar. Probed against
* real artifacts before this existed: same engineAbi, same projectShapes.
*/
describe('which build a module is', () => {
const shape = new Map([['Mover', { storage: 'host' as const, fields: new Map([['speed', 'f32']]) }]]);
/** One system's plan, as `planFor` would hand it over. */
const plan = (over: Partial<SysPlan> = {}): SysPlan => ({
system: 'MoveSystem', queries: [[{ comp: 'Mover', mut: true }]],
resources: [], channels: [], readers: [], writers: [],
slots: new Map(), ...over,
} as SysPlan);
const contractOf = (p: SysPlan) => abiHandshake(shape as never, [p], 8).moduleContract;
it('changes when a mut flag does, where neither other digest can', () => {
const writes = plan();
const reads = plan({ queries: [[{ comp: 'Mover', mut: false }]] });
const a = abiHandshake(shape as never, [writes], 8);
const b = abiHandshake(shape as never, [reads], 8);
expect(a.engineAbi).toBe(b.engineAbi);
expect(a.projectShapes).toBe(b.projectShapes);
expect(a.moduleContract).not.toBe(b.moduleContract);
});
it('changes for a resource, a reader and a writer alike', () => {
const base = contractOf(plan());
expect(contractOf(plan({ resources: [{ name: 'Score', mut: true }] }))).not.toBe(base);
expect(contractOf(plan({ readers: [{ slot: 0, event: 'Hit' }] }))).not.toBe(base);
expect(contractOf(plan({ writers: [{ slot: 0, event: 'Hit' }] }))).not.toBe(base);
});
it('is what the artifact bakes, in the halves a data-free module can carry', () => {
const fixture = resolve(ROOT, 'compiler/tests/fixtures/in-subset.ts');
const lowered = lowerProgram([fixture], builtinShapes());
const move = lowered.module.systems.find((s) => s.name === 'FixturePing')!;
const c = emitC(lowered.module, packLayout(lowered.module.comps),
[inlineSystem(move, lowered.module.fns)], 8);
expect(c.source).toContain(`es_module_contract_lo(void) { return 0x${c.handshake.moduleContract.slice(8)}u; }`);
expect(c.source).toContain(`es_module_contract_hi(void) { return 0x${c.handshake.moduleContract.slice(0, 8)}u; }`);
});
});