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.

perf(export): a playable ships its game deflated

esengine95190a524faa
diff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.ts
index 36d944089..c6f05cb55 100644
--- a/pipeline/src/export/exportPlayable.ts
+++ b/pipeline/src/export/exportPlayable.ts
@@ -8,7 +8,9 @@
* through instantiateWasm — so no separate single-file engine build;
* - assets as base64 data URLs + scenes inlined as <script> globals
* (keyed by the scene's @uuid: refs — EmbeddedAssetProvider resolves them);
- * - the playable host + esengine + project scripts esbuilt to ONE IIFE;
+ * - the playable host + esengine + project scripts esbuilt to ONE IIFE,
+ * deflated like the engine's own payloads and started by a small loader
+ * script — it is the page's largest span, and a 2MB cap is spent on it;
* - whatever the chosen ad network's profile injects (playableAdProfile.ts).
* Boots the SAME shipping runtime via initPlayableRuntime (play == ship).
*
@@ -91,6 +93,13 @@ function pack(bytes: Uint8Array | Buffer): PackedBytes {
return { z: deflateRawSync(bytes, { level: 9 }).toString('base64'), n: bytes.length };
}
+/** The loader lives beside the host it starts. One option names where the
+ * runtime's sources are, so a second way of finding them is a second thing to
+ * keep in step with a move. */
+function loaderEntryFor(hostEntry: string): string {
+ return path.join(path.dirname(hostEntry), `playableLoader${path.extname(hostEntry)}`);
+}
+
/**
* The playable page. Deliberately WITHOUT the web export's rotate-to-fit overlay:
* inside an ad SDK the container's size is the SDK's business, so `@media
@@ -111,7 +120,7 @@ function pack(bytes: Uint8Array | Buffer): PackedBytes {
function indexHtml(
title: string,
globals: string,
- bundle: string,
+ loader: string,
network: { head: string; bridge: string },
): string {
return `<!doctype html>
@@ -129,7 +138,7 @@ function indexHtml(
<body>
<canvas id="canvas"></canvas>${network.bridge ? `\n <script>${inlineSafe(network.bridge)}</script>` : ''}
<script>${inlineSafe(globals)}</script>
- <script>${inlineSafe(bundle)}</script>
+ <script>${inlineSafe(loader)}</script>
</body>
</html>
`;
@@ -280,6 +289,7 @@ export async function exportPlayable(opts: {
(scriptsAbs && existsSync(scriptsAbs) ? `import ${JSON.stringify(scriptsAbs)};\n` : '') +
`import ${JSON.stringify(opts.playableHostEntry)};\n`;
let bundle = '';
+ let loader = '';
try {
const { build } = await loadEsbuild();
const res = await build({
@@ -298,6 +308,21 @@ export async function exportPlayable(opts: {
});
errors.push(...explainBundleErrors(res.errors));
bundle = res.outputFiles?.[0]?.text ?? '';
+ // Built apart from the game, because it is the one script the page can still
+ // read: a loader inside the payload it inflates could never start it.
+ const loaded = await build({
+ entryPoints: [loaderEntryFor(opts.playableHostEntry)],
+ bundle: true,
+ format: 'iife',
+ platform: 'browser',
+ target: 'es2020',
+ minify: opts.minify ?? true,
+ write: false,
+ outfile: 'game-loader.js',
+ logLevel: 'silent',
+ });
+ errors.push(...explainBundleErrors(loaded.errors));
+ loader = loaded.outputFiles?.[0]?.text ?? '';
} catch (err) {
const e = err as { errors?: BundleMessage[]; message?: string };
errors.push(...(e.errors ? explainBundleErrors(e.errors) : [String(e.message ?? err)]));
@@ -347,12 +372,15 @@ export async function exportPlayable(opts: {
// agree on five names, and a sixth setting simply never got a global.
// A playable is one file on an ad network's page: it takes the GL context
// its host hands over, so a WebGPU request has nowhere to land.
- `window.__GAME_RUNTIME__=${JSON.stringify(playableRuntimeFields(opts.runtime ?? DEFAULT_RUNTIME_CONFIG))};`;
+ `window.__GAME_RUNTIME__=${JSON.stringify(playableRuntimeFields(opts.runtime ?? DEFAULT_RUNTIME_CONFIG))};` +
+ // Last of the globals: the loader script that follows them inflates this one
+ // and hands it to the page.
+ span('game-bundle.js', `window.__GAME_BUNDLE__=${JSON.stringify(pack(Buffer.from(bundle, 'utf8')))};`);
const adProfile = opts.adProfile ?? genericPlayableProfile;
const network = playableAdInjection(adProfile, { title, orientation });
const outFile = path.join(absOut, 'index.html');
- span('game-bundle.js', bundle);
- await writeFile(outFile, indexHtml(title, globals, bundle, network));
+ span('game-loader.js', loader);
+ await writeFile(outFile, indexHtml(title, globals, loader, network));
await rm(cookDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
const htmlBytes = (await stat(outFile)).size;
diff --git a/pipeline/src/runtime/playableLoader.ts b/pipeline/src/runtime/playableLoader.ts
new file mode 100644
index 000000000..d087dbf99
--- /dev/null
+++ b/pipeline/src/runtime/playableLoader.ts
@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file playableLoader.ts — inflate the game bundle, then run it.
+ *
+ * The engine's glue and its wasm travel deflated; the game's own bundle is the
+ * largest span in the page and travelled as source, which on a 2MB cap is the
+ * difference between fitting and not. It arrives as `__GAME_BUNDLE__` and runs
+ * from the same blob script the engine module already needs, so a page that can
+ * boot a playable at all can boot this one — no eval, nothing new to allow.
+ */
+import { inflateRaw } from './inflate';
+
+interface PackedBytes { z: string; n: number }
+declare const __GAME_BUNDLE__: PackedBytes;
+
+const packed = atob(__GAME_BUNDLE__.z);
+const bytes = new Uint8Array(packed.length);
+for (let i = 0; i < packed.length; i++) bytes[i] = packed.charCodeAt(i);
+
+const script = document.createElement('script');
+script.src = URL.createObjectURL(new Blob(
+ [new TextDecoder().decode(inflateRaw(bytes, __GAME_BUNDLE__.n))],
+ { type: 'text/javascript' },
+));
+document.body.appendChild(script);
diff --git a/pipeline/tests/export-playable.test.ts b/pipeline/tests/export-playable.test.ts
index aaa272353..96a8d0f12 100644
--- a/pipeline/tests/export-playable.test.ts
+++ b/pipeline/tests/export-playable.test.ts
@@ -116,8 +116,17 @@ describe('exportGame (playable)', () => {
expect(inlinedText(html, '__ENGINE_GLUE__')).toContain('WEB_GLUE'); // web glue text inlined
expect(html).toContain('__ENGINE_GLUE__'); // glue + wasm inlined as globals
expect(html).toContain('__ENGINE_WASM__');
- expect(html).toContain('createObjectURL'); // real host bundled (blob loader)
- expect(html).toContain('SpawnMarker'); // project script bundled
+ // Through the decoder, both of them: the game travels deflated now, so the
+ // page's own text would answer for the loader and not for what it starts.
+ expect(inlinedText(html, '__GAME_BUNDLE__')).toContain('createObjectURL'); // real host bundled
+ expect(inlinedText(html, '__GAME_BUNDLE__')).toContain('SpawnMarker'); // project script bundled
+ // And it travels deflated. Inlining the source again would satisfy every
+ // assertion above — this is the one that would notice, and the 2MB cap is
+ // spent on this span more than on any other.
+ const game = inlinedText(html, '__GAME_BUNDLE__');
+ expect(html).not.toContain(game.slice(0, 200));
+ expect(res.inlineParts?.find((p) => p.path === 'game-bundle.js')?.bytes ?? 0)
+ .toBeLessThan(game.length);
expect(html).toContain(`@uuid:${TEX}`); // asset keyed by ref
expect(html).toContain('data:image/png;base64,'); // asset inlined as data URL
// Logical path → embedded key map (path refs alias in memory at runtime;