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.

24.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    hot-update-rebind.test.ts
 * @brief   A hot update reaches every field that declares an asset, not the two
 *          the rebinder's author remembered.
 *
 * @details Seven built-in fields carry a texture; the rebinder knew `Sprite.texture`
 *          and `MeshRenderer.texture`. The other five — and every project or plugin
 *          component — kept rendering the pre-update image with nothing reporting a
 *          failure. The cases here are DERIVED from `component.assetFields`, so a
 *          field added tomorrow is covered tomorrow rather than when someone
 *          remembers to extend a list.
 */
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { App } from '../src/app/app';
import { World } from '../src/ecs/world';
import { defineComponent, getComponent, getComponentRegistry, type AnyComponentDef } from '../src/ecs/component';
import { COMPONENT_META } from '../src/ecs/component.generated';
import { Assets } from '../src/asset/Assets';
import type { Backend } from '../src/asset/Backend';
import type { Entity } from '../src/types';
import { ensureBuiltinComponentsRegistered } from '../src/ecs/component';
import { installHotUpdateRebind } from '../src/hotUpdateRebind';
import { connectFakeCpp } from './helpers/fakeEngine';
import { SceneManager, SceneManagerState, type SceneContext } from '../src/scene/sceneManager';
import { AssetScope } from '../src/asset/AssetLease';
import { Sprite, MeshRenderer, ParticleEmitter, TrailRenderer } from '../src/ecs/component';
import { UIVisual } from '../src/ui/core/ui-visual';
import { findLiveAssetBindings } from '../src/asset/liveAssetBindings';
import { migrateScopeBindings } from '../src/asset/liveAssetRebind';
import type { AssetLease } from '../src/asset/AssetLease';

/** The pool, modelled: every decode mints a handle, invalidate severs revival. */
function createPoolFake() {
    const byPath = new Map<string, number>();
    let next = 1;
    return {
        budget: 0,
        createTexture: vi.fn((): number => next++),
        registerTextureWithPath: vi.fn((handle: number, path: string) => { byPath.set(path, handle); }),
        acquireTextureByPath: vi.fn((path: string): number => byPath.get(path) ?? 0),
        invalidateTexturePath: vi.fn((path: string): boolean => byPath.delete(path)),
        releaseTexture: vi.fn(),
        getTextureDimensions: vi.fn(() => ({ width: 64, height: 64 })),
        getTextureGLId: vi.fn(() => 1),
        setTextureMetadata: vi.fn(),
    };
}

let pool = createPoolFake();
vi.mock('../src/wasm/resourceManager', () => ({
    requireResourceManager: () => pool,
    getResourceManager: () => pool,
    evictTextureDimensions: vi.fn(),
}));

const platformFactory = vi.hoisted(() => () => ({
    platformCreateCanvas: () => ({
        width: 64, height: 64,
        getContext: () => ({
            clearRect: vi.fn(), drawImage: vi.fn(),
            getImageData: () => ({ data: { buffer: new ArrayBuffer(64 * 64 * 4) } }),
        }),
    }),
    platformCreateImage: () => {
        const img: { width?: number; height?: number; onload?: () => void } = {};
        setTimeout(() => { img.width = 64; img.height = 64; img.onload?.(); }, 0);
        return img;
    },
    platformFetch: vi.fn(),
    platformReadFile: vi.fn(),
    platformReadTextFile: vi.fn(),
    platformFileExists: vi.fn(),
    platformLoadSubpackage: vi.fn(async () => {}),
    platformGetStorageItem: () => null,
    platformSetStorageItem: vi.fn(),
    platformWriteCacheFile: vi.fn(async () => {}),
}));
vi.mock('../src/platform', platformFactory);
vi.mock('../src/platform/base', platformFactory);

const materialFake = vi.hoisted(() => {
    let next = 100;
    return {
        reset: () => { next = 100; },
        Material: {
            createFromAsset: vi.fn((): number => next++),
            setUniform: vi.fn(),
            tex: vi.fn((handle: number) => ({ kind: 'tex', handle })),
            compileShader: vi.fn(() => 7),
            noteProgram: vi.fn(),
            releaseShader: vi.fn(),
            release: vi.fn(),
        },
    };
});
vi.mock('../src/render/material', () => ({ Material: materialFake.Material }));

function buildAssets(docs: Record<string, string> = {}): Assets {
    return Assets.create({
        backend: {
            fetchBinary: vi.fn(async () => new ArrayBuffer(8)),
            fetchText: vi.fn(async (url: string) => {
                const key = Object.keys(docs).find((k) => url.endsWith(k));
                return key ? docs[key] : '{}';
            }),
            resolveUrl: (p: string) => `http://test/${p}`,
        } as unknown as Backend,
        module: { _malloc: vi.fn(() => 0), _free: vi.fn(), HEAPU8: new Uint8Array(1 << 16), GL: null, FS: null } as never,
    });
}

// What every SDK entry does at load: register the engine's whole component
// catalogue. Without it the registry holds only what this test file happened to
// import, and the completeness check below would be measuring the imports.
ensureBuiltinComponentsRegistered();

/** Every (component, field) in the live registry that binds a texture. */
function declaredTextureFields(): Array<{ component: AnyComponentDef; field: string }> {
    const out: Array<{ component: AnyComponentDef; field: string }> = [];
    for (const component of getComponentRegistry().values()) {
        for (const f of component.assetFields) {
            if (f.type === 'texture') out.push({ component, field: f.field });
        }
    }
    return out;
}

/** Run frames until the reload's promise has landed and its swap been applied. */
async function settle(app: App, frames = 4): Promise<void> {
    for (let i = 0; i < frames; i++) {
        await app.tick(1 / 60);
        await Promise.resolve();
        await new Promise((r) => setTimeout(r, 0));
    }
}

describe('the hot-update rebinder reaches every declared texture field', () => {
    beforeEach(() => { pool = createPoolFake(); });

    it('rebinds all of them, including a component the project declared', async () => {
        // A project component is the case a hand-written list can never cover.
        const CustomVisual = defineComponent(
            'HotUpdateRebindTestVisual',
            { icon: 0, tint: 1 },
            { assetFields: [{ field: 'icon', type: 'texture' }] },
        );

        const app = App.new();
        connectFakeCpp(app.world);
        const assets = buildAssets();
        installHotUpdateRebind(app, assets);

        const before = await assets.loadTexture('hero.png');
        const fields = declaredTextureFields();
        // Completeness, against the engine's own declaration rather than a list
        // kept here: a texture field added to a C++ component and not covered
        // below fails this, instead of quietly going unrebound.
        const covered = new Set(fields.map((f) => `${f.component._name}.${f.field}`));
        const engineDeclared = Object.entries(COMPONENT_META).flatMap(([name, meta]) =>
            (meta.assetFields ?? [])
                .filter((f) => f.type === 'texture')
                .map((f) => `${name}.${f.field}`));
        expect(engineDeclared.length).toBeGreaterThanOrEqual(7);   // never vacuous
        expect([...covered]).toEqual(expect.arrayContaining(engineDeclared));
        expect(covered.has('HotUpdateRebindTestVisual.icon')).toBe(true);

        const bound: Array<{ entity: Entity; component: AnyComponentDef; field: string }> = [];
        for (const { component, field } of fields) {
            const entity = app.world.spawn();
            app.world.insert(entity, component, { [field]: before.handle } as never);
            bound.push({ entity, component, field });
        }
        // And one field of each kind left unbound, which a swap must not touch.
        const untouched = app.world.spawn();
        app.world.insert(untouched, CustomVisual, {});

        assets.invalidate('hero.png');
        await settle(app);

        const after = assets.getTexture('hero.png');
        expect(after).toBeDefined();
        expect(after!.handle).not.toBe(before.handle);

        for (const { entity, component, field } of bound) {
            const data = app.world.get(entity, component) as Record<string, unknown>;
            expect(`${component._name}.${field} = ${String(data[field])}`)
                .toBe(`${component._name}.${field} = ${after!.handle}`);
        }
        expect((app.world.get(untouched, CustomVisual) as { icon: number }).icon).toBe(0);
    });

    it('an unbound field is not a binding of the asset being replaced', () => {
        // 0 is what an unbound field holds; matching it would rebind the whole world.
        const world = new World();
        connectFakeCpp(world);
        const Widget = defineComponent(
            'HotUpdateRebindTestWidget', { icon: 0 },
            { assetFields: [{ field: 'icon', type: 'texture' }] },
        );
        const e = world.spawn();
        world.insert(e, Widget, {});

        expect(findLiveAssetBindings(world, 'texture', 0)).toEqual([]);
        expect(findLiveAssetBindings(world, 'texture', 7)).toEqual([]);
        world.insert(e, Widget, { icon: 7 });
        expect(findLiveAssetBindings(world, 'texture', 7)).toHaveLength(1);
    });

    it('does not hand a dying entity a new owner during despawn callbacks', () => {
        const world = new World(); connectFakeCpp(world);
        const entity = world.spawn(); world.insert(entity, Sprite, { texture: 7 });
        let pending: boolean | undefined;
        let bindingsDuringDespawn = -1;
        world.onDespawn(() => {
            pending = world.isDestructionPending(entity);
            bindingsDuringDespawn = findLiveAssetBindings(world, 'texture', 7).length;
        });
        world.despawn(entity);
        expect(pending).toBe(true);
        expect(bindingsDuringDespawn).toBe(0);
    });
});

describe('a replacement is a transaction per owning scope', () => {
    beforeEach(() => { pool = createPoolFake(); });

    /** An App with scenes, whose world's C++ side is the store above. */
    function sceneApp(): { app: App; assets: Assets; manager: SceneManagerState } {
        const app = App.new();
        connectFakeCpp(app.world);
        const assets = buildAssets();
        const manager = new SceneManagerState(app);
        app.insertResource(SceneManager, manager);
        installHotUpdateRebind(app, assets);
        return { app, assets, manager };
    }

    /** A scene that acquires `ref` for itself and binds it to `fields`. */
    function sceneHolding(
        app: App, assets: Assets, ref: string,
        fields: Array<{ component: AnyComponentDef; field: string }>,
    ) {
        return async (ctx: SceneContext): Promise<void> => {
            const scope = new AssetScope();
            const lease = await assets.acquireTexture(ref);
            scope.add(lease);
            ctx.trackAssetScope(scope);
            for (const { component, field } of fields) {
                const entity = ctx.spawn();
                app.world.insert(entity, component, { [field]: lease.value.handle } as never);
            }
        };
    }

    const boundValues = (app: App, component: AnyComponentDef, field: string): number[] =>
        app.world.getEntitiesWithComponents([component])
            .map((e) => (app.world.get(e, component) as Record<string, number>)[field]);

    it('two scenes holding one texture get one acquisition EACH', async () => {
        // The cardinality the world-wide swap got wrong: it acquired once and
        // moved both owners onto it, so one of the two receipts named an era
        // nothing was drawing and the era both were drawing had one holder.
        const { app, assets, manager } = sceneApp();
        const base = assets.sizes().refRows;

        manager.register({ name: 'a', setup: sceneHolding(app, assets, 'hero.png', [{ component: Sprite, field: 'texture' }]) });
        manager.register({ name: 'b', setup: sceneHolding(app, assets, 'hero.png', [{ component: TrailRenderer, field: 'texture' }]) });
        await manager.loadAdditive('a');
        await manager.loadAdditive('b');

        const before = assets.getTexture('hero.png')!.handle;
        expect(assets.sizes().refRows).toBe(base + 2);          // two owners, one era

        assets.invalidate('hero.png');
        await settle(app);

        const after = assets.getTexture('hero.png')!.handle;
        expect(after).not.toBe(before);
        expect(boundValues(app, Sprite, 'texture')).toEqual([after]);
        expect(boundValues(app, TrailRenderer, 'texture')).toEqual([after]);
        // Two owners still, of the new era: one acquisition each, and the era
        // they left has no holders.
        expect(assets.sizes().refRows).toBe(base + 2);

        await manager.unload('a');
        // B is still drawing it, and still owes exactly one release.
        expect(assets.sizes().refRows).toBe(base + 1);
        expect(boundValues(app, TrailRenderer, 'texture')).toEqual([after]);

        await manager.unload('b');
        expect(assets.sizes().refRows).toBe(base);              // nothing stranded
    });

    it('one scene\'s four fields move together, and it owes ONE release', async () => {
        // Per scope, not per binding: a scene left holding the new era for some
        // of its fields and the old one for the rest owes two receipts for one
        // replacement, and nothing afterwards can say which field is which.
        const { app, assets, manager } = sceneApp();
        const base = assets.sizes().refRows;
        const fields = [
            { component: Sprite, field: 'texture' },
            { component: UIVisual, field: 'texture' },
            { component: MeshRenderer, field: 'normalMap' },
            { component: ParticleEmitter, field: 'texture' },
        ];
        manager.register({ name: 'level', setup: sceneHolding(app, assets, 'hero.png', fields) });
        await manager.loadAdditive('level');

        const before = assets.getTexture('hero.png')!.handle;
        expect(assets.sizes().refRows).toBe(base + 1);

        assets.invalidate('hero.png');
        await settle(app);

        const after = assets.getTexture('hero.png')!.handle;
        expect(after).not.toBe(before);
        for (const { component, field } of fields) {
            expect(boundValues(app, component, field), `${component._name}.${field}`).toEqual([after]);
        }
        expect(assets.sizes().refRows).toBe(base + 1);          // one owner, one receipt

        await manager.unload('level');
        expect(assets.sizes().refRows).toBe(base);
    });

    it('five hot updates in a row leave the scene owing exactly one release', async () => {
        // The measured leak: each successful rebind took a texture out of the
        // ledger with no receipt, so five updates left five rows that no unload
        // could ever reach. What a scene owes is one release, always.
        const { app, assets, manager } = sceneApp();
        const base = assets.sizes().refRows;
        manager.register({
            name: 'level',
            setup: sceneHolding(app, assets, 'hero.png', [{ component: Sprite, field: 'texture' }]),
        });
        await manager.loadAdditive('level');

        for (let i = 0; i < 5; i++) {
            assets.invalidate('hero.png');
            await settle(app);
            expect(boundValues(app, Sprite, 'texture'), `after update ${i + 1}`)
                .toEqual([assets.getTexture('hero.png')!.handle]);
            expect(assets.sizes().refRows, `after update ${i + 1}`).toBe(base + 1);
        }

        await manager.unload('level');
        expect(assets.sizes().refRows).toBe(base);
    });

    it('a runtime sprite releases its replacement when the entity despawns', async () => {
        const { app, assets } = sceneApp();
        const base = assets.sizes().refRows;

        const lease = await assets.acquireTexture('hero.png');
        const entity = app.world.spawn();
        app.world.insert(entity, Sprite, { texture: lease.value.handle });

        assets.invalidate('hero.png');
        await settle(app);
        const after = assets.getTexture('hero.png')!.handle;
        expect(boundValues(app, Sprite, 'texture')).toEqual([after]);

        lease.release();                                  // the game lets go of its own era
        expect(assets.sizes().refRows).toBe(base + 1);
        expect(assets.appScope.size).toBe(0);
        app.world.despawn(entity);
        expect(assets.entityScopes.size).toBe(0);
        expect(assets.sizes().refRows).toBe(base);
    });

    it('runtime mesh materials end with their own entities, including instance sets', async () => {
        const app = App.new(); connectFakeCpp(app.world);
        const assets = buildAssets({ 'leaf.esmaterial': JSON.stringify({
            version: '1.0', type: 'material', shader: 'builtin:model',
            properties: { u_normalMap: 'leaf.png' },
        }) });
        installHotUpdateRebind(app, assets);
        const base = assets.sizes().refRows;
        for (let i = 0; i < 3; i++) {
            const initial = await assets.acquireTyped<{ handle: number }>('material', 'leaf.esmaterial');
            const entities = [app.world.spawn(), app.world.spawn()];
            for (const entity of entities) app.world.insert(entity, MeshRenderer, { material: initial.value.handle });
            app.world.insert(entities[0], getComponent('MeshInstances')!, {});
            assets.invalidate('leaf.esmaterial'); await settle(app, 8);
            const replacement = app.world.get(entities[0], MeshRenderer).material;
            expect(replacement).not.toBe(initial.value.handle);
            expect(app.world.get(entities[1], MeshRenderer).material).toBe(replacement);
            initial.release();
            expect(assets.appScope.size).toBe(0);
            expect(assets.entityScopes.size).toBe(2);
            app.world.despawn(entities[0]);
            expect(assets.entityScopes.size).toBe(1);
            expect(materialFake.Material.release).not.toHaveBeenCalledWith(replacement);
            app.world.despawn(entities[1]);
            expect(materialFake.Material.release).toHaveBeenCalledWith(replacement);
            expect(assets.entityScopes.size).toBe(0);
            expect(assets.sizes().refRows, `after generation ${i}`).toBe(base);
        }
    });

    it('returns a late replacement when its runtime entity despawned while loading', async () => {
        const { app, assets } = sceneApp();
        const initial = await assets.acquireTexture('hero.png');
        const entity = app.world.spawn();
        app.world.insert(entity, Sprite, { texture: initial.value.handle });
        const acquire = assets.acquireTexture.bind(assets);
        let finish!: (lease: Awaited<ReturnType<typeof acquire>>) => void;
        vi.spyOn(assets, 'acquireTexture').mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
        assets.invalidate('hero.png'); await app.tick(1 / 60);
        expect(assets.entityScopes.size).toBe(1);
        app.world.despawn(entity); initial.release();
        finish(await acquire('hero.png')); await settle(app);
        expect(assets.entityScopes.size).toBe(0);
        expect(assets.appScope.size).toBe(0);
        expect(assets.sizes().refRows).toBe(0);
    });
});

describe('a scope migrates all of its bindings or none', () => {
    /** A world whose Nth write refuses — the failure the rollback exists for. */
    function worldFailingWriteAt(nth: number): World {
        const world = new World();
        connectFakeCpp(world);
        let writes = 0;
        const set = world.set.bind(world);
        world.set = ((entity: never, component: never, data: never) => {
            if (++writes === nth) throw new Error('component store refused the write');
            return set(entity, component, data);
        }) as typeof world.set;
        return world;
    }

    it('puts back every binding it had already written, and gives the replacement back', () => {
        const scope = new AssetScope();
        let released = 0;
        const outgoing = {
            key: 'texture:hero.png', generation: 1, value: { handle: 11 },
            release: () => { released++; },
        };
        scope.add(outgoing as never);

        const world = worldFailingWriteAt(3);
        const Widget = defineComponent(
            'RollbackTestWidget', { icon: 0 },
            { assetFields: [{ field: 'icon', type: 'texture' }] },
        );
        const entities = [world.spawn(), world.spawn(), world.spawn(), world.spawn()];
        for (const e of entities) world.insert(e, Widget, { icon: 11 });

        let replacementReleased = 0;
        const replacement = {
            lease: {
                key: 'texture:hero.png', generation: 2, value: { handle: 22 },
                release: () => { replacementReleased++; },
            },
            boundValue: (lease: AssetLease) => (lease.value as { handle: number }).handle,
        };
        const migrated = migrateScopeBindings(
            world, scope, 'texture', 11, replacement as never, () => scope,
        );

        expect(migrated).toBe(false);
        // Every binding still holds the era the scope still owns...
        for (const e of entities) expect((world.get(e, Widget) as { icon: number }).icon).toBe(11);
        expect(released).toBe(0);
        // ...and the replacement was given back rather than kept by anyone.
        expect(replacementReleased).toBe(1);
        expect(scope.size).toBe(1);
        expect(scope.leases()[0]).toBe(outgoing);
    });
});

describe('a live binding follows the asset, whatever kind it is', () => {
    beforeEach(() => { pool = createPoolFake(); materialFake.reset(); });

    /** A material on a built-in shader, binding no textures of its own. */
    const MATERIAL = JSON.stringify({
        type: 'material', shader: 'builtin:sprite-unlit', properties: {},
    });

    it('a material field moves to the new generation, like a texture field', async () => {
        // Every handle-bound kind — material, font, mesh, environment — follows
        // the same transaction a texture does; nothing about it is texture-shaped.
        const app = App.new();
        connectFakeCpp(app.world);
        const assets = buildAssets({ 'hero.esmaterial': MATERIAL });
        installHotUpdateRebind(app, assets);

        const before = await assets.acquireTyped<{ handle: number }>('material', 'hero.esmaterial');
        const entity = app.world.spawn();
        app.world.insert(entity, MeshRenderer, { material: before.value.handle } as never);

        assets.invalidate('hero.esmaterial');
        await settle(app);

        const after = (app.world.get(entity, MeshRenderer) as { material: number }).material;
        expect(after, 'the field kept the handle from before the update')
            .not.toBe(before.value.handle);
        const fresh = await assets.acquireTyped<{ handle: number }>('material', 'hero.esmaterial');
        expect(after, 'the field moved to something other than the published era')
            .toBe(fresh.value.handle);
    });

    it('converging is not done while a reload is still in the air', async () => {
        // The barrier a host asks about after `applyUpdate`: the asset graph has
        // caught up, and this says whether the world reading it has. Answering
        // between the queues would say yes with an acquisition in flight.
        const app = App.new();
        connectFakeCpp(app.world);
        const assets = buildAssets({ 'hero.esmaterial': MATERIAL });
        const bindings = installHotUpdateRebind(app, assets);

        const before = await assets.acquireTyped<{ handle: number }>('material', 'hero.esmaterial');
        const entity = app.world.spawn();
        app.world.insert(entity, MeshRenderer, { material: before.value.handle } as never);

        assets.invalidate('hero.esmaterial');
        let converged = false;
        void bindings.settled().then(() => { converged = true; });

        await app.tick(1 / 60);
        await Promise.resolve();
        expect(converged, 'said the world had caught up with a reload in flight').toBe(false);

        await settle(app);
        expect(converged).toBe(true);
        expect((app.world.get(entity, MeshRenderer) as { material: number }).material)
            .not.toBe(before.value.handle);
    });

    it('which kinds can be rebound is read from the loader doors', async () => {
        // A ref-bound asset has nothing to move: the field holds the name, and
        // what the name means is the slot's business.
        const assets = buildAssets();

        expect(assets.handleBoundTypes()).toContain('material');
        expect(assets.handleBoundTypes()).not.toContain('anim-clip');
        expect(assets.handleBoundTypes()).not.toContain('tilemap');
    });
});