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.

22.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    aot-native-install.test.ts
 * @brief   Installing compiled systems on a host that loads a library.
 *
 * @details The host is stood in for, because what is worth pinning here is not
 *          that a `.dll` opens — `tests/aot/test_aot_host.cpp` does that against
 *          a real one — but the three things this side owes it: only the systems
 *          it BOUND become twins, the pools are re-reported when they may have
 *          moved, and the Changed ticks the compiled code cannot leave.
 *
 *          The first is the one that fails silently. The runner calls a twin
 *          wherever it finds one, so a twin for a system the host could not bind
 *          is a system that never runs at all.
 *
 *          The fourth is the script pools' epoch. The host keeps last frame's
 *          row table while the world stands, and it can read the engine's half
 *          itself — a script row appearing or going is the half only this side
 *          can see.
 */
import { describe, it, expect } from 'vitest';
import { World } from '../src/ecs/world';
import { defineComponent, getComponent } from '../src/ecs/component';
import { defineSystem, SystemRunner } from '../src/ecs/system';
import { defineEvent, EventReader, EventWriter, EventRegistry } from '../src/ecs/event';
import { Query, Mut, Changed } from '../src/ecs/query';
import { Commands } from '../src/ecs/commands';
import { ResourceStorage } from '../src/ecs/resource';
import { engineAbiDigest, projectShapeDigest } from '../src/ecs/aot/abiDigest';
import type { AotManifest } from '../src/ecs/aot/AotSystems';
import { installNativeAot, type NativeAotBindings } from '../src/ecs/aot/installNativeAot';
import { AotSystems } from '../src/ecs/aot/AotSystems';
import type { WasmHeap } from '../src/ecs/WasmPoolMemory';

/** Declared per test, not at module scope: the suite's setup resets the
 *  component context, and `installNativeAot` resolves names through it. */
const declareDrift = () => defineComponent('Drift', { x: 0 });

/** A linear heap, the way a native host's arena looks from here. */
function fakeHeap(): WasmHeap {
    const bytes = new Uint8Array(1 << 16);
    let next = 8;
    return {
        _malloc: (size: number) => { const at = next; next += (size + 7) & ~7; return at; },
        _free: () => {},
        HEAPU8: bytes,
    };
}

const MANIFEST: AotManifest = {
    engineAbi: engineAbiDigest(8),
    projectShapes: projectShapeDigest([{ name: 'Drift', fields: ['x'] }]),
    systems: [
        { name: 'DriftSystem', symbol: 'es_sys_Drift', commands: false, queries: [[{ comp: 'Drift', mut: true }]], resources: [] },
        { name: 'OtherSystem', symbol: 'es_sys_Other', commands: false, queries: [[{ comp: 'Drift', mut: true }]], resources: [] },
    ],
};

/** A host that can run only the systems it was told it could name. */
function fakeHost(runnable: readonly string[]) {
    const order = MANIFEST.systems.map((s) => s.name);
    const calls: number[] = [];
    const epochs: number[] = [];
    const reported: { name: string; rows: number; sparseCount: number }[] = [];
    const bindings: NativeAotBindings = {
        install: () => order.length,
        index: (name) => order.indexOf(name),
        bound: (i) => runnable.includes(order[i] ?? ''),
        scriptRows: (name, _sparse, sparseCount, rows) => {
            reported.push({ name, rows, sparseCount });
            return true;
        },
        resource: () => true,
        // Negative is "I still cannot name everything this reads" — the answer
        // that sends the system back to the interpreter for this frame.
        run: (i, scriptEpoch) => {
            if (!runnable.includes(order[i] ?? '')) return -1;
            calls.push(i);
            epochs.push(scriptEpoch);
            return 0;
        },
        reset: () => {},
    };
    return { bindings, calls, reported, epochs };
}

function fixture(boundNames: readonly string[]) {
    const Drift = declareDrift();
    const world = new World();
    const runner = new SystemRunner(world, new ResourceStorage());
    const host = fakeHost(boundNames);
    const runtime = installNativeAot({
        world, runner, modulePath: 'systems.dll', manifest: MANIFEST,
        heap: fakeHeap(), bindings: host.bindings,
    });
    return { world, runner, runtime, Drift, ...host };
}

/**
 * The same two systems, plus one that writes an event and one that reads one.
 * A reader's payloads come through a QUERY slot naming the event, which is what
 * the compiled artifact tells a host as well.
 */
const EVENT_MANIFEST: AotManifest = {
    engineAbi: engineAbiDigest(8),
    projectShapes: projectShapeDigest([
        { name: 'Drift', fields: ['x'] },
        { name: 'Hit', fields: ['amount'] },
    ]),
    systems: [
        {
            name: 'SendSystem', symbol: 'es_sys_Send', commands: false, resources: [],
            queries: [[{ comp: 'Drift', mut: true }]],
            writers: [{ slot: 0, event: 'Hit', fields: ['amount'] }],
        },
        {
            name: 'ReadSystem', symbol: 'es_sys_Read', commands: false, resources: [],
            queries: [[{ comp: 'Hit', mut: false }], [{ comp: 'Drift', mut: true }]],
            readers: [{ slot: 0, event: 'Hit', fields: ['amount'] }],
        },
        {
            name: 'PlainSystem', symbol: 'es_sys_Plain', commands: false, resources: [],
            queries: [[{ comp: 'Drift', mut: true }]],
        },
        // The other capability this road lacks, and the quiet one: a loading
        // host applies a despawn to its own Registry inside the call, and the
        // World the interpreter would have despawned from never hears.
        {
            name: 'ReapSystem', symbol: 'es_sys_Reap', commands: true, resources: [],
            queries: [[{ comp: 'Drift', mut: true }]],
        },
    ],
};

function eventFixture() {
    const Drift = declareDrift();
    const Hit = defineEvent<{ amount: number }>('Hit', { amount: 0 });
    const events = new EventRegistry();
    const world = new World();
    const runner = new SystemRunner(world, new ResourceStorage(), events);
    const order = EVENT_MANIFEST.systems.map((s) => s.name);
    const calls: string[] = [];
    // A host that can name and run EVERY system in the module — so what keeps
    // its hands off the two event systems is this side's decision, not its
    // inability, which is the thing under test.
    const bindings: NativeAotBindings = {
        install: () => order.length,
        index: (name) => order.indexOf(name),
        bound: () => true,
        scriptRows: () => true,
        resource: () => true,
        run: (i) => { calls.push(order[i] ?? `#${i}`); return 0; },
        reset: () => {},
    };
    const runtime = installNativeAot({
        world, runner, modulePath: 'systems.dll', manifest: EVENT_MANIFEST,
        heap: fakeHeap(), bindings,
    });
    return { world, runner, runtime, Drift, Hit, events, calls };
}

describe('installing compiled systems on a host that loads a library', () => {
    it('a retired runtime refuses saved and runner-owned native dispatchers',()=>{
        const f=fixture(['DriftSystem']),entity=f.world.spawn();f.world.insert(entity,f.Drift,{x:7});
        let interpreted=0;const system=defineSystem([Query(Mut(f.Drift))],()=>{interpreted++;},{name:'DriftSystem'});
        const dispatcher=f.runtime!.dispatcherFor(f.world),twin=f.runtime!.systems.get('DriftSystem');
        f.runner.run(system);expect(f.calls).toEqual([0]);f.runtime!.dispose?.();f.runtime!.dispose?.();
        f.runner.run(system);expect(interpreted).toBe(1);expect(f.calls).toEqual([0]);
        if(twin)expect(dispatcher.run(twin)).toBe(false);
    });
    it('interprets every matching row with a portable asset ref, then resumes compiled',()=>{
        const f=fixture(['DriftSystem']);
        const fields=[{field:'x',type:'texture'}];
        Object.defineProperty(f.Drift,'assetFields',{value:fields});
        const first=f.world.spawn(),second=f.world.spawn();
        f.world.insert(first,f.Drift,{x:7});f.world.insert(second,f.Drift,{x:'@uuid:unresolved'} as never);
        const seen:unknown[]=[];
        const system=defineSystem([Query(Mut(f.Drift))],query=>{
            for(const [,data] of query)seen.push(data.x);
        },{name:'DriftSystem'});
        f.runner.run(system);expect(seen).toEqual([7,'@uuid:unresolved']);expect(f.calls).toEqual([]);
        f.world.set(second,f.Drift,{x:9});f.runner.run(system);
        expect(f.calls).toEqual([0]);expect(seen).toEqual([7,'@uuid:unresolved']);
        f.world.set(first,f.Drift,{x:'@uuid:later'} as never);f.runner.run(system);
        expect(f.calls).toEqual([0]);expect(seen.slice(2)).toEqual(['@uuid:later',9]);
        fields.length=0;f.runner.run(system);
        expect(f.calls).toEqual([0]);expect(seen.slice(4)).toEqual(['@uuid:later',9]);
    });
    it('a system the host cannot run is interpreted that frame, not skipped', () => {
        const f = fixture(['DriftSystem']);
        const Drift = f.Drift;
        expect(f.runtime).not.toBeNull();
        // Every declared system has a twin: whether the host can run one is a
        // fact about the frame — a pool has no rows until an entity has that
        // component — so it is settled at the call and asked again next time.
        expect(f.runtime!.systems.size).toBe(2);

        let interpreted = 0;
        const other = defineSystem([Query(Mut(Drift))], () => { interpreted++; }, { name: 'OtherSystem' });
        const compiled = defineSystem([Query(Mut(Drift))], () => {
            throw new Error('the closure must not run when the host took this one');
        }, { name: 'DriftSystem' });

        const entity = f.world.spawn();
        f.world.insert(entity, Drift, { x: 0 });
        f.runner.run(compiled);
        f.runner.run(other);

        expect(f.calls).toEqual([0]);
        expect(interpreted).toBe(1);
    });

    it('every system interprets where the host can run none of them', () => {
        const f = fixture([]);
        const Drift = f.Drift;

        let interpreted = 0;
        const system = defineSystem([Query(Mut(Drift))], () => { interpreted++; }, { name: 'DriftSystem' });
        f.runner.run(system);
        f.runner.run(system);

        expect(f.calls).toEqual([]);
        // Twice, because a refusal is per frame: the host may be able to next one.
        expect(interpreted).toBe(2);
    });

    it('tells the host where the rows are, once per move rather than per frame', () => {
        const f = fixture(['DriftSystem']);
        const Drift = f.Drift;
        const system = defineSystem([Query(Mut(Drift))], () => {}, { name: 'DriftSystem' });
        const entity = f.world.spawn();
        f.world.insert(entity, Drift, { x: 0 });

        f.runner.run(system);
        const afterFirst = f.reported.length;
        expect(afterFirst).toBeGreaterThan(0);
        expect(f.reported[0]!.name).toBe('Drift');

        // Nothing moved, so nothing is said again — the epoch is the whole rule.
        f.runner.run(system);
        expect(f.reported.length).toBe(afterFirst);

        // A claimed row bumps it, and the host is told the new column.
        const second = f.world.spawn();
        f.world.insert(second, Drift, { x: 0 });
        f.runner.run(system);
        expect(f.reported.length).toBeGreaterThan(afterFirst);
    });

    it('hands the host the script epoch, which moves when a row does', () => {
        const f = fixture(['DriftSystem']);
        const Drift = f.Drift;
        const system = defineSystem([Query(Mut(Drift))], () => {}, { name: 'DriftSystem' });
        const entity = f.world.spawn();
        f.world.insert(entity, Drift, { x: 0 });

        f.runner.run(system);
        f.runner.run(system);
        // Nothing moved between them, and the host may keep its rows only
        // because this number said so.
        expect(f.epochs.length).toBe(2);
        expect(f.epochs[1]).toBe(f.epochs[0]);

        // A row claimed, and a row given up. Neither moves an address the engine
        // can see, and a deletion does not even change the column's length — so
        // this is the only report the host gets.
        const second = f.world.spawn();
        f.world.insert(second, Drift, { x: 0 });
        f.runner.run(system);
        expect(f.epochs[2]).toBeGreaterThan(f.epochs[1]!);

        f.world.remove(second, Drift);
        f.runner.run(system);
        expect(f.epochs[3]).toBeGreaterThan(f.epochs[2]!);
    });

    it('marks the Changed ticks the compiled code could not leave', () => {
        const f = fixture(['DriftSystem']);
        const Drift = f.Drift;
        const system = defineSystem([Query(Mut(Drift))], () => {}, { name: 'DriftSystem' });
        // A watcher is the only thing that can tell: the compiled code calls
        // nothing, so a `Mut` it honoured is invisible unless the host records it.
        const watched: number[] = [];
        const watcher = defineSystem([Query(Changed(Drift))], (query) => {
            let n = 0;
            for (const _ of query as Iterable<unknown>) n++;
            watched.push(n);
        }, { name: 'Watcher' });

        const entity = f.world.spawn();
        f.world.insert(entity, Drift, { x: 0 });
        // Past the tick the insert itself marked, so what the watcher sees next
        // is the dispatcher's doing and not the spawn's.
        f.world.advanceTick();
        f.runner.run(watcher);
        f.world.advanceTick();

        f.runner.run(system);
        f.runner.run(watcher);

        expect(watched.at(-1)).toBe(1);
    });
});


/**
 * A native host's ctx carries `events = 0` (AotHost.hpp) and the emitted C
 * dereferences it before it looks at a row: probed against a real artifact, a
 * writer-only system with ZERO rows segfaults on entry. Nothing stopped it —
 * the takeover question was "did the library export this symbol".
 */
describe('a capability a loading host cannot hand compiled code', () => {
    it('leaves an event WRITER to the interpreter, and the event still arrives', () => {
        const f = eventFixture();
        expect(f.runtime).not.toBeNull();

        let sent = 0;
        const send = defineSystem([Query(Mut(f.Drift)), EventWriter(f.Hit)], (_q, out) => {
            sent++;
            out.send({ amount: 7 });
        }, { name: 'SendSystem' });
        const seen: number[] = [];
        const watch = defineSystem([EventReader(f.Hit)], (hits) => {
            for (const h of hits) seen.push(h.amount);
        }, { name: 'WatchSystem' });

        const entity = f.world.spawn();
        f.world.insert(entity, f.Drift, { x: 0 });
        f.runner.run(send);
        f.events.swapAll();
        f.runner.run(watch);

        expect(f.calls).not.toContain('SendSystem');
        expect(sent).toBe(1);
        expect(seen).toEqual([7]);
    });

    it('leaves an event READER to the interpreter, which is the half that would go quiet', () => {
        const f = eventFixture();
        f.events.getBus(f.Hit).send({ amount: 3 });
        f.events.swapAll();

        const seen: number[] = [];
        const read = defineSystem([EventReader(f.Hit), Query(Mut(f.Drift))], (hits) => {
            for (const h of hits) seen.push(h.amount);
        }, { name: 'ReadSystem' });
        f.runner.run(read);

        expect(f.calls).not.toContain('ReadSystem');
        expect(seen).toEqual([3]);
    });

    it('leaves a system that COMMANDS to the interpreter, and the despawn lands', () => {
        const f = eventFixture();
        const reap = defineSystem([Query(Mut(f.Drift)), Commands()], (query, cmds) => {
            for (const [e] of query) cmds.despawn(e);
        }, { name: 'ReapSystem' });

        const entity = f.world.spawn();
        f.world.insert(entity, f.Drift, { x: 0 });
        f.runner.run(reap);

        expect(f.calls).not.toContain('ReapSystem');
        // The half that was silent: the twin ran, the C++ Registry lost the
        // entity and this world kept it in every query it matched.
        expect(f.world.valid(entity)).toBe(false);
    });

    it('counts the calls it took, which is what says installed is not ran', () => {
        const f = eventFixture();
        const plain = defineSystem([Query(Mut(f.Drift))], () => {}, { name: 'PlainSystem' });
        const entity = f.world.spawn();
        f.world.insert(entity, f.Drift, { x: 0 });
        f.runner.run(plain);
        f.runner.run(plain);

        // `App.compiledSystems` reports this to answer one question: a module
        // that loaded and was never dispatched to. Counted on the wasm road
        // only, so on the road whose fallback is by DESIGN it read 0 forever.
        expect(f.runtime!.systems.calls).toBe(2);
    });

    it('and takes the system that needs none of it', () => {
        const f = eventFixture();
        const plain = defineSystem([Query(Mut(f.Drift))], () => {
            throw new Error('the closure must not run when the host took this one');
        }, { name: 'PlainSystem' });
        const entity = f.world.spawn();
        f.world.insert(entity, f.Drift, { x: 0 });
        f.runner.run(plain);

        expect(f.calls).toEqual(['PlainSystem']);
    });
});


/**
 * Probed against two real native builds before this existed: one writing
 * Transform, one writing Mover, same engine and same components — SAME
 * engineAbi, SAME projectShapes, and the artifact's baked hash is a pure
 * function of those. Nothing paired a sidecar to the module it describes.
 */
describe('a module and the sidecar written beside it', () => {
    const PAIRED = 'aaaabbbbccccdddd';
    const paired = (contract: string | null): AotManifest => ({
        ...MANIFEST,
        moduleContract: contract ?? undefined,
    });

    function install(manifest: AotManifest, hostSays: string | undefined) {
        const order = manifest.systems.map((s) => s.name);
        const bindings: NativeAotBindings = {
            install: () => order.length,
            index: (name) => order.indexOf(name),
            bound: () => true,
            scriptRows: () => true,
            resource: () => true,
            run: () => 0,
            reset: () => {},
            ...(hostSays === undefined ? {} : { contract: () => hostSays }),
        };
        declareDrift();
        const world = new World();
        return () => installNativeAot({
            world, runner: new SystemRunner(world, new ResourceStorage()),
            modulePath: 'systems.dll', manifest, heap: fakeHeap(), bindings,
        });
    }

    it('are refused when they are from different builds', () => {
        expect(install(paired('0123456789abcdef'), PAIRED)).toThrow(/different builds/);
    });

    it('are refused when the module is paired and the sidecar predates pairing', () => {
        expect(install(paired(null), PAIRED)).toThrow(/different builds/);
    });

    it('install when they agree', () => {
        expect(install(paired(PAIRED), PAIRED)).not.toThrow();
    });

    /** A host too old to answer cannot be asked; that is unpaired, and it is
     *  the one case this cannot turn into a refusal without breaking every
     *  runtime template built before the question existed. */
    it('install where the host cannot say which build the module is', () => {
        expect(install(paired(PAIRED), '')).not.toThrow();
        expect(install(paired(PAIRED), undefined)).not.toThrow();
    });
});


/**
 * A payload's field ORDER is what compiled code baked in, and a manifest
 * compared against itself always agrees. `defineEvent` carries the payload as a
 * VALUE — what a component's defaults already are — so this side says what the
 * order is without being told by the module.
 */
describe('an event payload is a project shape', () => {
    const manifestFor = (fields: readonly string[]): AotManifest => ({
        engineAbi: engineAbiDigest(8),
        projectShapes: projectShapeDigest([
            { name: 'Drift', fields: ['x'] },
            { name: 'Struck', fields: [...fields] },
        ]),
        systems: [{
            name: 'AbsorbSystem', symbol: 'es_sys_Absorb', commands: false, resources: [],
            queries: [[{ comp: 'Struck', mut: false }], [{ comp: 'Drift', mut: true }]],
            readers: [{ slot: 0, event: 'Struck', fields: [...fields] }],
        }],
    });

    const install = (m: AotManifest) => () => new AotSystems().install(
        m, { es_sys_Absorb: () => {} }, (name) => getComponent(name), { addressBytes: 8 });

    it('installs where the payload this project declares is the one it was built for', () => {
        declareDrift();
        defineEvent<{ target: number; amount: number }>('Struck', { target: 0, amount: 0 });
        expect(install(manifestFor(['target', 'amount']))).not.toThrow();
    });

    /** A rename: the module reads a field now called something else, and every
     *  value it delivers is undefined. */
    it('refuses a module built against a payload this project no longer has', () => {
        declareDrift();
        defineEvent<{ target: number; power: number }>('Renamed', { target: 0, power: 0 });
        const m = manifestFor(['target', 'amount']);
        const renamed: AotManifest = {
            ...m,
            projectShapes: projectShapeDigest([
                { name: 'Drift', fields: ['x'] },
                { name: 'Renamed', fields: ['target', 'amount'] },
            ]),
            systems: [{ ...m.systems[0]!, queries: [[{ comp: 'Renamed', mut: false }], [{ comp: 'Drift', mut: true }]],
                readers: [{ slot: 0, event: 'Renamed', fields: ['target', 'amount'] }] }],
        };
        expect(install(renamed)).toThrow(/built for components/);
    });

    /** And the reorder, which changes every position without changing a name. */
    it('refuses a module built against the same fields in another order', () => {
        declareDrift();
        defineEvent<{ target: number; amount: number }>('Reordered', { amount: 0, target: 0 });
        const m = manifestFor(['target', 'amount']);
        const swapped: AotManifest = {
            ...m,
            projectShapes: projectShapeDigest([
                { name: 'Drift', fields: ['x'] },
                { name: 'Reordered', fields: ['target', 'amount'] },
            ]),
            systems: [{ ...m.systems[0]!, queries: [[{ comp: 'Reordered', mut: false }], [{ comp: 'Drift', mut: true }]],
                readers: [{ slot: 0, event: 'Reordered', fields: ['target', 'amount'] }] }],
        };
        expect(install(swapped)).toThrow(/built for components/);
    });
});