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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file assets-preload.test.ts
* @brief Assets.preload contract: explicit ref lists warm the typed caches
* with progress, types resolve via catalog → extension fallback, and
* undeterminable/failing refs land in `failed` without rejecting.
*/
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { Assets } from '../src/asset/Assets';
import { Catalog, type CatalogData } from '../src/asset/Catalog';
import type { Backend } from '../src/asset/Backend';
import type { AssetLoader } from '../src/asset/AssetLoader';
import { registerComponent } from '../src/ecs/component';
import { UITooltip } from '../src/ui/behavior/tooltip';
import type { SceneData } from '../src/scene/scene';
vi.mock('../src/wasm/resourceManager', () => ({
requireResourceManager: () => ({
createTexture: vi.fn(() => 42),
registerExternalTexture: vi.fn(() => 42),
releaseTexture: vi.fn(),
getTextureGLId: vi.fn(() => 1),
registerTextureWithPath: vi.fn(),
acquireTextureByPath: vi.fn(() => 0),
invalidateTexturePath: vi.fn(() => false),
getTextureDimensions: vi.fn(() => ({ width: 64, height: 64 })),
}),
getResourceManager: () => null,
evictTextureDimensions: vi.fn(),
}));
// TextureLoader/imageDecode import the concrete base module (cycle-free); the
// rest go through the barrel — mock both ids with one factory.
const platformFactory = vi.hoisted(() => () => ({
platformCreateCanvas: () => ({
width: 256, height: 256,
getContext: () => ({
clearRect: vi.fn(),
drawImage: vi.fn(),
getImageData: () => ({ data: { buffer: new ArrayBuffer(256 * 256 * 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(),
}));
vi.mock('../src/platform', platformFactory);
vi.mock('../src/platform/base', platformFactory);
const mockModule = {
_malloc: vi.fn(() => 0),
_free: vi.fn(),
HEAPU8: new Uint8Array(1024 * 1024),
GL: null,
FS: null,
} as never;
const catalogData: CatalogData = {
version: 1,
entries: {
'sprites/hero.png': { type: 'texture' },
'data/level.custom': { type: 'custom' },
},
addresses: {},
labels: {},
};
describe('Assets.preload', () => {
let assets: Assets;
let backend: Backend;
let customLoads: string[];
beforeEach(() => {
customLoads = [];
backend = {
fetchBinary: vi.fn(async () => new ArrayBuffer(8)),
fetchText: vi.fn(async () => 'payload'),
resolveUrl: (path: string) => `http://test/${path}`,
} as unknown as Backend;
assets = Assets.create({
backend,
catalog: Catalog.fromJson(catalogData),
module: mockModule,
});
const customLoader: AssetLoader<{ value: string }> = {
type: 'custom',
extensions: ['.custom'],
load: async (path) => {
customLoads.push(path);
return { value: path };
},
unload: vi.fn(),
};
assets.register(customLoader);
});
it('warms caches for catalog-typed and extension-inferred refs, with progress', async () => {
const ticks: Array<[number, number]> = [];
const { failed } = await assets.preload(
['sprites/hero.png', 'data/level.custom', 'data/other.custom'],
(loaded, total) => ticks.push([loaded, total]),
);
expect(failed).toEqual([]);
// 'data/other.custom' has no catalog entry — its type came from the
// .custom extension of the registered loader.
expect(customLoads.sort()).toEqual(['data/level.custom', 'data/other.custom']);
expect(assets.getTexture('sprites/hero.png')).toBeDefined();
expect(ticks[0]).toEqual([0, 3]);
expect(ticks[ticks.length - 1]).toEqual([3, 3]);
// The eventual real load is a pure cache hit — the loader doesn't re-run.
await assets.load('custom', 'data/level.custom');
expect(customLoads.filter(p => p === 'data/level.custom')).toHaveLength(1);
});
it('preloads a tooltip style prefab through component metadata and owns its lease', async () => {
registerComponent('UITooltip', UITooltip);
const unload = vi.fn();
assets.register({ type: 'prefab', extensions: ['.esprefab'], load: async () => ({ data: {} }), unload });
const scene: SceneData = { version: '1.0', name: 'Hints', entities: [
{ id: 1, name: 'Volume', parent: null, children: [], components: [
{ type: 'UITooltip', data: { stylePrefab: 'ui/Tip.esprefab' } },
] },
] };
const result = await assets.preloadSceneAssets(scene);
expect(result.missing).toEqual([]);
expect(result.acquisitions?.some(a => a.type === 'prefab' && a.path === 'ui/Tip.esprefab')).toBe(true);
result.scope.releaseAll(); expect(unload).toHaveBeenCalledTimes(1);
});
it('reports refs whose type cannot be determined without rejecting', async () => {
const { failed } = await assets.preload(['mystery/blob.xyz']);
expect(failed).toEqual([
{ ref: 'mystery/blob.xyz', reason: 'unresolved' },
]);
});
it('reports load failures per ref and still completes the rest', async () => {
const failing: AssetLoader<never> = {
type: 'broken',
extensions: ['.broken'],
load: async () => { throw new Error('boom'); },
unload: vi.fn(),
};
assets.register(failing);
const { failed } = await assets.preload(['a.broken', 'data/level.custom']);
expect(customLoads).toEqual(['data/level.custom']);
expect(failed).toHaveLength(1);
expect(failed[0]).toMatchObject({ ref: 'a.broken', type: 'broken', reason: 'load-failed', error: 'boom' });
});
});