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(playable): a zip-delivery network gets its archive, measured as the upload
esenginecf9148131bed
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.tsindex 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.tsindex 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.tsindex 209105906..3478e549a 100644--- a/desktop/electron/platformCatalog.ts+++ b/desktop/electron/platformCatalog.ts@@ -446,6 +446,9 @@ async function importPlatformModule(file: string): Promise<{ mod?: ProjectPlatfoif (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 | undefor (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.tsindex 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.tsnew file mode 100644index 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.tsxindex 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.tsindex 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.tsindex 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, rmSyncimport { 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.tsindex 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.tsnew file mode 100644index 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);+ });+});