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 A web package installs the subsystems its content uses, and no others.
*
* Two halves that must stay together. Staging a subpath only lets the PAGE
* resolve it; a subsystem is installed by something IMPORTING it, and on a lean
* entry nothing else does. A package with the first half and not the second
* boots, draws, and is quietly missing physics — which is how it shipped the
* first time.
*/
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 { writeFakeSdkDist } from './fixtures/fakeSdkDist';
import type { ModuleChoice } from '../src/project/format';
import { moduleOfComponent } from '../src/project/targetSupport';
import { OFFICIAL_PACKAGES } from './officialPackagesDir';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const HOSTS = path.join(HERE, '..', 'src', 'runtime');
const SCN = 'cccccccc-cccc-cccc-cccc-cccccccccccc';
/** The entries a real dist publishes, enough of them to tell apart. */
const SDK_FILES = {
'index.js': 'export const full = 1;\n',
'index.lean.js': 'export const lean = 1;\n',
'wasm.js': 'export const wasm = 1;\n',
'tilemap/index.js': 'export const tilemap = 1;\n',
'ai/index.js': 'export const ai = 1;\n',
'net/replication/index.js': 'export const repl = 1;\n',
'debug-channel/index.js': 'export const channel = 1;\n',
'shared/core.js': 'export const core = 1;\n',
};
function setup(components: string[]): { root: string; out: string } {
const root = mkdtempSync(path.join(tmpdir(), 'estella-installs-'));
mkdirSync(path.join(root, 'scenes'), { recursive: true });
writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify({
version: '1.0',
entities: [{ name: 'Root', components: components.map((type) => ({ type })) }],
}));
writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'),
JSON.stringify({ uuid: SCN, version: '2.0', type: 'scene', importer: {} }));
writeFakeSdkDist(path.join(root, '_sdk'), SDK_FILES);
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 }));
return { root, out: path.join(root, 'dist') };
}
const run = (f: { root: string; out: string }) => exportGame({
minifyScripts: false,
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,
});
describe('a web package built on a lean entry', () => {
it('imports the subsystem its content uses, not only resolves it', async () => {
const f = setup(['Tilemap']);
try {
const res = await run(f);
expect(res.errors).toEqual([]);
const page = readFileSync(path.join(f.out, 'index.html'), 'utf8');
const game = readFileSync(path.join(f.out, 'game.js'), 'utf8');
expect(page).toContain('"esengine":"./sdk/index.lean.js"');
expect(page).toContain('"esengine/tilemap":"./sdk/tilemap/index.js"');
// The half a page cannot show: something has to IMPORT it.
expect(game).toContain('import "esengine/tilemap"');
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
it('carries the subpath it installs and leaves the rest behind', async () => {
const f = setup(['Tilemap']);
try {
await run(f);
const sdk = path.join(f.out, 'sdk');
expect(existsSync(path.join(sdk, 'tilemap', 'index.js'))).toBe(true);
expect(existsSync(path.join(sdk, 'index.lean.js'))).toBe(true);
// A game with no agents and no session pays for neither.
expect(existsSync(path.join(sdk, 'ai', 'index.js'))).toBe(false);
expect(existsSync(path.join(sdk, 'net', 'replication', 'index.js'))).toBe(false);
expect(existsSync(path.join(sdk, 'index.js'))).toBe(false);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
it('installs nothing when the content needs nothing optional', async () => {
const f = setup(['Transform', 'Sprite']);
try {
await run(f);
const page = readFileSync(path.join(f.out, 'index.html'), 'utf8');
expect(page).toContain('"esengine":"./sdk/index.lean.js"');
expect(page).not.toContain('esengine/tilemap');
expect(readFileSync(path.join(f.out, 'game.js'), 'utf8')).not.toContain('import "esengine/');
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
// Video is installed by no subpath, so the project takes the whole entry —
// and then the page must name every subpath, because the whole entry has
// already carried every subsystem into the package.
it('falls back to the whole entry for a subsystem no subpath installs', async () => {
const f = setup(['Video']);
try {
await run(f);
const page = readFileSync(path.join(f.out, 'index.html'), 'utf8');
expect(page).toContain('"esengine":"./sdk/index.js"');
expect(page).toContain('"esengine/ai"');
expect(existsSync(path.join(f.out, 'sdk', 'index.js'))).toBe(true);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
// A dist from before the split has no lean entry; pointing `esengine` at a
// file that is not there is a package that cannot boot at all.
it('takes the whole entry when the SDK build produced no lean one', async () => {
const f = setup(['Tilemap']);
try {
rmSync(path.join(f.root, '_sdk'), { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
writeFakeSdkDist(path.join(f.root, '_sdk'),
Object.fromEntries(Object.entries(SDK_FILES).filter(([k]) => k !== 'index.lean.js')));
await run(f);
const page = readFileSync(path.join(f.out, 'index.html'), 'utf8');
expect(page).toContain('"esengine":"./sdk/index.js"');
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
});
/**
* A module a project refused, against content that uses it.
*
* The package this would otherwise make boots and draws and is missing the
* subsystem its own scene needs, with nothing saying which one — so the export
* refuses to make it, and names what argued.
*/
describe('the debug channel', () => {
it('is installed in a development build that names an editor, and nowhere else', async () => {
const f = setup(['Transform', 'Sprite']);
const dev = { ...f, out: path.join(f.root, 'dev') };
try {
await run(f);
const res = await exportGame({
minifyScripts: false,
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: dev.out, debugChannel: { url: 'ws://192.168.1.2:37420/?token=t' },
});
expect(res.errors).toEqual([]);
const shipped = (out: string) => ({
page: readFileSync(path.join(out, 'index.html'), 'utf8'),
game: readFileSync(path.join(out, 'game.js'), 'utf8'),
staged: existsSync(path.join(out, 'sdk', 'debug-channel', 'index.js')),
});
const withChannel = shipped(dev.out);
expect(withChannel.page).toContain('"esengine/debug-channel":"./sdk/debug-channel/index.js"');
expect(withChannel.game).toContain('import "esengine/debug-channel"');
expect(withChannel.staged).toBe(true);
const without = shipped(f.out);
expect(without.page).not.toContain('debug-channel');
expect(without.game).not.toContain('debug-channel');
expect(without.staged).toBe(false);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
});
describe('a web package whose project excluded a module', () => {
/** The export takes what the project said as an option, the way it takes every
* other project-derived setting; `packagingOptionsOf` is what derives it. */
const withChoice = (components: string[], modules: Record<string, ModuleChoice>) => ({
...setup(components), features: { modules },
});
const runWith = (f: ReturnType<typeof withChoice>) => exportGame({
minifyScripts: false,
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, features: f.features,
});
it('fails, naming the module and what said the project uses it', async () => {
const f = withChoice(['Tilemap'], { 'esengine/tilemap': 'exclude' });
try {
const res = await runWith(f);
expect(res.ok).toBe(false);
expect(res.errors.join('\n')).toContain('esengine/tilemap is excluded');
expect(res.errors.join('\n')).toContain('a tilemap component in the content');
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
it('builds when the excluded module is one the content does not use', async () => {
const f = withChoice(['Tilemap'], { 'esengine/ai': 'exclude' });
try {
const res = await runWith(f);
expect(res.errors).toEqual([]);
expect(readFileSync(path.join(f.out, 'game.js'), 'utf8')).toContain('import "esengine/tilemap"');
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
// What `include` is for: a module only a script reaches, which no scan sees.
it('installs one the project forced in although nothing detected it', async () => {
const f = withChoice(['Transform'], { 'esengine/replication': 'include' });
try {
await runWith(f);
expect(readFileSync(path.join(f.out, 'game.js'), 'utf8'))
.toContain('import "esengine/replication"');
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
});
/**
* The page shows the components its documents carry; the build has more evidence
* than that. So the two are not equal — but everything the page calls used has
* to be installed, or a creator is told a module ships and it does not.
*/
describe('what the page says and what the build installs', () => {
const pageWouldSay = (components: string[]): string[] => {
const used = new Set<string>();
for (const name of components) {
const module = moduleOfComponent(name);
if (module !== null) used.add(module);
}
return [...used].sort();
};
it('agree for content that uses several modules', async () => {
const f = setup(['Tilemap', 'NavAgent', 'Health']);
try {
await run(f);
const page = pageWouldSay(['Tilemap', 'NavAgent', 'Health']);
expect(page).toEqual(['esengine/ai', 'esengine/gameplay', 'esengine/tilemap']);
const game = readFileSync(path.join(f.out, 'game.js'), 'utf8');
for (const module of page) expect(game).toContain(`import ${JSON.stringify(module)}`);
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
it('agree that nothing optional is used, for content that uses none', async () => {
const f = setup(['Transform', 'Sprite']);
try {
await run(f);
expect(pageWouldSay(['Transform', 'Sprite'])).toEqual([]);
expect(readFileSync(path.join(f.out, 'game.js'), 'utf8')).not.toContain('import "esengine/');
} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }
});
});