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 codegen.test.ts
* @brief The compiled code and the interpreter must produce the SAME BYTES.
*
* @details Up to here every test has compared an interpreter against node; both are
* JavaScript, and neither is what ships. This one compiles the emitted
* C with a real compiler and runs it in another process.
*
* The differential is over the IMAGE, not over selected fields. The
* host materialises a SysCtx, the bytes go to a program that knows
* nothing but `es_sys_*`, and what comes back is compared to what the
* interpreter produced from the identical starting bytes — memcmp, the
* whole world. A per-field check would pass while a system wrote one
* byte past a component, which is precisely the failure a contract made
* of offsets has.
*
* Two more properties are asserted because they are what make this a
* contract rather than a convention: the object file has no undefined
* symbol besides the memory base — the empty import section, as far as
* a native build can show it — and the generated C compiles with no
* warning at all.
*
* If no C compiler is on PATH the differential CANNOT run, and this
* file says so out loud rather than reporting green — a gate that never
* saw its subject is worse than a missing one, because it is counted.
*/
import { describe, it, expect } from 'vitest';
import { execFileSync, spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { lowerProgram } from '../src/frontend';
import { verifySystem } from '../src/verify';
import { inlineSystem } from '../src/inline';
import { builtinShapes } from '../src/builtins';
import { AbiMemory, flushCommands, materialize, packLayout, planFor, runOnAbi } from '../src/abi';
import { CFLAGS, cSymbol, emitC, type CModule } from '../src/codegen';
import { findHostCC } from '../src/hostCC';
import { abiHashFor } from '../src/abi';
import type { AbiLayout } from '../src/abi';
import { F64, type EirSystem } from '../src/eir';
import type { Row } from '../src/interp';
import { moveSystem } from '../../examples/ecs-basics/src/systems/move';
import { driftSystem, gateSystem } from './fixtures/in-subset';
import { PROBE } from './probe';
import { builtinShapes as shapesForPins } from '../src/builtins';
import type { StubSystem } from './stubs/esengine';
const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));
const FIXTURE = resolve(fileURLToPath(new URL('./fixtures/in-subset.ts', import.meta.url)));
const N = 24;
const FRAMES = 12;
/** Small enough that a frame is one cheap pipe, big enough for the world above. */
const IMAGE = 1 << 16;
const CC = findHostCC();
/** The harness: linear memory in on stdin, linear memory out on stdout. */
const MAIN_C = `/* Test scaffolding, not compiler output. */
#include <stdio.h>
#include <stdlib.h>
#if defined(_WIN32)
#include <io.h>
#include <fcntl.h>
#endif
#include "estella_abi.h"
#if defined(ES_ADDR_BASE)
unsigned char *es_memory;
#endif
void ES_ENTRY(es_addr_t ctx);
static unsigned char *img;
#if !defined(ES_ADDR_BASE)
static uint32_t rd32(uint32_t off) { uint32_t v; memcpy(&v, img + off, 4); return v; }
/*
* The other address model: the image carries a ctx of OFFSETS, and this rebuilds
* it out of real pointers. Every write the system makes still lands inside the
* image, which is what makes the two models comparable byte for byte.
*/
static es_addr_t at(uint32_t off) { return (es_addr_t)(uintptr_t)(img + off); }
static es_addr_t relocate(uint32_t ctxOff, int nq, const int *comps, int nres) {
static EsSysCtx c;
EsQueryRows *qs = (EsQueryRows *)calloc((size_t)(nq > 0 ? nq : 1), sizeof(EsQueryRows));
es_addr_t *res = (es_addr_t *)calloc((size_t)(nres > 0 ? nres : 1), sizeof(es_addr_t));
uint32_t qOff = rd32(ctxOff);
uint32_t rOff = rd32(ctxOff + 4u);
int k, j;
for (k = 0; k < nq; ++k) {
uint32_t rowsOff = rd32(qOff + (uint32_t)(k * 2) * 4u);
uint32_t count = rd32(qOff + (uint32_t)(k * 2 + 1) * 4u);
uint32_t stride = (uint32_t)comps[k] + 1u;
uint32_t n = count * stride, i;
es_addr_t *rows = (es_addr_t *)calloc(n > 0 ? n : 1, sizeof(es_addr_t));
for (i = 0; i < n; ++i) {
uint32_t w = rd32(rowsOff + i * 4u);
/* Slot 0 of a row is an entity id, not an address. */
rows[i] = (i % stride == 0u) ? (es_addr_t)w : at(w);
}
qs[k].rows = (es_addr_t)(uintptr_t)rows;
qs[k].count = count;
}
for (j = 0; j < nres; ++j) res[j] = at(rd32(rOff + (uint32_t)j * 4u));
c.queries = (es_addr_t)(uintptr_t)qs;
c.resources = (es_addr_t)(uintptr_t)res;
c.cmdBuf = at(rd32(ctxOff + 8u));
c.cmdCap = rd32(ctxOff + 12u);
c.cmdCount = at(rd32(ctxOff + 16u));
c.events = 0;
return (es_addr_t)(uintptr_t)&c;
}
#endif
int main(int argc, char **argv) {
long n;
uint32_t ctxOff;
int nq, nres, i;
int comps[16];
if (argc < 5) { fprintf(stderr, "usage: run <bytes> <ctx> <nres> <nq> [comps...]\\n"); return 2; }
n = strtol(argv[1], NULL, 10);
ctxOff = (uint32_t)strtoul(argv[2], NULL, 10);
nres = (int)strtol(argv[3], NULL, 10);
nq = (int)strtol(argv[4], NULL, 10);
if (nq > 16 || argc < 5 + nq) { fprintf(stderr, "too many queries\\n"); return 6; }
for (i = 0; i < nq; ++i) comps[i] = (int)strtol(argv[5 + i], NULL, 10);
img = (unsigned char *)malloc((size_t)n);
if (!img) return 3;
#if defined(_WIN32)
/* Text mode would insert a 0x0d before every 0x0a in the image. */
_setmode(_fileno(stdin), _O_BINARY);
_setmode(_fileno(stdout), _O_BINARY);
#endif
if (fread(img, 1, (size_t)n, stdin) != (size_t)n) return 4;
#if defined(ES_ADDR_BASE)
es_memory = img;
(void)nres; (void)nq; (void)comps;
ES_ENTRY((es_addr_t)ctxOff);
#else
ES_ENTRY(relocate(ctxOff, nq, comps, nres));
#endif
if (fwrite(img, 1, (size_t)n, stdout) != (size_t)n) return 5;
return 0;
}
`;
/**
* One executable per system. The entry symbol is a -D so main is shared, and so
* is the address model: `offset` is a host that owns one block (a wasm2c
* deployment), `pointer` is one that hands over real addresses (the C++
* engine). Same generated source, compiled twice.
*/
type Addressing = 'offset' | 'pointer';
function build(dir: string, cModule: CModule, symbol: string, how: Addressing = 'offset'): string {
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'estella_abi.h'), cModule.header);
writeFileSync(join(dir, 'estella_offsets.h'), cModule.offsets);
writeFileSync(join(dir, 'systems.c'), cModule.source);
writeFileSync(join(dir, 'main.c'), MAIN_C);
const exe = join(dir, `${symbol}${process.platform === 'win32' ? '.exe' : ''}`);
const out = spawnSync(CC!, [
...CFLAGS, '-Wall', '-Wextra',
...(how === 'offset' ? ['-DES_ADDR_BASE'] : []),
`-DES_ENTRY=${symbol}`,
'-o', exe,
join(dir, 'main.c'), join(dir, 'systems.c'),
'-lm',
], { encoding: 'utf8' });
if (out.status !== 0) throw new Error(`${CC} failed:\n${out.stderr}`);
// A warning in generated code is a warning nobody will ever read, so the bar
// is zero rather than "none that matter".
expect(out.stderr.trim(), 'the generated C must compile without a warning').toBe('');
return exe;
}
/** One call of the contract: materialise, run the compiled code, flush. */
/** The event records one call appended, as [slot, ...fields] per record. */
function recordsOf(mem: AbiMemory, sys: EirSystem, run: () => void): number[][] {
const plan = planFor(sys);
const before = materialize(mem, plan);
run();
const used = mem.u32[before.eventCount >> 2]!;
const out: number[][] = [];
for (let i = 0; i < used;) {
// One slot word then the payload's fields; a writer's record length is
// what the plan says its event declares.
const slot = mem.f64[(before.eventBuf >> 3) + i]!;
const event = plan.writers.find((w) => w.slot === slot)?.event ?? '';
const len = (fixtures.module.events.get(event)?.fields.size ?? 0) + 1;
out.push([...mem.f64.subarray((before.eventBuf >> 3) + i, (before.eventBuf >> 3) + i + len)]);
i += len;
}
return out;
}
function frameOfC(exe: string, mem: AbiMemory, sys: EirSystem): void {
const plan = planFor(sys);
const call = materialize(mem, plan);
const image = Buffer.from(mem.buffer);
// The shape of the ctx, which a pointer-addressing host needs in order to
// rebuild it. A real host knows this from the system it is calling.
const shape = [
String(plan.resources.length),
String(plan.queries.length),
...plan.queries.map((q) => String(q.length)),
];
const out = execFileSync(exe, [String(image.length), String(call.ctx), ...shape], {
input: image,
maxBuffer: image.length * 2 + (1 << 16),
});
expect(out.length, 'the harness returned a different image').toBe(image.length);
image.set(out);
flushCommands(mem, call);
}
// =============================================================================
// the corpus: one shipped system, and the fixtures covering the rest of the subset
// =============================================================================
const shipped = lowerProgram([
resolve(ROOT, 'examples/ecs-basics/src/systems/move.ts'),
resolve(ROOT, 'examples/ecs-basics/src/components.ts'),
], builtinShapes());
const fixtures = lowerProgram([FIXTURE], builtinShapes());
function systemOf(result: typeof shipped, name: string): EirSystem {
const sys = result.module.systems.find((s) => s.name === name);
if (!sys) throw new Error(`no system '${name}': ${JSON.stringify(result.diagnostics)}`);
expect(verifySystem(sys, result.module.comps, result.module.fns), name).toEqual([]);
return inlineSystem(sys, result.module.fns);
}
/** Deterministic, and spread so every branch of every fixture is taken. */
function seed(i: number): Record<string, 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,
rate: (i % 11) * 12,
};
}
/** Stores round through f32 for an engine pool; a JS world that did not would
* drift from the image by construction rather than by bug. */
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 transformRow(tx: number, ty: number): Row {
return f32Row({
position: { x: tx, y: 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 },
});
}
function movedWorld(layout: AbiLayout): AbiMemory {
const mem = new AbiMemory(layout, IMAGE);
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']! });
}
return mem;
}
function fixtureWorld(layout: AbiLayout): AbiMemory {
const mem = new AbiMemory(layout, IMAGE);
mem.addResource('Time', { delta: 1 / 30, elapsed: 0 });
// A service, mirrored: the same two answers the interpreter's fake object
// gives, placed the way a host places them.
mem.addResource('Input', {});
mem.setResourceBit('Input', 'isKeyDown', 'KeyW', true);
mem.setResourceBit('Input', 'isKeyPressed', 'Space', true);
// Payloads for a reader to walk, in the image so both sides see the same.
for (let i = 1; i <= 3; i++) mem.addPayload('FixturePinged', { by: i * 7 });
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('FixtureDrift', i, { rate: s['rate']!, wrap: 100, enabled: i % 4 !== 0 });
mem.addComponent('FixtureClamp', i, { lo: -50, hi: 50, push: 30 });
// The probe values are the point of this component, not a default: they
// are where libm and ECMAScript disagree.
mem.addComponent('FixtureMathProbe', i, { v: PROBE[(i - 1) % PROBE.length]! });
// An ENGINE component, so these land at EHT's offsets and encodings:
// fov at byte 4 (a repack would say 1) and isActive as one byte at 24.
mem.addComponent('Camera', i, {
fov: 40 + (i % 9) * 8, orthoSize: 1 + (i % 5), aspectRatio: 1.25 + (i % 3) * 0.5,
isActive: i % 3 !== 0,
});
}
return mem;
}
const same = (a: AbiMemory, b: AbiMemory): boolean =>
Buffer.from(a.buffer).equals(Buffer.from(b.buffer));
// =============================================================================
// Skipped, never RETURNED from: an early return left these thirteen tests
// unregistered, so a machine with no compiler reported a smaller suite passing
// rather than a suite it could not run. globalSetup owns the announcement.
describe.skipIf(!CC)('the emitted C says what the interpreter says', () => {
const tmp = mkdtempSync(join(tmpdir(), 'estella-aot-'));
it('MoveSystem: the whole image agrees with the interpreter, and both with node', () => {
const move = systemOf(shipped, 'MoveSystem');
const layout = packLayout(shipped.module.comps);
const exe = build(join(tmp, 'move'), emitC(shipped.module, layout, [move]), cSymbol('MoveSystem'));
const byInterp = movedWorld(layout);
const byC = movedWorld(layout);
expect(same(byC, byInterp), 'the two runs did not start from the same bytes').toBe(true);
// node, over the same file the compiler read — a retyped copy would only
// ever agree with its own mistakes.
const transforms = new Map<number, Row>();
const movers = new Map<number, Row>();
const entities: number[] = [];
for (let i = 1; i <= N; i++) {
const s = seed(i);
entities.push(i);
transforms.set(i, transformRow(s['tx']!, s['ty']!));
movers.set(i, f32Row({ speed: s['speed']!, directionX: s['dx']!, directionY: s['dy']! }));
}
const time = { delta: 1 / 30 };
const stub = (moveSystem as unknown as StubSystem).fn as unknown as (q: unknown, t: unknown) => void;
for (let f = 0; f < FRAMES; f++) {
runOnAbi(move, byInterp, layout, shipped.module.fns);
frameOfC(exe, byC, move);
stub({
*[Symbol.iterator]() {
for (const e of entities) yield [e, transforms.get(e)!, movers.get(e)!];
},
}, time);
for (let i = 1; i <= N; i++) {
const want = transforms.get(i)!['position'] as Record<string, number>;
expect(byC.read('Transform', i, 'position.x'), `frame ${f} entity ${i}`).toBe(want['x']);
expect(byC.read('Transform', i, 'position.y'), `frame ${f} entity ${i}`).toBe(want['y']);
}
}
// The whole image, not the fields this test thought to look at.
expect(same(byC, byInterp), 'compiled and interpreted images differ somewhere').toBe(true);
expect(same(byC, movedWorld(layout)), 'nothing moved, so agreeing proves nothing').toBe(false);
});
// Every feature the subset gained after MoveSystem: branches and `&&`,
// ternaries, folded module constants with a shadowing local, an inlined
// helper, and the Math arguments where libm and ECMAScript disagree.
for (const name of ['FixtureDrift', 'FixtureClampSys', 'FixtureTuned', 'FixtureHelpers',
'FixtureMathOps', 'FixtureCamera', 'FixtureGate', 'FixturePong', 'FixtureTrig']) {
it(`${name}: the whole image agrees with the interpreter`, () => {
const sys = systemOf(fixtures, name);
const layout = packLayout(fixtures.module.comps);
const exe = build(join(tmp, name), emitC(fixtures.module, layout, [sys]), cSymbol(name));
const byInterp = fixtureWorld(layout);
const byC = fixtureWorld(layout);
for (let f = 0; f < FRAMES; f++) {
runOnAbi(sys, byInterp, layout, fixtures.module.fns);
frameOfC(exe, byC, sys);
expect(same(byC, byInterp), `${name}: images differ at frame ${f}`).toBe(true);
}
expect(same(byC, fixtureWorld(layout)), `${name} changed nothing`).toBe(false);
});
}
/**
* The one comparison that judges the MIRROR. Everything else has both sides
* reading bits; here the C reads a bit and node calls the method, so they
* agree only if the host placed the answer where the compiler expects it.
*/
it('FixtureGate: a bit the host set answers what the method answers', () => {
const gate = systemOf(fixtures, 'FixtureGate');
const layout = packLayout(fixtures.module.comps);
const exe = build(join(tmp, 'gate-node'), emitC(fixtures.module, layout, [gate]), cSymbol('FixtureGate'));
const mem = fixtureWorld(layout);
const drifts = new Map<number, Row>();
const entities: number[] = [];
for (let i = 1; i <= N; i++) {
entities.push(i);
drifts.set(i, { rate: seed(i)['rate']!, wrap: 100, enabled: i % 4 !== 0 });
}
// The object the bits were mirrored FROM, answering by method.
const input = { isKeyDown: (k: string) => k === 'KeyW', isKeyPressed: (k: string) => k === 'Space' };
const stub = (gateSystem as unknown as StubSystem).fn as unknown as (q: unknown, i: unknown) => void;
for (let f = 0; f < FRAMES; f++) {
frameOfC(exe, mem, gate);
stub({
*[Symbol.iterator]() { for (const e of entities) yield [e, drifts.get(e)!]; },
}, input);
}
for (const e of entities) {
expect([e, mem.read('FixtureDrift', e, 'rate')])
.toEqual([e, (drifts.get(e)! as { rate: number }).rate]);
}
// With the key up neither side moves, which is the `return` arriving in
// both — and it is a different assertion from "they agree".
expect(entities.some((e) => (drifts.get(e)! as { rate: number }).rate !== seed(e)['rate']!)).toBe(true);
});
/**
* The WRITING half. Its effect is not in the image — a sent payload lives in
* the per-call queue — so the records themselves are what the two sides have
* to agree on, read back the way a host reads them.
*/
it('FixturePing: the records the C appends are the records the interpreter does', () => {
const ping = systemOf(fixtures, 'FixturePing');
const layout = packLayout(fixtures.module.comps);
const exe = build(join(tmp, 'ping'), emitC(fixtures.module, layout, [ping]), cSymbol('FixturePing'));
const byC = fixtureWorld(layout);
const byInterp = fixtureWorld(layout);
const fromC = recordsOf(byC, ping, () => frameOfC(exe, byC, ping));
const fromInterp = recordsOf(byInterp, ping,
() => runOnAbi(ping, byInterp, layout, fixtures.module.fns));
expect(fromC).toEqual(fromInterp);
// An empty queue would agree with anything at all.
expect(fromC.length).toBeGreaterThan(0);
});
it('FixtureDrift also agrees with node, not only with the interpreter', () => {
const drift = systemOf(fixtures, 'FixtureDrift');
const layout = packLayout(fixtures.module.comps);
const exe = build(join(tmp, 'drift-node'), emitC(fixtures.module, layout, [drift]),
cSymbol('FixtureDrift'));
const mem = fixtureWorld(layout);
const transforms = new Map<number, Row>();
const drifts = new Map<number, Row>();
const entities: number[] = [];
for (let i = 1; i <= N; i++) {
const s = seed(i);
entities.push(i);
transforms.set(i, transformRow(s['tx']!, s['ty']!));
// A defineComponent shape is host-stored, so f64 — no fround here.
drifts.set(i, { rate: s['rate']!, wrap: 100, enabled: i % 4 !== 0 });
}
const time = { delta: 1 / 30, elapsed: 0 };
const stub = (driftSystem as unknown as StubSystem).fn as unknown as (q: unknown, t: unknown) => void;
for (let f = 0; f < FRAMES; f++) {
frameOfC(exe, mem, drift);
stub({
*[Symbol.iterator]() {
for (const e of entities) yield [e, transforms.get(e)!, drifts.get(e)!];
},
}, time);
}
for (const e of entities) {
const want = transforms.get(e)!['position'] as Record<string, number>;
expect(mem.read('Transform', e, 'position.x'), `entity ${e}`).toBe(want['x']);
expect(mem.read('Transform', e, 'position.y'), `entity ${e}`).toBe(want['y']);
}
});
it('an offset comes from EHT, and a repack cannot guess it', () => {
// Most engine layouts ARE dense once alignment is applied, which is why
// a repack agreed for so long. These four have a member EHT does not
// expose in front, so a repack reads into it.
const shapes = shapesForPins();
const at = (comp: string, path: string): number | null =>
shapes.get(comp)!.fields.get(path)!.offset;
expect(at('BitmapText', 'color.r'), 'a repack would say 0').toBe(12);
expect(at('DragonBonesAnimation', 'timeScale'), 'a repack would say 0').toBe(48);
expect(at('SpineAnimation', 'timeScale'), 'a repack would say 0').toBe(48);
expect(at('UINode', 'alignSelf'), 'a repack would say 73').toBe(76);
});
it('a bool is one byte, and an integer leaf is refused rather than guessed', () => {
const layout = packLayout(fixtures.module.comps);
const cam = layout.comps.get('Camera')!;
expect(cam.leaves.get('isActive')!.byteOffset).toBe(24);
expect(cam.leaves.get('isActive')!.enc).toBe('bool8');
expect(cam.leaves.get('priority')!.enc).toBe('i32');
const { source } = emitC(fixtures.module, layout, [systemOf(fixtures, 'FixtureCamera')]);
expect(emitC(fixtures.module, layout, [systemOf(fixtures, 'FixtureCamera')]).offsets)
.toContain('#define ES_OFF_Camera_isActive 24u');
// One byte. Read as a float it would take three bytes of `priority` with
// it, and produce a number rather than an error.
expect(source).toMatch(/es_bool\(\w+ \+ ES_OFF_Camera_isActive\)/);
expect(source).toMatch(/es_set_bool\(\w+ \+ ES_OFF_Camera_isActive/);
});
it('the same source addressed as pointers gives the same image', () => {
// Why the address is a machine property: the C++ engine hands over
// 64-bit component pointers, which no 32-bit offset can name. Compiling
// the SAME file both ways makes that claim checkable.
const move = systemOf(shipped, 'MoveSystem');
const layout = packLayout(shipped.module.comps);
const c = emitC(shipped.module, layout, [move]);
const byOffset = build(join(tmp, 'addr-off'), c, cSymbol('MoveSystem'), 'offset');
const byPointer = build(join(tmp, 'addr-ptr'), c, cSymbol('MoveSystem'), 'pointer');
const a = movedWorld(layout);
const b = movedWorld(layout);
for (let f = 0; f < FRAMES; f++) {
frameOfC(byOffset, a, move);
frameOfC(byPointer, b, move);
expect(same(a, b), `address models diverged at frame ${f}`).toBe(true);
}
expect(same(a, movedWorld(layout)), 'nothing moved, so agreeing proves nothing').toBe(false);
});
it('the object file has nothing to import but the memory it lives in', () => {
const layout = packLayout(shipped.module.comps);
const cModule = emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]);
const dir = join(tmp, 'imports');
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'estella_abi.h'), cModule.header);
writeFileSync(join(dir, 'estella_offsets.h'), cModule.offsets);
writeFileSync(join(dir, 'systems.c'), cModule.source);
const obj = join(dir, 'systems.o');
const out = spawnSync(CC!, [...CFLAGS, '-Wall', '-Wextra', '-c',
join(dir, 'systems.c'), '-o', obj], { encoding: 'utf8' });
expect(out.status, out.stderr).toBe(0);
expect(out.stderr.trim()).toBe('');
// The contract is about the wasm import section; natively the same
// property is "no undefined symbol". `es_memory` is the linear memory itself, which
// on wasm is not an import at all — it IS the module's memory.
const nm = spawnSync('nm', [obj], { encoding: 'utf8' });
if (nm.status !== 0) {
console.warn('[codegen] nm unavailable — the undefined-symbol check did NOT run.');
return;
}
const undef = nm.stdout.split(/\r?\n/)
.filter((l) => /\s[Uu]\s/.test(l))
.map((l) => l.trim().split(/\s+/).pop()!)
.filter((s) => s !== 'es_memory');
// Compiled WITHOUT ES_ADDR_BASE, so there is not even a memory base to
// resolve: an address is a pointer and the object file is closed.
expect(undef, 'a compiled system may not call the engine').toEqual([]);
});
it('the artifact carries what it baked in about the engine', () => {
const layout = packLayout(shipped.module.comps);
const c = emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]);
expect(c.decls).toContain(`#define ES_ABI_ENGINE_DIGEST 0x${c.handshake.engineAbi}ULL`);
expect(c.handshake.engineAbi).toMatch(/^[0-9a-f]{16}$/);
expect(c.handshake.projectShapes).toMatch(/^[0-9a-f]{16}$/);
});
it('the project digest follows the shapes the systems NAME, and only those', () => {
const layout = packLayout(shipped.module.comps);
const move = systemOf(shipped, 'MoveSystem');
const before = emitC(shipped.module, layout, [move]).handshake;
// A component nobody compiled against must not invalidate the module.
const extra = new Map(shipped.module.comps);
extra.set('Unrelated', {
name: 'Unrelated', storage: 'host',
fields: new Map([['x', { type: F64, enc: 'f64', offset: null } as const]]),
});
const widened = emitC({ ...shipped.module, comps: extra }, packLayout(extra), [move]);
expect(widened.handshake.projectShapes).toBe(before.projectShapes);
// A component it DOES name, with a field added, must.
const changed = new Map(shipped.module.comps);
const mover = changed.get('Mover')!;
changed.set('Mover', {
...mover,
fields: new Map([...mover.fields, ['drag', { type: F64, enc: 'f64', offset: null } as const]]),
});
const moved = emitC({ ...shipped.module, comps: changed }, packLayout(changed), [move]);
expect(moved.handshake.projectShapes).not.toBe(before.projectShapes);
});
it('parameter order is in the MANIFEST, which is why it is not in a digest', () => {
// A digest could only say "something moved". The order is what the host
// follows when it fills the ctx, so it is carried rather than compared.
const layout = packLayout(shipped.module.comps);
const { decls } = emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]);
expect(decls).toContain('{ "Transform", "Mover" }');
expect(decls).toContain('{ "Time" }');
});
it('what the artifact exports is what a host computes, at both widths', () => {
// The C compiler folds it out of the contract hash and its own
// sizeof(es_addr_t), so ask one for both widths and compare against the
// TS side a loader would use.
const layout = packLayout(shipped.module.comps);
const c = emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]);
const dir = join(tmp, 'handshake');
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'estella_abi.h'), c.header);
writeFileSync(join(dir, 'estella_offsets.h'), c.offsets);
writeFileSync(join(dir, 'systems.c'), c.source);
writeFileSync(join(dir, 'systems_decl.c'), c.decls);
writeFileSync(join(dir, 'main.c'), [
'#include <stdio.h>',
'#include "estella_abi.h"',
'extern const uint64_t es_abi_hash;',
'#if defined(ES_ADDR_BASE)',
'unsigned char *es_memory;',
'#endif',
'int main(void) {',
' printf("%016llx %d\\n", (unsigned long long)es_abi_hash, (int)sizeof(es_addr_t));',
' return 0;',
'}',
].join('\n'));
for (const [flags, bytes] of [[['-DES_ADDR_BASE'], 4], [[], 8]] as const) {
const exe = join(dir, `h${bytes}${process.platform === 'win32' ? '.exe' : ''}`);
const built = spawnSync(CC!, [...CFLAGS, '-Wall', '-Wextra', ...flags, '-o', exe,
join(dir, 'main.c'), join(dir, 'systems.c'), join(dir, 'systems_decl.c'), '-lm'],
{ encoding: 'utf8' });
expect(built.status, built.stderr).toBe(0);
expect(built.stderr.trim()).toBe('');
const [got, width] = execFileSync(exe, { encoding: 'utf8' }).trim().split(' ');
// 8 only where the platform's pointers are; a 32-bit host would say 4
// and the assertion below would then be about the width it really has.
expect(abiHashFor(c.handshake.engineAbi, Number(width) as 4 | 8)).toBe(got);
if (flags.length > 0) expect(Number(width)).toBe(bytes);
}
});
it('a component field is one load at a constant offset', () => {
const layout = packLayout(shipped.module.comps);
const { source } = emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]);
// EIR's whole reason for existing, readable in the output itself.
expect(source).toMatch(/es_f32\(\w+ \+ ES_OFF_Transform_position_x\)/);
expect(emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]).offsets)
.toMatch(/#define ES_OFF_Transform_position_x \d+u/);
// And the thing v0 had that v1 does not: a call back across the boundary.
expect(source).not.toMatch(/\bes_abi_\w+\(/);
});
});
/**
* What a road has to hand a compiled system before it does anything. A host
* that passes 0 in `events` faults on a frame where the system would have done
* nothing, which is why `installNativeAot` leaves event systems interpreted.
* Narrow this and that rule can be narrowed with it.
*/
describe('what the emitted C reaches for before it does anything', () => {
it('a writer dereferences the event block at entry, not at the send', () => {
const layout = packLayout(fixtures.module.comps);
const ping = systemOf(fixtures, 'FixturePing');
const { source } = emitC(fixtures.module, layout, [ping], 8);
const body = source.slice(source.indexOf(cSymbol('FixturePing')));
const prologue = body.slice(0, body.indexOf('for ('));
expect(prologue).toContain('ES_PTR(es_c->events)');
expect(prologue).toMatch(/es_ev_buf = \(double \*\)ES_PTR\(es_ev->buf\)/);
});
/** A reader asks for its payloads through a query slot that names the EVENT,
* which is what the artifact's declaration table tells a host as well. */
it('a reader names its event where a host reads a component name', () => {
const layout = packLayout(fixtures.module.comps);
const { decls } = emitC(fixtures.module, layout, [systemOf(fixtures, 'FixturePong')], 8);
expect(decls).toContain('"FixturePinged"');
});
});