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(playable): a zip-delivery network gets its archive, measured as the upload

esenginecf9148131bed
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index f733b8b2c..b54484bb9 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -155,6 +155,9 @@ export interface ExportGameResult {
/** iOS: the generated `.xcodeproj`, for the editor to open. Absent when the
* engine is not built for iOS here (the export still carries its content). */
xcodeProject?: string;
+ /** Playable, zip-delivery networks: the archive written beside the HTML — the file
+ * the network takes an upload of. */
+ zipFile?: string;
}
/** The web host page. `orientation` pins the canvas to a screen orientation (rotate-
diff --git a/desktop/electron/exportPlayable.ts b/desktop/electron/exportPlayable.ts
index 6507e10af..19dc546a5 100644
--- a/desktop/electron/exportPlayable.ts
+++ b/desktop/electron/exportPlayable.ts
@@ -25,6 +25,7 @@ import type { OnExportProgress } from './exportProgress';
import { esengineAlias } from './esengineResolve';
import { orientationCss, orientationOverlayHtml, orientationLockScript, type ScreenOrientation } from './orientationHtml';
import { genericPlayableProfile, playableAdInjection, type PlayableAdProfile } from './playableAdProfile';
+import { makeZip } from './zipWriter';
import {
sceneUsesPhysics, detectSpineVersion, detectSpineVersionJson,
spineModuleId, SIDE_MODULE_FILE, type SpineVersion,
@@ -35,8 +36,13 @@ export interface ExportPlayableResult {
platform: 'playable';
outDir: string;
included: number;
- /** Final index.html size in bytes (for ad-network size limits). */
+ /** Size of the file that gets UPLOADED, which the network's limit applies to: the
+ * archive for a zip-delivery network, else index.html itself. */
bytes: number;
+ /** index.html on its own — the same as {@link bytes} unless a zip was written. */
+ htmlBytes: number;
+ /** The archive written for a zip-delivery network (absolute path). */
+ zipFile?: string;
warnings: string[];
errors: string[];
}
@@ -306,7 +312,21 @@ export async function exportPlayable(opts: {
await writeFile(outFile, indexHtml(title, globals, bundle, orientation, network));
await rm(cookDir, { recursive: true, force: true });
- const bytes = (await stat(outFile)).size;
+ const htmlBytes = (await stat(outFile)).size;
+
+ // 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
+ // to look at the thing.
+ let zipFile: string | undefined;
+ let bytes = htmlBytes;
+ if (adProfile.delivery === 'zip') {
+ progress({ phase: 'Archiving' });
+ zipFile = path.join(absOut, 'playable.zip');
+ await writeFile(zipFile, makeZip([{ name: 'index.html', data: await readFile(outFile) }]));
+ // The archive is the file being sent, so it is the one the limit applies to.
+ bytes = (await stat(zipFile)).size;
+ }
+
// A full WASM engine + assets routinely exceeds what a network accepts, and each
// network caps differently — say which cap and where it comes from, so this reads
// as a fact to check rather than a number to trust.
@@ -317,5 +337,8 @@ export async function exportPlayable(opts: {
}
if (adProfile.deliveryNote) warnings.push(adProfile.deliveryNote);
- return { ok: errors.length === 0, platform: 'playable', outDir: absOut, included: cook.included.length, bytes, warnings, errors };
+ return {
+ ok: errors.length === 0, platform: 'playable', outDir: absOut,
+ included: cook.included.length, bytes, htmlBytes, zipFile, warnings, errors,
+ };
}
diff --git a/desktop/electron/platformCatalog.ts b/desktop/electron/platformCatalog.ts
index 209105906..3478e549a 100644
--- a/desktop/electron/platformCatalog.ts
+++ b/desktop/electron/platformCatalog.ts
@@ -446,6 +446,9 @@ async function importPlatformModule(file: string): Promise<{ mod?: ProjectPlatfo
if (typeof candidate.limitNote !== 'string' || !candidate.limitNote) {
return { error: 'playable profile needs a `limitNote` saying where `maxBytes` comes from' };
}
+ if (candidate.delivery !== undefined && candidate.delivery !== 'single-html' && candidate.delivery !== 'zip') {
+ return { error: `\`delivery\` must be 'single-html' or 'zip' (got ${JSON.stringify(candidate.delivery)})` };
+ }
return { mod: candidate };
}
if (typeof candidate.emitConfigFiles !== 'function') return { error: 'profile has no `emitConfigFiles(ctx)`' };
@@ -542,11 +545,16 @@ export async function loadPlayableProfile(root: string | null, id: string | unde
for (const file of await projectPlatformFiles(root)) {
const { mod } = await importPlatformModule(file);
if (!mod || mod.kind !== 'playable' || mod.id !== id) continue;
+ // Field by field rather than a spread: this object crosses into the export as a
+ // profile, and a project module carrying stray keys (or a mini-game field) must
+ // not become part of one.
return {
id: mod.id,
label: mod.label,
maxBytes: mod.maxBytes as number,
limitNote: mod.limitNote as string,
+ delivery: mod.delivery,
+ deliveryNote: mod.deliveryNote,
emitHead: mod.emitHead,
emitBridge: mod.emitBridge,
};
diff --git a/desktop/electron/playableAdProfile.ts b/desktop/electron/playableAdProfile.ts
index 3e3e09a32..3450b69e0 100644
--- a/desktop/electron/playableAdProfile.ts
+++ b/desktop/electron/playableAdProfile.ts
@@ -37,11 +37,14 @@ export interface PlayableAdProfile {
* check it against the network's current docs rather than trusting us. */
readonly limitNote: string;
/**
- * Something the developer must still do by hand before this package can be
- * uploaded — Google takes a ZIP, and the export writes a bare index.html.
- * Reported as a warning, because an export that looks finished but is not
- * uploadable is worse than one that says so.
+ * What the network actually takes an upload of. `'zip'` also writes
+ * `playable.zip` beside the HTML — Google accepts only an archive — and is what
+ * the size limit is then measured against, since that is the file being sent.
+ * Default `'single-html'`.
*/
+ readonly delivery?: 'single-html' | 'zip';
+ /** Anything else the developer must know before uploading. Reported as a
+ * warning, because an export that looks finished but isn't is worse. */
readonly deliveryNote?: string;
/** Markup for `<head>`: an orientation meta tag, the network's own SDK script. */
emitHead?(ctx: PlayableAdContext): string;
@@ -95,7 +98,7 @@ export const googlePlayableProfile: PlayableAdProfile = {
label: 'Google Ads (App campaigns)',
maxBytes: 5 * 1024 * 1024,
limitNote: 'Google accepts a .ZIP up to 5MB',
- deliveryNote: 'Google uploads a .ZIP — compress this index.html before uploading.',
+ delivery: 'zip',
// The orientation meta tag is required alongside the exit API.
emitHead: (ctx) => '<script src="https://tpc.googlesyndication.com/pagead/gadgets/html5/api/exitapi.js"></script>\n'
+ ` <meta name="ad.orientation" content="${ctx.orientation}">`,
diff --git a/desktop/electron/zipWriter.ts b/desktop/electron/zipWriter.ts
new file mode 100644
index 000000000..42e1c76cd
--- /dev/null
+++ b/desktop/electron/zipWriter.ts
@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A minimal ZIP writer, for the ad networks that upload a ZIP rather than a
+ * bare HTML file (Google App campaigns).
+ *
+ * Written rather than depended on: what a playable needs is one deflated
+ * entry at the archive root, which is the simplest case the format has — no
+ * directories, no zip64, no encryption. A dependency for that would be more
+ * surface than the format.
+ *
+ * Deterministic by construction: entries carry a FIXED DOS timestamp, so the
+ * same input always produces byte-identical output. An export that changes
+ * only because the clock moved is an export you cannot diff.
+ */
+import { deflateRawSync } from 'node:zlib';
+
+export interface ZipEntry {
+ /** Path inside the archive. Networks want `index.html` at the root. */
+ name: string;
+ data: Buffer;
+}
+
+const CRC_TABLE = (() => {
+ const table = new Uint32Array(256);
+ for (let i = 0; i < 256; i++) {
+ let c = i;
+ for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+ table[i] = c >>> 0;
+ }
+ return table;
+})();
+
+function crc32(buf: Buffer): number {
+ let c = 0xffffffff;
+ for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+ return (c ^ 0xffffffff) >>> 0;
+}
+
+// 1980-01-01 00:00:00 in DOS date/time — the epoch of the format itself, and the
+// conventional stand-in for "no meaningful time" in reproducible archives.
+const DOS_TIME = 0;
+const DOS_DATE = 0x0021;
+
+/** Build a ZIP archive holding `entries`, each deflated at the archive root. */
+export function makeZip(entries: readonly ZipEntry[]): Buffer {
+ const locals: Buffer[] = [];
+ const centrals: Buffer[] = [];
+ let offset = 0;
+
+ for (const entry of entries) {
+ const name = Buffer.from(entry.name, 'utf8');
+ const compressed = deflateRawSync(entry.data, { level: 9 });
+ const crc = crc32(entry.data);
+
+ const local = Buffer.alloc(30);
+ local.writeUInt32LE(0x04034b50, 0);
+ local.writeUInt16LE(20, 4); // version needed
+ local.writeUInt16LE(0x0800, 6); // UTF-8 names
+ local.writeUInt16LE(8, 8); // deflate
+ local.writeUInt16LE(DOS_TIME, 10);
+ local.writeUInt16LE(DOS_DATE, 12);
+ local.writeUInt32LE(crc, 14);
+ local.writeUInt32LE(compressed.length, 18);
+ local.writeUInt32LE(entry.data.length, 22);
+ local.writeUInt16LE(name.length, 26);
+ local.writeUInt16LE(0, 28); // no extra field
+ locals.push(local, name, compressed);
+
+ const central = Buffer.alloc(46);
+ central.writeUInt32LE(0x02014b50, 0);
+ central.writeUInt16LE(20, 4); // version made by
+ central.writeUInt16LE(20, 6); // version needed
+ central.writeUInt16LE(0x0800, 8);
+ central.writeUInt16LE(8, 10);
+ central.writeUInt16LE(DOS_TIME, 12);
+ central.writeUInt16LE(DOS_DATE, 14);
+ central.writeUInt32LE(crc, 16);
+ central.writeUInt32LE(compressed.length, 20);
+ central.writeUInt32LE(entry.data.length, 24);
+ central.writeUInt16LE(name.length, 28);
+ central.writeUInt16LE(0, 30); // extra
+ central.writeUInt16LE(0, 32); // comment
+ central.writeUInt16LE(0, 34); // disk
+ central.writeUInt16LE(0, 36); // internal attrs
+ central.writeUInt32LE(0, 38); // external attrs
+ central.writeUInt32LE(offset, 42);
+ centrals.push(central, name);
+
+ offset += local.length + name.length + compressed.length;
+ }
+
+ const centralSize = centrals.reduce((n, b) => n + b.length, 0);
+ const end = Buffer.alloc(22);
+ end.writeUInt32LE(0x06054b50, 0);
+ end.writeUInt16LE(0, 4); // this disk
+ end.writeUInt16LE(0, 6); // disk with central dir
+ end.writeUInt16LE(entries.length, 8);
+ end.writeUInt16LE(entries.length, 10);
+ end.writeUInt32LE(centralSize, 12);
+ end.writeUInt32LE(offset, 16);
+ end.writeUInt16LE(0, 20); // no archive comment
+
+ return Buffer.concat([...locals, ...centrals, end]);
+}
diff --git a/desktop/src/components/BuildDialog.tsx b/desktop/src/components/BuildDialog.tsx
index 43bd66cc5..989719d29 100644
--- a/desktop/src/components/BuildDialog.tsx
+++ b/desktop/src/components/BuildDialog.tsx
@@ -45,8 +45,10 @@ interface Result {
ok: boolean;
outDir: string;
included: number;
- /** Final size in bytes (playable single-file export). */
+ /** Size of the file that gets uploaded (playable: the archive, else the HTML). */
bytes?: number;
+ /** The archive a zip-delivery ad network needs (playable). */
+ zipFile?: string;
warnings: string[];
errors: string[];
/** iOS: the .xcodeproj the export wrote around its content. */
@@ -735,7 +737,11 @@ export function BuildDialog() {
<CheckCircle2 size={14} /> {t('build.packagedSummary', { count: result.included, size: result.bytes ? ` · ${mb(result.bytes)}` : '', out: result.outDir })}
</span>
<div className="build__next selectable">
- {result.xcodeProject ? t('build.next.iosProject') : def.next(result.outDir)}
+ {result.xcodeProject
+ ? t('build.next.iosProject')
+ : result.zipFile
+ ? t('build.next.playableZip')
+ : def.next(result.outDir)}
</div>
{result.ok && (
<div className="build__actions">
diff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.ts
index eebc2cd1b..82ae6cb3b 100644
--- a/desktop/src/i18n/messages/project.ts
+++ b/desktop/src/i18n/messages/project.ts
@@ -126,6 +126,10 @@ export const projectMessages = defineMessages({
en: 'Open {out}/ in WeChat DevTools, then set your appid in project.config.json.',
zh: '在微信开发者工具中打开 {out}/,然后在 project.config.json 中设置 appid。',
},
+ 'build.next.playableZip': {
+ en: 'Upload playable.zip (this network takes an archive). Preview over http below — its real surface is an ad-network iframe.',
+ zh: '上传 playable.zip(该平台收的是归档包)。可在下方通过 http 预览——它的真实宿主是广告平台的 iframe。',
+ },
'build.next.playable': {
en: 'Preview over http below (its real surface is an ad-network iframe). Note: a full engine usually exceeds ad-network size limits.',
zh: '在下方通过 http 预览(其真实运行环境是广告网络的 iframe)。注意:完整引擎通常会超出广告网络的体积限制。',
diff --git a/desktop/tests/export-playable.test.ts b/desktop/tests/export-playable.test.ts
index 0f3318270..964950eab 100644
--- a/desktop/tests/export-playable.test.ts
+++ b/desktop/tests/export-playable.test.ts
@@ -12,6 +12,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
import { exportGame } from '../electron/exportGame';
const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -128,6 +129,36 @@ describe('exportGame (playable)', () => {
expect(res.warnings.join('\n')).toMatch(/over the 0\.0MB limit for Acme Ads \(Acme caps playables at 16 bytes\)/);
}, 60_000);
+ // A zip-delivery network gets an archive with index.html at the root, and the cap
+ // then applies to the ARCHIVE — the file actually being uploaded.
+ it('writes playable.zip for a zip-delivery network and measures that', async () => {
+ const o = path.join(root, 'dist-playable-zip');
+ const res = await exportGame({
+ root, entryScene: 'scenes/main.esscene', gameHostEntry: 'unused-for-playable',
+ playableHostEntry: PLAYABLE_HOST, scriptsEntry: 'src/main.ts',
+ sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'),
+ outDir: o, platform: 'playable',
+ playableAdProfile: {
+ id: 'zipnet', label: 'Zip Net', maxBytes: 5 * 1024 * 1024,
+ limitNote: 'Zip Net docs', delivery: 'zip',
+ },
+ });
+ expect(res.ok).toBe(true);
+
+ const zip = path.join(o, 'playable.zip');
+ expect(existsSync(zip)).toBe(true);
+ // The HTML stays: it is what "Preview over http" serves.
+ expect(existsSync(path.join(o, 'index.html'))).toBe(true);
+ expect(execFileSync('unzip', ['-t', zip], { encoding: 'utf8' })).toContain('No errors detected');
+ expect(execFileSync('unzip', ['-Z1', zip], { encoding: 'utf8' }).trim()).toBe('index.html');
+ // What the entry unpacks to IS the exported page, byte for byte.
+ const unpacked = execFileSync('unzip', ['-p', zip, 'index.html'], { encoding: 'utf8', maxBuffer: 1 << 26 });
+ expect(unpacked).toBe(readFileSync(path.join(o, 'index.html'), 'utf8'));
+ // `bytes` is the upload, not the page — they differ, and the compressed one is smaller.
+ expect(res.zipFile).toBe(zip);
+ expect(res.bytes).toBeLessThan(res.htmlBytes!);
+ }, 60_000);
+
it('injects nothing and keeps the default cap with no network selected', async () => {
const o = path.join(root, 'dist-playable-generic');
const res = await exportGame({
diff --git a/desktop/tests/platform-catalog.test.ts b/desktop/tests/platform-catalog.test.ts
index ad9d02878..9b204dfd1 100644
--- a/desktop/tests/platform-catalog.test.ts
+++ b/desktop/tests/platform-catalog.test.ts
@@ -332,7 +332,8 @@ describe('playable ad networks', () => {
.toContain('<script src="https://tpc.googlesyndication.com/pagead/gadgets/html5/api/exitapi.js"></script>');
expect(google.emitHead!({ title: 'T', orientation: 'portrait' })).toContain('content="portrait"');
expect(google.emitBridge!({ title: 'T', orientation: 'portrait' })).toContain('ExitApi.exit');
- expect(google.deliveryNote).toMatch(/ZIP/);
+ // Google takes an archive, and the export writes one for it.
+ expect(google.delivery).toBe('zip');
// The MRAID family clicks through with mraid.open() and needs nothing in head —
// the host webview injects mraid itself.
for (const id of ['mraid', 'unity', 'applovin']) {
@@ -346,6 +347,25 @@ describe('playable ad networks', () => {
expect(await loadPlayableProfile(root, 'nope')).toBeNull();
});
+ it('carries a project profile\'s zip delivery through to the export', async () => {
+ writePlatform('zipnet.mjs', `export default {
+ id: 'zipnet', kind: 'playable', label: 'Zip Net',
+ maxBytes: 5242880, limitNote: 'Zip Net docs', delivery: 'zip',
+ deliveryNote: 'name the archive after the campaign',
+ };`);
+ const profile = await loadPlayableProfile(root, 'zipnet');
+ expect(profile).toMatchObject({ delivery: 'zip', deliveryNote: 'name the archive after the campaign' });
+ });
+
+ it('rejects a delivery mode that is neither shape', async () => {
+ writePlatform('oddnet.mjs', `export default {
+ id: 'oddnet', kind: 'playable', label: 'Odd Net',
+ maxBytes: 1, limitNote: 'x', delivery: 'tarball',
+ };`);
+ const row = (await listPlayableNetworks(root)).find((r) => r.id === 'oddnet');
+ expect(row!.error).toMatch(/delivery/);
+ });
+
it('rejects a playable profile missing the facts the warning needs', async () => {
writePlatform('bad.mjs', "export default { id: 'bad', kind: 'playable', label: 'Bad' };");
const row = (await listPlayableNetworks(root)).find((r) => r.id === 'bad');
diff --git a/desktop/tests/zip-writer.test.ts b/desktop/tests/zip-writer.test.ts
new file mode 100644
index 000000000..4e07c0562
--- /dev/null
+++ b/desktop/tests/zip-writer.test.ts
@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The ZIP writer, checked against a REAL unzip rather than against a reader
+ * of our own — a hand-rolled archive that only our own code can open is worth
+ * nothing, since the thing that opens it for real is an ad network's pipeline.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { makeZip } from '../electron/zipWriter';
+
+let dir: string;
+/** `unzip` ships with macOS and most Linux; skip rather than fail where it doesn't. */
+let hasUnzip = true;
+
+beforeAll(() => {
+ dir = mkdtempSync(path.join(tmpdir(), 'es-zip-'));
+ try {
+ execFileSync('unzip', ['-v'], { stdio: 'ignore' });
+ } catch {
+ hasUnzip = false;
+ }
+});
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('makeZip', () => {
+ it('writes an archive a real unzip accepts, with the content intact', () => {
+ if (!hasUnzip) return;
+ // Repetitive enough that deflate must actually be exercised (a stored-only
+ // archive would pass a naive round-trip but not prove the deflate path).
+ const html = `<!doctype html><html><body>${'<span>playable</span>'.repeat(500)}</body></html>`;
+ const zip = makeZip([{ name: 'index.html', data: Buffer.from(html, 'utf8') }]);
+ const file = path.join(dir, 'playable.zip');
+ writeFileSync(file, zip);
+
+ // -t verifies every entry's CRC — the check that catches a malformed header.
+ expect(execFileSync('unzip', ['-t', file], { encoding: 'utf8' })).toContain('No errors detected');
+ // The entry must sit at the archive ROOT: networks look for index.html there.
+ expect(execFileSync('unzip', ['-Z1', file], { encoding: 'utf8' }).trim()).toBe('index.html');
+ expect(execFileSync('unzip', ['-p', file, 'index.html'], { encoding: 'utf8', maxBuffer: 1 << 24 })).toBe(html);
+ // Deflate actually happened.
+ expect(zip.length).toBeLessThan(html.length / 2);
+ });
+
+ it('is deterministic, so an export only changes when its content does', () => {
+ const data = Buffer.from('same bytes', 'utf8');
+ const a = makeZip([{ name: 'index.html', data }]);
+ const b = makeZip([{ name: 'index.html', data }]);
+ expect(a.equals(b)).toBe(true);
+ });
+
+ it('round-trips binary content and multiple entries', () => {
+ if (!hasUnzip) return;
+ const bin = Buffer.from(Array.from({ length: 1024 }, (_, i) => i & 0xff));
+ const zip = makeZip([
+ { name: 'index.html', data: Buffer.from('<html></html>', 'utf8') },
+ { name: 'payload.bin', data: bin },
+ ]);
+ const file = path.join(dir, 'multi.zip');
+ writeFileSync(file, zip);
+ expect(execFileSync('unzip', ['-t', file], { encoding: 'utf8' })).toContain('No errors detected');
+ execFileSync('unzip', ['-o', file, '-d', path.join(dir, 'out')], { stdio: 'ignore' });
+ expect(readFileSync(path.join(dir, 'out', 'payload.bin')).equals(bin)).toBe(true);
+ });
+});