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
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.tsindex 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>): Engireturn 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.mjsindex 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.mjsindex 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);