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
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.ymlindex 256b4881f..f97ff302c 100644--- a/.github/workflows/android-canary-apk.yml+++ b/.github/workflows/android-canary-apk.yml@@ -124,7 +124,7 @@ jobs:[ -z "$name" ] && continueecho "::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" ]; thendiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.### Fixeddiff --git a/build-tools/utils/aab.d.ts b/build-tools/utils/aab.d.tsindex 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.jsindex 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.tsindex 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.jsindex 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.tsindex 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.jsindex 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/desktopindex 7e51dcad6..47d797d1d 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 7e51dcad6217b202be3a056ee90c20696612687e+Subproject commit 47d797d1d96ac0b2b7a2d541cd712b5a1c26f44fdiff --git a/docs/astro/src/content/docs/publishing/android-ios.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdxindex 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** as26 through v0.37.0, which was a claim rather than a capability: those builds installdiff --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 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.mjsindex 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 previewdiff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.mjsindex 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,]);