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
//
// The persistent content-addressed disk cache behind offline hot-update: the http
// backend serves cached (content-addressed, immutable) assets without the network,
// the node adapter backs it with a real filesystem, and both cache wrappers degrade
// to "no cache" on a platform (web) that omits the methods.
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { rm } from 'node:fs/promises';
import { HttpBackend, FileSystemBackend } from '../src/asset/Backend';
import { setPlatform, platformReadCacheFile, platformWriteCacheFile } from '../src/platform/base';
import type { PlatformAdapter, PlatformResponse } from '../src/platform/types';
import { nodeAdapter } from '../src/platform/node';
function mockPlatform(over: Partial<PlatformAdapter>): PlatformAdapter {
return {
name: 'web',
fetch: vi.fn(),
readFile: vi.fn(), readTextFile: vi.fn(), fileExists: vi.fn(),
loadImagePixels: vi.fn(), instantiateWasm: vi.fn(),
createCanvas: vi.fn(), createImage: vi.fn(), now: () => 0,
bindInputEvents: vi.fn(), createAudioBackend: vi.fn(),
devicePixelRatio: () => 1,
getStorageItem: () => null, setStorageItem: vi.fn(),
removeStorageItem: vi.fn(), clearStorage: vi.fn(),
...over,
} as unknown as PlatformAdapter;
}
function okResponse(bytes: ArrayBuffer): PlatformResponse {
return {
ok: true, status: 200, statusText: 'OK', headers: {},
json: async () => ({}), text: async () => '', arrayBuffer: async () => bytes,
};
}
describe('HttpBackend content cache (offline hot-update store)', () => {
it('serves a cached http asset without touching the network (offline)', async () => {
const cached = new Uint8Array([1, 2, 3, 4]).buffer;
const fetch = vi.fn(() => { throw new Error('offline'); });
setPlatform(mockPlatform({ fetch: fetch as never, readCacheFile: async () => cached }));
const got = await new HttpBackend({ baseUrl: '' }).fetchBinary('https://cdn/assets/abcd.png');
expect(new Uint8Array(got)).toEqual(new Uint8Array([1, 2, 3, 4]));
expect(fetch).not.toHaveBeenCalled(); // cache hit ⇒ no network
});
it('falls through to the network on a cache miss', async () => {
const net = new Uint8Array([9, 9]).buffer;
const fetch = vi.fn(async () => okResponse(net));
setPlatform(mockPlatform({ fetch: fetch as never, readCacheFile: async () => null }));
const got = await new HttpBackend({ baseUrl: '' }).fetchBinary('https://cdn/assets/x.png');
expect(new Uint8Array(got)).toEqual(new Uint8Array([9, 9]));
expect(fetch).toHaveBeenCalledOnce();
});
it('never consults the cache for non-http (local/same-origin) paths', async () => {
const net = new Uint8Array([7]).buffer;
const readCacheFile = vi.fn(async () => new Uint8Array([0]).buffer);
const fetch = vi.fn(async () => okResponse(net));
setPlatform(mockPlatform({ fetch: fetch as never, readCacheFile }));
const got = await new HttpBackend({ baseUrl: '' }).fetchBinary('estella://project/a.png');
expect(new Uint8Array(got)).toEqual(new Uint8Array([7]));
expect(readCacheFile).not.toHaveBeenCalled(); // local path bypasses the cache
});
});
describe('a packaged realm (mini-game, native) reaches a CDN url over the network', () => {
// Its own files are read from the package; a hot update's manifest and assets
// live on a CDN, and reading those as package paths found nothing.
it('fetches a manifest from the CDN as text', async () => {
const fetch = vi.fn(async () => ({ ok: true, status: 200, text: async () => '{"version":"2.0"}' }));
const readTextFile = vi.fn(async () => { throw new Error('not in the package'); });
setPlatform(mockPlatform({ fetch: fetch as never, readTextFile }));
expect(await new FileSystemBackend().fetchText('https://cdn/asset-manifest.json')).toBe('{"version":"2.0"}');
expect(readTextFile).not.toHaveBeenCalled();
});
it('serves an updated asset from the cache first, as the web does', async () => {
const cached = new Uint8Array([7, 7]).buffer;
const fetch = vi.fn();
setPlatform(mockPlatform({ fetch: fetch as never, readCacheFile: async () => cached }));
expect(await new FileSystemBackend().fetchBinary('https://cdn/assets/abcd.png')).toBe(cached);
expect(fetch).not.toHaveBeenCalled();
});
it('asks for bytes, so a host that answers text by default hands over the image itself', async () => {
const fetch = vi.fn(async () => okResponse(new ArrayBuffer(4)));
setPlatform(mockPlatform({ fetch: fetch as never, readCacheFile: async () => null }));
await new FileSystemBackend().fetchBinary('https://cdn/assets/abcd.png');
expect(fetch).toHaveBeenCalledWith('https://cdn/assets/abcd.png', expect.objectContaining({ responseType: 'arraybuffer' }));
});
it('still reads its own files from the package', async () => {
const readFile = vi.fn(async () => new ArrayBuffer(3));
const fetch = vi.fn();
setPlatform(mockPlatform({ fetch: fetch as never, readFile }));
expect((await new FileSystemBackend().fetchBinary('assets/hero.png')).byteLength).toBe(3);
expect(fetch).not.toHaveBeenCalled();
});
});
describe('node adapter disk cache (real filesystem)', () => {
const dir = join(tmpdir(), `esengine-cache-test-${process.pid}`);
beforeEach(() => { process.env.ESENGINE_CACHE_DIR = dir; });
afterEach(async () => {
delete process.env.ESENGINE_CACHE_DIR;
await rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
});
it('round-trips bytes through the filesystem, misses on an absent key', async () => {
const key = 'https://cdn/assets/deadbeef.png';
expect(await nodeAdapter.readCacheFile(key)).toBeNull(); // empty cache
await nodeAdapter.writeCacheFile(key, new Uint8Array([5, 6, 7, 8, 9]).buffer);
const got = await nodeAdapter.readCacheFile(key);
expect(got).not.toBeNull();
expect(new Uint8Array(got!)).toEqual(new Uint8Array([5, 6, 7, 8, 9]));
expect(await nodeAdapter.readCacheFile('https://cdn/assets/other.png')).toBeNull();
});
it('end-to-end: HttpBackend serves an updated asset from the real disk cache OFFLINE', async () => {
const url = 'https://cdn/v2/assets/cafebabe.png';
const bytes = new Uint8Array([10, 20, 30, 40]).buffer;
// Platform: real node fs cache (temp dir above) + a fetch that always fails (offline).
const offlineFetch = vi.fn(() => { throw new Error('offline'); });
setPlatform(mockPlatform({
fetch: offlineFetch as never,
readCacheFile: (k) => nodeAdapter.readCacheFile(k),
writeCacheFile: (k, b) => nodeAdapter.writeCacheFile(k, b),
}));
// "applyUpdate" persisted the verified bytes to disk while online…
await platformWriteCacheFile(url, bytes);
// …now, offline, the http backend loads them straight off disk (no network).
const got = await new HttpBackend({ baseUrl: '' }).fetchBinary(url);
expect(new Uint8Array(got)).toEqual(new Uint8Array([10, 20, 30, 40]));
expect(offlineFetch).not.toHaveBeenCalled();
});
});
describe('cache wrappers degrade on a platform with no cache (web)', () => {
it('does not claim storage when an adapter method exists but the host has no cache bindings', async () => {
const write = vi.fn(async () => {});
setPlatform(mockPlatform({ writeCacheFile: write, hasCacheStorage: () => false }));
expect(await platformWriteCacheFile('k', new ArrayBuffer(2))).toBe('unsupported');
expect(write).not.toHaveBeenCalled();
});
it('read returns null and write says unsupported when the adapter omits the methods', async () => {
setPlatform(mockPlatform({})); // no readCacheFile / writeCacheFile
expect(await platformReadCacheFile('k')).toBeNull();
await expect(platformWriteCacheFile('k', new ArrayBuffer(2))).resolves.toBe('unsupported');
});
});