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
feat(native): an exported project becomes an app with its own identity
yhh946a2bfbbf27
diff --git a/.gitignore b/.gitignoreindex 5173d1dc7..ed65707cc 100644--- a/.gitignore+++ b/.gitignore@@ -130,3 +130,8 @@ docs/REARCH_*.mdnative/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.ymldiff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.jsindex 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.jsindex 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.jsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 thediff --git a/desktop/src/settings/projectSettings.ts b/desktop/src/settings/projectSettings.tsindex 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.mdindex 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 realgame never runs. A project's own scripts (`defineComponent` / `defineSystem`)diff --git a/native/android/host/AndroidManifest.xml b/native/android/host/AndroidManifest.xmldeleted file mode 100644index 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.innew file mode 100644index 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.insimilarity index 63%rename from native/ios/App/Info.plistrename to native/ios/App/Info.plist.inindex 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.ymlindex 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.estelladeploymentTarget:@@ -29,7 +36,8 @@ targets:type: foldersettings: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.