Skip to content

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.

5.7 KB
Raw Blame
// 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'));
    });
});