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(android): an APK deflates its native libraries — an empty project is 20 MB, not 54
yhh393ec6a53c70
diff --git a/bench/aot-native/README.md b/bench/aot-native/README.mdindex 9801c549f..cc7a715c2 100644--- a/bench/aot-native/README.md+++ b/bench/aot-native/README.md@@ -77,8 +77,9 @@ system properties there (`adb shell setprop debug.estella.bench_frames 300`, lik4.6x on the phone for a project that changes nothing. Those numbers are the nointl V8;the shipped one carries Intl (a game script with a Unicode property escape did notparse without it) and measures the same (14.32 / 4.78 ms). Its APK is 20.9 MB larger-than the QuickJS one (53.8 vs 32.9 MB): `libv8android.so` is 24.9 MB, stored-uncompressed.+than the QuickJS one (53.8 vs 32.9 MB) with its libraries stored. The APK now deflates+them by default (`compressNativeLibs`): the same empty project is 19.9 MB, and+ember-radio went from 105.8 to 71.9 MB.## What was measured (2026-08-27, i5-14600K, Windows, QuickJS-ng in the native host)diff --git a/build-tools/utils/apk.d.ts b/build-tools/utils/apk.d.tsindex 8a5fffdba..b663bfc18 100644--- a/build-tools/utils/apk.d.ts+++ b/build-tools/utils/apk.d.ts@@ -25,6 +25,8 @@ export function assembleApk(options: {icon?: Buffer;/** Also carry the emulator's x86_64 libraries. Default: phone ABIs only. */emulatorAbi?: boolean;+ /** Deflate the native libraries (extractNativeLibs=true). Default true; false stores them 16 KiB-aligned for in-place mapping. */+ compressNativeLibs?: boolean;/** Libraries the export built, by ABI (the project's compiled systems): packaged beside the template's own in `lib/<abi>/`. An ABI the package does not carry is ignored. */extraLibs?: Record<string, string[]>;}): Buffer;@@ -32,4 +34,6 @@ export function assembleApk(options: {export function signApkV2(zip: Buffer, key: SigningKey): Buffer;export function packageEntries(dir: string, prefix: string): Array<{ name: string; data: Buffer }>;export function apkFileName(appId: string): string;+/** The manifest's extractNativeLibs set to @p extract, whatever the template wrote. */+export function withExtractNativeLibs(manifestText: string, extract: boolean): string;export function extraLibEntries(extraLibs: Record<string, string[]> | undefined, abi: string, prefix: string): Array<{ name: string; data: Buffer }>;diff --git a/build-tools/utils/apk.js b/build-tools/utils/apk.jsindex 623925f71..356cc4421 100644--- a/build-tools/utils/apk.js+++ b/build-tools/utils/apk.js@@ -11,9 +11,13 @@// one button. Each has a written spec; each is implemented here, and each is// checked against an independent implementation in the tests.//-// Native libraries are STORED and 16 KiB-aligned, with extractNativeLibs=false:-// the OS maps them straight out of the package, which halves the install and is-// the posture Android 15's 16 KiB page size requires anyway.+// Native libraries are COMPRESSED by default, with extractNativeLibs=true: an APK+// is what a player downloads (a store, a link, a QQ group), and the engine's four+// libraries are 54 MB stored and 19 MB deflated. Android then unpacks them once at+// install. `compressNativeLibs: false` keeps the other posture — STORED and 16+// KiB-aligned with extractNativeLibs=false, mapped straight out of the package,+// which halves the installed footprint for a package whose download size does not+// matter. The App Bundle always stores: Google Play compresses what it delivers.import path from 'path';import { createHash, createPublicKey, sign as cryptoSign } from 'crypto';@@ -146,16 +150,33 @@ export function extraLibEntries(extraLibs, abi, prefix) {return (extraLibs?.[abi] ?? []).map((file) => ({ name: `${prefix}/${path.basename(file)}`, data: readFileSync(file) }));}+/**+ * The manifest's `extractNativeLibs`, set to what the package does with its+ * libraries: a compressed one MUST be extracted, or the loader finds nothing to+ * map and the app dies on launch. Written over the attribute itself, so a template+ * installed before the setting existed (it carries a literal "false") is right too.+ */+export function withExtractNativeLibs(manifestText, extract) {+ const value = extract ? 'true' : 'false';+ if (/android:extractNativeLibs="[^"]*"/.test(manifestText)) {+ return manifestText.replace(/android:extractNativeLibs="[^"]*"/, `android:extractNativeLibs="${value}"`);+ }+ return manifestText.replace(/<application\b/, `<application android:extractNativeLibs="${value}"`);+}+export function assembleApk(options) {const { templateDir, contentDir, app } = options;const dex = path.join(templateDir, 'classes.dex');const hasDex = existsSync(dex);const resources = appResources(options.icon ?? readFileSync(path.join(templateDir, DEFAULT_ICON)));+ const compress = options.compressNativeLibs !== false;- const manifest = compileManifest(fillTemplate(+ const manifest = compileManifest(withExtractNativeLibs(fillTemplate(readFileSync(path.join(templateDir, 'AndroidManifest.xml.in'), 'utf8'), {...androidManifestValues(app, { hasCode: hasDex }),- }), resources.references);+ }), compress), resources.references);+ // Deflated, or stored where the loader can map them in place (see the header).+ const lib = (e) => (compress ? e : { ...e, store: true, align: PAGE_ALIGNMENT });// The architectures a phone runs, and the emulator's too only when asked: the emulator// ABI is half of the package and no player's device can use it.@@ -169,12 +190,10 @@ export function assembleApk(options) {{ name: 'resources.arsc', data: resources.arsc, store: true, align: 4 },...resources.files,...(hasDex ? [{ name: 'classes.dex', data: readFileSync(dex) }] : []),- ...abis.flatMap((abi) => packageEntries(path.join(templateDir, 'lib', abi), `lib/${abi}`)- .map((e) => ({ ...e, store: true, align: PAGE_ALIGNMENT }))),+ ...abis.flatMap((abi) => packageEntries(path.join(templateDir, 'lib', abi), `lib/${abi}`).map(lib)),// What the export built for each ABI (the project's compiled systems), loaded- // by bare name from the same place, so stored and aligned the same way.- ...abis.flatMap((abi) => extraLibEntries(options.extraLibs, abi, `lib/${abi}`)- .map((e) => ({ ...e, store: true, align: PAGE_ALIGNMENT }))),+ // by bare name from the same place, so packed the same way.+ ...abis.flatMap((abi) => extraLibEntries(options.extraLibs, abi, `lib/${abi}`).map(lib)),// The template's assets (the SDK bytecode) first, so a project cannot// shadow them by accident and quietly change what the host boots....(existsSync(templateAssets) ? packageEntries(templateAssets, 'assets') : []),diff --git a/desktop b/desktopindex 1214b4363..664420714 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 1214b4363749fb0a910442d65cad7e2275c48a51+Subproject commit 6644207149d463795588e099cb0ef05772ca1933diff --git a/docs/astro/src/content/docs/publishing/android-ios.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdxindex 8ae917072..79176ce45 100644--- a/docs/astro/src/content/docs/publishing/android-ios.mdx+++ b/docs/astro/src/content/docs/publishing/android-ios.mdx@@ -270,11 +270,17 @@ The engine runs native at full speed everywhere. Your game script does too onis compiled to machine code as it would be in a browser, with nothing to change inthe project. On a Snapdragon 8 Elite phone, a frame of 5,000 scripted entities thattook 64 ms on the interpreter takes 14 ms on V8 (on a desktop CPU: 76 ms → 8 ms).-V8 adds about 21 MB to a package: `libv8android.so` per ABI, with the Unicode data-`Intl` and Unicode regular expressions (`/\p{L}/u`) need, stored uncompressed as-Android prefers for native libraries. Scripts see the same language a browser runs;+V8 is `libv8android.so` per ABI, with the Unicode data `Intl` and Unicode regular+expressions (`/\p{L}/u`) need, so scripts see the same language a browser runs;`TextEncoder` / `TextDecoder` are provided by the host.+**The APK deflates its native libraries** (Project Settings → Android → *Compress+native libraries*, on by default): an empty project downloads as about 20 MB rather+than 54, and Android unpacks the libraries once at install. Turn it off to store+them for the system to map in place — half the installed size, nearly three times+the download. The App Bundle always stores them; Google Play compresses what it+delivers.+On **iOS** your game script is interpreted, by QuickJS: Apple's rules allow no JIToutside its own browser. A per-entity loop written in TypeScript is the one thingthat costs meaningfully more there than in a browser — prefer the engine's owndiff --git a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdxindex 89da98308..24ce3cb15 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx@@ -226,9 +226,12 @@ Android 的下限是 29,因为引擎的字体路径调用 `AFontMatcher_create`,引擎在各平台都以原生全速运行。**Android** 上游戏脚本也一样:它跑在带 JIT 的 V8 上,和 Chrome 是同一个引擎——同一份脚本会像在浏览器里那样编译成机器码,项目里什么都不用改。在骁龙 8 Elite 手机上:5000 个脚本实体的一帧,解释器要 64 毫秒,V8 上是 14 毫秒-(桌面 CPU 上是 76 → 8 毫秒)。V8 让包体大约增加 21 MB:每个 ABI 一份 `libv8android.so`,-带上 `Intl` 与 Unicode 正则(`/\p{L}/u`)要用的 Unicode 数据,按 Android 对原生库的偏好不压缩存放。-脚本看到的是和浏览器一样的语言;`TextEncoder` / `TextDecoder` 由宿主提供。+(桌面 CPU 上是 76 → 8 毫秒)。V8 是每个 ABI 一份 `libv8android.so`,带上 `Intl` 与 Unicode 正则(`/\p{L}/u`)要用的+Unicode 数据,所以脚本看到的是和浏览器一样的语言;`TextEncoder` / `TextDecoder` 由宿主提供。++**APK 会压缩存放原生库**(项目设置 → Android → *压缩原生库*,默认开启):空项目下载约 20 MB+而不是 54 MB,安装时由 Android 解压一次。关闭则不压缩存放、由系统直接映射——安装后占用减半,+下载体积接近三倍。App Bundle 始终不压缩:Google Play 会自行压缩下发。**iOS** 上游戏脚本由 QuickJS 解释执行:Apple 不允许自家浏览器以外的 JIT。用 TypeScript 写的逐实体循环,是那里比浏览器里明显更贵的那一样东西——diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex 0b8e32f16..79f7d8301 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -553,6 +553,8 @@ export interface ExportGameOptions {androidAppBundle?: boolean;/** Android: also carry the emulator's x86_64 libraries. Absent ⇒ phone ABIs only. */androidEmulatorAbi?: boolean;+ /** Android: deflate the .apk's native libraries (extracted at install). Absent ⇒ true. */+ androidCompressNativeLibs?: boolean;/** A project-supplied mini-game export profile (`.esengine/platforms/<id>.mjs`),* for a platform the editor does not ship. Present ⇒ the mini-game pipeline* runs with it, whatever `platform` says. Loaded by the main process, which is@@ -1375,6 +1377,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>const assembly = {templateDir: template, contentDir: absOut, app: appConfig, key, icon,emulatorAbi: opts.androidEmulatorAbi === true,+ compressNativeLibs: opts.androidCompressNativeLibs !== false,...(androidAotLibs ? { extraLibs: androidAotLibs } : {}),};apkFile = path.join(absOut, apkFileName(appConfig.id));diff --git a/pipeline/src/export/projectExportOptions.ts b/pipeline/src/export/projectExportOptions.tsindex b1a37d0a5..9786572f2 100644--- a/pipeline/src/export/projectExportOptions.ts+++ b/pipeline/src/export/projectExportOptions.ts@@ -103,6 +103,7 @@ export async function projectExportOptions(androidVersionCode: plat?.android?.versionCode,androidAppBundle: plat?.android?.appBundle,androidEmulatorAbi: plat?.android?.emulatorAbi,+ androidCompressNativeLibs: plat?.android?.compressNativeLibs,androidOutput: plat?.android?.output,...(platform === 'android' && plat?.android?.releaseKey? { androidKey: () => androidReleaseKey(root, plat.android!.releaseKey!, secrets.androidKeyPassphrase) }diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.tsindex 3bae1a080..124615eb5 100644--- a/pipeline/src/project/format.ts+++ b/pipeline/src/project/format.ts@@ -317,6 +317,14 @@ export interface AndroidPackaging {* run them. Turn it on for a build you will install in an emulator.*/emulatorAbi?: boolean;+ /**+ * Deflate the native libraries inside the .apk (default true): 54 MB of engine+ * becomes ~19 MB to download, and Android unpacks it once at install. False+ * stores them and lets the OS map them from the package — half the installed+ * size, nearly three times the download. The .aab always stores; Google Play+ * compresses what it delivers.+ */+ compressNativeLibs?: boolean;/*** The release identity a shipping build is signed with: two PEM paths, relative* to the project or absolute. Keep the files out of the project's repository;@@ -1074,6 +1082,7 @@ export function parseManifest(raw: unknown): ProjectManifest {if (an.output === 'package' || an.output === 'project') a.output = an.output;if (typeof an.appBundle === 'boolean') a.appBundle = an.appBundle;if (typeof an.emulatorAbi === 'boolean') a.emulatorAbi = an.emulatorAbi;+ if (typeof an.compressNativeLibs === 'boolean') a.compressNativeLibs = an.compressNativeLibs;const key = an.releaseKey as Record<string, unknown> | undefined;if (key && typeof key.privateKey === 'string' && typeof key.certificate === 'string') {a.releaseKey = { privateKey: key.privateKey, certificate: key.certificate };diff --git a/pipeline/tests/apk-extra-libs.test.ts b/pipeline/tests/apk-extra-libs.test.tsindex 8876539c4..1dec0749d 100644--- a/pipeline/tests/apk-extra-libs.test.ts+++ b/pipeline/tests/apk-extra-libs.test.ts@@ -10,7 +10,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, copyFileSync, rmSync } from 'nodimport { tmpdir } from 'node:os';import path from 'node:path';import { fileURLToPath } from 'node:url';-import { assembleApk } from '../../build-tools/utils/apk.js';+import { assembleApk, withExtractNativeLibs } from '../../build-tools/utils/apk.js';import { readZip } from '../../build-tools/utils/zip.js';import { debugSigningKey } from '../../build-tools/utils/androidKeystore.js';import { ANDROID_AOT_LIBRARY } from '../src/export/androidAot';@@ -60,7 +60,7 @@ describe('an APK with compiled systems', () => {const apk = assembleApk({templateDir: template, contentDir: content,app: { id: 'com.example.aot', name: 'Aot', version: '1.0', versionCode: 1 } as never,- key: debugSigningKey(), emulatorAbi: true, extraLibs: built,+ key: debugSigningKey(), emulatorAbi: true, extraLibs: built, compressNativeLibs: false,});const entries = new Map(readZip(apk).map((e) => [e.name, e.data]));@@ -77,3 +77,46 @@ describe('an APK with compiled systems', () => {}});});++describe('how an APK packs its native libraries', () => {+ const build = (compressNativeLibs?: boolean) => {+ const dir = mkdtempSync(path.join(tmpdir(), 'estella-apk-libs-'));+ try {+ const template = path.join(dir, 'template');+ mkdirSync(path.join(template, 'lib', 'arm64-v8a'), { recursive: true });+ // Compressible like a real library, so deflate has something to win.+ writeFileSync(path.join(template, 'lib', 'arm64-v8a', 'libestella_js_host.so'), Buffer.alloc(64 * 1024, 7));+ copyFileSync(path.join(ROOT, 'native/android/host/AndroidManifest.xml.in'), path.join(template, 'AndroidManifest.xml.in'));+ copyFileSync(path.join(ROOT, 'native/icon.png'), path.join(template, 'icon.png'));+ const content = path.join(dir, 'content');+ mkdirSync(content, { recursive: true });+ writeFileSync(path.join(content, 'game.config.json'), '{}');+ return assembleApk({+ templateDir: template, contentDir: content,+ app: { id: 'com.example.libs', name: 'Libs', version: '1.0', versionCode: 1 } as never,+ key: debugSigningKey(), ...(compressNativeLibs === undefined ? {} : { compressNativeLibs }),+ });+ } finally {+ rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });+ }+ };++ it('deflates them by default — an APK is what a player downloads', () => {+ const apk = build();+ expect(layoutOf(apk).get('lib/arm64-v8a/libestella_js_host.so')?.method).toBe(8);+ });++ it('stores them page-aligned when asked, for the loader to map in place', () => {+ const at = layoutOf(build(false)).get('lib/arm64-v8a/libestella_js_host.so')!;+ expect(at.method).toBe(0);+ expect(at.dataAt % 16384).toBe(0);+ });++ it('tells the installer to extract exactly the libraries it compressed, whatever the template wrote', () => {+ const written = '<application android:hasCode="true" android:extractNativeLibs="false">';+ expect(withExtractNativeLibs(written, true)).toContain('android:extractNativeLibs="true"');+ expect(withExtractNativeLibs(written, false)).toContain('android:extractNativeLibs="false"');+ expect(withExtractNativeLibs('<application android:label="x">', true))+ .toContain('<application android:extractNativeLibs="true" android:label="x">');+ });+});