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(native): an exported project becomes an app with its own identity

yhh946a2bfbbf27
diff --git a/.gitignore b/.gitignore
index 5173d1dc7..ed65707cc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -130,3 +130,8 @@ docs/REARCH_*.md
native/ios/*.xcodeproj/
native/ios/Content/*
!native/ios/Content/.gitkeep
+
+# Generated by `cli native` from the committed templates, carrying the app
+# identity the exported project declares. See native/README.md.
+native/ios/App/Info.plist
+native/ios/app.generated.yml
diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.js
index bb8cf61b9..d1138a806 100644
--- a/build-tools/tasks/native.js
+++ b/build-tools/tasks/native.js
@@ -16,6 +16,7 @@ import * as logger from '../utils/logger.js';
import { runCommand, getCpuCount, resolvePython } from '../utils/emscripten.js';
import { requireSdk, requireNdk, sdkCmake } from '../utils/android.js';
import { packageNativeApk } from './nativePackage.js';
+import { readAppConfig, iosInterfaceOrientations, fillTemplate } from '../utils/nativeApp.js';
// Generate the native (QuickJS) ECS bindings from the SAME reflection source EHT
// uses for the web embind bindings — so the two surfaces can never drift. Written
@@ -250,6 +251,46 @@ async function stageIosContent(rootDir, contentDir) {
// folder reference needs; staging content must not delete it.
if (keepText !== null) writeFileSync(keep, keepText);
logger.success(`iOS content: native/ios/Content ← ${path.relative(rootDir, from)}`);
+ return from;
+}
+
+/**
+ * Fill in the app's identity for the Xcode project: Info.plist from its committed
+ * template (name, version, and the orientations the OS may rotate among), plus the
+ * generated yml project.yml includes for the bundle id.
+ *
+ * Written on every iOS build, with defaults when no project has been staged, so
+ * xcodegen always has both files — it runs after this by construction, since the
+ * project links the xcframework this build produces.
+ */
+async function writeIosAppIdentity(rootDir, contentDir) {
+ const app = contentDir ? readAppConfig(contentDir, (m) => logger.warn(m)) : readAppConfig('', () => {});
+ const iosDir = path.join(rootDir, 'native', 'ios');
+
+ const template = readFileSync(path.join(iosDir, 'App', 'Info.plist.in'), 'utf8');
+ const orientations = iosInterfaceOrientations(app.orientation)
+ .map((o) => `\t\t<string>${o}</string>`).join('\n');
+ writeFileSync(path.join(iosDir, 'App', 'Info.plist'), fillTemplate(template, {
+ APP_NAME: app.name,
+ VERSION_NAME: app.version,
+ VERSION_CODE: app.versionCode,
+ ORIENTATIONS: orientations,
+ }), 'utf8');
+
+ // project.yml includes this; keeping the bundle id out of the committed file is
+ // what lets two projects build from one checkout without editing it.
+ writeFileSync(path.join(iosDir, 'app.generated.yml'),
+ '# Written by `cli native --target ios` from the exported project\'s app.config.json.\n'
+ + '# Included by project.yml — do not edit, and do not commit.\n'
+ + 'targets:\n'
+ + ' EstellaiOS:\n'
+ + ' settings:\n'
+ + ' base:\n'
+ + ` PRODUCT_BUNDLE_IDENTIFIER: ${app.id}\n`
+ + ` MARKETING_VERSION: "${app.version}"\n`
+ + ` CURRENT_PROJECT_VERSION: "${app.versionCode}"\n`, 'utf8');
+
+ logger.info(`App: ${app.name} (${app.id}) v${app.version} — ${app.orientation}`);
}
async function buildIosHost(options) {
@@ -296,7 +337,8 @@ async function buildIosHost(options) {
logger.success(`iOS host: ${path.join(slice.dir, 'libestella_ios.a')}`);
await assembleXcframework(rootDir, env);
- if (options.content) await stageIosContent(rootDir, options.content);
+ const staged = options.content ? await stageIosContent(rootDir, options.content) : null;
+ await writeIosAppIdentity(rootDir, staged);
logger.info('Next: cd native/ios && xcodegen && open EstellaiOS.xcodeproj — pick your Team, then Run.');
}
diff --git a/build-tools/tasks/nativePackage.js b/build-tools/tasks/nativePackage.js
index a401e46b6..0cc4088fc 100644
--- a/build-tools/tasks/nativePackage.js
+++ b/build-tools/tasks/nativePackage.js
@@ -7,16 +7,20 @@
// its content go in as assets/, which is where the host's readAsset() looks.
import path from 'path';
-import { existsSync } from 'fs';
-import { mkdir, copyFile, cp, rm } from 'fs/promises';
+import { existsSync, readFileSync } from 'fs';
+import { mkdir, copyFile, cp, rm, writeFile } from 'fs/promises';
import config from '../build.config.js';
import * as logger from '../utils/logger.js';
import { runCommand } from '../utils/emscripten.js';
import { requireSdk, requireNdk, buildTool, platformJar, ndkTool, ndkLibcxxShared, javaHome, jdkTool } from '../utils/android.js';
+import { readAppConfig, androidScreenOrientation, fillTemplate } from '../utils/nativeApp.js';
const HOST_LIBRARY = 'libestella_js_host.so';
-const HOST_APK = 'estella-js-host.apk';
-const HOST_MANIFEST = 'host';
+const MANIFEST_TEMPLATE = path.join('native', 'android', 'host', 'AndroidManifest.xml.in');
+
+/** The APK is named after the app it contains, so packaging a second project does
+ * not quietly replace the first one's file. */
+const apkName = (appId) => `${appId.split('.').pop() || 'estella'}.apk`;
// A debug keystore is enough to sideload; Android Studio uses the same one. Create
// it on first use so packaging never stops to ask for credentials.
@@ -82,29 +86,40 @@ export async function packageNativeApk(options = {}) {
// export — cooked assets + manifests + scenes + game.config.json. A whole-
// directory copy, so nothing here carries a file list that could drift from
// what the export actually wrote.
- let assetsDir = null;
- if (options.content) {
- const content = path.isAbsolute(options.content) ? options.content : path.join(rootDir, options.content);
- if (!existsSync(content)) throw new Error(`--content dir not found: ${content}`);
- assetsDir = path.join(staging, 'assets');
- logger.step(`Staging exported content from ${path.relative(rootDir, content)}...`);
- await cp(content, assetsDir, { recursive: true });
- } else {
+ if (!options.content) {
// Nothing to run: the host boots game.config.json and there is no built-in
// fallback, by design — the packaged game takes the same path every real
// game takes.
throw new Error('The host needs a project to run: pass --content <dir> from '
+ "Package Project -> Android (or `exportGame({ platform: 'android' })`).");
}
+ const content = path.isAbsolute(options.content) ? options.content : path.join(rootDir, options.content);
+ if (!existsSync(content)) throw new Error(`--content dir not found: ${content}`);
+ await cp(content, path.join(staging, 'assets'), { recursive: true });
+ logger.step(`Staging exported content from ${path.relative(rootDir, content)}...`);
+
+ // The app the content asks to be: identity, version, and the orientation the
+ // OS must lock the window to. The manifest is a template because all four vary
+ // per project — a static one is why every example installed over the last.
+ const app = readAppConfig(content, (m) => logger.warn(m));
+ const manifest = path.join(staging, 'AndroidManifest.xml');
+ await writeFile(manifest, fillTemplate(readFileSync(path.join(rootDir, MANIFEST_TEMPLATE), 'utf8'), {
+ APP_ID: app.id,
+ APP_NAME: app.name,
+ VERSION_NAME: app.version,
+ VERSION_CODE: app.versionCode,
+ SCREEN_ORIENTATION: androidScreenOrientation(app.orientation),
+ }));
+ logger.info(`App: ${app.name} (${app.id}) v${app.version} — ${app.orientation}`);
const unsigned = path.join(staging, 'unsigned.apk');
- const aligned = path.join(buildDir, HOST_APK);
+ const aligned = path.join(buildDir, apkName(app.id));
logger.step('Linking resources (aapt2)...');
// aapt2 produces the base APK from the manifest alone; the payload (libraries
// and assets) is added below, where the entry names are ours to control.
await runCommand(buildTool(sdk, 'aapt2'), [
'link',
- '--manifest', path.join(rootDir, 'native', 'android', HOST_MANIFEST, 'AndroidManifest.xml'),
+ '--manifest', manifest,
'-I', platformJar(sdk, platform),
'-o', unsigned,
]);
diff --git a/build-tools/utils/nativeApp.js b/build-tools/utils/nativeApp.js
new file mode 100644
index 000000000..15aad1728
--- /dev/null
+++ b/build-tools/utils/nativeApp.js
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// The app identity an editor export declares, and what each platform calls it.
+//
+// `app.config.json` sits beside `game.config.json` in an export for a native
+// target. The split is deliberate: game.config.json is what the RUNTIME reads to
+// play the game; this is what the PACKAGER reads to build an application around
+// it. Identity, version and orientation are properties the OS owns — the engine
+// can letterbox but cannot rotate a phone — so they are settled here, once, from
+// the project, rather than by a flag on whoever happens to run the build.
+
+import path from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+/** What the editor writes; see desktop/electron/exportGame.ts NativeAppConfig. */
+const DEFAULTS = {
+ id: 'com.estella.game',
+ name: 'Estella',
+ version: '1.0',
+ versionCode: 1,
+ orientation: 'landscape',
+};
+
+/**
+ * Read an export's `app.config.json`. Missing or unreadable falls back to the
+ * defaults with a warning rather than failing: a content dir produced by an older
+ * editor still packages, it just ships a generic identity.
+ *
+ * @param contentDir Absolute path of the exported project.
+ * @param warn Sink for the "no app.config.json" notice.
+ */
+export function readAppConfig(contentDir, warn = () => {}) {
+ const file = path.join(contentDir, 'app.config.json');
+ if (!existsSync(file)) {
+ warn(`no app.config.json in ${path.basename(contentDir)} — packaging with a default identity `
+ + `(${DEFAULTS.id}). Re-export from the editor to carry the project's own.`);
+ return { ...DEFAULTS };
+ }
+ try {
+ const parsed = JSON.parse(readFileSync(file, 'utf8'));
+ return {
+ id: typeof parsed.id === 'string' && parsed.id ? parsed.id : DEFAULTS.id,
+ name: typeof parsed.name === 'string' && parsed.name ? parsed.name : DEFAULTS.name,
+ version: typeof parsed.version === 'string' && parsed.version ? parsed.version : DEFAULTS.version,
+ versionCode: Number.isInteger(parsed.versionCode) && parsed.versionCode > 0
+ ? parsed.versionCode : DEFAULTS.versionCode,
+ orientation: parsed.orientation === 'portrait' ? 'portrait' : DEFAULTS.orientation,
+ };
+ } catch (err) {
+ warn(`app.config.json is unreadable (${err.message}) — packaging with a default identity.`);
+ return { ...DEFAULTS };
+ }
+}
+
+/**
+ * The manifest value for an orientation. `sensorPortrait` / `sensorLandscape`
+ * rather than the plain values: a phone held the other way up still works, but the
+ * app never crosses into the aspect it was not designed for. That is what a game
+ * ships with — a hard `portrait` leaves an upside-down phone stubbornly rotated.
+ */
+export function androidScreenOrientation(orientation) {
+ return orientation === 'portrait' ? 'sensorPortrait' : 'sensorLandscape';
+}
+
+/**
+ * The `UISupportedInterfaceOrientations` array for an orientation. iOS has no
+ * "sensor" mode: you list the ones you allow, and the OS rotates among them.
+ */
+export function iosInterfaceOrientations(orientation) {
+ return orientation === 'portrait'
+ ? ['UIInterfaceOrientationPortrait', 'UIInterfaceOrientationPortraitUpsideDown']
+ : ['UIInterfaceOrientationLandscapeLeft', 'UIInterfaceOrientationLandscapeRight'];
+}
+
+/** Substitute `@NAME@` placeholders in a committed template. */
+export function fillTemplate(text, values) {
+ return text.replace(/@([A-Z_]+)@/g, (match, key) => (key in values ? String(values[key]) : match));
+}
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index e6ca1cf26..aa4334741 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -41,6 +41,29 @@ import { isNativePlatform, type ExportPlatform } from '../src/project/platforms'
import { collectSubsystems, subsystemGapWarnings, targetGaps, type Subsystem } from '../src/project/targetSupport';
export type { ExportPlatform };
+/**
+ * `app.config.json` — what the native packagers need to build an *application*
+ * around the content, as opposed to what the runtime needs to play it.
+ *
+ * Everything here is a property the OS owns: an installed app has one identity,
+ * one version, and one orientation, none of which the engine can change from
+ * inside. `cli native --package` turns this into an AndroidManifest; the Xcode
+ * project turns it into Info.plist keys.
+ */
+export interface NativeAppConfig {
+ /** Reverse-DNS: the Android manifest package / the iOS bundle identifier. */
+ id: string;
+ /** The name under the launcher icon. */
+ name: string;
+ /** Version as a store displays it (`versionName` / `CFBundleShortVersionString`). */
+ version: string;
+ /** Android's integer build ordinal (`versionCode`). */
+ versionCode: number;
+ /** The orientation the app locks to. A phone cannot be rotated by the engine,
+ * so this is the only place it can be expressed. */
+ orientation: ScreenOrientation;
+}
+
/** A switchable scene the export ships: SceneManager name + project-relative path. */
export interface ExportScene {
name: string;
@@ -341,6 +364,13 @@ export async function exportGame(opts: {
desktopProductName?: string;
/** WeChat appid (Project Settings → Packaging → WeChat). */
wechatAppid?: string;
+ /** Reverse-DNS application id for a native target (format.ts resolveAppId).
+ * Written into app.config.json, where the packagers read it. */
+ appId?: string;
+ /** The app's version, as a store shows it (ProjectManifest.version). */
+ appVersion?: string;
+ /** Android's build ordinal. Absent ⇒ 1. */
+ androidVersionCode?: number;
/** 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
@@ -572,6 +602,23 @@ export async function exportGame(opts: {
};
await writeFile(path.join(payloadDir, 'game.config.json'), JSON.stringify(gameConfig, null, 2) + '\n');
+ // A native target also needs the app's IDENTITY, and it is deliberately not in
+ // game.config.json: the runtime never reads it. Orientation, the bundle id and
+ // the version are OS-level properties of the installed application — the engine
+ // can letterbox but cannot rotate a phone — so they are declared for whoever
+ // assembles the app (`cli native --package`, and the Xcode project), the same
+ // way the mini-game export writes the vendor's game.json beside the content.
+ if (nativeContent) {
+ const appConfig: NativeAppConfig = {
+ id: opts.appId ?? 'com.estella.game',
+ name: title,
+ version: opts.appVersion ?? '1.0',
+ versionCode: opts.androidVersionCode ?? 1,
+ orientation,
+ };
+ await writeFile(path.join(payloadDir, 'app.config.json'), JSON.stringify(appConfig, null, 2) + '\n');
+ }
+
// 6. Desktop: wrap the payload in a runnable Electron app.
if (platform === 'desktop') { progress({ phase: 'Staging Electron app' }); await stageDesktopApp(absOut, title, orientation, opts.desktopAppId, opts.desktopProductName); }
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 192d7c21e..65dfed331 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -40,7 +40,7 @@ import { installCrashCapture, logsDir } from './resilience';
import { mcpMode, startMcpEndpoint } from './mcpEndpoint';
import { checkForUpdate } from './updateCheck';
import { listPlatforms, loadProjectPlatform, createProjectPlatform, type PlatformRuntimeDirs } from './platformCatalog';
-import { resolveLayout, resolveScripts, resolveOrientation, resolveScreenFit, type ExportPlatform } from '../src/project/format';
+import { resolveLayout, resolveScripts, resolveOrientation, resolveScreenFit, resolveAppId, type ExportPlatform } from '../src/project/format';
import type { WorkspaceState } from '../src/project/format';
// Enable WebGPU in the renderer so the viewport's WebGPU backend (Settings →
@@ -849,6 +849,10 @@ ipcMain.handle(
desktopAppId: plat?.desktop?.appId,
desktopProductName: plat?.desktop?.productName,
wechatAppid: plat?.wechat?.appid,
+ // The app's identity, by the one rule every target resolves it with.
+ appId: opts?.platform === 'ios' ? resolveAppId(manifest, 'ios') : resolveAppId(manifest, 'android'),
+ appVersion: manifest.version,
+ androidVersionCode: plat?.android?.versionCode,
// 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/i18n/messages/settings.ts b/desktop/src/i18n/messages/settings.ts
index 6ff854129..d93baa9fe 100644
--- a/desktop/src/i18n/messages/settings.ts
+++ b/desktop/src/i18n/messages/settings.ts
@@ -72,6 +72,7 @@ export const settingsMessages = defineMessages({
'set.group.gravity': { en: 'Gravity', zh: '重力' },
'set.group.collisionLayers': { en: 'Collision Layers', zh: '碰撞层' },
'set.group.solver': { en: 'Solver', zh: '求解器' },
+ 'set.group.application': { en: 'Application', zh: '应用' },
'set.group.wechat': { en: 'WeChat', zh: '微信' },
'set.group.desktop': { en: 'Desktop', zh: '桌面' },
@@ -223,10 +224,20 @@ export const settingsMessages = defineMessages({
},
'set.orientation.portrait': { en: 'Portrait', zh: '竖屏' },
'set.orientation.landscape': { en: 'Landscape', zh: '横屏' },
- 'set.project.packaging.desktop.appId': { en: 'App ID', zh: 'App ID' },
+ 'set.project.packaging.appId': { en: 'Application ID', zh: '应用 ID' },
+ 'set.project.packaging.appId.desc': {
+ en: 'Reverse-DNS id the installed app is known by — the Android manifest package, the iOS bundle id, the desktop installer id. Empty derives one from the project name; a published app should set its own, because a store keeps it forever.',
+ zh: '已安装应用的反向域名 id——Android 的 manifest package、iOS 的 bundle id、桌面安装包的 id。留空则按项目名推导;正式发布的应用应当自己指定,因为应用商店会永久沿用它。',
+ },
+ 'set.project.packaging.android.versionCode': { en: 'Android Version Code', zh: 'Android 版本号' },
+ 'set.project.packaging.android.versionCode.desc': {
+ en: 'The integer Google Play orders builds by — it must increase with every upload. The version users see comes from the project version.',
+ zh: 'Google Play 用来排序构建的整数,每次上传都必须递增。用户看到的版本号来自项目版本。',
+ },
+ 'set.project.packaging.desktop.appId': { en: 'Desktop App ID', zh: '桌面 App ID' },
'set.project.packaging.desktop.appId.desc': {
- en: 'Reverse-DNS id for the installer (electron-builder appId), e.g. com.studio.game.',
- zh: '安装包的反向域名 id(electron-builder appId),例如 com.studio.game。',
+ en: 'Overrides the Application ID for the desktop installer only (electron-builder appId).',
+ zh: '仅为桌面安装包覆盖应用 ID(electron-builder appId)。',
},
'set.project.packaging.desktop.productName': { en: 'Product name', zh: '产品名称' },
'set.project.packaging.desktop.productName.desc': {
diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.ts
index 512ff9ecc..6d53952fb 100644
--- a/desktop/src/project/format.ts
+++ b/desktop/src/project/format.ts
@@ -124,6 +124,13 @@ export type CameraScaleMode = 'none' | 'fixed-width' | 'fixed-height' | 'expand'
export interface WeChatPackaging { appid?: string; }
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; }
+/** iOS's slice: the bundle identifier Xcode signs against. */
+export interface IosPackaging { appId?: string; }
+
/** A packaging target — defined in `./platforms`, where the built-in vocabulary
* lives, and re-exported here because the manifest is what persists it. */
export type { ExportPlatform } from './platforms';
@@ -163,8 +170,25 @@ export interface ProjectPackaging {
excludeScenes?: string[];
/** Per-platform output-dir overrides (else the per-platform default). */
outDir?: Partial<Record<ExportPlatform, string>>;
- /** Per-platform packaging config (appid, app id, …). */
- platforms?: { wechat?: WeChatPackaging; desktop?: DesktopPackaging };
+ /**
+ * The application identifier (reverse-DNS) every installable target needs: the
+ * Android manifest package, the iOS bundle id, the Electron appId. One project
+ * ships as one application, so it is declared once here; a target that genuinely
+ * differs overrides it below, the way a texture's Import Settings have a default
+ * and per-platform overrides.
+ *
+ * Absent ⇒ derived from the project name (see {@link resolveAppId}), so a build
+ * always has one — but a shipped app should say its own.
+ */
+ appId?: string;
+ /** Per-platform packaging config: each target's slice of the app identity, plus
+ * whatever only it has (a WeChat appid, an Android versionCode). */
+ platforms?: {
+ wechat?: WeChatPackaging;
+ desktop?: DesktopPackaging;
+ android?: AndroidPackaging;
+ ios?: IosPackaging;
+ };
}
/** Committed project identity + config (`project.esproject`). */
@@ -371,6 +395,7 @@ export function parseManifest(raw: unknown): ProjectManifest {
// mobile targets were one row — becomes the id this editor spells.
if (typeof p.platform === 'string' && p.platform !== '') pkg.platform = normalizePlatform(p.platform);
if (p.config === 'development' || p.config === 'shipping') pkg.config = p.config;
+ if (typeof p.appId === 'string' && p.appId !== '') pkg.appId = p.appId;
if (typeof p.sourceMaps === 'boolean') pkg.sourceMaps = p.sourceMaps;
if (typeof p.openFolder === 'boolean') pkg.openFolder = p.openFolder;
// Project-wide orientation. `orientation` is authoritative; a project written by
@@ -412,6 +437,21 @@ export function parseManifest(raw: unknown): ProjectManifest {
if (typeof dt.productName === 'string') d.productName = dt.productName;
if (Object.keys(d).length > 0) platforms.desktop = d;
}
+ const an = pl.android as Record<string, unknown> | undefined;
+ if (an && typeof an === 'object') {
+ const a: AndroidPackaging = {};
+ if (typeof an.appId === 'string') a.appId = an.appId;
+ if (typeof an.versionCode === 'number' && Number.isInteger(an.versionCode) && an.versionCode > 0) {
+ a.versionCode = an.versionCode;
+ }
+ if (Object.keys(a).length > 0) platforms.android = a;
+ }
+ const io = pl.ios as Record<string, unknown> | undefined;
+ if (io && typeof io === 'object') {
+ const i: IosPackaging = {};
+ if (typeof io.appId === 'string') i.appId = io.appId;
+ if (Object.keys(i).length > 0) platforms.ios = i;
+ }
// Legacy playable.orientation (its only field) also migrates; the platform
// block itself is gone (playable has no per-platform config anymore).
const pa = pl.playable as Record<string, unknown> | undefined;
@@ -446,6 +486,35 @@ export function resolveOrientation(manifest: Pick<ProjectManifest, 'packaging' |
return manifest.packaging?.orientation ?? orientationFromDesignResolution(manifest.designResolution);
}
+/**
+ * A reverse-DNS application id derived from the project name — the last-resort
+ * default, so a build always has one to sign. Non-alphanumerics collapse to a
+ * single dot-safe segment, and a leading digit is prefixed (a Java package
+ * segment cannot start with one, which is what Android checks).
+ */
+export function appIdFromName(name: string): string {
+ const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '')
+ || 'game';
+ return `com.estella.${/^\d/.test(slug) ? `a${slug}` : slug}`;
+}
+
+/**
+ * The application id a target ships under: the platform's own override, else the
+ * project-wide one, else derived from the project name. One rule, so the editor's
+ * settings page, the exporter and the packagers cannot disagree about a project's
+ * identity.
+ */
+export function resolveAppId(
+ manifest: Pick<ProjectManifest, 'name' | 'packaging'>,
+ platform: 'android' | 'ios' | 'desktop',
+): string {
+ const platforms = manifest.packaging?.platforms;
+ const override = platform === 'android' ? platforms?.android?.appId
+ : platform === 'ios' ? platforms?.ios?.appId
+ : platforms?.desktop?.appId;
+ return override || manifest.packaging?.appId || appIdFromName(manifest.name);
+}
+
/** cameraScaleMode → the engine's CanvasScaleMode value the runtime consumes
* (FixedWidth=0, FixedHeight=1, Expand=2, Shrink=3, Match=4), or -1 (SCREEN_FIT_OFF)
* for 'none'/absent — the camera keeps its raw orthoSize. Single-sourced here so the
diff --git a/desktop/src/settings/projectSettings.ts b/desktop/src/settings/projectSettings.ts
index ad41054ca..9fd14faa0 100644
--- a/desktop/src/settings/projectSettings.ts
+++ b/desktop/src/settings/projectSettings.ts
@@ -300,6 +300,34 @@ settingsRegistry.register({
},
});
+// The application identifier every installable target needs. One project ships as
+// one application, so it is declared once; a target that genuinely differs
+// overrides it below. Absent ⇒ derived from the project name, so a build always
+// has something to sign — but a shipped app should say its own.
+settingsRegistry.register({
+ id: 'project.packaging.appId',
+ type: 'string', scope: 'project', section: 'packaging', group: t('set.group.application'),
+ label: t('set.project.packaging.appId'),
+ description: t('set.project.packaging.appId.desc'),
+ placeholder: 'com.studio.game', default: '',
+ bind: {
+ get: () => ProjectStore.packagingSettings().appId ?? '',
+ set: (v) => void ProjectStore.setPackaging({ appId: v || undefined }),
+ },
+});
+
+settingsRegistry.register({
+ id: 'project.packaging.android.versionCode',
+ type: 'number', scope: 'project', section: 'packaging', group: t('set.group.application'),
+ label: t('set.project.packaging.android.versionCode'),
+ description: t('set.project.packaging.android.versionCode.desc'),
+ default: 1, min: 1, step: 1,
+ bind: {
+ get: () => ProjectStore.platformPackaging().android?.versionCode ?? 1,
+ set: (v) => void ProjectStore.setPlatformPackaging('android', { versionCode: Math.max(1, Math.round(v)) }),
+ },
+});
+
settingsRegistry.register({
id: 'project.packaging.desktop.appId',
type: 'string', scope: 'project', section: 'packaging', group: t('set.group.desktop'),
diff --git a/native/README.md b/native/README.md
index 2be8f3819..090204b30 100644
--- a/native/README.md
+++ b/native/README.md
@@ -211,6 +211,28 @@ node build-tools/cli.js native --target ios --dawn "$DAWN" \
--dawn-build "$DAWN/out-ios" --quickjs "$QJS" --content dist-ios
```
+An export for a native target writes a second file beside the content:
+`app.config.json` — the app's **identity**, as opposed to what the runtime needs
+to play the game. Identity, version and orientation are properties the OS owns
+(the engine can letterbox, but it cannot rotate a phone), so they are settled once
+from the project and read by whoever assembles the app:
+
+| app.config.json | Android | iOS |
+|---|---|---|
+| `id` | manifest `package` | `PRODUCT_BUNDLE_IDENTIFIER` |
+| `name` | `android:label` | `CFBundleDisplayName` |
+| `version` / `versionCode` | `versionName` / `versionCode` | `MARKETING_VERSION` / `CURRENT_PROJECT_VERSION` |
+| `orientation` | `android:screenOrientation` (`sensorLandscape` / `sensorPortrait`) | `UISupportedInterfaceOrientations` |
+
+Which is why `native/android/host/AndroidManifest.xml.in` and
+`native/ios/App/Info.plist.in` are templates: the concrete files are generated per
+project. A static manifest is why every project installed over the last one under
+one name — now two projects from one checkout are two apps on the phone, each
+locked to the orientation its design resolution implies. The application id comes
+from Project Settings → Packaging → Application ID, or is derived from the project
+name when unset (`sensorLandscape` / `sensorPortrait` rather than the hard values,
+so a phone held the other way up still works).
+
`game.config.json` is what the host boots, through `ESEngine.initNativeGame`;
without one it says so and stops, rather than falling back to something a real
game never runs. A project's own scripts (`defineComponent` / `defineSystem`)
diff --git a/native/android/host/AndroidManifest.xml b/native/android/host/AndroidManifest.xml
deleted file mode 100644
index cc2a022f1..000000000
--- a/native/android/host/AndroidManifest.xml
+++ /dev/null
@@ -1,11 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.estella.jshost" android:versionCode="1" android:versionName="1.0">
- <uses-sdk android:minSdkVersion="26" android:targetSdkVersion="33" />
- <uses-feature android:name="android.hardware.vulkan.version" android:version="0x400003" android:required="true" />
- <application android:label="EstellaJS" android:hasCode="false" android:extractNativeLibs="true">
- <activity android:name="android.app.NativeActivity" android:label="EstellaJS" android:configChanges="orientation|keyboardHidden|screenSize|screenLayout|density" android:exported="true">
- <meta-data android:name="android.app.lib_name" android:value="estella_js_host" />
- <intent-filter><action android:name="android.intent.action.MAIN" /><category android:name="android.intent.category.LAUNCHER" /></intent-filter>
- </activity>
- </application>
-</manifest>
diff --git a/native/android/host/AndroidManifest.xml.in b/native/android/host/AndroidManifest.xml.in
new file mode 100644
index 000000000..3bd35b787
--- /dev/null
+++ b/native/android/host/AndroidManifest.xml.in
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ The APK's manifest, as a template. Packaging substitutes the app's identity from
+ the exported project's app.config.json: an installed app has one identity, one
+ version and one orientation, and none of them can be decided here.
+
+ Everything left alone is the host itself: a NativeActivity (no Java, so hasCode
+ is false), Vulkan 1.0.3 as a hard requirement, and the config changes the host
+ handles rather than being restarted for.
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ package="@APP_ID@"
+ android:versionCode="@VERSION_CODE@"
+ android:versionName="@VERSION_NAME@">
+ <uses-sdk android:minSdkVersion="26" android:targetSdkVersion="33" />
+ <uses-feature android:name="android.hardware.vulkan.version" android:version="0x400003" android:required="true" />
+ <application android:label="@APP_NAME@" android:hasCode="false" android:extractNativeLibs="true">
+ <activity android:name="android.app.NativeActivity"
+ android:label="@APP_NAME@"
+ android:screenOrientation="@SCREEN_ORIENTATION@"
+ android:configChanges="orientation|keyboardHidden|screenSize|screenLayout|density"
+ android:exported="true">
+ <meta-data android:name="android.app.lib_name" android:value="estella_js_host" />
+ <intent-filter><action android:name="android.intent.action.MAIN" /><category android:name="android.intent.category.LAUNCHER" /></intent-filter>
+ </activity>
+ </application>
+</manifest>
diff --git a/native/ios/App/Info.plist b/native/ios/App/Info.plist.in
similarity index 63%
rename from native/ios/App/Info.plist
rename to native/ios/App/Info.plist.in
index e5327a2ba..f0ba03100 100644
--- a/native/ios/App/Info.plist
+++ b/native/ios/App/Info.plist.in
@@ -1,5 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+ The app's Info.plist, as a template. `cli native --target ios --content <dir>`
+ substitutes the identity from the exported project's app.config.json and writes
+ Info.plist beside this file (gitignored), the same way the APK's manifest is
+ filled in. Everything not substituted is the host: Metal + arm64 required, no
+ status bar, a plain launch screen.
+-->
<plist version="1.0">
<dict>
<key>CFBundleDevelopmentRegion</key>
@@ -11,13 +18,15 @@
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundleName</key>
- <string>Estella</string>
+ <string>@APP_NAME@</string>
+ <key>CFBundleDisplayName</key>
+ <string>@APP_NAME@</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
- <string>1.0</string>
+ <string>@VERSION_NAME@</string>
<key>CFBundleVersion</key>
- <string>1</string>
+ <string>@VERSION_CODE@</string>
<key>LSRequiresIPhoneOS</key>
<true/>
<key>UILaunchScreen</key>
@@ -31,16 +40,11 @@
<true/>
<key>UISupportedInterfaceOrientations</key>
<array>
- <string>UIInterfaceOrientationPortrait</string>
- <string>UIInterfaceOrientationLandscapeLeft</string>
- <string>UIInterfaceOrientationLandscapeRight</string>
+@ORIENTATIONS@
</array>
<key>UISupportedInterfaceOrientations~ipad</key>
<array>
- <string>UIInterfaceOrientationPortrait</string>
- <string>UIInterfaceOrientationPortraitUpsideDown</string>
- <string>UIInterfaceOrientationLandscapeLeft</string>
- <string>UIInterfaceOrientationLandscapeRight</string>
+@ORIENTATIONS@
</array>
</dict>
</plist>
diff --git a/native/ios/project.yml b/native/ios/project.yml
index 9821cae1c..31e1f09c3 100644
--- a/native/ios/project.yml
+++ b/native/ios/project.yml
@@ -9,6 +9,13 @@
# under assets/ — the host reads both through the same project-relative paths.
name: EstellaiOS
+# The app's identity — bundle id and version — comes from the exported project,
+# written here by `cli native --target ios` (which must run before xcodegen
+# anyway: this project links the xcframework it produces). Keeping it out of this
+# committed file is what lets two projects build from one checkout.
+include:
+ - app.generated.yml
+
options:
bundleIdPrefix: com.estella
deploymentTarget:
@@ -29,7 +36,8 @@ targets:
type: folder
settings:
base:
- PRODUCT_BUNDLE_IDENTIFIER: com.estella.EstellaiOS
+ # PRODUCT_BUNDLE_IDENTIFIER / MARKETING_VERSION come from app.generated.yml.
+ # Info.plist is generated from App/Info.plist.in at the same time.
INFOPLIST_FILE: App/Info.plist
# -ObjC keeps the view controller / app delegate classes in the static
# library alive; the linker would otherwise drop TUs nothing references.