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 Which optional modules a web package carries: the ones its content can
* ask for, and no others. A dropped module is a 404 at boot.
*/
import { describe, it, expect } from 'vitest';
import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { exportGame } from '../src/export/exportGame';
import { runtimeConfigOf } from '../src/project/runtimeConfig';
import { writeFakeSdkDist } from './fixtures/fakeSdkDist';
import { OFFICIAL_PACKAGES } from './officialPackagesDir';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const HOSTS = path.join(HERE, '..', '..', 'pipeline', 'src', 'runtime');
const SCN = 'cccccccc-cccc-cccc-cccc-cccccccccccc';
const PFB = 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee';
const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });
/** Every module the engine ships, so a test can assert what did NOT come along. */
const ALL_MODULES = [
'physics', 'physics3d', 'basis', 'videodec', 'dragonbones',
'spine21', 'spine38', 'spine41', 'spine42', 'spine43',
];
interface Fixture { root: string; out: string }
function setup(scene: unknown, extra?: (root: string) => void): Fixture {
const root = mkdtempSync(path.join(tmpdir(), 'estella-sidemod-'));
mkdirSync(path.join(root, 'scenes'), { recursive: true });
writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify(scene));
writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
writeFakeSdkDist(path.join(root, '_sdk'));
mkdirSync(path.join(root, '_wasm'), { recursive: true });
writeFileSync(path.join(root, '_wasm', 'esengine.js'), 'export default () => {};');
writeFileSync(path.join(root, '_wasm', 'esengine.wasm'), 'ENGINE');
writeFileSync(path.join(root, '_wasm', 'wasm.manifest.json'), JSON.stringify({ schema: 1 }));
for (const m of ALL_MODULES) {
writeFileSync(path.join(root, '_wasm', `${m}.js`), `export default () => {};/*${m}*/`);
writeFileSync(path.join(root, '_wasm', `${m}.wasm`), m.toUpperCase());
}
extra?.(root);
return { root, out: path.join(root, 'dist') };
}
const run = (
f: Fixture,
runtime?: Parameters<typeof exportGame>[0]['runtime'],
features?: Parameters<typeof exportGame>[0]['features'],
packAssets?: boolean,
) => exportGame({
root: f.root, entryScene: 'scenes/main.esscene', hostsDir: HOSTS, packagesDir: OFFICIAL_PACKAGES,
sdkDistDir: path.join(f.root, '_sdk'), wasmDir: path.join(f.root, '_wasm'),
outDir: f.out, ...(runtime ? { runtime } : {}), ...(features ? { features } : {}),
...(packAssets === undefined ? {} : { packAssets }),
});
/** The module artifact base names the package actually carries. */
function shipped(out: string): string[] {
return ALL_MODULES.filter((m) => existsSync(path.join(out, 'wasm', `${m}.wasm`)));
}
const entities = (...components: Array<{ type: string; data?: unknown }>) =>
[{ id: 0, components }];
describe('web package side modules', () => {
it('removes old texture hashes after editing and unreferencing a sprite texture', async () => {
const tex = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'Sprite', data: { texture: `@uuid:${tex}` } }) }, (root) => {
mkdirSync(path.join(root, 'assets'));
writeFileSync(path.join(root, 'assets/hero.png'), 'PNGDATA');
writeFileSync(path.join(root, 'assets/hero.png.meta'), meta(tex, 'texture'));
});
const texturePath = () => JSON.parse(readFileSync(path.join(f.out, 'asset-manifest.json'), 'utf8')).groups.main.assets[tex].path as string;
try {
expect((await run(f)).ok).toBe(true);
const first = texturePath();
writeFileSync(path.join(f.out, 'host-config.json'), 'KEEP');
writeFileSync(path.join(f.out, 'assets/custom.txt'), 'KEEP');
writeFileSync(path.join(f.root, 'assets/hero.png'), 'CHANGEDPNGDATA');
expect((await run(f)).ok).toBe(true);
const second = texturePath();
expect(second).not.toBe(first);
expect(existsSync(path.join(f.out, first))).toBe(false);
expect(existsSync(path.join(f.out, second))).toBe(true);
writeFileSync(path.join(f.root, 'scenes/main.esscene'), JSON.stringify({ version: '1.0', entities: [] }));
expect((await run(f)).ok).toBe(true);
expect(existsSync(path.join(f.out, second))).toBe(false);
expect(existsSync(path.join(f.out, 'assets/custom.txt'))).toBe(true);
expect(existsSync(path.join(f.out, 'host-config.json'))).toBe(true);
expect(readFileSync(path.join(f.root, 'assets/hero.png'), 'utf8')).toBe('CHANGEDPNGDATA');
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
it('removes an old pack when exporting its materials as separate files', async () => {
const a = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', b = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
const f = setup({ version: '1.0', entities: [{ id: 0, components: [{ type: 'Sprite', data: { material: `@uuid:${a}` } }] },
{ id: 1, components: [{ type: 'Sprite', data: { material: `@uuid:${b}` } }] }] }, (root) => {
mkdirSync(path.join(root, 'assets'));
for (const [name, uuid, value] of [['a', a, 1], ['b', b, 2]]) {
writeFileSync(path.join(root, `assets/${name}.esmaterial`), JSON.stringify({ shader: 'builtin:sprite', properties: { value } }));
writeFileSync(path.join(root, `assets/${name}.esmaterial.meta`), meta(uuid as string, 'material'));
}
});
try {
expect((await run(f)).ok).toBe(true);
const old = JSON.parse(readFileSync(path.join(f.out, 'asset-manifest.json'), 'utf8')).groups.main.assets[a].pack.file as string;
expect(existsSync(path.join(f.out, old))).toBe(true);
expect((await run(f, undefined, undefined, false)).ok).toBe(true);
expect(existsSync(path.join(f.out, old))).toBe(false);
const current = JSON.parse(readFileSync(path.join(f.out, 'asset-manifest.json'), 'utf8')).groups.main.assets[a];
expect(current.pack).toBeUndefined();
expect(existsSync(path.join(f.out, current.path))).toBe(true);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
it('drops a removed solver and preserves output-root files on re-export', async () => {
const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'RigidBody2D', data: {} }) });
try {
expect((await run(f)).ok).toBe(true);
expect(shipped(f.out)).toEqual(['physics']);
writeFileSync(path.join(f.out, 'host-config.json'), 'KEEP');
writeFileSync(path.join(f.root, 'scenes', 'main.esscene'), JSON.stringify({ version: '1.0', name: 'Main', entities: [] }));
expect((await run(f)).ok).toBe(true);
expect(shipped(f.out)).toEqual([]);
expect(existsSync(path.join(f.out, 'wasm', 'physics.js'))).toBe(false);
expect(existsSync(path.join(f.out, 'host-config.json'))).toBe(true);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
it('carries the engine and nothing optional for a scene that asks for nothing', async () => {
const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'Sprite', data: {} }) });
try {
const res = await run(f);
expect(res.errors).toEqual([]);
expect(shipped(f.out)).toEqual([]);
// The engine core and the dir's other contents are never the scan's to drop.
expect(existsSync(path.join(f.out, 'wasm', 'esengine.wasm'))).toBe(true);
expect(existsSync(path.join(f.out, 'wasm', 'esengine.js'))).toBe(true);
expect(existsSync(path.join(f.out, 'wasm', 'wasm.manifest.json'))).toBe(true);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
it('carries the 2D solver for a scene with a body', async () => {
const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'RigidBody2D', data: { bodyType: 1 } }) });
try {
expect(shipped((await run(f), f.out))).toEqual(['physics']);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
it('carries the 2D solver a project declares but no scene uses', async () => {
const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'Sprite', data: {} }) });
try {
// The project's declaration, which is what the build reads: `runtime` is
// the packaged game's copy of the same manifest, not a second authority.
const features = { physics: { enabled: true } };
await run(f, runtimeConfigOf({ features }), features);
expect(shipped(f.out)).toEqual(['physics']);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
it('carries the 3D solver for a 3D body, and never implies it from the 2D flag', async () => {
const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'RigidBody3D', data: {} }) });
try {
await run(f);
expect(shipped(f.out)).toEqual(['physics3d']);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
// Joints and mesh colliders are 3D physics components like the bodies are;
// the scan answers for every type the runtime's own gate counts.
it.each(['HingeJoint3D', 'SwingTwistJoint3D', 'SixDOFJoint3D'])('carries the 3D solver for %s, not only for a body', async (type) => {
const f = setup({ version: '1.0', name: 'Main', entities: entities({ type, data: {} }) });
try {
await run(f);
expect(shipped(f.out)).toEqual(['physics3d']);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
it('carries the 3D solver for a mesh collider', async () => {
const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'MeshCollider3D', data: {} }) });
try {
await run(f);
expect(shipped(f.out)).toEqual(['physics3d']);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
// The runtime expands prefabs before it asks whether the scene needs physics,
// so a body reachable only through a prefab is one the package must carry.
it('carries what a shipped prefab needs, not only what a scene holds', async () => {
const f = setup(
{ version: '1.0', name: 'Main', entities: entities({ type: 'Spawner', data: { prefab: `@uuid:${PFB}` } }) },
(root) => {
mkdirSync(path.join(root, 'prefabs'), { recursive: true });
writeFileSync(path.join(root, 'prefabs', 'enemy.esprefab'), JSON.stringify({
version: '1.0', name: 'Enemy', rootEntityId: 'r',
entities: [{ prefabEntityId: 'r', name: 'Enemy', parent: null, children: [], visible: true, components: [{ type: 'RigidBody2D', data: { bodyType: 1 } }] }],
}));
writeFileSync(path.join(root, 'prefabs', 'enemy.esprefab.meta'), meta(PFB, 'prefab'));
},
);
try {
const res = await run(f);
expect(res.errors).toEqual([]);
expect(shipped(f.out)).toEqual(['physics']);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
it('fails the export when the content needs a module the wasm dir has not built', async () => {
const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'RigidBody3D', data: {} }) });
rmSync(path.join(f.root, '_wasm', 'physics3d.js'));
try {
const res = await run(f);
expect(res.ok).toBe(false);
expect(res.errors.join('\n')).toMatch(/physics3d/);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
}, 60_000);
});