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.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  Who decides when world transforms are recomposed.
 *
 * A staleness epoch that producers advance and consumers wait on. A render
 * frame is not a mutation: a server with no frames still recomposes, and two
 * fixed steps inside one frame each get their own answer.
 */
import { describe, it, expect, beforeAll } from 'vitest';
import { App } from '../src/app/app';
import { Sprite, Transform } from '../src/ecs/component';
import type { CppRegistry, ESEngineModule } from '../src/wasm';
import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';

describe.skipIf(!HAS_WASM)('world transform authority', () => {
    let module: ESEngineModule;
    beforeAll(async () => { module = await loadWasmModule(); });

    it('composes a legal hierarchy beyond the former 256-level cutoff', () => {
        const registry = new module.Registry() as unknown as CppRegistry;
        const app = App.new(); app.connectCpp(registry, module);
        const world = app.world;
        let parent: ReturnType<typeof world.spawn> | undefined;
        for (let i = 0; i < 600; ++i) {
            const child = world.spawn();
            world.insert(child, Transform, { position: { x: 1, y: 0, z: 0 } });
            if (parent !== undefined) world.setParent(child, parent);
            parent = child;
        }
        world.ensureTransformsComposed();
        expect(world.get(parent!, Transform).worldPosition.x).toBe(600);
        world.disconnectCpp(); (registry as any).delete();
    });

    /** A parent at 100 and a child 5 to its right, on a server with no renderer. */
    function parented() {
        const app = App.new();
        app.connectCpp(new module.Registry() as unknown as CppRegistry, module);
        const world = app.world;
        const parent = world.spawn('parent');
        world.insert(parent, Transform, { position: { x: 100, y: 0, z: 0 } });
        const child = world.spawn('child');
        world.insert(child, Transform, { position: { x: 5, y: 0, z: 0 } });
        world.setParent(child, parent);
        const worldX = () => (world.get(child, Transform) as { worldPosition: { x: number } })
            .worldPosition.x;
        return { app, world, parent, child, worldX };
    }

    it('composes for a server that has no renderer at all', () => {
        const { world, worldX } = parented();
        world.ensureTransformsComposed();
        expect(worldX()).toBe(105);
    });

    it('recomposes for each of two steps inside one frame', () => {
        const { world, parent, worldX } = parented();
        world.update(parent, Transform, (t) => { (t as { position: { x: number } }).position.x = 10; });
        world.ensureTransformsComposed();
        expect(worldX()).toBe(15);

        // No frame boundary between these: replication samples on every fixed
        // step, and a frame may run several.
        world.update(parent, Transform, (t) => { (t as { position: { x: number } }).position.x = 20; });
        world.ensureTransformsComposed();
        expect(worldX()).toBe(25);
    });

    it('composes once for any number of consumers in one generation', () => {
        const { world, parent, worldX } = parented();
        world.update(parent, Transform, (t) => { (t as { position: { x: number } }).position.x = 7; });
        const epoch = world.transformEpoch();

        world.ensureTransformsComposed();
        world.ensureTransformsComposed();
        world.ensureTransformsComposed();

        expect(worldX()).toBe(12);
        // Composing does not itself count as a mutation: writing the world
        // fields must not advance the epoch, or every compose is stale again.
        expect(world.transformEpoch()).toBe(epoch);
    });

    it('a render frame is not a mutation', () => {
        const { world } = parented();
        world.ensureTransformsComposed();
        const epoch = world.transformEpoch();
        module.renderer_beginFrame(0);
        expect(world.transformEpoch()).toBe(epoch);
    });

    it('every legal write path advances the epoch', () => {
        const { world, parent } = parented();
        const advances = (fn: () => void): boolean => {
            const before = world.transformEpoch();
            fn();
            return world.transformEpoch() !== before;
        };
        expect(advances(() => world.update(parent, Transform, (t) => {
            (t as { position: { x: number } }).position.x += 1;
        }))).toBe(true);
        expect(advances(() => world.set(parent, Transform,
            world.get(parent, Transform)))).toBe(true);
        expect(advances(() => world.markChanged(parent, Transform))).toBe(true);
        // Hierarchy moves a subtree without touching a single transform.
        const other = world.spawn('other');
        world.insert(other, Transform, { position: { x: 0, y: 0, z: 0 } });
        expect(advances(() => world.setParent(other, parent))).toBe(true);
    });

    it('survives the wasm heap growing under the notifier', () => {
        const { world, parent, worldX } = parented();
        world.ensureTransformsComposed();

        // A cached typed-array view detaches when Emscripten replaces the heap,
        // and writes to it go nowhere while looking like they worked.
        const before = module.HEAPU32.buffer;
        const blocks: number[] = [];
        for (let i = 0; i < 64 && module.HEAPU32.buffer === before; i++) {
            blocks.push((module as unknown as { _malloc(n: number): number })._malloc(8 << 20));
        }
        expect(blocks.length).toBeGreaterThan(0);

        world.update(parent, Transform, (t) => { (t as { position: { x: number } }).position.x = 400; });
        world.ensureTransformsComposed();
        expect(worldX()).toBe(405);
    });

    it('keeps two worlds apart even at the same epoch value', () => {
        const a = parented();
        a.world.ensureTransformsComposed();
        expect(a.worldX()).toBe(105);

        // A second registry, composed at whatever number the shared epoch holds:
        // having composed the first world says nothing about this one.
        const b = parented();
        b.world.ensureTransformsComposed();
        expect(b.worldX()).toBe(105);
    });

    it('composes a chain built after the first compose', () => {
        const app = App.new();
        app.connectCpp(new module.Registry() as unknown as CppRegistry, module);
        const world = app.world;
        world.ensureTransformsComposed();
        const p = world.spawn();
        world.insert(p, Transform, { position: { x: 3, y: 0, z: 0 } });
        const c = world.spawn();
        world.insert(c, Transform, { position: { x: 4, y: 0, z: 0 } });
        world.setParent(c, p);
        world.ensureTransformsComposed();
        expect((world.get(c, Transform) as { worldPosition: { x: number } }).worldPosition.x).toBe(7);
        world.disconnectCpp();
    });
});

describe.skipIf(!HAS_WASM)('a compiled system that moves transforms', () => {
    let module: ESEngineModule;
    beforeAll(async () => { module = await loadWasmModule(); });

    it('invalidates composition with no Changed consumer anywhere', () => {
        const app = App.new();
        app.connectCpp(new module.Registry() as unknown as CppRegistry, module);
        const world = app.world;
        const parent = world.spawn();
        world.insert(parent, Transform, { position: { x: 100, y: 0, z: 0 } });
        const child = world.spawn();
        world.insert(child, Transform, { position: { x: 5, y: 0, z: 0 } });
        world.setParent(child, parent);
        world.ensureTransformsComposed();

        // Nothing tracks Transform: no Changed() filter, no replication, no
        // write reader. Composition staleness must not depend on any of them —
        // the AOT dispatcher reports it before the tracking filter, not inside.
        expect(world.isChangeTracked(Transform)).toBe(false);

        const before = world.transformEpoch();
        world.invalidateTransformComposition();
        expect(world.transformEpoch()).not.toBe(before);

        world.update(parent, Transform, (t) => { (t as { position: { x: number } }).position.x = 200; });
        world.ensureTransformsComposed();
        expect((world.get(child, Transform) as { worldPosition: { x: number } }).worldPosition.x)
            .toBe(205);
        world.disconnectCpp();
    });
});

/**
 * The editor's generated field setter writes the same bytes every other producer
 * writes, and until now said nothing. It got away with it because an editor
 * always has a renderer — so these run without one, which is the only way to tell
 * "it announced" apart from "something else was drawing anyway".
 */
describe.skipIf(!HAS_WASM)('the editor writes through the same authority', () => {
    let module: ESEngineModule;
    beforeAll(async () => { module = await loadWasmModule(); });

    interface EditorApi {
        editor_setFloat(reg: CppRegistry, e: number, comp: string, field: string, v: number): boolean;
        editor_addComponent(reg: CppRegistry, e: number, name: string): boolean;
    }
    const editor = (): EditorApi => module as unknown as EditorApi;
    const worldPosX = (reg: CppRegistry, e: number): number =>
        (reg as unknown as { getTransform(e: number): { worldPosition: { x: number } } })
            .getTransform(e).worldPosition.x;

    /** A parent at 100 and a child 5 to its right, with no renderer installed. */
    function parented() {
        const app = App.new();
        const registry = new module.Registry() as unknown as CppRegistry;
        app.connectCpp(registry, module);
        const world = app.world;
        const parent = world.spawn('parent');
        world.insert(parent, Transform, { position: { x: 100, y: 0, z: 0 } });
        const child = world.spawn('child');
        world.insert(child, Transform, { position: { x: 5, y: 0, z: 0 } });
        world.setParent(child, parent);
        world.ensureTransformsComposed();
        return { app, world, registry, parent, child };
    }

    it('a generated field setter recomposes a world that has no renderer', () => {
        const { world, registry, parent, child } = parented();
        expect(worldPosX(registry, child)).toBe(105);

        const before = world.transformEpoch();
        expect(editor().editor_setFloat(registry, parent, 'Transform', 'position.x', 300)).toBe(true);
        expect(world.transformEpoch()).not.toBe(before);

        world.ensureTransformsComposed();
        expect(worldPosX(registry, child)).toBe(305);
        world.disconnectCpp();
    });

    it('the euler path announces too, not just the vector fields', () => {
        const { world, registry, parent } = parented();
        const before = world.transformEpoch();
        expect(editor().editor_setFloat(registry, parent, 'Transform', 'rotation.z', 90)).toBe(true);
        expect(world.transformEpoch()).not.toBe(before);
        world.disconnectCpp();
    });

    it('a setter for any other component announces nothing', () => {
        const { world, registry, parent } = parented();
        world.insert(parent, Sprite, {});
        const before = world.transformEpoch();

        // Staleness is about the composition's inputs. A generated setter that
        // bumped the epoch for every component would recompose the whole world on
        // any editor edit, and no test of the composition would catch it.
        expect(editor().editor_setFloat(registry, parent, 'Sprite', 'size.x', 42)).toBe(true);
        expect(world.transformEpoch()).toBe(before);
        world.disconnectCpp();
    });

    it('adding a Transform under a parent composes it into place', () => {
        const app = App.new();
        const registry = new module.Registry() as unknown as CppRegistry;
        app.connectCpp(registry, module);
        const world = app.world;
        const parent = world.spawn('parent');
        world.insert(parent, Transform, { position: { x: 100, y: 0, z: 0 } });
        // Parented, but carrying no Transform: nothing composes it, and nothing
        // should — it has no world position to have.
        const child = world.spawn('child');
        world.setParent(child, parent);
        world.ensureTransformsComposed();

        expect(editor().editor_addComponent(registry, child, 'Transform')).toBe(true);
        world.ensureTransformsComposed();
        expect(worldPosX(registry, child)).toBe(100);
        world.disconnectCpp();
    });
});

/**
 * A core with no emscripten module — the shape a native host connects in — reads
 * neither half of the seam off `module`, so it hands them over instead. Here the
 * web engine stands in for that host: the epoch view and the compose call are the
 * engine's own, reached the way a native binding would deliver them.
 */
describe.skipIf(!HAS_WASM)('a core that hands the composition seam over', () => {
    let module: ESEngineModule;
    beforeAll(async () => { module = await loadWasmModule(); });

    /** What a native host binds: a one-word view, and the call that composes. On a
     *  native core the word lives in an arena that never moves; here it borrows the
     *  wasm heap, which is why nothing in these tests grows it. */
    const handedOver = (registry: CppRegistry) => ({
        epoch: new Uint32Array(module.HEAPU32.buffer, module.transform_epochAddress!(), 1),
        ensure: () => module.transform_ensureComposed!(registry),
    });

    function parented(handOver: boolean) {
        const app = App.new();
        const registry = new module.Registry() as unknown as CppRegistry;
        app.connectCpp(registry, undefined,
            handOver ? { transformComposition: handedOver(registry) } : {});
        const world = app.world;
        const parent = world.spawn('parent');
        world.insert(parent, Transform, { position: { x: 100, y: 0, z: 0 } });
        const child = world.spawn('child');
        world.insert(child, Transform, { position: { x: 5, y: 0, z: 0 } });
        world.setParent(child, parent);
        const worldX = () => (world.get(child, Transform) as { worldPosition: { x: number } })
            .worldPosition.x;
        return { world, parent, worldX };
    }

    it('composes through the seam it was handed', () => {
        const { world, parent, worldX } = parented(true);
        world.ensureTransformsComposed();
        expect(worldX()).toBe(105);

        const before = world.transformEpoch();
        world.update(parent, Transform, (t) => { (t as { position: { x: number } }).position.x = 200; });
        expect(world.transformEpoch()).not.toBe(before);
        world.ensureTransformsComposed();
        expect(worldX()).toBe(205);
        world.disconnectCpp();
    });

    it('without it, an announcement goes nowhere and nothing recomposes', () => {
        const { world, worldX } = parented(false);
        world.ensureTransformsComposed();
        expect(world.transformEpoch()).toBe(-1);
        expect(worldX()).toBe(0);
        world.disconnectCpp();
    });
});

/**
 * What a consumer maintaining an incremental structure reads: a serial saying
 * WHICH composition it is looking at, and the entities that one changed. The
 * pair is the whole contract — a set without a serial cannot tell "nothing
 * moved" from "you missed three compositions".
 */
describe.skipIf(!HAS_WASM)('the composition reports what it changed', () => {
    let module: ESEngineModule;
    beforeAll(async () => { module = await loadWasmModule(); });

    function scene() {
        const app = App.new();
        const registry = new module.Registry() as unknown as CppRegistry;
        app.connectCpp(registry, module);
        const world = app.world;
        const a = world.spawn('a');
        world.insert(a, Transform, { position: { x: 1, y: 0, z: 0 } });
        const b = world.spawn('b');
        world.insert(b, Transform, { position: { x: 2, y: 0, z: 0 } });
        return { app, world, a, b };
    }
    const ids = (world: App['world']) => [...(world.compositionChanges()!.changed)];

    it('names the entities whose output moved, and only those', () => {
        const { world, a, b } = scene();
        expect(world.setTransformChangeTracking(true)).toBe(true);
        world.ensureTransformsComposed();

        world.takeCompositionChanges();
        world.update(b, Transform, (t) => { (t as { position: { x: number } }).position.x = 40; });
        world.ensureTransformsComposed();
        expect(ids(world)).toEqual([b as number]);

        // A write that moves nothing: the epoch cannot tell it from movement and
        // the comparison can, which is the whole reason the set is worth having.
        world.takeCompositionChanges();
        world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 1; });
        world.ensureTransformsComposed();
        expect(ids(world)).toEqual([]);
        world.setTransformChangeTracking(false);
        world.disconnectCpp();
    });

    it('advances the serial once per composition and not at all without one', () => {
        const { world, a } = scene();
        world.setTransformChangeTracking(true);
        world.ensureTransformsComposed();
        const first = world.compositionChanges()!.serial;

        // Nothing was invalidated, so nothing composed.
        world.ensureTransformsComposed();
        world.ensureTransformsComposed();
        expect(world.compositionChanges()!.serial).toBe(first);

        world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 9; });
        world.ensureTransformsComposed();
        expect(world.compositionChanges()!.serial).toBe(first + 1);
        world.setTransformChangeTracking(false);
        world.disconnectCpp();
    });

    it('reports nothing while tracking is off, and the serial still moves', () => {
        const { world, a } = scene();
        world.setTransformChangeTracking(false);
        world.ensureTransformsComposed();
        const before = world.compositionChanges()!.serial;

        world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 3; });
        world.ensureTransformsComposed();
        const after = world.compositionChanges()!;
        expect(after.serial).toBe(before + 1);
        expect(after.changed.length).toBe(0);
        world.disconnectCpp();
    });

    it('a second world composing in between shows up as a gap', () => {
        const first = scene();
        first.world.setTransformChangeTracking(true);
        first.world.ensureTransformsComposed();
        const seen = first.world.compositionChanges()!.serial;

        // Another world composes; the serial is the engine's, not this world's,
        // so a consumer that missed compositions has to be able to see that.
        const other = scene();
        other.world.ensureTransformsComposed();
        other.world.disconnectCpp();

        first.world.update(first.a, Transform,
            (t) => { (t as { position: { x: number } }).position.x = 50; });
        first.world.ensureTransformsComposed();
        expect(first.world.compositionChanges()!.serial).toBeGreaterThan(seen + 1);
        first.world.setTransformChangeTracking(false);
        first.world.disconnectCpp();
    });

    it('accumulates across compositions, because a renderer composes every frame', () => {
        const { world, a, b } = scene();
        world.setTransformChangeTracking(true);
        world.ensureTransformsComposed();
        world.takeCompositionChanges();

        // Three compositions between one consumer's reads is the ordinary case:
        // a listen server composes each frame and samples every few. Reporting
        // only the last one would drop the first two.
        world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 11; });
        world.ensureTransformsComposed();
        world.update(b, Transform, (t) => { (t as { position: { x: number } }).position.x = 22; });
        world.ensureTransformsComposed();

        expect([...ids(world)].sort()).toEqual([a as number, b as number].sort());
        // Reading does not consume: a consumer that throws half way through has
        // not acknowledged, and is handed the same work again.
        expect(ids(world).length).toBe(2);
        world.takeCompositionChanges();
        expect(ids(world)).toEqual([]);
        world.setTransformChangeTracking(false);
        world.disconnectCpp();
    });

    it('drops a set that grew past the rebuild it would save', () => {
        const app = App.new();
        const registry = new module.Registry() as unknown as CppRegistry;
        app.connectCpp(registry, module);
        const world = app.world;
        const all = [];
        for (let i = 0; i < 8; i++) {
            const e = world.spawn();
            world.insert(e, Transform, { position: { x: i + 1, y: 0, z: 0 } });
            all.push(e);
        }
        world.setTransformChangeTracking(true);
        world.ensureTransformsComposed();
        world.takeCompositionChanges();

        // Every entity, twice, with nothing acknowledged in between: more pending
        // changes than a composition writes, so replaying them costs more than
        // reading the world again.
        for (let pass = 1; pass <= 2; pass++) {
            for (const e of all) {
                world.update(e, Transform,
                    (t) => { (t as { position: { x: number } }).position.x += 10 * pass; });
            }
            world.ensureTransformsComposed();
        }
        const pending = world.compositionChanges()!;
        expect(pending.overflowed).toBe(true);
        expect(pending.changed.length).toBe(0);

        // And it stays dropped until acknowledged, rather than half-filling again.
        world.update(all[0]!, Transform, (t) => { (t as { position: { x: number } }).position.x = 900; });
        world.ensureTransformsComposed();
        expect(world.compositionChanges()!.overflowed).toBe(true);
        world.takeCompositionChanges();
        expect(world.compositionChanges()!.overflowed).toBe(false);
        world.setTransformChangeTracking(false);
        world.disconnectCpp();
    });

    it('a core that cannot report says so instead of answering nothing', () => {
        const app = App.new();
        const registry = new module.Registry() as unknown as CppRegistry;
        // The seam without its optional third half — a host too old to report.
        app.connectCpp(registry, undefined, {
            transformComposition: {
                epoch: new Uint32Array(module.HEAPU32.buffer, module.transform_epochAddress!(), 1),
                ensure: () => module.transform_ensureComposed!(registry),
            },
        });
        expect(app.world.setTransformChangeTracking(true)).toBe(false);
        expect(app.world.compositionChanges()).toBeNull();
        app.world.disconnectCpp();
    });
});