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(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.md
index 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`, lik
4.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 not
parse 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.ts
index 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.js
index 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/desktop
index 1214b4363..664420714 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 1214b4363749fb0a910442d65cad7e2275c48a51
+Subproject commit 6644207149d463795588e099cb0ef05772ca1933
diff --git a/docs/astro/src/content/docs/publishing/android-ios.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdx
index 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 on
is compiled to machine code as it would be in a browser, with nothing to change in
the project. On a Snapdragon 8 Elite phone, a frame of 5,000 scripted entities that
took 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 JIT
outside its own browser. A per-entity loop written in TypeScript is the one thing
that costs meaningfully more there than in a browser — prefer the engine's own
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 'nod
import { 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">');
+ });
+});