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(editor): offer the App Bundle beside the APK

esengine994bf37ca20b
diff --git a/build-tools/cli.js b/build-tools/cli.js
index 56f1d1419..7b44f7525 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -170,6 +170,7 @@ program
.option('--ios-min <version>', 'iOS deployment target', '17.0')
.option('--simulator', 'iOS: build the simulator slice (needs a simulator Dawn)', false)
.option('--package', 'Assemble the app around --content from the installed runtime template: Android a signed APK, iOS an Xcode project', false)
+ .option('--aab', 'Android --package: also write the Google Play upload format (.aab)', false)
.option('--key <pem>', 'Android --package: PEM private key to sign with (default: the development key)')
.option('--cert <pem>', 'Android --package: PEM certificate for --key')
.option('--passphrase <text>', 'Passphrase for an encrypted --key')
@@ -198,6 +199,7 @@ program
iosMin: options.iosMin,
simulator: options.simulator,
package: options.package,
+ aab: options.aab,
key: options.key,
cert: options.cert,
passphrase: options.passphrase,
diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.js
index a3cbd2497..b628e71aa 100644
--- a/build-tools/tasks/native.js
+++ b/build-tools/tasks/native.js
@@ -23,6 +23,7 @@ import {
import { readAppConfig, fillTemplate } from '../utils/nativeApp.js';
import { emitIosXcodeProject } from '../utils/iosProject.js';
import { assembleApk, apkFileName } from '../utils/apk.js';
+import { assembleAab, aabFileName } from '../utils/aab.js';
import { debugSigningKey, signingKeyFromPem } from '../utils/androidKeystore.js';
// Generate the native (QuickJS) ECS bindings from the SAME reflection source EHT
@@ -529,14 +530,24 @@ async function packageAndroidApk(options) {
: debugSigningKey();
if (!options.key) logger.info('Signing with the development key (sideload only — not for a store).');
+ const assembly = { templateDir: template.dir, contentDir, app, abi, key };
logger.step('Assembling the APK...');
- const apk = assembleApk({ templateDir: template.dir, contentDir, app, abi, key });
+ const apk = assembleApk(assembly);
const out = path.join(contentDir, apkFileName(app.id));
writeFileSync(out, apk);
logger.success(`APK: ${out} (${(apk.length / 1048576).toFixed(1)} MB)`);
logger.info(`App: ${app.name} (${app.id}) v${app.version} — ${app.orientation}, signed by ${key.name}`);
logger.info(`Install it with: adb install -r ${out}`);
+
+ if (options.aab) {
+ logger.step('Assembling the App Bundle...');
+ const bundle = assembleAab(assembly);
+ const aab = path.join(contentDir, aabFileName(app.id));
+ writeFileSync(aab, bundle);
+ logger.success(`App Bundle: ${aab} (${(bundle.length / 1048576).toFixed(1)} MB)`);
+ logger.info('Upload it to Google Play — a bundle is not installable; Play builds the APKs from it.');
+ }
}
/**
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index 9ff0f72a3..5a24a7eba 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -39,6 +39,7 @@ import { ESENGINE_EXTERNAL } from './esengineResolve';
import { orientationCss, orientationOverlayHtml, orientationLockScript, orientationLockCspHash, type ScreenOrientation } from './orientationHtml';
import { emitIosXcodeProject, type IosProjectSources } from '../../build-tools/utils/iosProject.js';
import { assembleApk, apkFileName } from '../../build-tools/utils/apk.js';
+import { assembleAab, aabFileName } from '../../build-tools/utils/aab.js';
import { debugSigningKey, type SigningKey } from '../../build-tools/utils/androidKeystore.js';
import { isNativePlatform, type ExportPlatform } from '../src/project/platforms';
import { collectSubsystems, subsystemGapWarnings, targetGaps, type Subsystem } from '../src/project/targetSupport';
@@ -159,6 +160,9 @@ export interface ExportGameResult {
/** Android: the signed APK. Absent when no Android runtime template is
* installed (the export still carries its content). */
apkFile?: string;
+ /** Android: the signed App Bundle, when the project asked for one. Play takes
+ * this; it is not installable. */
+ aabFile?: string;
/** Playable, zip-delivery networks: the archive written beside the HTML — the file
* the network takes an upload of. */
zipFile?: string;
@@ -390,6 +394,8 @@ export async function exportGame(opts: {
appVersion?: string;
/** Android's build ordinal. Absent ⇒ 1. */
androidVersionCode?: number;
+ /** Android: also write the Google Play upload format (.aab) beside the .apk. */
+ androidAppBundle?: 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
@@ -533,6 +539,7 @@ export async function exportGame(opts: {
/** iOS: set once the project is written around the content (see below). */
let xcodeProject: string | undefined;
let apkFile: string | undefined;
+ let aabFile: string | undefined;
await mkdir(payloadDir, { recursive: true });
const common: BuildOptions = {
bundle: true,
@@ -678,10 +685,14 @@ export async function exportGame(opts: {
const template = opts.androidTemplate ?? null;
if (template) {
const key = opts.androidKey ?? debugSigningKey();
+ const assembly = { templateDir: template.dir, contentDir: absOut, app: appConfig, abi: template.abi, key };
apkFile = path.join(absOut, apkFileName(appConfig.id));
- await writeFile(apkFile, assembleApk({
- templateDir: template.dir, contentDir: absOut, app: appConfig, abi: template.abi, key,
- }));
+ await writeFile(apkFile, assembleApk(assembly));
+ if (opts.androidAppBundle) {
+ progress({ phase: 'Assembling the App Bundle' });
+ aabFile = path.join(absOut, aabFileName(appConfig.id));
+ await writeFile(aabFile, assembleAab(assembly));
+ }
} else {
warnings.push('No Android runtime template is installed for this editor version, so no APK '
+ 'was assembled — the content is here. Install one from the Android row in Package '
@@ -695,6 +706,6 @@ export async function exportGame(opts: {
return {
ok: errors.length === 0, platform, outDir: absOut, included: cook.included.length,
- warnings, errors, ...(xcodeProject ? { xcodeProject } : {}), ...(apkFile ? { apkFile } : {}),
+ warnings, errors, ...(xcodeProject ? { xcodeProject } : {}), ...(apkFile ? { apkFile } : {}), ...(aabFile ? { aabFile } : {}),
};
}
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index ffd056c52..76c111a97 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -882,6 +882,7 @@ ipcMain.handle(
appId: opts?.platform === 'ios' ? resolveAppId(manifest, 'ios') : resolveAppId(manifest, 'android'),
appVersion: manifest.version,
androidVersionCode: plat?.android?.versionCode,
+ androidAppBundle: plat?.android?.appBundle,
// One project-wide orientation for every target: the explicit packaging
// setting, else derived from the design resolution's aspect.
orientation: resolveOrientation(manifest),
diff --git a/desktop/src/components/BuildDialog.tsx b/desktop/src/components/BuildDialog.tsx
index 73b3feba9..bd00ecc67 100644
--- a/desktop/src/components/BuildDialog.tsx
+++ b/desktop/src/components/BuildDialog.tsx
@@ -57,6 +57,8 @@ interface Result {
xcodeProject?: string;
/** Android: the signed APK the export assembled. */
apkFile?: string;
+ /** Android: the App Bundle, when the project asked for one. */
+ aabFile?: string;
}
/** Nav groupings. Order here is the order they appear. */
@@ -215,6 +217,9 @@ export function BuildDialog() {
// that is a per-build decision, not a property of the project. The list arrives from
// the main process, since it includes the networks the PROJECT defines.
const [adNetwork, setAdNetwork] = useState<string>(saved.platforms?.playable?.network ?? 'generic');
+ // The Play upload format, beside the installable APK. A per-build decision that
+ // the project remembers, like the ad network above.
+ const [appBundle, setAppBundle] = useState(saved.platforms?.android?.appBundle ?? false);
const [adNetworks, setAdNetworks] = useState<PlayableNetworkOption[]>([]);
const [advOpen, setAdvOpen] = useState(false);
const [copiedFix, setCopiedFix] = useState(false);
@@ -472,6 +477,8 @@ export function BuildDialog() {
// Awaited, not fired-and-forgotten: the export resolves the network from the
// manifest, so a race here would package for the previous one.
if (platform === 'playable') await ProjectStore.setPlatformPackaging('playable', { network: adNetwork });
+ // Same reason: the export reads the bundle choice from the manifest.
+ if (platform === 'android') await ProjectStore.setPlatformPackaging('android', { appBundle });
// 'auto' → honor each asset's Import Settings (the cook then reads per-asset
// texture/audio compression + Max Size); 'skip' → ship everything raw.
const compress = assetCompression === 'auto';
@@ -726,6 +733,12 @@ export function BuildDialog() {
)}
<Group title={t('build.secBuild')}>
+ {platform === 'android' && (
+ <label className="build__opt" title={t('build.appBundleTip')}>
+ <input type="checkbox" checked={appBundle} onChange={(e) => setAppBundle(e.target.checked)} />
+ {t('build.appBundle')}
+ </label>
+ )}
{platform === 'playable' && (
<>
<div className="build__row">
@@ -908,7 +921,9 @@ export function BuildDialog() {
{result.xcodeProject
? t('build.next.iosProject')
: result.apkFile
- ? t('build.next.apk', { apk: result.apkFile })
+ ? (result.aabFile
+ ? t('build.next.apkAab', { apk: result.apkFile, aab: result.aabFile })
+ : t('build.next.apk', { apk: result.apkFile }))
: result.zipFile
? t('build.next.playableZip')
: def.next(result.outDir)}
diff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.ts
index d01ca8764..e786e868c 100644
--- a/desktop/src/i18n/messages/project.ts
+++ b/desktop/src/i18n/messages/project.ts
@@ -161,7 +161,16 @@ export const projectMessages = defineMessages({
en: 'Signed APK: {apk} — install it with adb install -r, or copy it to the device.',
zh: '已签名 APK:{apk} —— 用 adb install -r 安装,或直接拷到设备上。',
},
+ 'build.next.apkAab': {
+ en: 'Signed APK: {apk} (install it with adb install -r). App Bundle for Google Play: {aab} — upload it; a bundle cannot be installed directly.',
+ zh: '已签名 APK:{apk}(用 adb install -r 安装)。Google Play 上传用 App Bundle:{aab} —— 直接上传即可,bundle 本身无法安装。',
+ },
'build.showApk': { en: 'Show APK', zh: '显示 APK' },
+ 'build.appBundle': { en: 'Google Play App Bundle (.aab)', zh: 'Google Play App Bundle(.aab)' },
+ 'build.appBundleTip': {
+ en: 'Also write the upload format Google Play requires for new apps, beside the installable APK. A bundle cannot be installed on a device — Play builds the APKs from it.',
+ zh: '在可安装的 APK 之外,另写一份 Google Play 对新应用强制要求的上传格式。bundle 无法直接装到设备上——Play 会用它生成各机型的 APK。',
+ },
'build.next.ios': {
en: 'The content is in {out}. Install the iOS runtime template to get an Xcode project written around it.',
zh: '内容已写入 {out}。安装 iOS 运行时模板后,导出会围绕它写出 Xcode 工程。',
diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.ts
index 240956173..7fffde389 100644
--- a/desktop/src/project/format.ts
+++ b/desktop/src/project/format.ts
@@ -127,7 +127,19 @@ export interface DesktopPackaging { appId?: string; productName?: string; }
/** Android's slice of the app identity. `appId` is the manifest package — the
* identity a store keeps forever; `versionCode` is the integer Play orders builds
* by, which has no counterpart on any other target. */
-export interface AndroidPackaging { appId?: string; versionCode?: number; }
+export interface AndroidPackaging {
+ appId?: string;
+ versionCode?: number;
+ /**
+ * Also write the Google Play upload format (`.aab`) beside the `.apk`.
+ *
+ * Off by default because the two are for different moments: the APK is what
+ * installs on a device you are holding, the bundle is what a store takes and
+ * cannot be installed at all. Producing both on every iteration would double the
+ * output for the one that is not being used.
+ */
+ appBundle?: boolean;
+}
/** iOS's slice: the bundle identifier Xcode signs against. */
export interface IosPackaging { appId?: string; }