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.

19.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, vi } from 'vitest';
import { Assets } from '../src/asset/Assets';
import { Catalog } from '../src/asset/Catalog';
import type { AddressableManifest } from '../src/asset/AddressableManifest';
import type { Backend } from '../src/asset/Backend';
import { contentHashHex } from '../src/asset/contentHash';

// The bytes backendServing.fetchBinary returns (8 zero bytes) → the content hash a
// candidate manifest must claim for the integrity check to pass.
const REMOTE_HASH = contentHashHex(new Uint8Array(8));

const mockModule = {
    _malloc: vi.fn(() => 0),
    _free: vi.fn(),
    HEAPU8: new Uint8Array(1024),
    GL: null,
    FS: null,
} as any;

vi.mock('../src/wasm/resourceManager', () => ({
    requireResourceManager: () => ({
        createTexture: vi.fn(() => 42),
        releaseTexture: vi.fn(),
        invalidateTexturePath: vi.fn(() => false),
    }),
    getResourceManager: () => null,
    evictTextureDimensions: vi.fn(),
}));

// In-memory platform storage + content cache so persistence and the offline
// disk-cache write round-trip in the test.
vi.mock('../src/platform', () => {
    const store = new Map<string, string>();
    const cache = new Map<string, ArrayBuffer>();
    return {
        platformLoadSubpackage: vi.fn(() => Promise.resolve()),
        platformGetStorageItem: (k: string) => store.get(k) ?? null,
        platformSetStorageItem: (k: string, v: string) => { store.set(k, v); },
        platformRemoveStorageItem: (k: string) => { store.delete(k); },
        platformWriteCacheFile: vi.fn((k: string, b: ArrayBuffer) => { cache.set(k, b); return Promise.resolve('stored'); }),
        __store: store,
        __cache: cache,
    };
});

/** A cdn (`remote`) manifest keyed by uuid — the shape a cooked build emits.
 *  `hash` overrides the single asset's contentHash + content-addressed path. */
function cdnManifest(hash: string, revision: string): AddressableManifest {
    return {
        version: '2.0',
        revision,
        groups: {
            cdn: {
                bundleMode: 'remote',
                labels: [],
                assets: {
                    'uuid-1': {
                        path: `assets/${hash}.png`, address: 'assets/hero.png',
                        type: 'texture', size: 10, labels: [], contentHash: hash,
                    },
                },
            },
        },
    };
}

function createAssets(backend: Backend): Assets {
    return Assets.create({ backend, catalog: Catalog.empty(), module: mockModule });
}

function backendServing(manifestJson?: AddressableManifest): Backend {
    return {
        fetchBinary: vi.fn(async () => new ArrayBuffer(8)),
        fetchText: vi.fn(async () => (manifestJson ? JSON.stringify(manifestJson) : '{}')),
        resolveUrl: vi.fn((p: string) => p),
    } as any;
}

describe('Assets.loadGroup — remote group', () => {
    it('resolves remote assets against the CDN root (absolute url passthrough)', async () => {
        const assets = createAssets(backendServing());
        assets.setManifest(cdnManifest('aaaa', 'rev-1'));
        assets.setRemoteRoot('https://cdn.example.com/build/');
        const spy = vi.spyOn(assets, 'acquireTexture').mockResolvedValue({
            key: 'texture:x', generation: 1,
            value: { handle: 1, width: 1, height: 1 }, release: () => {},
        } as any);

        await assets.loadGroup('cdn');

        expect(spy).toHaveBeenCalledWith('https://cdn.example.com/build/assets/aaaa.png');
    });

    it('trims a trailing slash on the root exactly once', async () => {
        const assets = createAssets(backendServing());
        assets.setManifest(cdnManifest('bbbb', 'rev-1'));
        assets.setRemoteRoot('https://cdn.example.com');
        const spy = vi.spyOn(assets, 'acquireTexture').mockResolvedValue({
            key: 'texture:x', generation: 1,
            value: { handle: 1, width: 1, height: 1 }, release: () => {},
        } as any);

        await assets.loadGroup('cdn');

        expect(spy).toHaveBeenCalledWith('https://cdn.example.com/assets/bbbb.png');
    });
});

describe('a remote group with no CDN root ships inside the package', () => {
    // The cook staged the bytes under `remote/<group>/…` and there is no origin
    // to fetch from, so where they are is the REALM's question — the manifest's
    // address is the authored name, which the package does not carry.
    const PACKAGED: AddressableManifest = {
        version: '2.0',
        revision: 'rev-1',
        groups: {
            cdn: {
                bundleMode: 'remote',
                labels: [],
                assets: {
                    'uuid-1': {
                        path: 'remote/cdn/assets/cdn/art.ktx2.bin',
                        address: 'assets/cdn/art.png',
                        type: 'texture', size: 10, labels: [],
                    },
                },
            },
        },
    } as AddressableManifest;

    /** What every packaged realm installs: any spelling → the staged path. */
    const packagedResolver = (ref: string): string => {
        const key = ref.replace(/^@uuid:/, '');
        return key === 'uuid-1' || key === 'assets/cdn/art.png'
            ? 'remote/cdn/assets/cdn/art.ktx2.bin'
            : ref;
    };

    it('loads the staged path, whichever spelling names it', () => {
        const assets = createAssets(backendServing());
        assets.setManifest(PACKAGED);
        assets.setAssetRefResolver(packagedResolver);
        // No setRemoteRoot: this build ships the bytes and has no CDN.

        // The scene's field is rewritten to the authored path at load, so this is
        // the spelling the texture actually asks for on a device.
        expect(assets.resolveLoadPath('assets/cdn/art.png')).toBe('remote/cdn/assets/cdn/art.ktx2.bin');
        expect(assets.resolveLoadPath('@uuid:uuid-1')).toBe('remote/cdn/assets/cdn/art.ktx2.bin');
    });

    it('still goes to the CDN once a root is set', () => {
        const assets = createAssets(backendServing());
        assets.setManifest(PACKAGED);
        assets.setAssetRefResolver(packagedResolver);
        assets.setRemoteRoot('https://cdn.example.com');

        expect(assets.resolveLoadPath('assets/cdn/art.png'))
            .toBe('https://cdn.example.com/remote/cdn/assets/cdn/art.ktx2.bin');
    });
});

/** A cdn manifest whose one asset is REF-BOUND — a slot, not a handle. */
function cdnSlotManifest(hash: string, revision: string): AddressableManifest {
    return {
        version: '2.0',
        revision,
        groups: {
            cdn: {
                bundleMode: 'remote',
                labels: [],
                assets: {
                    'uuid-w': {
                        path: `assets/${hash}.widget`, address: 'assets/hero.widget',
                        type: 'json', size: 10, labels: [], contentHash: hash,
                    },
                },
            },
        },
    };
}

describe('a slot is keyed by what the asset IS, not by where this revision serves it', () => {
    it('the same slot re-prepares from the new revision\'s url', async () => {
        // Keyed by the resolved url, a slot is revision-specific: the update
        // publishes nothing into it, and every holder — components look their
        // ref up on each frame — reads the old era for the life of the app.
        const backend = backendServing(cdnSlotManifest(REMOTE_HASH, 'rev-2'));
        const assets = createAssets(backend);
        assets.setManifest(cdnSlotManifest('aaaa', 'rev-1'));
        assets.setRemoteRoot('https://cdn/v1');
        const loadedFrom: string[] = [];
        assets.register({
            type: 'widget', extensions: ['.widget'],
            registry: {
                prepare: async (path) => {
                    loadedFrom.push(path);
                    return { published: { from: path }, value: { id: 'assets/hero.widget' } };
                },
            },
        });

        const held = await assets.acquireTyped('widget', 'assets/hero.widget');
        expect(loadedFrom).toEqual(['https://cdn/v1/assets/aaaa.widget']);

        await assets.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });
        await assets.applyUpdate();

        expect(loadedFrom[1], 'the update published nothing into the slot')
            .toBe(`https://cdn/v2/assets/${REMOTE_HASH}.widget`);
        expect(assets.sizes().registrySlots, 'the update opened a second slot for one asset').toBe(1);
        expect(assets.resolveRegistryAsset('widget', 'assets/hero.widget'))
            .toEqual({ from: `https://cdn/v2/assets/${REMOTE_HASH}.widget` });
        held.release();
    });
});

describe('a hot update reaches what was built from what it changed', () => {
    it('re-prepares the asset that read a changed one, against the new content', async () => {
        // The changed asset itself is content-addressed, so the next load of it
        // finds the update on its own. What CANNOT is an era already built from
        // it: it holds what it read at the revision it was prepared in.
        const backend = backendServing(cdnManifest(REMOTE_HASH, 'rev-2'));
        const assets = createAssets(backend);
        assets.setManifest(cdnManifest('aaaa', 'rev-1'));
        assets.setRemoteRoot('https://cdn/v1');
        const builtFrom: string[] = [];
        assets.register({
            type: 'widget', extensions: ['.widget'],
            registry: {
                prepare: async (path, ctx) => {
                    await ctx.readSource!('assets/hero.png');
                    builtFrom.push(assets.resolveLoadPath('assets/hero.png'));
                    return { published: { path }, value: { id: path } };
                },
            },
        });
        await assets.acquireTyped('widget', 'w.widget');
        expect(builtFrom).toEqual(['https://cdn/v1/assets/aaaa.png']);

        await assets.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });
        await assets.applyUpdate();

        // No flushing: applyUpdate resolving MEANS the asset graph agrees with
        // the manifest. What reads the graph converges on a frame, which is the
        // other barrier and not this one.
        expect(builtFrom[1], 'the widget kept the revision it was built in')
            .toBe(`https://cdn/v2/assets/${REMOTE_HASH}.png`);
    });
});

describe('Assets.checkForUpdate / applyUpdate', () => {
    it('checkForUpdate diffs the fetched manifest against the active one without applying', async () => {
        const assets = createAssets(backendServing(cdnManifest('zzzz', 'rev-2')));
        assets.setManifest(cdnManifest('aaaa', 'rev-1'));
        assets.setRemoteRoot('https://cdn/v1');

        const plan = await assets.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });

        expect(plan.hasUpdate).toBe(true);
        expect(plan.changedAssets.map((c) => c.key)).toEqual(['uuid-1']);
        expect(plan.totalBytes).toBe(10);
        expect(plan.fromRevision).toBe('rev-1');
        expect(plan.toRevision).toBe('rev-2');
        // Not applied yet: the active manifest and root are unchanged.
        expect(assets.getManifest()?.revision()).toBe('rev-1');
        expect(assets.remoteRoot).toBe('https://cdn/v1');
    });

    it('applyUpdate downloads+verifies, then atomically swaps manifest+root and notifies', async () => {
        const backend = backendServing(cdnManifest(REMOTE_HASH, 'rev-2'));
        const assets = createAssets(backend);
        assets.setManifest(cdnManifest('aaaa', 'rev-1'));
        assets.setRemoteRoot('https://cdn/v1');
        const rebinds: Array<{ ref: string; type: string }> = [];
        assets.onInvalidate((e) => rebinds.push({ ref: e.ref, type: e.type }));

        await assets.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });
        const progress: [number, number][] = [];
        const result = await assets.applyUpdate((loaded, total) => progress.push([loaded, total]));

        expect(result).toMatchObject({ ok: true, updated: 1, failed: [], revision: 'rev-2' });
        expect(result.stages).toEqual({ verified: true, applied: true, persisted: null, cached: true });
        // Manifest + root are now the update's.
        expect(assets.getManifest()?.revision()).toBe('rev-2');
        expect(assets.remoteRoot).toBe('https://cdn/v2');
        // The changed asset was downloaded + verified from the NEW cdn root.
        expect(backend.fetchBinary).toHaveBeenCalledWith(`https://cdn/v2/assets/${REMOTE_HASH}.png`);
        // …and its verified bytes were written to the offline disk cache, keyed by
        // the immutable cdn url — so a later boot loads them without the CDN.
        const platform = await import('../src/platform');
        expect((platform as unknown as { __cache: Map<string, ArrayBuffer> })
            .__cache.get(`https://cdn/v2/assets/${REMOTE_HASH}.png`)?.byteLength).toBe(8);
        // A renderer bound to the changed asset's stable key is told to rebind.
        // The manifest knew the kind; the notification carries it.
        expect(rebinds).toEqual([{ ref: 'uuid-1', type: 'texture' }]);
        expect(progress[0]).toEqual([0, 1]);
        expect(progress[progress.length - 1]).toEqual([1, 1]);
    });

    it('applyUpdate rolls back (manifest unchanged, no rebind) on an integrity mismatch', async () => {
        // The candidate manifest claims a hash the served bytes do not match.
        const assets = createAssets(backendServing(cdnManifest('deadbeefdeadbeef', 'rev-2')));
        assets.setManifest(cdnManifest('aaaa', 'rev-1'));
        assets.setRemoteRoot('https://cdn/v1');
        const rebinds: Array<{ ref: string; type: string }> = [];
        assets.onInvalidate((e) => rebinds.push({ ref: e.ref, type: e.type }));

        await assets.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });
        const result = await assets.applyUpdate();

        expect(result.ok).toBe(false);
        expect(result.failed).toEqual([{ path: 'assets/deadbeefdeadbeef.png', reason: 'integrity' }]);
        // Rolled back: the old manifest + root stay active and nobody rebound.
        expect(assets.getManifest()?.revision()).toBe('rev-1');
        expect(assets.remoteRoot).toBe('https://cdn/v1');
        expect(rebinds).toEqual([]);
    });

    it('applyUpdate rolls back when a download fails', async () => {
        const backend = backendServing(cdnManifest(REMOTE_HASH, 'rev-2'));
        (backend.fetchBinary as any).mockRejectedValue(new Error('network'));
        const assets = createAssets(backend);
        assets.setManifest(cdnManifest('aaaa', 'rev-1'));

        await assets.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });
        const result = await assets.applyUpdate();

        expect(result.ok).toBe(false);
        expect(result.failed[0].reason).toBe('fetch');
        expect(assets.getManifest()?.revision()).toBe('rev-1'); // unchanged
    });

    it('applyUpdate is a no-op without a prior checkForUpdate', async () => {
        const assets = createAssets(backendServing());
        assets.setManifest(cdnManifest('aaaa', 'rev-1'));
        const progress: [number, number][] = [];
        await assets.applyUpdate((l, t) => progress.push([l, t]));
        expect(assets.getManifest()?.revision()).toBe('rev-1');
        expect(progress).toContainEqual([0, 0]);
    });
});

describe('Assets.resolveLoadPath — @uuid refs to remote assets (model-2)', () => {
    it('resolves a remote-group asset (by @uuid / uuid / address) to the CDN url when a root is set', () => {
        const assets = createAssets(backendServing());
        assets.setManifest(cdnManifest('aaaa', 'rev-1')); // cdn remote; uuid-1 → assets/aaaa.png, address assets/hero.png
        assets.setRemoteRoot('https://cdn.example.com/v1');
        expect(assets.resolveLoadPath('@uuid:uuid-1')).toBe('https://cdn.example.com/v1/assets/aaaa.png');
        expect(assets.resolveLoadPath('uuid-1')).toBe('https://cdn.example.com/v1/assets/aaaa.png');
        expect(assets.resolveLoadPath('assets/hero.png')).toBe('https://cdn.example.com/v1/assets/aaaa.png');
    });

    it('falls through to the normal resolver with no remote root (same-origin realms)', () => {
        const assets = createAssets(backendServing());
        assets.setManifest(cdnManifest('aaaa', 'rev-1'));
        assets.setAssetRefResolver((r) => (r === '@uuid:uuid-1' ? 'estella://project/assets/hero.png' : r));
        // No remoteRoot → the addressable manifest does not hijack resolution.
        expect(assets.resolveLoadPath('@uuid:uuid-1')).toBe('estella://project/assets/hero.png');
    });

    it('leaves local / lazy assets to the normal resolver (only remote groups are routed)', () => {
        const assets = createAssets(backendServing());
        assets.setManifest({
            version: '2.0',
            groups: { main: { bundleMode: 'local', labels: [], assets: { 'uuid-x': { path: 'a.png', type: 'texture', size: 1, labels: [] } } } },
        } as any);
        assets.setRemoteRoot('https://cdn');
        assets.setAssetRefResolver((r) => (r === '@uuid:uuid-x' ? 'a.png' : r));
        expect(assets.resolveLoadPath('@uuid:uuid-x')).toBe('a.png');
    });

    it('after applyUpdate, an @uuid ref resolves to the NEW remote path (scene assets hot-update)', async () => {
        const assets = createAssets(backendServing(cdnManifest(REMOTE_HASH, 'rev-2')));
        assets.setManifest(cdnManifest('aaaa', 'rev-1'));
        assets.setRemoteRoot('https://cdn/v1');
        expect(assets.resolveLoadPath('@uuid:uuid-1')).toBe('https://cdn/v1/assets/aaaa.png');

        await assets.checkForUpdate({ manifestUrl: 'm.json', remoteRoot: 'https://cdn/v2' });
        expect((await assets.applyUpdate()).ok).toBe(true);

        expect(assets.resolveLoadPath('@uuid:uuid-1')).toBe(`https://cdn/v2/assets/${REMOTE_HASH}.png`);
    });
});

describe('Assets.restorePersistedUpdate', () => {
    it('persists an applied update and restores it into a fresh Assets', async () => {
        const backend = backendServing(cdnManifest(REMOTE_HASH, 'rev-2'));
        const first = createAssets(backend);
        first.setManifest(cdnManifest('aaaa', 'rev-1'));
        first.setRemoteRoot('https://cdn/v1');

        // Arm persistence (nothing stored yet → false), then update.
        expect(first.restorePersistedUpdate('hotupdate:demo')).toBe(false);
        await first.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });
        await first.applyUpdate();

        // A returning player boots a fresh Assets straight onto the updated manifest.
        const second = createAssets(backendServing());
        second.setManifest(cdnManifest('aaaa', 'rev-1'));
        const restored = second.restorePersistedUpdate('hotupdate:demo');
        expect(restored).toBe(true);
        expect(second.getManifest()?.revision()).toBe('rev-2');
        expect(second.remoteRoot).toBe('https://cdn/v2');
    });

    it('returns false when nothing is persisted under the key', () => {
        const assets = createAssets(backendServing());
        expect(assets.restorePersistedUpdate('hotupdate:absent')).toBe(false);
    });
});