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.

feat(export): a web package bundles the SDK with the host and the scripts, so what the game does not reach is not shipped

yhhbd55cfb35cab
diff --git a/pipeline/src/bundle/importMap.ts b/pipeline/src/bundle/importMap.ts
index b0e09d8f0..aa2837896 100644
--- a/pipeline/src/bundle/importMap.ts
+++ b/pipeline/src/bundle/importMap.ts
@@ -60,6 +60,9 @@ export function engineImportMap(entry: string, subpaths: Iterable<string>): Engi
return finish(imports);
}
+/** A page with nothing to resolve: the SDK is inside the bundles it loads, so no bare `esengine` reaches the browser. */
+export const NO_IMPORT_MAP: EngineImportMap = finish({});
+
/** Every subsystem the engine has, for a realm that authors all of them. */
export const FULL_IMPORT_MAP: EngineImportMap = finish({
esengine: STAGED + FULL_ENTRY_FILE,
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 9229d6255..996681176 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -39,7 +39,7 @@ import { packagedHotUpdate } from './hotUpdateConfig';
import {
DEFAULT_RUNTIME_CONFIG, packagedRuntimeFields, withAudioLoadTypes, type RuntimeProjectConfig,
} from '../project/runtimeConfig';
-import { engineImportMap, FULL_IMPORT_MAP, LEAN_ENTRY_FILE, FULL_ENTRY_FILE, type EngineImportMap } from '../bundle/importMap';
+import { engineImportMap, FULL_IMPORT_MAP, NO_IMPORT_MAP, LEAN_ENTRY_FILE, FULL_ENTRY_FILE, type EngineImportMap } from '../bundle/importMap';
import { engineInstalls, forcedSideModules, moduleChoices, type EngineInstallPlan } from '../bundle/engineInstalls';
import { exportMiniGame } from './exportMiniGame';
import { wechatExportProfile, douyinExportProfile, kuaishouExportProfile, bilibiliExportProfile, quickgameExportProfile, alipayExportProfile, huaweiExportProfile } from './miniGameExportProfile';
@@ -59,7 +59,7 @@ import type { PlayableCheckReport } from './playableCheck';
import { exportPlayable } from './exportPlayable';
import { genericPlayableProfile, type PlayableAdProfile } from './playableAdProfile';
import type { OnExportProgress } from './exportProgress';
-import { ESENGINE_EXTERNAL, ESENGINE_SUBPATHS } from '../bundle/esengineResolve';
+import { ESENGINE_EXTERNAL, ESENGINE_SUBPATHS, esengineAlias } from '../bundle/esengineResolve';
import { officialPackagesPlugin } from '../bundle/officialPackages';
import type { RpkSigningKey } from './rpk';
import { buildCompiledSystems, type BuildMode } from '../bundle/buildCompiledSystems';
@@ -507,6 +507,11 @@ export interface ExportGameOptions {
webConnect?: string[];
/** Web: carry the plain-JavaScript engine for browsers without WebAssembly. Absent ⇒ false. */
webEngineJs?: boolean;
+ /**
+ * Web: bundle the SDK, the host and the project scripts into one tree-shaken, code-split graph (one shared SDK) instead
+ * of copying the SDK's chunks beside the page for an import map to resolve. Absent ⇒ true; false keeps the copied tree.
+ */
+ bundleEngine?: boolean;
leaderboardEncryptionKey?: string;
sdkDistDir: string;
/** The engine runtime to copy. */
@@ -1017,6 +1022,10 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
errors.push(`cook manifest: ${err instanceof Error ? err.message : String(err)}`);
}
+ /** Web: the SDK is bundled with the host and the scripts, not copied beside them. */
+ const bundleEngine = platform === 'web' && opts.bundleEngine !== false
+ && process.env.ESTELLA_WEB_BUNDLE_ENGINE !== '0'
+ && existsSync(path.join(opts.sdkDistDir, FULL_ENTRY_FILE));
/** What the host must import, or null when this build has no project code. */
let scriptsFile: string | null = null;
/** The `esengine/*` specifiers the bundles above left for the import map. */
@@ -1087,7 +1096,8 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
plugins: [esengineGlobalPlugin(), officialPackagesPlugin(opts.packagesDir)],
entryPoints: [scriptsAbs], outfile: path.join(payloadDir, 'scripts.js'),
})
- : await build({ ...common, entryPoints: [scriptsAbs], outfile: path.join(payloadDir, 'scripts.mjs') });
+ // Bundling the engine in rebuilds this below, once the plan is known; this pass is only evidence.
+ : await build({ ...common, entryPoints: [scriptsAbs], outfile: path.join(payloadDir, 'scripts.mjs'), write: !bundleEngine });
errors.push(...explainBundleErrors(proj.errors));
for (const spec of externalEngineImports(proj.metafile)) scriptImports.add(spec);
}
@@ -1117,19 +1127,52 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
// a subpath only lets the page resolve it; a subsystem is installed by
// something importing it, and on a lean entry nothing else does.
const hostEntry = runtimeHostEntry(opts.hostsDir, 'gameHost');
- const host = await build({
- ...common,
- define: { ...common.define, __ESTELLA_LAN_PREVIEW__: opts.developmentPreview ? 'true' : 'false' },
- stdin: {
- contents: plan.subpaths.map((m) => `import ${JSON.stringify(m)};\n`).join('')
- + `import ${JSON.stringify(hostEntry)};\n`,
- resolveDir: path.dirname(hostEntry),
- loader: 'js',
- sourcefile: 'game-entry.js',
- },
- outfile: path.join(payloadDir, 'game.js'),
- });
- errors.push(...explainBundleErrors(host.errors));
+ const hostContents = plan.subpaths.map((m) => `import ${JSON.stringify(m)};\n`).join('')
+ + `import ${JSON.stringify(hostEntry)};\n`;
+ const define = { ...common.define, __ESTELLA_LAN_PREVIEW__: opts.developmentPreview ? 'true' : 'false' };
+ if (bundleEngine) {
+ // One graph: the host and the scripts import the SDK from the same chunks, so there is one instance of it (what
+ // the import map gave the copied tree), and what neither of them reaches is not shipped.
+ const entryId = 'estella:game-entry';
+ const leanEntry = plan.lean && existsSync(path.join(opts.sdkDistDir, LEAN_ENTRY_FILE));
+ await rm(path.join(payloadDir, 'chunks'), { recursive: true, force: true });
+ await rm(path.join(payloadDir, 'scripts.mjs'), { force: true });
+ const bundled = await build({
+ ...common,
+ define,
+ external: [],
+ alias: esengineAlias(opts.sdkDistDir, leanEntry ? LEAN_ENTRY_FILE : FULL_ENTRY_FILE),
+ splitting: true,
+ outdir: payloadDir,
+ entryNames: '[name]',
+ chunkNames: 'chunks/[name]-[hash]',
+ entryPoints: [{ in: entryId, out: 'game' }, ...(scriptsFile && scriptsAbs ? [{ in: scriptsAbs, out: 'scripts' }] : [])],
+ plugins: [...(common.plugins ?? []), {
+ name: 'estella-game-entry',
+ setup(b) {
+ b.onResolve({ filter: /^estella:game-entry$/ }, () => ({ path: entryId, namespace: 'estella-entry' }));
+ b.onLoad({ filter: /.*/, namespace: 'estella-entry' }, () => ({
+ contents: hostContents, resolveDir: path.dirname(hostEntry), loader: 'js',
+ }));
+ },
+ }],
+ });
+ errors.push(...explainBundleErrors(bundled.errors));
+ if (scriptsFile) scriptsFile = 'scripts.js';
+ } else {
+ const host = await build({
+ ...common,
+ define,
+ stdin: {
+ contents: hostContents,
+ resolveDir: path.dirname(hostEntry),
+ loader: 'js',
+ sourcefile: 'game-entry.js',
+ },
+ outfile: path.join(payloadDir, 'game.js'),
+ });
+ errors.push(...explainBundleErrors(host.errors));
+ }
}
} catch (err) {
@@ -1217,7 +1260,11 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
: engineImportMap(FULL_ENTRY_FILE, Object.keys(ESENGINE_SUBPATHS));
progress({ phase: 'Copying SDK + runtime' });
- if (existsSync(opts.sdkDistDir)) {
+ if (bundleEngine) {
+ // The SDK is inside game.js and the chunks beside it; a tree left by an earlier export would only be dead weight.
+ engineMap = NO_IMPORT_MAP;
+ await rm(path.join(payloadDir, 'sdk'), { recursive: true, force: true });
+ } else if (existsSync(opts.sdkDistDir)) {
const sdkOut = await resetRuntimeTree(payloadDir, 'sdk', [opts.sdkDistDir, opts.wasmDir]);
await cp(opts.sdkDistDir, sdkOut, {
recursive: true, filter: shipsToBrowser(sourceMaps, opts.sdkDistDir, engineMap.entries),
diff --git a/pipeline/tests/export-web-bundle.test.ts b/pipeline/tests/export-web-bundle.test.ts
new file mode 100644
index 000000000..942f46220
--- /dev/null
+++ b/pipeline/tests/export-web-bundle.test.ts
@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A web package carries the part of the SDK its game reaches, in one graph.
+ *
+ * The copied tree shipped every shared chunk of the SDK beside the page — the whole union of every
+ * entry's code, terrain and water in a project with neither. The package now bundles the SDK, the
+ * game host and the project's scripts together and lets the bundler drop what none of them reaches.
+ *
+ * Built from the real SDK: a stub tree cannot be bundled, and this is the claim that the shipped
+ * graph keeps ONE copy of the engine for the host and the scripts both.
+ */
+import { describe, it, expect, afterAll } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync, 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 { OFFICIAL_PACKAGES } from './officialPackagesDir';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const HOSTS = path.join(HERE, '..', 'src', 'runtime');
+const SDK = path.join(HERE, '..', '..', 'sdk', 'dist');
+const SCN = 'dddddddd-dddd-dddd-dddd-dddddddddddd';
+
+const roots: string[] = [];
+afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true, maxRetries: 5 }); });
+
+function project(): string {
+ const root = mkdtempSync(path.join(tmpdir(), 'estella-web-bundle-'));
+ roots.push(root);
+ mkdirSync(path.join(root, 'scenes'), { recursive: true });
+ mkdirSync(path.join(root, 'src'), { recursive: true });
+ writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify({
+ version: '1.0', entities: [{ name: 'Root', components: [{ type: 'Transform' }] }],
+ }));
+ writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'),
+ JSON.stringify({ uuid: SCN, version: '2.0', type: 'scene', importer: {} }));
+ // The project's own code reaches the SDK by the bare name, like any game.
+ writeFileSync(path.join(root, 'src', 'main.ts'),
+ "import { defineSystem, Schedule } from 'esengine';\nvoid defineSystem; void Schedule;\nexport const ready = true;\n");
+ 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;
+}
+
+function jsBytes(dir: string): number {
+ let total = 0;
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) { if (entry.name !== 'wasm' && entry.name !== 'assets') total += jsBytes(full); }
+ else if (/\.m?js$/.test(entry.name)) total += statSync(full).size;
+ }
+ return total;
+}
+
+const run = (root: string, out: string, bundleEngine: boolean) => exportGame({
+ root, entryScene: 'scenes/main.esscene', hostsDir: HOSTS, packagesDir: OFFICIAL_PACKAGES,
+ scriptsEntry: 'src/main.ts', sdkDistDir: SDK, wasmDir: path.join(root, '_wasm'),
+ outDir: out, platform: 'web', minifyScripts: true, bundleEngine,
+});
+
+describe.skipIf(!existsSync(path.join(SDK, 'index.lean.js')))('a web package built from the real SDK', () => {
+ it('bundles the SDK with the host and the scripts, and ships no copied tree', async () => {
+ const root = project();
+ const out = path.join(root, 'dist');
+ // The suite runs the copied tree by default; this is the one place that builds the bundled one.
+ const saved = process.env.ESTELLA_WEB_BUNDLE_ENGINE;
+ delete process.env.ESTELLA_WEB_BUNDLE_ENGINE;
+ let res;
+ try { res = await run(root, out, true); } finally {
+ if (saved !== undefined) process.env.ESTELLA_WEB_BUNDLE_ENGINE = saved;
+ }
+ expect(res.ok, res.errors.join('; ')).toBe(true);
+
+ expect(existsSync(path.join(out, 'sdk'))).toBe(false);
+ expect(existsSync(path.join(out, 'chunks'))).toBe(true);
+ const cfg = JSON.parse(readFileSync(path.join(out, 'game.config.json'), 'utf8'));
+ expect(cfg.scripts).toBe('scripts.js');
+
+ // Nothing is left for a page to resolve, and the host and the scripts import the SDK from the same chunks:
+ // two copies of the core would split every identity-keyed resource between them.
+ const html = readFileSync(path.join(out, 'index.html'), 'utf8');
+ expect(html).toContain('"imports":{}');
+ const game = readFileSync(path.join(out, 'game.js'), 'utf8');
+ const scripts = readFileSync(path.join(out, 'scripts.js'), 'utf8');
+ for (const text of [game, scripts]) expect(text).not.toMatch(/from\s*["']esengine/);
+ const chunkOf = (text: string) => new Set([...text.matchAll(/["']\.\/chunks\/([^"']+)["']/g)].map((m) => m[1]));
+ const shared = [...chunkOf(scripts)].filter((c) => chunkOf(game).has(c));
+ expect(shared.length, 'scripts.js and game.js import a chunk in common').toBeGreaterThan(0);
+ }, 120_000);
+
+ it('ships far less script than the copied tree for the same game', async () => {
+ const root = project();
+ const bundledOut = path.join(root, 'dist-bundled');
+ const copiedOut = path.join(root, 'dist-copied');
+ const saved = process.env.ESTELLA_WEB_BUNDLE_ENGINE;
+ delete process.env.ESTELLA_WEB_BUNDLE_ENGINE;
+ let bundled; let copied;
+ try {
+ bundled = await run(root, bundledOut, true);
+ copied = await run(root, copiedOut, false);
+ } finally {
+ if (saved !== undefined) process.env.ESTELLA_WEB_BUNDLE_ENGINE = saved;
+ }
+ expect(bundled.ok, bundled.errors.join('; ')).toBe(true);
+ expect(copied.ok, copied.errors.join('; ')).toBe(true);
+ expect(existsSync(path.join(copiedOut, 'sdk'))).toBe(true);
+ expect(jsBytes(bundledOut)).toBeLessThan(jsBytes(copiedOut) * 0.6);
+ }, 180_000);
+});
diff --git a/pipeline/vitest.config.ts b/pipeline/vitest.config.ts
index 0b38e6eb8..5b06f3156 100644
--- a/pipeline/vitest.config.ts
+++ b/pipeline/vitest.config.ts
@@ -18,5 +18,8 @@ export default defineConfig({
// The native AOT build needs a C compiler; a run without one must declare
// it rather than skip. See globalSetup.ts.
globalSetup: ['tests/globalSetup.ts'],
+ // The web export bundles the SDK it is given, and most of these tests hand it a stub tree that is not a bundle. They exercise the
+ // copied tree; the tree-shaken package is built from the real SDK in export-web-bundle.test.ts.
+ env: { ESTELLA_WEB_BUNDLE_ENGINE: '0' },
},
});
diff --git a/tools/check-headless-export.mjs b/tools/check-headless-export.mjs
index c4adb902a..e15d60afb 100644
--- a/tools/check-headless-export.mjs
+++ b/tools/check-headless-export.mjs
@@ -29,7 +29,7 @@ const PROJECT = path.join(ROOT, 'examples', 'hello-world');
const CLI = path.join(ROOT, 'pipeline', 'bin', 'estella.mjs');
/** What a web package has to carry to be one at all. */
-const EXPECTED = ['index.html', 'game.js', 'game.config.json', 'scripts.mjs', 'sdk', 'wasm', 'assets'];
+const EXPECTED = ['index.html', 'game.js', 'game.config.json', 'scripts.js', 'chunks', 'wasm', 'assets'];
const work = mkdtempSync(path.join(tmpdir(), 'estella-headless-'));
const out = path.join(work, 'package');
diff --git a/tools/check-script-failure.mjs b/tools/check-script-failure.mjs
index 5e722ab49..707224fc4 100644
--- a/tools/check-script-failure.mjs
+++ b/tools/check-script-failure.mjs
@@ -130,7 +130,7 @@ mkdirSync(WORK, { recursive: true });
{
const out = pack(project('sound'), 'sound');
const cfg = JSON.parse(readFileSync(path.join(out, 'game.config.json'), 'utf8'));
- check('a project with code declares it in the package', cfg.scripts === 'scripts.mjs',
+ check('a project with code declares it in the package', /^scripts\.m?js$/.test(cfg.scripts),
`scripts ${JSON.stringify(cfg.scripts)}`);
const run = boot(out);
const said = errorLines(run.text);