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 generated.test.ts
* @brief The C artifacts the engine builds against, and their freshness.
*
* @details The C++ side has to compile without running this compiler, so the
* contract header and one compiled system are checked in. Checked-in
* generated files drift, so this regenerates them and compares — the
* same bargain EHT's outputs already make.
*
* To refresh after changing the code generator:
*
* ESTELLA_AOT_WRITE=1 pnpm --filter @estella/compiler test
*/
import { describe, it, expect } from 'vitest';
import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { lowerProgram, brokenPromises } from '../src/frontend';
import { verifySystem } from '../src/verify';
import { inlineSystem } from '../src/inline';
import { builtinShapes } from '../src/builtins';
import { packLayout } from '../src/abi';
import { emitC } from '../src/codegen';
import { engineAbiDigest } from '../../sdk/src/ecs/aot/abiDigest';
const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));
const WRITE = process.env['ESTELLA_AOT_WRITE'] === '1';
/** The one system the corpus marks `@compiled`, which is what makes it a fixture
* worth checking in: it is shipped code, not something written for a test. */
const result = lowerProgram([
resolve(ROOT, 'examples/ecs-basics/src/systems/move.ts'),
resolve(ROOT, 'examples/ecs-basics/src/components.ts'),
], builtinShapes());
function artifact(path: string, want: string): void {
if (WRITE) {
// Only when it differs: a rewrite of the same bytes moves the mtime every
// freshness check reads, and the engine built a minute ago reads as stale.
const same = existsSync(path) && readFileSync(path, 'utf8').replace(/\r\n/g, '\n') === want;
if (!same) {
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, want);
}
return;
}
const rel = path.slice(ROOT.length + 1);
expect(existsSync(path), `${rel} is missing — regenerate with ESTELLA_AOT_WRITE=1`).toBe(true);
// Normalised: git may have handed the working tree CRLF, and the difference
// is not one anybody wants a diff about.
const have = readFileSync(path, 'utf8').replace(/\r\n/g, '\n');
expect(have, `${rel} is stale — regenerate with ESTELLA_AOT_WRITE=1`).toBe(want);
}
describe('the C artifacts the engine builds against', () => {
const move = result.module.systems.find((s) => s.name === 'MoveSystem');
it('lowers the promised system', () => {
expect(brokenPromises(result)).toEqual([]);
expect(move).toBeDefined();
expect(verifySystem(move!, result.module.comps, result.module.fns)).toEqual([]);
});
const layout = packLayout(result.module.comps);
// Width 8: the only consumer is a native harness, and a fixture that bakes
// the other width is not the artifact a native build makes.
const c = emitC(result.module, layout, [inlineSystem(move!, result.module.fns)], 8);
it('the contract header, where the engine can include it', () => {
artifact(join(ROOT, 'src/esengine/aot/estella_abi.h'), c.header);
});
it('the offsets and the system, where the harness can build them', () => {
artifact(join(ROOT, 'tests/aot/generated/estella_offsets.h'), c.offsets);
artifact(join(ROOT, 'tests/aot/generated/move_system.c'), c.source);
});
/** The C++ host reads the table out of the artifact; a wasm host must not
* compile it, because a data section of its own overwrites the engine's. */
it('and the declarations, which only a linking host compiles', () => {
artifact(join(ROOT, 'tests/aot/generated/move_system_decl.c'), c.decls);
});
/**
* The digest a HOST compares a module against, from the same function the
* module's own comes from — so a native host carries no second opinion
* about what this engine is.
*/
it('the engine digest, where a native host can compare against it', () => {
artifact(join(ROOT, 'src/esengine/aot/EngineDigest.generated.h'), [
'/* GENERATED by @estella/compiler — do not edit. */',
'/* What this engine is, for a host opening a compiled module. */',
'#pragma once',
'',
'#include "esengine/aot/estella_abi.h"',
'',
'/* One per address width, because the width is IN the digest: a host that',
' took the other one would refuse every module built for it. */',
`#define ES_ENGINE_ABI_DIGEST_32 0x${engineAbiDigest(4)}ULL`,
`#define ES_ENGINE_ABI_DIGEST_64 0x${engineAbiDigest(8)}ULL`,
'#define ES_ENGINE_ABI_DIGEST \\',
' (sizeof(es_addr_t) == 8 ? ES_ENGINE_ABI_DIGEST_64 : ES_ENGINE_ABI_DIGEST_32)',
'',
].join('\n'));
});
it('and the hash the harness compares, so it is not a second copy', () => {
artifact(join(ROOT, 'tests/aot/generated/move_system_hash.h'), [
'/* GENERATED by @estella/compiler — do not edit. */',
'/* The contract half of the handshake. The width half is the harness. */',
`#define ES_EXPECTED_CONTRACT_HASH 0x${c.handshake.engineAbi}ULL`,
'/* And which BUILD the artifact beside this one is, which the sidecar',
' written with it has to carry too. */',
`#define ES_EXPECTED_MODULE_CONTRACT 0x${c.handshake.moduleContract}ULL`,
'',
].join('\n'));
});
});