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.

fix(export): a playable's one file is the build, not a copy of it

esenginea94cc17f809a
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 4995c4613..678663fbe 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -236,6 +236,8 @@ export interface ExportGameResult {
/** Playable, zip-delivery networks: the archive written beside the HTML — the file
* the network takes an upload of. */
zipFile?: string;
+ /** Playable: what the single file is made of. See ExportPlayableResult. */
+ inlineParts?: { path: string; bytes: number }[];
/** What the package weighs, and how it fared against the limits in force.
* Absent when the export failed, or when measuring itself did. */
size?: BuildSizeReport;
@@ -467,6 +469,7 @@ async function attachSizeReport(result: ExportGameResult, opts: ExportGameOption
projectMaxBytes: opts.sizeBudgetBytes,
deliverable,
packages,
+ inlineOf: result.inlineParts ? { file: 'index.html', parts: result.inlineParts } : undefined,
});
return { ...result, size };
} catch {
diff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.ts
index 2a08eba19..502d37958 100644
--- a/pipeline/src/export/exportPlayable.ts
+++ b/pipeline/src/export/exportPlayable.ts
@@ -44,6 +44,14 @@ export interface ExportPlayableResult {
htmlBytes: number;
/** The archive written for a zip-delivery network (absolute path). */
zipFile?: string;
+ /**
+ * What the single file is MADE OF, each span under the path those bytes would
+ * carry if this target shipped them loose. Sums to {@link htmlBytes}.
+ *
+ * Without it the size report can only say the build is one `index.html` of
+ * n bytes — true, and useless on the one target where size is a hard cap.
+ */
+ inlineParts: { path: string; bytes: number }[];
warnings: string[];
errors: string[];
}
@@ -188,6 +196,13 @@ export async function exportPlayable(opts: {
const errors: string[] = [];
await mkdir(absOut, { recursive: true });
const cookDir = path.join(absOut, '.playable-cook');
+ // What each span of the finished file costs, under the path those bytes would
+ // carry if this target shipped them loose — so a playable's composition reads
+ // in the same vocabulary as the web and WeChat ones, rather than being one
+ // opaque file. Filled where the bytes are JOINED: a reader that parsed the
+ // finished HTML back apart would be a second account of the same
+ // concatenation, and the one that drifts.
+ const spans: { path: string; bytes: number }[] = [];
// 1. Cook reachable assets to a temp dir (everything ends up inlined → removed after).
progress({ phase: 'Cooking assets' });
@@ -219,6 +234,9 @@ export async function exportPlayable(opts: {
const key = `@uuid:${e.uuid}`;
assets[key] = `data:${mimeOf(e.path)};base64,${buf.toString('base64')}`;
pathMap[e.sourcePath ?? e.path] = key;
+ // The data URL, not the file: base64 is what this asset actually costs the
+ // package, and the +33% is the thing a developer is being asked to see.
+ spans.push({ path: e.path, bytes: assets[key].length });
}
} catch (err) {
errors.push(`assets: ${err instanceof Error ? err.message : String(err)}`);
@@ -291,13 +309,17 @@ export async function exportPlayable(opts: {
// 6. Assemble the single HTML, then drop the temp cook dir.
progress({ phase: 'Assembling HTML' });
+ const span = (p: string, text: string): string => {
+ spans.push({ path: p, bytes: Buffer.byteLength(text, 'utf8') });
+ return text;
+ };
const globals =
- `window.__ENGINE_GLUE__=${JSON.stringify(glue)};` +
- `window.__ENGINE_WASM__=${JSON.stringify(wasmB64)};` +
- `window.__SIDE_MODULES__=${JSON.stringify(sideModules)};` +
+ span('wasm/esengine.js', `window.__ENGINE_GLUE__=${JSON.stringify(glue)};`) +
+ span('wasm/esengine.wasm', `window.__ENGINE_WASM__=${JSON.stringify(wasmB64)};`) +
+ span('wasm/side-modules', `window.__SIDE_MODULES__=${JSON.stringify(sideModules)};`) +
`window.__GAME_ASSETS__=${JSON.stringify(assets)};` +
`window.__GAME_PATHMAP__=${JSON.stringify(pathMap)};` +
- `window.__GAME_SCENES__=${JSON.stringify(scenes)};` +
+ span(`scenes/${sceneName}.json`, `window.__GAME_SCENES__=${JSON.stringify(scenes)};`) +
`window.__GAME_FIRST__=${JSON.stringify(sceneName)};` +
// ONE global for the project's settings, in the same shape game.config.json
// carries them. Five separate globals meant the host and the export had to
@@ -308,10 +330,16 @@ export async function exportPlayable(opts: {
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));
await rm(cookDir, { recursive: true, force: true });
const htmlBytes = (await stat(outFile)).size;
+ // The page itself, plus the JSON scaffolding around the spans above (each
+ // asset's key and quotes, the small globals). Derived rather than summed so
+ // the parts always add up to the file, whatever else the assembly gains.
+ const inlined = spans.reduce((n, s) => n + s.bytes, 0);
+ spans.push({ path: 'index.html', bytes: Math.max(0, htmlBytes - inlined) });
// A network that uploads an archive gets one, with index.html at the root. The HTML
// stays beside it: it is what "Preview over http" serves, and what a developer opens
@@ -336,6 +364,6 @@ export async function exportPlayable(opts: {
return {
ok: errors.length === 0, platform: 'playable', outDir: absOut,
- included: cook.included.length, bytes, htmlBytes, zipFile, warnings, errors,
+ included: cook.included.length, bytes, htmlBytes, zipFile, inlineParts: spans, warnings, errors,
};
}
diff --git a/pipeline/src/export/sizeReport.ts b/pipeline/src/export/sizeReport.ts
index faf7721e4..9f420924d 100644
--- a/pipeline/src/export/sizeReport.ts
+++ b/pipeline/src/export/sizeReport.ts
@@ -274,7 +274,15 @@ export async function measureBuild(opts: {
profileBudgets?: readonly SizeBudget[];
/** `packaging.sizeBudget[platform]`, in bytes. */
projectMaxBytes?: number;
- /** Absolute path to the single uploaded file, when the target makes one. */
+ /**
+ * Absolute path to the single uploaded file, when the target makes one.
+ *
+ * Weighed on its own; it does NOT exclude itself from the directory totals.
+ * A deliverable that repackages loose files is already in {@link packages},
+ * and the playable's is not a repackaging at all — its `index.html` IS the
+ * build, so excluding it left the composition of the one target where size is
+ * a hard cap reading as an empty directory.
+ */
deliverable?: string;
/**
* Absolute paths to packages written INSIDE `root` — the .apk, the .aab, the
@@ -284,11 +292,26 @@ export async function measureBuild(opts: {
* counting both would double every byte and report a build at twice its
* weight. They are measured on their own (as the deliverable) and left out of
* the directory totals.
+ *
+ * This is the ONLY thing that excludes a file, so a caller that writes a new
+ * kind of package has to name it here — which is the question being asked
+ * ("does this repackage what is already there?"), rather than a proxy for it.
*/
packages?: readonly string[];
+ /**
+ * A single-file target's file, and what it is made of — each span under the
+ * path those bytes would carry loose. The file is replaced by its spans, so a
+ * playable is composed in the same vocabulary as every other target instead of
+ * weighing in as one nameless `other`.
+ *
+ * The producer supplies these, because the assembly is where the bytes are
+ * joined and it already knows; parsing the finished file back apart would be a
+ * second account of the same concatenation.
+ */
+ inlineOf?: { file: string; parts: readonly { path: string; bytes: number }[] };
}): Promise<BuildSizeReport> {
const excluded: string[] = [];
- for (const file of [...(opts.packages ?? []), ...(opts.deliverable ? [opts.deliverable] : [])]) {
+ for (const file of opts.packages ?? []) {
const rel = path.relative(opts.root, file);
// path-sandbox: not a boundary — classifying which built files a report counts.
if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) excluded.push(normalizeRel(rel));
@@ -297,7 +320,10 @@ export async function measureBuild(opts: {
// is the assembled app DIRECTORY, and excluding only its own name would leave
// every byte inside it counted a second time.
const files = (await collectBuildFiles(opts.root))
- .filter((f) => !isUnder(normalizeRel(f.path), excluded));
+ .filter((f) => !isUnder(normalizeRel(f.path), excluded))
+ .flatMap((f) => (opts.inlineOf && normalizeRel(f.path) === normalizeRel(opts.inlineOf.file)
+ ? [...opts.inlineOf.parts]
+ : [f]));
let manifest: unknown = null;
try {
manifest = JSON.parse(await readFile(path.join(opts.root, 'asset-manifest.json'), 'utf8'));
diff --git a/pipeline/tests/size-report.test.ts b/pipeline/tests/size-report.test.ts
index 7ca286ad7..8a8635845 100644
--- a/pipeline/tests/size-report.test.ts
+++ b/pipeline/tests/size-report.test.ts
@@ -242,6 +242,26 @@ describe('measuring a build on disk', () => {
expect(report.deliverableBytes).toBe(5020); // everything inside the app
});
+ it('still weighs the single file a playable ships, which is the build rather than a copy of it', async () => {
+ // The playable's whole output is one index.html — nothing sits loose beside
+ // it to double-count, so the repackaging rule that covers an .apk does not
+ // apply. Excluding it left byKind, largest and fileCount empty on the ONE
+ // target whose size is a hard cap, so the export could say "over by 64%" and
+ // not one byte of where it went. Note there is no `packages` here: that is
+ // the shape, and it is what the two cases above never exercise.
+ await write('index.html', 3_444_304);
+ const report = await measureBuild({
+ root: dir,
+ platform: 'playable',
+ deliverable: path.join(dir, 'index.html'),
+ });
+ expect(report.fileCount).toBe(1);
+ expect(report.packageBytes).toBe(3_444_304);
+ expect(report.byKind).toEqual([{ kind: 'other', bytes: 3_444_304, count: 1 }]);
+ expect(report.largest[0]?.path).toBe('index.html');
+ expect(report.deliverableBytes).toBe(3_444_304); // and still weighed as the upload
+ });
+
it('reads the manifest the export wrote, so buckets agree with the runtime', async () => {
await write('asset-manifest.json', 0);
await writeFile(path.join(dir, 'asset-manifest.json'), JSON.stringify(MANIFEST));