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 aot-dispatch.test.ts
* @brief The scheduler runs a compiled twin, and the world comes out the same.
*
* @details The differential moved up one level. Everything before compared a
* compiled system against an oracle by hand; this schedules the SAME
* system twice — once as the TypeScript closure the author wrote, once
* as the twin a build produced — and requires the two worlds to agree.
*
* That is the shape of the pixel gate the roadmap ends at, minus the
* pixels: same project, two runs, and nothing may differ.
*/
import { describe, it, expect } from 'vitest';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { World } from '../src/ecs/world';
import { defineComponent } from '../src/ecs/component';
import { defineSystem, SystemRunner } from '../src/ecs/system';
import { Query, Mut, Changed } from '../src/ecs/query';
import { ResourceStorage } from '../src/ecs/resource';
import { WasmPoolMemory, type WasmHeap } from '../src/ecs/WasmPoolMemory';
import { AotContext } from '../src/ecs/aot/AotContext';
import { AotSystems, type AotManifest } from '../src/ecs/aot/AotSystems';
import type { AotAddresses, AotRuntime } from '../src/ecs/aot/AotRuntime';
import { AotDispatch } from '../src/ecs/aot/AotDispatch';
import type { AnyComponentDef } from '../src/ecs/component';
import { engineAbiDigest, projectShapeDigest } from '../src/ecs/aot/abiDigest';
import type { Entity } from '../src/types';
import { emccPath } from '../../build-tools/utils/emscripten.js';
import { FakeEngine } from './fakeEngine';
import { buildAotModule } from './helpers/aotFade';
const N = 20;
const FRAMES = 10;
/** What a build for THIS engine would have written into the manifest. */
const ENGINE = engineAbiDigest(4);
const DECAY_FIELDS = ['remaining', 'rate'];
const SHAPES = projectShapeDigest([{ name: 'Decay', fields: DECAY_FIELDS }]);
const EMCC = emccPath();
/** `Decay`: remaining -= rate, and despawn once it reaches zero. */
const SYSTEM_C = `#include <stdint.h>
#include <string.h>
typedef uint32_t es_addr_t;
#define ES_PTR(a) ((unsigned char *)(a))
typedef struct { es_addr_t rows, count; } EsQueryRows;
typedef struct { uint32_t kind, a, b, c; } EsCmd;
typedef struct { es_addr_t queries, resources, cmdBuf, cmdCap, cmdCount, events; } EsSysCtx;
static double ld(const unsigned char *p) { double v; memcpy(&v, p, 8); return v; }
static void st(unsigned char *p, double v) { memcpy(p, &v, 8); }
void es_sys_Decay(es_addr_t ctx) {
const EsSysCtx *c = (const EsSysCtx *)ES_PTR(ctx);
const EsQueryRows *q = (const EsQueryRows *)ES_PTR(c->queries);
EsCmd *cmds = (EsCmd *)ES_PTR(c->cmdBuf);
uint32_t *count = (uint32_t *)ES_PTR(c->cmdCount);
uint32_t n = *count;
const es_addr_t *rows = (const es_addr_t *)ES_PTR(q[0].rows);
for (es_addr_t i = 0; i < q[0].count; ++i) {
const es_addr_t *row = rows + i * 2u;
unsigned char *m = ES_PTR(row[1]);
st(m, ld(m) - ld(m + 8)); /* remaining -= rate */
if (ld(m) <= 0.0 && n < (uint32_t)c->cmdCap) {
cmds[n].kind = 1u; cmds[n].a = (uint32_t)row[0];
cmds[n].b = 0u; cmds[n].c = 0u; n += 1u;
}
}
*count = n;
}
`;
const buildModule = (): Uint8Array => buildAotModule(EMCC!, SYSTEM_C, 'es_sys_Decay');
/**
* The system the author wrote. The twin is held against THIS, so the C above is
* the compiler's job to produce — here it stands in for what it produced.
*/
function makeWorld(): {
world: World; runner: SystemRunner; Decay: AnyComponentDef; system: ReturnType<typeof defineSystem>;
} {
const world = new World();
const resources = new ResourceStorage();
const runner = new SystemRunner(world, resources);
const Decay = defineComponent('Decay', { remaining: 1, rate: 0.1 }) as AnyComponentDef;
const system = defineSystem([Query(Mut(Decay))], (query) => {
const doomed: Entity[] = [];
for (const [entity, decay] of query as Iterable<[Entity, { remaining: number; rate: number }]>) {
decay.remaining -= decay.rate;
if (decay.remaining <= 0) doomed.push(entity);
}
for (const entity of doomed) world.despawn(entity);
}, { name: 'Decay' });
return { world, runner, Decay, system };
}
function seed(world: World, Decay: AnyComponentDef): Entity[] {
const out: Entity[] = [];
for (let i = 1; i <= N; i++) {
const entity = world.spawn();
world.insert(entity, Decay, { remaining: i * 0.1, rate: 0.1 });
out.push(entity);
}
return out;
}
function snapshot(world: World, Decay: AnyComponentDef, entities: readonly Entity[]): string {
return entities
.filter((e) => world.valid(e) && world.has(e, Decay))
.map((e) => `${e}:${(world.get(e, Decay) as { remaining: number }).remaining}`)
.join(',');
}
describe('the scheduler and its compiled twin', () => {
it.skipIf(!EMCC)('portable asset refs run through the interpreter until every row is addressable',async()=>{
const b=makeWorld(),heap=new FakeEngine(),memory=new WasmPoolMemory(heap);
b.world.useScriptPoolMemory(memory);
Object.defineProperty(b.Decay,'assetFields',{value:[{field:'remaining',type:'texture'}]});
const first=b.world.spawn(),second=b.world.spawn();
b.world.insert(first,b.Decay,{remaining:1,rate:0.1});
b.world.insert(second,b.Decay,{remaining:'@uuid:pending',rate:0.1} as never);
const instance=await WebAssembly.instantiate(new WebAssembly.Module(buildModule() as unknown as BufferSource),{env:{memory:heap.memory}});
const exports=instance.exports as unknown as Record<string,unknown>;
(exports['_initialize'] as (()=>void)|undefined)?.();
const systems=new AotSystems();systems.install({engineAbi:ENGINE,projectShapes:SHAPES,systems:[{name:'Decay',symbol:'es_sys_Decay',queries:[[{comp:'Decay',mut:true}]],resources:[]}]},exports,name=>name==='Decay'?b.Decay:undefined);
const runtime:AotRuntime={systems,addresses:{componentNamed:name=>name==='Decay'?b.Decay:undefined,resourceAt:()=>undefined,resourceWriteBack:()=>{},payloadRows:()=>[],sendEvent:()=>{},releasePayloads:()=>{}},ctx:new AotContext(memory),dispatcherFor:w=>new AotDispatch(w,runtime)};
b.runner.useAot(runtime);
const seen:unknown[]=[];
const system=defineSystem([Query(Mut(b.Decay))],query=>{for(const [,data] of query as Iterable<[Entity,{remaining:unknown}]>)seen.push(data.remaining);},{name:'Decay'});
b.runner.run(system);expect(seen).toEqual([1,'@uuid:pending']);expect(systems.calls).toBe(0);
b.world.set(second,b.Decay,{remaining:1,rate:0.1});b.runner.run(system);
expect(systems.calls).toBe(1);expect((b.world.get(first,b.Decay) as {remaining:number}).remaining).toBeCloseTo(0.9);
// A cached row table must become invalid when a live view gains a ref.
b.world.update(first,b.Decay,data=>{(data as unknown as {remaining:unknown}).remaining='@uuid:later';});b.runner.run(system);
expect(systems.calls).toBe(1);expect(seen.slice(2)).toEqual(['@uuid:later',0.9]);
expect(heap.staticsIntact()).toBe(true);
});
it('reports whether this gate could run at all', () => {
if (EMCC) console.log('[aot-dispatch] the twin ran under the real runner');
else console.warn('[aot-dispatch] NO EMSDK — the dispatch did NOT run (pnpm emsdk:setup).');
expect(true).toBe(true);
});
it('with nothing installed there is nothing to dispatch to', () => {
const { runner, Decay, system, world } = makeWorld();
const entities = seed(world, Decay);
runner.useAot(null);
runner.run(system);
// The closure ran: this is the path every editor preview takes, and it
// must not have noticed that AOT exists.
expect((world.get(entities[9]!, Decay) as { remaining: number }).remaining)
.toBeCloseTo(0.9, 10);
});
it.skipIf(!EMCC)('the twin leaves the world the closure would have', async () => {
const bytes = buildModule();
// Interpreted.
const a = makeWorld();
const aEntities = seed(a.world, a.Decay);
for (let f = 0; f < FRAMES; f++) a.runner.run(a.system);
// Compiled, over rows in a linear memory the module shares.
const b = makeWorld();
const heap = new FakeEngine();
const memory = new WasmPoolMemory(heap);
b.world.useScriptPoolMemory(memory);
const bEntities = seed(b.world, b.Decay);
const instance = await WebAssembly.instantiate(
new WebAssembly.Module(bytes as unknown as BufferSource),
{ env: { memory: heap.memory } });
const exports = instance.exports as unknown as Record<string, unknown>;
(exports['_initialize'] as (() => void) | undefined)?.();
const manifest: AotManifest = {
engineAbi: ENGINE,
projectShapes: SHAPES,
systems: [{
name: 'Decay', symbol: 'es_sys_Decay',
queries: [[{ comp: 'Decay', mut: true }]], resources: [],
}],
};
const systems = new AotSystems();
systems.install(manifest, exports, (name) => (name === 'Decay' ? b.Decay : undefined));
const addresses: AotAddresses = {
componentNamed: (name) => (name === 'Decay' ? b.Decay : undefined),
resourceAt: () => undefined,
};
const runtime: AotRuntime = {
systems, addresses, ctx: new AotContext(memory),
dispatcherFor: (w) => new AotDispatch(w, runtime),
};
b.runner.useAot(runtime);
for (let f = 0; f < FRAMES; f++) b.runner.run(b.system);
expect(snapshot(b.world, b.Decay, bEntities)).toBe(snapshot(a.world, a.Decay, aEntities));
// A run where nothing despawned would compare two full worlds and prove
// only that neither moved.
expect(aEntities.filter((e) => a.world.valid(e)).length).toBeLessThan(N);
expect(aEntities.filter((e) => a.world.valid(e)).length).toBeGreaterThan(0);
// Nothing the module did may reach the bytes the engine keeps for
// itself — not its data section on load, not a stack spill on a call.
expect(heap.staticsIntact()).toBe(true);
});
it.skipIf(!EMCC)('a twin marks Changed, which it cannot do for itself', async () => {
// The compiled code calls nothing, so a `Mut` it honoured is invisible
// unless the host records it. A watcher is the only thing that can tell.
const bytes = buildModule();
const seen: number[] = [];
const build = async (compiled: boolean): Promise<number[]> => {
const w = makeWorld();
const watched: number[] = [];
const watcher = defineSystem([Query(Changed(w.Decay))], (query) => {
let n = 0;
for (const _ of query as Iterable<unknown>) n++;
watched.push(n);
}, { name: 'Watcher' });
const heap = new FakeEngine();
const memory = new WasmPoolMemory(heap);
if (compiled) w.world.useScriptPoolMemory(memory);
seed(w.world, w.Decay);
if (compiled) {
const instance = await WebAssembly.instantiate(
new WebAssembly.Module(bytes as unknown as BufferSource),
{ env: { memory: heap.memory } });
const exports = instance.exports as unknown as Record<string, unknown>;
(exports['_initialize'] as (() => void) | undefined)?.();
const systems = new AotSystems();
systems.install({
engineAbi: ENGINE,
projectShapes: SHAPES,
systems: [{
name: 'Decay', symbol: 'es_sys_Decay',
queries: [[{ comp: 'Decay', mut: true }]], resources: [],
}],
}, exports, (name) => (name === 'Decay' ? w.Decay : undefined));
const runtime: AotRuntime = {
systems,
addresses: {
componentNamed: (name) => (name === 'Decay' ? w.Decay : undefined),
resourceAt: () => undefined,
},
ctx: new AotContext(memory),
dispatcherFor: (world) => new AotDispatch(world, runtime),
};
w.runner.useAot(runtime);
}
for (let f = 0; f < 4; f++) {
if (f === 0) w.world.advanceTick();
w.runner.run(w.system);
w.runner.run(watcher);
}
return watched;
};
const interpreted = await build(false);
const compiled = await build(true);
seen.push(...compiled);
expect(interpreted.some((n) => n > 0), 'the watcher never saw a change either way')
.toBe(true);
expect(interpreted.slice(1).every(n => n > 0), 'later writes in the same tick were missed')
.toBe(true);
expect(compiled).toEqual(interpreted);
});
it('a module built for another ENGINE is refused, and says which', () => {
const systems = new AotSystems();
const manifest: AotManifest = {
engineAbi: 'deadbeefdeadbeef', projectShapes: SHAPES, systems: [],
};
// The message has to name the fix, and the fix for this one is to rebuild
// the module — not the project.
expect(() => systems.install(manifest, {}, () => undefined))
.toThrow(/Rebuild the module against this engine/);
expect(systems.size).toBe(0);
});
it('a module built for other COMPONENT SHAPES is refused, and says which', () => {
const w = makeWorld();
const systems = new AotSystems();
const manifest: AotManifest = {
engineAbi: ENGINE,
// What a build would have written before someone added a field.
projectShapes: projectShapeDigest([{ name: 'Decay', fields: ['remaining'] }]),
systems: [{
name: 'Decay', symbol: 'es_sys_Decay',
queries: [[{ comp: 'Decay', mut: true }]], resources: [],
}],
};
expect(() => systems.install(manifest, { es_sys_Decay: () => { /* */ } },
(name) => (name === 'Decay' ? w.Decay : undefined)))
.toThrow(/Rebuild the project/);
});
it('a component nobody compiled against does not invalidate a module', () => {
const w = makeWorld();
// Declared in this project and named by no compiled system: the digest is
// scoped to what the module reads, so this must not refuse it.
defineComponent('Unrelated', { whatever: 1 });
const systems = new AotSystems();
systems.install({
engineAbi: ENGINE, projectShapes: SHAPES,
systems: [{
name: 'Decay', symbol: 'es_sys_Decay',
queries: [[{ comp: 'Decay', mut: true }]], resources: [],
}],
}, { es_sys_Decay: () => { /* */ } }, (name) => (name === 'Decay' ? w.Decay : undefined));
expect(systems.size).toBe(1);
});
it('a manifest naming a symbol the module lacks is refused too', () => {
const systems = new AotSystems();
const manifest: AotManifest = {
engineAbi: ENGINE, projectShapes: projectShapeDigest([]),
systems: [{ name: 'Ghost', symbol: 'es_sys_Ghost', queries: [], resources: [] }],
};
expect(() => systems.install(manifest, {}, () => undefined))
.toThrow(/exports no 'es_sys_Ghost'/);
});
});