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.

perf(android): a package carries the phone ABI, and the template strips libc++

yhhe444ce618f69
diff --git a/.github/workflows/android-canary-apk.yml b/.github/workflows/android-canary-apk.yml
index 256b4881f..f97ff302c 100644
--- a/.github/workflows/android-canary-apk.yml
+++ b/.github/workflows/android-canary-apk.yml
@@ -124,7 +124,7 @@ jobs:
[ -z "$name" ] && continue
echo "::group::packaging $name"
node pipeline/bin/estella.mjs export "examples/$name" \
- --platform android --template template \
+ --platform android --template template --emulator-abi \
--out "build/pkg/$name" --json "build/pkg/$name.json"
APK=$(node -e "process.stdout.write(require('./build/pkg/$name.json').apkFile || '')")
if [ -z "$APK" ]; then
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 54a11cfb8..227d23a2e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,7 @@ published separately; it ships inside the editor.
- **One rule picks the environment light.** The frame, the bake in the editor and the command-line bake each chose their own; the two bakes took the first light naming an environment whether or not it was enabled, hidden or lit. They now take what the frame takes, so a scene whose first environment light is switched off bakes against the next one.
- **UASTC textures ship under zstd.** Cooked and cached UASTC textures are supercompressed: 59% fewer bytes over a sample of 24 ORCA Bistro textures, 47% over 256-pixel crops of them, with identical decoded pixels. Existing cook caches are encoded again once.
+- **An Android package carries the phone ABI only.** An empty APK was 75.9 MB, half of it the emulator's x86_64 libraries no phone can run. Packages now carry `arm64-v8a`; tick *Include the emulator (x86_64)* in the Android settings, or pass `--emulator-abi`, for a build to install in an emulator. The same choice applies to the App Bundle. The template's `libc++_shared.so` is stripped like the other two libraries (9.2 MB to 1.3 MB per ABI) from the next published template; an empty arm64 package measured 38.3 MB with the current one.
### Fixed
diff --git a/build-tools/utils/aab.d.ts b/build-tools/utils/aab.d.ts
index 6d6e25b1c..98a7c90f3 100644
--- a/build-tools/utils/aab.d.ts
+++ b/build-tools/utils/aab.d.ts
@@ -14,6 +14,8 @@ export function assembleAab(options: {
contentDir: string;
app: ApkAppIdentity;
key: SigningKey;
+ /** Also carry the emulator's x86_64 libraries. Default: phone ABIs only. */
+ emulatorAbi?: boolean;
}): Buffer;
export function aabFileName(appId: string): string;
diff --git a/build-tools/utils/aab.js b/build-tools/utils/aab.js
index 94b218ab0..f68640c09 100644
--- a/build-tools/utils/aab.js
+++ b/build-tools/utils/aab.js
@@ -23,7 +23,7 @@ import { packageEntries } from './apk.js';
import { message, bytesField } from './protobuf.js';
import { compileProtoManifest } from './androidProtoXml.js';
import { appResources } from './androidResources.js';
-import { DEFAULT_ICON, templateAbis } from './nativeTemplate.js';
+import { DEFAULT_ICON, packageAbis, noPackageAbisMessage } from './nativeTemplate.js';
import { jarSignatureFiles } from './jarSign.js';
import { fillTemplate, androidManifestValues } from './nativeApp.js';
@@ -57,10 +57,10 @@ export function assembleAab(options) {
...androidManifestValues(app, { hasCode: hasDex }),
}), resources.references);
- // Every architecture: Play splits the bundle per device, which is what the
- // format is for.
- const abis = templateAbis(templateDir);
- if (abis.length === 0) throw new Error('The runtime template carries no native libraries.');
+ // Play splits the bundle per device, so this is about what is uploaded, not what a player
+ // downloads: the same device ABIs as the APK, and the emulator's only when asked.
+ const abis = packageAbis(templateDir, { emulator: options.emulatorAbi });
+ if (abis.length === 0) throw new Error(noPackageAbisMessage(templateDir, { emulator: options.emulatorAbi }));
const templateAssets = path.join(templateDir, 'assets');
const entries = [
diff --git a/build-tools/utils/apk.d.ts b/build-tools/utils/apk.d.ts
index 164e07e61..dba4818a1 100644
--- a/build-tools/utils/apk.d.ts
+++ b/build-tools/utils/apk.d.ts
@@ -23,6 +23,8 @@ export function assembleApk(options: {
key: SigningKey;
/** The launcher icon; the template's default when absent. */
icon?: Buffer;
+ /** Also carry the emulator's x86_64 libraries. Default: phone ABIs only. */
+ emulatorAbi?: boolean;
}): Buffer;
export function signApkV2(zip: Buffer, key: SigningKey): Buffer;
diff --git a/build-tools/utils/apk.js b/build-tools/utils/apk.js
index 427825902..c83717f5e 100644
--- a/build-tools/utils/apk.js
+++ b/build-tools/utils/apk.js
@@ -21,7 +21,7 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
import { makeZip, zipLayout } from './zip.js';
import { compileManifest } from './androidBinaryXml.js';
import { appResources } from './androidResources.js';
-import { DEFAULT_ICON, templateAbis } from './nativeTemplate.js';
+import { DEFAULT_ICON, packageAbis, noPackageAbisMessage } from './nativeTemplate.js';
import { fillTemplate, androidManifestValues } from './nativeApp.js';
/** The boundary a mapped `.so` must start on — a 16 KiB page, which every
@@ -152,10 +152,10 @@ export function assembleApk(options) {
...androidManifestValues(app, { hasCode: hasDex }),
}), resources.references);
- // Every architecture the template carries, so one package installs on a phone
- // and in an emulator alike — the device picks the one it can run.
- const abis = templateAbis(templateDir);
- if (abis.length === 0) throw new Error('The runtime template carries no native libraries.');
+ // 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.
+ const abis = packageAbis(templateDir, { emulator: options.emulatorAbi });
+ if (abis.length === 0) throw new Error(noPackageAbisMessage(templateDir, { emulator: options.emulatorAbi }));
const templateAssets = path.join(templateDir, 'assets');
const entries = [
diff --git a/build-tools/utils/nativeTemplate.d.ts b/build-tools/utils/nativeTemplate.d.ts
index 634078b14..aba8b1180 100644
--- a/build-tools/utils/nativeTemplate.d.ts
+++ b/build-tools/utils/nativeTemplate.d.ts
@@ -48,6 +48,8 @@ export const TEMPLATE_FORMAT: number;
export const TEMPLATE_MANIFEST: string;
export const BYTECODE_FILE: string;
export const ANDROID_ABIS: readonly string[];
+/** The ABIs a phone can run; a package carries only these unless asked for the emulator's. */
+export const ANDROID_DEVICE_ABIS: readonly string[];
export function templateId(platform: TemplatePlatform): TemplatePlatform;
@@ -56,6 +58,10 @@ export function templateId(platform: TemplatePlatform): TemplatePlatform;
export const TEMPLATE_PLATFORMS: readonly TemplatePlatform[];
export function isTemplatePlatform(platform: unknown): platform is TemplatePlatform;
export function templateAbis(dir: string): string[];
+/** The ABIs one package carries: the device ABIs, and the emulator's when `emulator` is set. */
+export function packageAbis(dir: string, options?: { emulator?: boolean }): string[];
+/** Why a template has nothing to package under the ABI choice made. */
+export function noPackageAbisMessage(dir: string, options?: { emulator?: boolean }): string;
export interface TemplateEntry {
/** Path inside the template. */
rel: string;
diff --git a/build-tools/utils/nativeTemplate.js b/build-tools/utils/nativeTemplate.js
index 54b3881b0..01ec03f62 100644
--- a/build-tools/utils/nativeTemplate.js
+++ b/build-tools/utils/nativeTemplate.js
@@ -110,6 +110,13 @@ export function isTemplatePlatform(platform) {
*/
export const ANDROID_ABIS = ['arm64-v8a', 'x86_64'];
+/**
+ * The ABIs a phone can run. A package carries only these unless it is asked for the
+ * emulator's too: x86_64 is the other half of the engine's size, and no player's device
+ * can use it.
+ */
+export const ANDROID_DEVICE_ABIS = ['arm64-v8a'];
+
/**
* What a template holds, per platform.
*
@@ -202,7 +209,9 @@ export function templateLayout(platform, options = {}) {
from: (ctx) => ctx.dawnLibrary?.(abi),
},
{
- rel: `lib/${abi}/libc++_shared.so`, abi, optional: n > 0, releaseRequired: true,
+ // Stripped like the two above: the NDK's own copy carries 7.5 MB of debug
+ // info per ABI, which is 8 of the 9.2 MB it weighs.
+ rel: `lib/${abi}/libc++_shared.so`, strip: true, abi, optional: n > 0, releaseRequired: true,
from: (ctx) => ctx.libcxxShared?.(abi),
},
]);
@@ -282,6 +291,27 @@ export function templateAbis(dir) {
return ANDROID_ABIS.filter((abi) => existsSync(path.join(dir, 'lib', abi, 'libestella_js_host.so')));
}
+/**
+ * The ABIs one package carries: the template's device ABIs, and the emulator's as well
+ * when `emulator` asks. Empty when the template has none of what was asked for, which the
+ * assembler reports by name rather than writing an app that installs on nothing.
+ *
+ * @param {string} dir An installed android template.
+ * @param {{emulator?: boolean}} [options]
+ */
+export function packageAbis(dir, options = {}) {
+ return templateAbis(dir).filter((abi) => options.emulator || ANDROID_DEVICE_ABIS.includes(abi));
+}
+
+/** The message for a template that has nothing to package under the ABI choice made. */
+export function noPackageAbisMessage(dir, options = {}) {
+ const has = templateAbis(dir);
+ if (has.length === 0) return 'The runtime template carries no native libraries.';
+ return `The runtime template carries only ${has.join(', ')}, and ${options.emulator ? 'none of it' : 'no device ABI'} `
+ + 'can be packaged. Install a template that includes arm64-v8a'
+ + `${options.emulator ? '' : ', or ask for the emulator ABI (emulatorAbi / --emulator-abi) to package an emulator-only template'}.`;
+}
+
/** What a template is missing, if anything — the one readiness test. */
export function missingTemplateFiles(dir, platform, options) {
return requiredTemplateFiles(platform, options).filter((rel) => !existsSync(path.join(dir, rel)));
diff --git a/desktop b/desktop
index 7e51dcad6..47d797d1d 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 7e51dcad6217b202be3a056ee90c20696612687e
+Subproject commit 47d797d1d96ac0b2b7a2d541cd712b5a1c26f44f
diff --git a/docs/astro/src/content/docs/publishing/android-ios.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdx
index a43a57c2a..148b53f15 100644
--- a/docs/astro/src/content/docs/publishing/android-ios.mdx
+++ b/docs/astro/src/content/docs/publishing/android-ios.mdx
@@ -55,9 +55,14 @@ where Xcode does the assembling.
|---|---|---|
| Minimum OS | **Android 10** (API 29) | **iOS 17.0** |
| Declared target | API 33 | — |
-| CPU | `arm64-v8a` (every real device) + `x86_64` (the emulator) | arm64 device + simulator slice |
+| CPU | `arm64-v8a` (every real device); `x86_64` (the emulator) only when asked | arm64 device + simulator slice |
| GPU | **Vulkan 1.0.3 required** — declared `required="true"`, so a device without it does not see the app on Play | Metal |
+An Android package carries the phone ABI only, which is about half of what it used to
+weigh. To try a build in an emulator, tick *Include the emulator (x86_64)* in the Android
+section (or pass `--emulator-abi` on the command line) and install that one; leave it off
+for anything you ship.
+
Android's floor is 29 because the engine's font path calls `AFontMatcher_create`,
which is API 29 — below that there is nothing to fall back to. It was **declared** as
26 through v0.37.0, which was a claim rather than a capability: those builds install
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 846039cdf..35448b849 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
@@ -48,9 +48,11 @@ Android 两者都给,是因为它两者都做得到:编辑器既能直接装配
|---|---|---|
| 最低系统 | **Android 10**(API 29) | **iOS 17.0** |
| 声明的 target | API 33 | — |
-| CPU | `arm64-v8a`(所有真机)+ `x86_64`(模拟器) | arm64 真机 + 模拟器切片 |
+| CPU | `arm64-v8a`(所有真机);`x86_64`(模拟器)仅在勾选时打入 | arm64 真机 + 模拟器切片 |
| GPU | **要求 Vulkan 1.0.3**——声明为 `required="true"`,不具备的设备在 Play 上根本看不到这个应用 | Metal |
+Android 安装包默认只打入真机的 ABI,体积比之前小了约一半。要在模拟器里试玩,请在 Android 设置里勾选“包含模拟器(x86_64)”(命令行用 `--emulator-abi`)再安装那一份;要发布的包请保持关闭。
+
Android 的下限是 29,因为引擎的字体路径调用 `AFontMatcher_create`,那是 API 29——
再往下没有可退的路。直到 v0.37.0 它**声明**的都还是 26,而那是个说法而非能力:
那些构建能装到 Android 10 和 11 上,然后起不来——因为 NDK 被要求按更高的 API 构建,
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index f7be8c18d..f4ba36335 100644
--- a/pipeline/bin/estella.mjs
+++ b/pipeline/bin/estella.mjs
@@ -33,6 +33,8 @@ const USAGE = `usage: node pipeline/bin/estella.mjs export <projectDir> [options
--scripts <path> scripts entry, project-relative (default: the project's scripts.main)
--template <dir> android/ios/desktop: the runtime template to wrap, else the installed one
--output project android: emit a Gradle project instead of an apk
+ --emulator-abi android: also carry the emulator's x86_64 libraries (about half of an empty
+ package; phones do not run them, so the default leaves them out)
--json <file> also write the result here, for a caller that reads it back
--enforce-budget fail (exit 1) when the package is over a size limit
--minify minify the bundled scripts, as a shipping build (or profile) does
@@ -69,7 +71,7 @@ The panorama itself is not shipped — a light references the \`.esenv\`.`;
/** Options take a value; these do not — without the distinction a trailing flag
* swallows nothing, ends the loop, and a CI job silently gets no gate. */
-const FLAGS = new Set(['enforce-budget', 'minify', 'no-aot']);
+const FLAGS = new Set(['enforce-budget', 'minify', 'no-aot', 'emulator-abi']);
function parseArgs(argv) {
const [command, projectDir, ...rest] = argv;
@@ -945,6 +947,7 @@ try {
} : {}),
iosSources: platform === 'ios' && templateDir ? iosTemplateSources(templateDir) : null,
...(opts.output === 'project' ? { androidOutput: 'project' } : {}),
+ ...(opts['emulator-abi'] ? { androidEmulatorAbi: true } : {}),
...(opts.minify ? { minify: true } : {}),
...(opts['debug-channel'] ? { debugChannel: { url: opts['debug-channel'] } } : {}),
// `dev` is what the AOT step calls "do not compile" — the editor's preview
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 4df894ce9..a52211092 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -537,6 +537,8 @@ export interface ExportGameOptions {
androidVersionCode?: number;
/** Android: also write the Google Play upload format (.aab) beside the .apk. */
androidAppBundle?: boolean;
+ /** Android: also carry the emulator's x86_64 libraries. Absent ⇒ phone ABIs only. */
+ androidEmulatorAbi?: 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
@@ -1331,7 +1333,10 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
warnings.push('This shipping APK is signed with the development key, which Google Play refuses: '
+ 'set a release key under Project Settings → Android → Signing.');
}
- const assembly = { templateDir: template, contentDir: absOut, app: appConfig, key, icon };
+ const assembly = {
+ templateDir: template, contentDir: absOut, app: appConfig, key, icon,
+ emulatorAbi: opts.androidEmulatorAbi === true,
+ };
apkFile = path.join(absOut, apkFileName(appConfig.id));
await writeFile(apkFile, assembleApk(assembly));
if (opts.androidAppBundle) {
diff --git a/pipeline/src/export/projectExportOptions.ts b/pipeline/src/export/projectExportOptions.ts
index bcd8f462c..d19373173 100644
--- a/pipeline/src/export/projectExportOptions.ts
+++ b/pipeline/src/export/projectExportOptions.ts
@@ -102,6 +102,7 @@ export async function projectExportOptions(
...(platform === 'wechat' && plat?.wechat?.emscriptenGLX ? { miniGameGlx: true } : {}),
androidVersionCode: plat?.android?.versionCode,
androidAppBundle: plat?.android?.appBundle,
+ androidEmulatorAbi: plat?.android?.emulatorAbi,
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 d6aaa0638..586d87759 100644
--- a/pipeline/src/project/format.ts
+++ b/pipeline/src/project/format.ts
@@ -303,6 +303,13 @@ export interface AndroidPackaging {
* output for the one that is not being used.
*/
appBundle?: boolean;
+ /**
+ * Also carry the emulator's x86_64 libraries in the package.
+ *
+ * Off by default: they are about half of an empty package and no player's phone can
+ * run them. Turn it on for a build you will install in an emulator.
+ */
+ emulatorAbi?: 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;
@@ -1025,6 +1032,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;
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/native-template.test.ts b/pipeline/tests/native-template.test.ts
index 3acd4ab39..20f703875 100644
--- a/pipeline/tests/native-template.test.ts
+++ b/pipeline/tests/native-template.test.ts
@@ -366,6 +366,17 @@ describe('what a PUBLISHED template must carry', () => {
.toEqual(expect.arrayContaining(['lib/x86_64/libestella_js_host.so']));
});
+ it('strips every native library of the template, libc++ included', async () => {
+ // The NDK's own libc++_shared carries 7.5 MB of debug info per ABI, which was 8 of its
+ // 9.2 MB in a shipped APK.
+ const { templateLayout } = await import('../../build-tools/utils/nativeTemplate.js');
+ const libs = templateLayout('android').filter((e: { rel: string }) => e.rel.startsWith('lib/'));
+ expect(libs.length).toBeGreaterThan(0);
+ for (const e of libs as { rel: string; strip?: boolean }[]) {
+ expect(e.strip, `${e.rel} ships with its debug info`).toBe(true);
+ }
+ });
+
it('counts a directory entry as held when something inside it is', () => {
// A zip stores files, never the folder — so `java` is present because
// `java/com/...` is, and absent when nothing under it shipped.
diff --git a/pipeline/tests/project-packaging.test.ts b/pipeline/tests/project-packaging.test.ts
index a005c7189..e3fdf5889 100644
--- a/pipeline/tests/project-packaging.test.ts
+++ b/pipeline/tests/project-packaging.test.ts
@@ -76,6 +76,13 @@ describe('parseManifest — packaging', () => {
expect(bad.packaging?.platforms?.android).toBeUndefined();
});
+ it('keeps whether an Android package carries the emulator ABI, and reads only a boolean', () => {
+ const on = parseManifest({ name: 'X', packaging: { platforms: { android: { emulatorAbi: true } } } });
+ expect(on.packaging?.platforms?.android).toEqual({ emulatorAbi: true });
+ const bad = parseManifest({ name: 'X', packaging: { platforms: { android: { emulatorAbi: 'yes' } } } });
+ expect(bad.packaging?.platforms?.android).toBeUndefined();
+ });
+
it('parses excludeScenes, dropping non-string / empty entries', () => {
const m = parseManifest({
name: 'X',
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 593c63d39..6e3e5a705 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,10 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'perf(android): a package carries the phone ABI, and the template strips libc++':
+ { note: 'An Android package carries the phone ABI only.' },
+ 'feat(editor): include the emulator ABI as an Android packaging setting':
+ { note: 'An Android package carries the phone ABI only.' },
'feat(render): editor-view studio preview lighting and preview exposure':
{ note: 'The viewport can light the scene with a studio preview, and expose it.' },
'feat(editor): studio preview lighting and preview exposure for the viewport':
diff --git a/tools/verify-native-boot.mjs b/tools/verify-native-boot.mjs
index 572273910..296a70fb0 100644
--- a/tools/verify-native-boot.mjs
+++ b/tools/verify-native-boot.mjs
@@ -745,6 +745,8 @@ function packageExample(driver, name, opts) {
path.join(ROOT, 'examples', name),
'--platform', driver.name,
'--template', opts.template,
+ // The matrix installs on an x86_64 emulator, which a package built for phones omits.
+ ...(driver.name === 'android' ? ['--emulator-abi'] : []),
'--out', path.join(work, 'dist'),
'--json', report,
]);