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.

docs(mobile): the Android & iOS guide, and the target lists that stopped at four

esengine6c20766fe68a
diff --git a/README.md b/README.md
index 5d42eb7eb..be0f02c39 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/esengine/estella)](https://github.com/esengine/estella/releases)
[![C++20](https://img.shields.io/badge/C%2B%2B-20-blue.svg)](https://isocpp.org/)
-[![Platform](https://img.shields.io/badge/Platform-Web%20%7C%20WeChat-green.svg)]()
+[![Platform](https://img.shields.io/badge/Platform-Web%20%7C%20Desktop%20%7C%20WeChat%20%7C%20Android%20%7C%20iOS-green.svg)]()
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/esengine/estella)
[Website](https://estellaengine.com) • [Getting Started](#getting-started) • [Documentation](#documentation) • [Discord](https://discord.gg/sAX6PXZ9) • [QQ群: 481923584](https://qm.qq.com/q/BONa5LXQ0U)
@@ -21,7 +21,7 @@
## What is Estella?
-Estella is a **2D game engine** with a TypeScript SDK driven by a high-performance **C++/WebAssembly** backend. It ships with a visual editor for scene editing and project management, and outputs games that run in **web browsers** and **WeChat MiniGames**.
+Estella is a **2D game engine** with a TypeScript SDK driven by a high-performance **C++/WebAssembly** backend. It ships with a visual editor for scene editing and project management, and outputs games that run in **web browsers**, on the **desktop**, in **WeChat MiniGames**, as single-file **playable ads**, and as native **Android / iOS** apps.
<div align="center">
<img src="docs/assets/editor-hero-c5bfd2f3.png" alt="An action-RPG scene open in the Estella editor" width="900" />
@@ -35,7 +35,7 @@ Estella is a **2D game engine** with a TypeScript SDK driven by a high-performan
- **Type-safe** — First-class TypeScript SDK with `defineSystem`, `defineComponent`, and `Query`
- **Data-oriented** — Entity-Component-System architecture for scalable game logic
- **Visual editor** — Scene hierarchy, inspector, asset browser — no JSON editing
-- **Cross-platform** — One codebase, deploy to web browsers and WeChat MiniGames
+- **Cross-platform** — One codebase, deploy to web, desktop, WeChat MiniGames, playable ads, and native mobile
- **Spine & Physics** — Built-in Spine animation and physics support
## Features
@@ -44,9 +44,10 @@ Estella is a **2D game engine** with a TypeScript SDK driven by a high-performan
|---------|-------------|
| **Visual Editor** | Scene editor with hierarchy, inspector, and asset management |
| **ECS Architecture** | Compose entities from reusable components, drive behavior with systems |
-| **WebGL Rendering** | Sprites, cameras, Spine animations, custom shaders — all in WebAssembly |
+| **WebGL / WebGPU Rendering** | Sprites, cameras, Spine animations, custom shaders — all in WebAssembly |
| **TypeScript SDK** | Type-safe API: `defineSystem`, `defineComponent`, `Query`, `Commands` |
-| **Cross-Platform** | Single codebase targeting web browsers and WeChat MiniGames |
+| **Cross-Platform** | One project → web, desktop, WeChat MiniGames, playable ads, and native Android / iOS |
+| **Native mobile** | A real arm64 app rendering through an embedded Dawn (Metal / Vulkan) — not a WebView |
## Getting Started
@@ -95,6 +96,8 @@ Full documentation: [estellaengine.com/docs](https://estellaengine.com/docs)
- [ECS Architecture](https://estellaengine.com/docs/core-concepts/ecs/)
- [Components](https://estellaengine.com/docs/core-concepts/components/)
- [Systems](https://estellaengine.com/docs/core-concepts/systems/)
+- [Building & Exporting](https://estellaengine.com/docs/guides/build-export/)
+- [Android & iOS](https://estellaengine.com/docs/guides/mobile/)
## Contributing
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 84620795a..d48d4e057 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -126,6 +126,7 @@ export default defineConfig({
{ label: 'Saving & Loading', translations: { 'zh-CN': '存档与读档' }, slug: 'guides/save' },
{ label: 'Localization', translations: { 'zh-CN': '本地化' }, slug: 'guides/localization' },
{ label: 'Building & Exporting', translations: { 'zh-CN': '构建与导出' }, slug: 'guides/build-export' },
+ { label: 'Android & iOS', translations: { 'zh-CN': 'Android 与 iOS' }, slug: 'guides/mobile' },
{ label: 'Hot Update', translations: { 'zh-CN': '热更新' }, slug: 'guides/hot-update' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
{ label: 'Mini-Game Platforms', translations: { 'zh-CN': '小游戏平台' }, slug: 'guides/minigame-platforms' },
diff --git a/docs/astro/src/assets/guides/en/build-dialog.png b/docs/astro/src/assets/guides/en/build-dialog.png
index a4c8f3964..b7f24a87d 100644
Binary files a/docs/astro/src/assets/guides/en/build-dialog.png and b/docs/astro/src/assets/guides/en/build-dialog.png differ
diff --git a/docs/astro/src/assets/guides/en/build-mobile.png b/docs/astro/src/assets/guides/en/build-mobile.png
new file mode 100644
index 000000000..8cf04124f
Binary files /dev/null and b/docs/astro/src/assets/guides/en/build-mobile.png differ
diff --git a/docs/astro/src/assets/guides/zh/build-dialog.png b/docs/astro/src/assets/guides/zh/build-dialog.png
index a3d75ce28..097ed17a3 100644
Binary files a/docs/astro/src/assets/guides/zh/build-dialog.png and b/docs/astro/src/assets/guides/zh/build-dialog.png differ
diff --git a/docs/astro/src/assets/guides/zh/build-mobile.png b/docs/astro/src/assets/guides/zh/build-mobile.png
new file mode 100644
index 000000000..c86b37216
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/build-mobile.png differ
diff --git a/docs/astro/src/content/docs/getting-started/introduction.mdx b/docs/astro/src/content/docs/getting-started/introduction.mdx
index f7049552b..776c0b276 100644
--- a/docs/astro/src/content/docs/getting-started/introduction.mdx
+++ b/docs/astro/src/content/docs/getting-started/introduction.mdx
@@ -6,7 +6,7 @@ description: What Estella is and why it exists.
Estella is a **2D game engine** with a TypeScript SDK driven by a
high-performance **C++/WebAssembly** backend. It ships with a visual editor for
scene editing and project management, and exports one project to **the web,
-desktop, WeChat MiniGames, and playable ads**.
+desktop, WeChat MiniGames, playable ads, and native Android / iOS apps**.
## Why Estella?
@@ -19,7 +19,8 @@ desktop, WeChat MiniGames, and playable ads**.
- **Visual editor** — scene hierarchy, inspector, and asset browser; no JSON
editing.
- **Cross-platform** — one project, exported to the web, desktop, WeChat
- MiniGames, and single-file playable ads.
+ MiniGames, single-file playable ads, and native Android / iOS apps (arm64 +
+ an embedded Dawn, not a WebView).
- **Batteries included** — physics, tilemaps, particles, materials & 2D lighting,
animation, Spine, audio, UI, and a gameplay AI layer.
@@ -29,7 +30,7 @@ desktop, WeChat MiniGames, and playable ads**.
|-------|--------------|
| **TypeScript SDK** (`esengine`) | The authored surface: `App`, `World`, systems, components, queries, plugins. |
| **WasmBridge** | The single boundary between the SDK and the engine, with a generated, hash-checked memory layout. |
-| **C++ / WebAssembly** | The engine core: ECS storage, the renderer (`GfxDevice`), resources, particles, tilemaps, text. |
+| **C++ / WebAssembly** | The engine core: ECS storage, the renderer (`GfxDevice`), resources, particles, tilemaps, text. On [mobile](/docs/guides/mobile/) the same core is compiled to arm64 instead. |
For the full architecture, see
[`ARCHITECTURE.md`](https://github.com/esengine/estella/blob/master/docs/ARCHITECTURE.md).
diff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdx
index f4b3eb136..dfd9fc0ad 100644
--- a/docs/astro/src/content/docs/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/guides/build-export.mdx
@@ -1,25 +1,27 @@
---
title: Building & Exporting
-description: Ship one project to Web, Desktop, WeChat MiniGame, or a single-file Playable Ad from the editor's Package Project dialog — build configs, output folders, packaging settings, and the runtime prerequisites.
+description: Ship one project to Web, Desktop, WeChat MiniGame, a single-file Playable Ad, or a native Android / iOS app from the editor's Package Project dialog — build configs, output folders, packaging settings, and the runtime prerequisites.
---
import { Aside, Steps } from '@astrojs/starlight/components';
-One Estella project ships to four targets — **Web**, **Desktop**, **WeChat
-MiniGame**, and a single-file **Playable Ad** — all from the editor. The export uses
-the **same runtime you played in the editor**, so what you shipped is what you tested
-(*play == ship*).
+One Estella project ships to six targets — **Web**, **Desktop**, **WeChat
+MiniGame**, a single-file **Playable Ad**, and native **Android** / **iOS** apps —
+all from the editor. The export uses the **same runtime you played in the editor**,
+so what you shipped is what you tested (*play == ship*).
## Exporting from the editor
-![The Build dialog — platform picker, configuration, output, and cook options](../../../assets/guides/en/build-dialog.png)
+![The Package Project dialog — the target list, build configuration, output folder, and scenes in build](../../../assets/guides/en/build-dialog.png)
-*The Build dialog: pick a **platform** (Web / Desktop / WeChat / Playable), a configuration, the output folder, and the cook options — then Build.*
+*The Package Project dialog: pick a **target** from the categorized list, a configuration, the output folder, and the [cook options](#asset-cook-options) — then Package.*
<Steps>
1. Open **File → Build…** to bring up the **Package Project** dialog.
-2. Pick a **platform** (Web / Desktop / WeChat / Playable).
+2. Pick a **target** from the list — grouped as *General* (Web / Desktop /
+ Playable), *Mini-games* (WeChat and any the project added), and *Mobile*
+ (Android / iOS).
3. Choose a **build config** — *Development* or *Shipping* (Shipping minifies) — an
**output folder**, source maps, and the [asset cook options](#asset-cook-options).
4. Check the **Scenes in build** list — untick scenes you don't want to ship, and
@@ -69,6 +71,12 @@ and opens it in your browser.
| **Desktop** | An Electron app source tree. | `dist-desktop/` | `cd dist-desktop && npm install && npm start` — or `npm run dist` for a native `.dmg` / `.exe` / AppImage installer. |
| **WeChat** | A WeChat MiniGame package. | `dist-wechat/` | Open the folder in WeChat DevTools and set your AppID. See [WeChat MiniGame](/docs/guides/wechat/). |
| **Playable** | One self-contained `index.html` with everything inlined — no external requests, as ad networks require. | `dist-playable/` | **Preview over http** (its real surface is an ad-network iframe). Pick the [ad network](#playable-ad-networks) so the CTA and the size check match where it ships. |
+| **Android** | Content for a **native** arm64 app (Vulkan) — a real APK, not a WebView. | `dist-android/` | `node build-tools/cli.js native --package --content dist-android` wraps it in a signed APK. See [Android & iOS](/docs/guides/mobile/). |
+| **iOS** | Content for a **native** arm64 app (Metal), plus the Xcode project when the engine is built for iOS here. | `dist-ios/` | Open the generated Xcode project, pick a signing team, Run. See [Android & iOS](/docs/guides/mobile/). |
+
+The mobile targets export app **content**, not a runnable payload: the engine, the
+SDK and the game runtime live in the app binary. That is also why they need a
+toolchain the other four do not — see [prerequisites](#runtime-prerequisites) below.
## Playable ad networks
@@ -138,8 +146,8 @@ packages through the same pipeline.
Web, Desktop and **Playable** all reuse the engine runtime that ships with the
editor, so they export with no setup — a playable inlines that same web runtime
(glue as a blob module, wasm as base64) rather than needing a build of its own.
-**WeChat** is the exception: its WebAssembly loader differs, so its runtime is built
-once:
+**WeChat** is the exception among the web-based targets: its WebAssembly loader
+differs, so its runtime is built once:
```bash
# only before the first WeChat export
@@ -153,6 +161,35 @@ module for each engine feature the game uses (`physics-wechat`, `spine-wechat`,
`basis-wechat` for compressed textures) — see
[WeChat MiniGame](/docs/guides/wechat/).
+The dialog distinguishes **two kinds** of missing prerequisite, because they don't
+block the same amount:
+
+- A missing **engine runtime** (Web / Playable / WeChat) means the package cannot
+ be produced at all.
+- A missing **native toolchain** (Android / iOS) does not. The export still writes
+ the app's content; only the final assembly into an installable app needs the
+ toolchain, and that step can run on another machine — an iOS build always does
+ when the editor is on Windows.
+
+<Aside type="caution" title="Mobile needs an engine checkout">
+ Android and iOS are the one pair of targets the editor download does not carry
+ end to end: the native host is built once from an engine source checkout (Dawn +
+ QuickJS), plus the Android SDK/NDK or macOS with Xcode. See
+ [Android & iOS](/docs/guides/mobile/).
+</Aside>
+
+## Content a target cannot render
+
+A target does not necessarily compile every subsystem the editor can author. When
+one doesn't, the export **names the gap and the scenes that hit it** rather than
+writing a package that is quietly missing half a scene — the warning lists the
+subsystem (tilemaps, particles, post-processing, physics, Spine, video, text) and
+the files that authored it.
+
+No target currently has a gap: the native app compiles the whole engine source
+list, and the three subsystems that are separate side modules on the web are
+compiled into its binary instead. The check stays because that can change.
+
## Side modules
Optional engine features ship as separate WebAssembly **side modules** — an
@@ -193,35 +230,56 @@ runtime API.
## Asset cook options
-The Package dialog also drives what the **cook** does to your assets:
-
-- **Compress audio** — re-encode WAV sources to MP3 at cook (per-asset Import
- Settings can opt a clip out or pick a bitrate; other audio formats pass
- through unchanged).
-- **Compress textures** — encode PNGs to GPU-ready **KTX2** (Basis Universal), which
- the runtime transcodes to the best format each device supports (ASTC → ETC2 → S3TC,
- falling back to RGBA8). Smaller downloads and less VRAM; leave off to ship raw PNGs.
-- **Pack `.atlas` folders** — pack the loose PNGs in each `<name>.atlas/` folder into
- atlas pages at cook time, so many small sprites ship as one texture and batch in one
- draw call.
-- **Content addressing** is on by default for Web/Desktop (each file named by a hash of
- its bytes — immutable URLs, automatic dedupe).
+What the **cook** does to an individual asset is that asset's own business —
+per-asset **Import Settings** in the Inspector, with a tab per platform, so a
+texture can be compressed harder for a phone than for the web. The build only
+picks whether to honor those settings at all:
+
+- **Compression → By import settings** — each texture and audio clip compresses per
+ its Import Settings (PNG → **KTX2** Basis Universal, Max Size, WAV → MP3), and
+ `<name>.atlas/` folders pack into atlas pages so many small sprites ship as one
+ texture and batch in one draw call.
+- **Compression → Skip all** — ship everything raw, for fast iteration.
+
+KTX2 textures are transcoded by the runtime to the best format each device
+supports (ASTC → ETC2 → S3TC, falling back to RGBA8), with their mip chains —
+smaller downloads and less VRAM.
+
+**Content addressing** is on by default for Web/Desktop (each file named by a hash
+of its bytes — immutable URLs, automatic dedupe). **Advanced** holds the CDN root
+for [hot update](/docs/guides/hot-update/), source maps, and whether to open the
+output folder when the build finishes.
+
+<Aside type="caution" title="Assets only your code names are culled">
+ The cook ships what it can **reach** from the scenes in the build. Anything named
+ only in code — a texture in rich-text markup, a clip played by url, a prefab
+ spawned by path — is culled, and the editor never notices because it serves the
+ project straight off disk. Mark that folder **Delivery → Always include in
+ builds** in the Content Browser. See
+ [Assets](/docs/guides/assets/#shipping-what-only-code-names).
+</Aside>
## Packaging settings
Per-target metadata lives in **Project Settings → Packaging** and is saved with the
project:
+- **Application ID** — the 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.
- **WeChat** — AppID.
-- **Desktop** — application id and product name (used to name the installer).
+- **Desktop** — application id override and product name (used to name the installer).
+- **Android** — version code, the integer Google Play orders builds by.
### Screen orientation
Orientation is **one project-wide setting**, not per-target: **Project Settings →
Display → Orientation** (portrait or landscape), right beside the design resolution.
Every target honors it — the WeChat `game.json` `deviceOrientation`, the web build's
-rotate-to-fit prompt (and a best-effort `screen.orientation.lock`), and the desktop
-window's aspect. Left unset, it's **derived from the design resolution's aspect**
+rotate-to-fit prompt (and a best-effort `screen.orientation.lock`), the desktop
+window's aspect, and the native app's `app.config.json` (the engine can letterbox
+but cannot rotate a phone). Left unset, it's **derived from the design resolution's aspect**
(wider-or-square ⇒ landscape, taller ⇒ portrait), so a landscape design ships
landscape everywhere with zero configuration.
@@ -246,15 +304,19 @@ node build-tools/cli.js build -t web # build the engine (web target)
node build-tools/cli.js build -t wechat # …the WeChat runtime
node build-tools/cli.js sdk # build the SDK only
node build-tools/cli.js watch # rebuild on change (engine dev)
+node build-tools/cli.js native --target ios # …the native mobile host
```
<Aside type="note">
Most game developers never run the build CLI beyond the one-time WeChat
- runtime builds — day-to-day work happens in the editor and the SDK.
+ runtime build — day-to-day work happens in the editor and the SDK. The
+ exception is [mobile](/docs/guides/mobile/), where the CLI is also what
+ assembles the app around an export.
</Aside>
## See also
+- [Android & iOS](/docs/guides/mobile/) — the native app: prerequisites, assembling it, and what only bites on a device.
- [WeChat MiniGame](/docs/guides/wechat/) — subpackage layout and platform-specific quirks.
- [Assets](/docs/guides/assets/) — how the cook step bundles and content-addresses assets.
- [Profiling & Diagnostics](/docs/guides/profiling/) — check frame time and draw calls before you ship.
diff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/guides/mobile.mdx
new file mode 100644
index 000000000..286753db5
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/mobile.mdx
@@ -0,0 +1,215 @@
+---
+title: Android & iOS
+description: Package an Estella project as a real native mobile app — an arm64 build rendering through an embedded Dawn (Metal / Vulkan), not a WebView. Toolchain prerequisites, the export, assembling the app, and what only bites on a device.
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+**Android** and **iOS** package your project as a **real native app**: the engine's
+C++ core compiled to arm64, rendering through an embedded
+[Dawn](https://dawn.googlesource.com/dawn) (WebGPU → **Metal** on iOS, **Vulkan** on
+Android), with your game scripts running on an embedded JS engine
+([QuickJS-ng](https://github.com/quickjs-ng/quickjs)). It is **not** a WebView and
+not a wrapper around the web build — there is no browser in the process.
+
+The authoring model is identical to every other target. The same scenes, the same
+components, the same TypeScript. Nothing in a project is mobile-specific.
+
+<Aside type="caution" title="Pre-1.0 — needs an engine checkout">
+ Unlike Web / Desktop / WeChat / Playable, the mobile targets are **not
+ self-contained in the editor download**. Assembling the installable app needs
+ the native host built once from an engine source checkout, plus the platform's
+ own toolchain (see [Prerequisites](#prerequisites)). The editor still exports
+ the app's *content* from any install — that half never needs a toolchain.
+</Aside>
+
+## Two platforms, one runtime
+
+Android and iOS are offered as **two targets, not one "Mobile"**, because they
+package through entirely different toolchains (Android SDK + NDK vs. Xcode) — one
+row could not tell you what to run, whether this machine can run it, or where the
+package comes out.
+
+They do share **one runtime and one export payload**. The engine, the SDK and the
+game runtime all live in the app binary, so what an export writes is app
+**content** — your scenes, scripts and cooked assets — rather than a runnable
+package the way `dist-web/` is.
+
+| | Android | iOS |
+|---|---|---|
+| Graphics | Vulkan (via Dawn) | Metal (via Dawn) |
+| Export output | `dist-android/` | `dist-ios/` |
+| Assembled by | `aapt2` + `apksigner` (Android SDK/NDK) | Xcode |
+| Assembly host OS | any desktop OS | **macOS only** |
+| Result | a signed `.apk` | an Xcode project you open, sign and run |
+
+## Prerequisites
+
+The Package dialog distinguishes **two kinds** of missing prerequisite, and they
+are not the same severity:
+
+- A missing **engine runtime** means the package cannot be produced at all.
+- A missing **native toolchain** does not. The export still writes the app's
+ content; only the final assembly needs the toolchain, and **that step can run on
+ another machine** — an iOS build always does when the editor is on Windows.
+
+![The Package Project dialog with the Android target selected, warning that the Android SDK was not found](../../../assets/guides/en/build-mobile.png)
+
+*Package Project → **MOBILE → Android**. The warning names the missing piece and says exactly how much it blocks: the content is written either way.*
+
+<Steps>
+
+1. **Build the native host once.** Dawn and QuickJS are multi-GB / separate
+ projects, so they are fetched rather than vendored. The one-time recipe (and
+ the exact `cmake` invocations) is in
+ [`native/README.md`](https://github.com/esengine/estella/blob/master/native/README.md).
+
+2. **Install the platform toolchain.**
+ - *Android* — Android SDK + **NDK r28**. The editor finds it via `ANDROID_HOME`
+ or Android Studio's default install location.
+ - *iOS* — **macOS with Xcode**. Apple ships no toolchain for other operating
+ systems, so the dialog says so rather than pretending otherwise.
+
+3. **Check the dialog.** The target's row carries a warning triangle until the
+ probe passes, and the panel names what is missing.
+
+</Steps>
+
+## Exporting
+
+<Steps>
+
+1. **File → Build…**, then pick **Android** or **iOS** under **MOBILE**.
+2. Choose a build config and an output folder (`dist-android` / `dist-ios` by
+ default). Source maps are not offered — there is no browser devtools to
+ consume them.
+3. Check **Scenes in build** as you would for any target.
+4. **Package**. The export cooks assets, bundles scripts, and writes the app's
+ content plus an `app.config.json` carrying the app's identity.
+
+</Steps>
+
+Then assemble the app around that content:
+
+```bash
+# Android — writes a signed APK (debug keystore unless --keystore says otherwise)
+node build-tools/cli.js native --package --content dist-android
+
+# iOS (on a Mac) — writes the Xcode project around the content
+node build-tools/cli.js native --target ios --package --content dist-ios
+```
+
+<Aside type="tip" title="iOS: the export can write the Xcode project for you">
+ When the engine has been built for iOS on the same machine, the **export itself**
+ emits the Xcode project — generating one needs no compiler (the engine is a
+ prebuilt `.xcframework`, and the app shell is a `main.m` plus a plist), so it
+ belongs in the export rather than behind a command you have to find. Open it,
+ pick your signing team, and Run. If the engine was never built for iOS here, the
+ export still writes the content and says which command produces the missing piece.
+</Aside>
+
+## App identity
+
+A native app has OS-level properties the engine never reads — the runtime cannot
+rotate a phone, and a store keeps a bundle id forever — so they are declared for
+whoever assembles the app, in **Project Settings → Packaging**:
+
+| Setting | What it becomes |
+|---|---|
+| **Application ID** | The Android manifest package and the iOS bundle id (reverse-DNS). Left empty it is derived from the project name; a published app should set its own. |
+| **Android Version Code** | The integer Google Play orders builds by — it must increase with every upload. The version users see comes from the project version. |
+| **Orientation** | *Project Settings → Display → Orientation*, one project-wide setting every target honors. Left unset it follows the design resolution's aspect. |
+
+The export writes these into `app.config.json` beside the content — deliberately
+**not** in `game.config.json`, which is what the runtime reads.
+
+## What runs on a device
+
+**Everything.** The mobile targets compile the whole engine source list, and the
+three subsystems that ship as separate WebAssembly side modules on the web
+(Box2D, the Spine runtime, the MPEG-1 video decoder) are compiled **into the app
+binary** instead — a device has no dynamic-linking story and no reason for one.
+`app.sideModules` still answers for them, so the runtime's own feature gating
+behaves exactly as it does in a browser.
+
+| Subsystem | On device |
+|---|---|
+| Sprites, tilemaps, particles, post-processing | Native (Dawn) |
+| Text, bitmap text, rich text | Same atlas + layout as the web; glyphs rasterized from the OS font |
+| Physics (Box2D) | Compiled in; solved across worker threads |
+| Spine | Compiled in — one runtime version per binary (`-DESTELLA_SPINE_VERSION`) |
+| Video | Compiled in (cooked at build, decoded on device) |
+| Audio | Native mixer ([miniaudio](https://miniaud.io/)) — CoreAudio / AAudio |
+| Text input | The platform's **soft keyboard** is the field's editing surface |
+| Networking | The OS network stack (`NSURLSession` / `HttpURLConnection`) |
+| Compressed textures | KTX2 transcoded to the device's format (ASTC → ETC2 → BC), with mip chains |
+| Lifecycle | `onShow` / `onHide` and OS memory warnings reach the app |
+
+If a future build ever *does* drop a subsystem, the export names it — with the
+scenes that use it — instead of quietly shipping a package missing half a scene.
+
+## What only bites on a device
+
+These are the differences worth knowing before your first device build. Each one
+shipped broken at least once because the editor serves a project straight off
+disk and never notices.
+
+### Assets only your code names get culled
+
+A build ships what it can **reach** from the entry scenes. That is right for
+anything a scene names — and blind to anything named **only in code**: a texture
+in rich-text markup, a clip played by url, a prefab spawned by path. Those get
+culled, and the first you hear of it is a silent button or a missing image on the
+phone.
+
+Mark the folder in the **Content Browser**: right-click → **Delivery → Always
+include in builds**. It writes `alwaysInclude` into the same
+`.esengine/asset-groups.json` that already decides local / subpackage / remote
+delivery:
+
+```json
+{
+ "version": "1.0",
+ "groups": {
+ "markup-images": {
+ "folder": "assets/textures",
+ "mode": "local",
+ "alwaysInclude": true
+ }
+ }
+}
+```
+
+Off by default, deliberately — reachability is what keeps a build from shipping
+everything. See [Assets](/docs/guides/assets/#shipping-what-only-code-names).
+
+### Tune textures for the platform where memory is tightest
+
+Per-asset **Import Settings** have a tab per platform, mobile targets included —
+so a texture can be compressed harder for a phone than for the web without
+touching the source PNG. See [Assets](/docs/guides/assets/).
+
+### Your game script is interpreted
+
+The engine runs native at full speed; **only your game script** runs on QuickJS,
+which has no JIT (Apple's rules leave no other option, and Android is kept
+identical rather than divergent). A per-entity loop written in TypeScript is the
+one thing that costs meaningfully more here than in a browser — prefer the
+engine's own systems and bulk APIs over hand-written per-entity iteration in the
+hot path.
+
+### The first launch after an install
+
+Parsing the SDK bundle on a device takes ~14 s, and a compile cache does not exist
+until one launch has paid for it — which would be the launch right after an
+install. So the **bytecode is built with the app** and rides along in its assets:
+fresh-install-to-first-frame is ~0.6 s rather than 14.4 s. It is best effort (it
+needs a compiler for the build machine); a machine without one still produces a
+working app that compiles on first run.
+
+## See also
+
+- [Building & Exporting](/docs/guides/build-export/) — every target, the cook options, and the Package dialog.
+- [Assets](/docs/guides/assets/) — reachability culling, delivery groups, and import settings.
+- [Screen & Design Resolution](/docs/core-concepts/screen/) — designing for a phone's aspect.
+- [`native/README.md`](https://github.com/esengine/estella/blob/master/native/README.md) — the host's architecture and the full build recipe.
diff --git a/docs/astro/src/content/docs/index.mdx b/docs/astro/src/content/docs/index.mdx
index b1e493c71..b31c7730d 100644
--- a/docs/astro/src/content/docs/index.mdx
+++ b/docs/astro/src/content/docs/index.mdx
@@ -3,7 +3,7 @@ title: Estella
description: A fast 2D game engine powered by WebAssembly and ECS, with a visual editor.
template: splash
hero:
- tagline: A fast 2D game engine with a TypeScript SDK, a C++/WebAssembly core, and a visual editor. Ship one project to the web, desktop, WeChat MiniGames, and playable ads.
+ tagline: A fast 2D game engine with a TypeScript SDK, a C++/WebAssembly core, and a visual editor. Ship one project to the web, desktop, WeChat MiniGames, playable ads, and native Android / iOS apps.
actions:
- text: Get Started
link: /docs/getting-started/introduction/
@@ -40,8 +40,8 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
UI, and a gameplay AI layer.
</Card>
<Card title="Cross-platform" icon="laptop">
- One project, exported to the web, desktop, WeChat MiniGames, and single-file
- playable ads.
+ One project, exported to the web, desktop, WeChat MiniGames, single-file
+ playable ads, and native Android / iOS apps.
</Card>
</CardGrid>
@@ -53,5 +53,5 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
<LinkCard title="Sprites & Rendering" href="/docs/guides/sprites/" description="Draw images — tint, size, sort, and layer them." />
<LinkCard title="Physics" href="/docs/guides/physics/" description="Rigid bodies, colliders, joints, and spatial queries." />
<LinkCard title="Gameplay AI" href="/docs/guides/ai/" description="Navigation, perception, state machines, behavior trees." />
- <LinkCard title="Building & Exporting" href="/docs/guides/build-export/" description="Ship to web, desktop, WeChat, and playable ads." />
+ <LinkCard title="Building & Exporting" href="/docs/guides/build-export/" description="Ship to web, desktop, WeChat, playable ads, Android and iOS." />
</CardGrid>
diff --git a/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx b/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx
index 12d92e27d..7f331fa97 100644
--- a/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx
+++ b/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx
@@ -5,7 +5,7 @@ description: Estella 是什么,以及它为什么存在。
Estella 是一个 **2D 游戏引擎**:上层是 TypeScript SDK,底层由高性能的
**C++/WebAssembly** 内核驱动。它自带一个用于场景编辑与项目管理的可视化编辑器,
-把一个项目导出到 **Web、桌面、微信小游戏和 Playable 广告**。
+把一个项目导出到 **Web、桌面、微信小游戏、Playable 广告,以及原生 Android / iOS 应用**。
## 为什么选择 Estella?
@@ -14,7 +14,8 @@ Estella 是一个 **2D 游戏引擎**:上层是 TypeScript SDK,底层由高
`Query`。
- **数据导向** —— Entity-Component-System 架构,游戏逻辑可规模化扩展。
- **可视化编辑器** —— 场景层级、检视面板、资源浏览器,无需手写 JSON。
-- **跨平台** —— 一个项目,导出到 Web、桌面、微信小游戏和单文件 Playable 广告。
+- **跨平台** —— 一个项目,导出到 Web、桌面、微信小游戏、单文件 Playable 广告,
+ 以及原生 Android / iOS 应用(arm64 + 内嵌 Dawn,不是 WebView)。
- **开箱即用** —— 物理、瓦片地图、粒子、材质与 2D 光照、动画、Spine、音频、UI,
以及一套游戏 AI 层。
@@ -24,7 +25,7 @@ Estella 是一个 **2D 游戏引擎**:上层是 TypeScript SDK,底层由高
|----|------|
| **TypeScript SDK**(`esengine`) | 你编写的界面:`App`、`World`、系统、组件、查询、插件。 |
| **WasmBridge** | SDK 与引擎之间的唯一边界,内存布局由生成器产出并经哈希校验。 |
-| **C++ / WebAssembly** | 引擎内核:ECS 存储、渲染器(`GfxDevice`)、资源、粒子、瓦片地图、文本。 |
+| **C++ / WebAssembly** | 引擎内核:ECS 存储、渲染器(`GfxDevice`)、资源、粒子、瓦片地图、文本。在[移动端](/docs/zh-cn/guides/mobile/),同一份内核改为编译到 arm64。 |
完整架构见
[`ARCHITECTURE.md`](https://github.com/esengine/estella/blob/master/docs/ARCHITECTURE.md)。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
index 4a94f3a0f..cd5f9d07d 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
@@ -1,24 +1,25 @@
---
title: 构建与导出
-description: 从编辑器的"打包项目"对话框把一个项目发布到 Web、桌面、微信小游戏或单文件 Playable 广告——构建配置、输出目录、打包设置与运行时前置条件。
+description: 从编辑器的"打包项目"对话框把一个项目发布到 Web、桌面、微信小游戏、单文件 Playable 广告,或原生 Android / iOS 应用——构建配置、输出目录、打包设置与运行时前置条件。
---
import { Aside, Steps } from '@astrojs/starlight/components';
-一个 Estella 项目可发布到四个目标——**Web**、**桌面**、**微信小游戏**和单文件 **Playable 广告**
-——全部从编辑器完成。导出用的是**你在编辑器里运行的同一套运行时**,所以你发布的就是你测过的
-(*play == ship*)。
+一个 Estella 项目可发布到六个目标——**Web**、**桌面**、**微信小游戏**、单文件 **Playable 广告**,
+以及原生 **Android** / **iOS** 应用——全部从编辑器完成。导出用的是**你在编辑器里运行的同一套运行时**,
+所以你发布的就是你测过的(*play == ship*)。
## 从编辑器导出
-![打包对话框——平台选择器、配置、输出与 cook 选项](../../../../assets/guides/zh/build-dialog.png)
+![打包项目对话框——目标列表、构建配置、输出目录与构建场景](../../../../assets/guides/zh/build-dialog.png)
-*打包对话框:选一个**平台**(Web / 桌面 / 微信 / Playable)、一个配置、输出目录,以及 cook 选项——然后构建。*
+*打包项目对话框:从分组的列表里选一个**目标**、一个配置、输出目录,以及 [cook 选项](#资产烘焙选项)——然后 Package。*
<Steps>
1. 打开 **文件 → Build…** 调出 **打包项目(Package Project)** 对话框。
-2. 选一个**平台**(Web / 桌面 / 微信 / Playable)。
+2. 从列表里选一个**目标**——分为*通用*(Web / 桌面 / Playable)、*小游戏*
+ (微信,以及项目自己添加的)、*移动*(Android / iOS)。
3. 选一个**构建配置**——*Development* 或 *Shipping*(Shipping 会压缩)——一个**输出目录**、
source map,以及[资产烘焙选项](#资产烘焙选项)。
4. 检查**构建场景(Scenes in build)**列表——取消勾选不想发布的场景,需要的话换一个
@@ -60,6 +61,11 @@ import { Aside, Steps } from '@astrojs/starlight/components';
| **桌面** | 一棵 Electron 应用源码树。 | `dist-desktop/` | `cd dist-desktop && npm install && npm start`——或 `npm run dist` 出原生 `.dmg` / `.exe` / AppImage 安装包。 |
| **微信** | 一个微信小游戏包。 | `dist-wechat/` | 在微信开发者工具里打开该文件夹并设置你的 AppID。见 [微信小游戏](/docs/zh-cn/guides/wechat/)。 |
| **Playable** | 一个自包含的 `index.html`,一切内联——无外部请求(广告平台的要求)。 | `dist-playable/` | **Preview over http**(它的真实宿主是广告平台的 iframe)。先选好[广告平台](#试玩广告平台),CTA 与体积检查才对得上投放目标。 |
+| **Android** | **原生** arm64 应用(Vulkan)的内容——真 APK,不是 WebView。 | `dist-android/` | `node build-tools/cli.js native --package --content dist-android` 把它包成已签名的 APK。见 [Android 与 iOS](/docs/zh-cn/guides/mobile/)。 |
+| **iOS** | **原生** arm64 应用(Metal)的内容;若本机已为 iOS 构建过引擎,还会附带 Xcode 工程。 | `dist-ios/` | 打开生成的 Xcode 工程,选签名 Team,Run。见 [Android 与 iOS](/docs/zh-cn/guides/mobile/)。 |
+
+移动目标导出的是应用**内容**而非可直接运行的载荷:引擎、SDK 和游戏运行时都住在应用二进制里。
+这也是它们需要另外四个目标不需要的工具链的原因——见下文的[前置条件](#运行时前置条件)。
## 试玩广告平台
@@ -120,8 +126,8 @@ export default {
## 运行时前置条件
Web、桌面与 **Playable** 都复用随编辑器附带的引擎运行时,所以导出无需准备——试玩包内联的
-就是同一份 web 运行时(glue 作为 blob 模块、wasm 以 base64 传入),不需要单独构建。**微信**是
-例外:它的 WebAssembly 加载器不同,运行时需先构建一次:
+就是同一份 web 运行时(glue 作为 blob 模块、wasm 以 base64 传入),不需要单独构建。在这些基于
+网页的目标里 **微信**是例外:它的 WebAssembly 加载器不同,运行时需先构建一次:
```bash
# 仅在首次微信导出前
@@ -133,6 +139,28 @@ node build-tools/cli.js build -t wechat
侧模块(`physics-wechat`、`spine-wechat`,压缩纹理用 `basis-wechat`)——见
[微信小游戏](/docs/zh-cn/guides/wechat/)。
+对话框区分**两类**缺失的前置条件,因为它们挡住的程度并不一样:
+
+- 缺**引擎运行时**(Web / Playable / 微信)意味着根本产不出包。
+- 缺**原生工具链**(Android / iOS)则不然。导出照样把应用内容写出来;只有最后组装成
+ 可安装应用那一步需要工具链,而那一步可以在另一台机器上跑——编辑器在 Windows 上时,
+ iOS 构建本来就得如此。
+
+<Aside type="caution" title="移动端需要引擎源码检出">
+ Android 和 iOS 是唯一一对编辑器下载包没有端到端自带的目标:原生宿主需要先从引擎源码
+ 检出构建一次(Dawn + QuickJS),再加上 Android SDK/NDK,或装有 Xcode 的 macOS。见
+ [Android 与 iOS](/docs/zh-cn/guides/mobile/)。
+</Aside>
+
+## 目标渲染不了的内容
+
+一个目标未必编译了编辑器能创作的每个子系统。当它确实缺某个子系统时,导出会**点名这个缺口
+以及踩到它的场景**,而不是写出一个悄悄少了半个场景的包——警告会列出子系统(瓦片地图、粒子、
+后处理、物理、Spine、视频、文本)和创作它的文件。
+
+目前没有任何目标存在缺口:原生应用编译整份引擎源码清单,网页端作为独立侧模块的那三个子系统
+在这里是编进二进制的。这项检查保留着,因为情况可能变。
+
## 侧模块
可选的引擎特性以独立的 WebAssembly **侧模块**发布——每个模块是一对 emscripten
@@ -164,27 +192,41 @@ node build-tools/cli.js build -t wechat
## 资产烘焙选项
-打包对话框还控制**烘焙**如何处理你的资产:
+烘焙如何处理**某一个**资产,是那个资产自己的事——在检视面板的逐资产**导入设置**里,
+每个平台一个页签,所以一张纹理可以为手机压得比网页端更狠。构建这一层只决定是否遵循这些设置:
-- **压缩音频** —— 打包时把 WAV 源重编码为 MP3(可在资产的导入设置中单独关闭或选码率;
- 其他音频格式原样通过)。
-- **压缩纹理** —— 把 PNG 编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
- 设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8)。下载更小、显存更省;关掉则
- 发布原始 PNG。
-- **打包 `.atlas` 文件夹** —— 烘焙时把每个 `<name>.atlas/` 文件夹里零散的 PNG 打包成图集页,
+- **资源压缩 → 按导入设置** —— 每张纹理与每段音频按各自的导入设置压缩
+ (PNG → **KTX2** Basis Universal、Max Size、WAV → MP3),`<name>.atlas/` 文件夹打包成图集页,
于是许多小精灵作为一张纹理发布、在一次绘制里合批。
-- **内容寻址** 对 Web/桌面默认开启(每个文件按字节哈希命名——URL 不可变、自动去重)。
+- **资源压缩 → 全部跳过** —— 一律原样输出,便于快速迭代。
+
+KTX2 纹理由运行时转码为设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8),并带上
+mip 链——下载更小、显存更省。
+
+**内容寻址** 对 Web/桌面默认开启(每个文件按字节哈希命名——URL 不可变、自动去重)。
+**高级**里放着[热更新](/docs/zh-cn/guides/hot-update/)的 CDN 根地址、source map,
+以及构建结束后是否打开输出目录。
+
+<Aside type="caution" title="只有代码点名的资产会被剔除">
+ cook 发布的是它能从构建场景**可达**的东西。只在代码里点名的东西——富文本标记里的纹理、
+ 按 url 播放的音频、按路径 spawn 的预制体——会被剔除,而编辑器直接从磁盘伺服项目,
+ 根本不会察觉。请在内容浏览器里把那个文件夹标记为 **交付方式 → 总是打进构建**。见
+ [资源](/docs/zh-cn/guides/assets/#只有代码点名的资产)。
+</Aside>
## 打包设置
每个目标的元数据在 **项目设置 → 打包(Packaging)** 里,并随项目保存:
+- **应用 ID** —— 已安装应用的反向域名 id:Android 的 manifest package、iOS 的 bundle id、
+ 桌面安装包的 id。留空则按项目名推导;正式发布的应用应当自己指定,因为应用商店会永久沿用它。
- **微信** —— AppID。
-- **桌面** —— 应用 id 和产品名(用于命名安装包)。
+- **桌面** —— 应用 id 覆盖和产品名(用于命名安装包)。
+- **Android** —— 版本号,Google Play 用来排序构建的整数。
### 屏幕方向
-方向是**一个项目级设置**,而非逐平台:**项目设置 → 显示(Display) → 屏幕方向**(竖屏或横屏),就在设计分辨率旁边。所有目标都遵循它——微信 `game.json` 的 `deviceOrientation`、Web 构建的"请旋转设备"提示(以及尽力而为的 `screen.orientation.lock`)、桌面窗口的宽高比。留空则**从设计分辨率的宽高比推导**(更宽或方形 ⇒ 横屏,更高 ⇒ 竖屏),因此横屏设计零配置即在各处横屏发布。
+方向是**一个项目级设置**,而非逐平台:**项目设置 → 显示(Display) → 屏幕方向**(竖屏或横屏),就在设计分辨率旁边。所有目标都遵循它——微信 `game.json` 的 `deviceOrientation`、Web 构建的"请旋转设备"提示(以及尽力而为的 `screen.orientation.lock`)、桌面窗口的宽高比,以及原生应用的 `app.config.json`(引擎能 letterbox,却转不动手机)。留空则**从设计分辨率的宽高比推导**(更宽或方形 ⇒ 横屏,更高 ⇒ 竖屏),因此横屏设计零配置即在各处横屏发布。
**试玩包是有意的例外**:它从不锁定页面方向。在广告 SDK 里,容器尺寸由 SDK 决定,因此"请旋转设备"这类遮罩可能把游戏永久挡住——玩家转了手机却毫无变化,因为那条 media query 一直在读容器而不是设备。试玩包保持自适应(各平台都要求如此),方向只在平台需要时**声明**出去,例如 Google 的 `ad.orientation` meta 标签。请为两种比例都设计,或用[相机适配](#)做 letterbox,让构图在任一比例下都成立。
@@ -200,15 +242,18 @@ node build-tools/cli.js build -t web # 构建引擎(web 目标)
node build-tools/cli.js build -t wechat # …微信运行时
node build-tools/cli.js sdk # 只构建 SDK
node build-tools/cli.js watch # 改动即重建(引擎开发)
+node build-tools/cli.js native --target ios # …原生移动宿主
```
<Aside type="note">
- 大多数游戏开发者除了那一次性的微信 / Playable 运行时构建外,从不需要动构建 CLI——日常工作都在
- 编辑器和 SDK 里。
+ 大多数游戏开发者除了那一次性的微信运行时构建外,从不需要动构建 CLI——日常工作都在
+ 编辑器和 SDK 里。例外是[移动端](/docs/zh-cn/guides/mobile/):在那里,围绕导出组装应用
+ 也由这个 CLI 完成。
</Aside>
## 参见
+- [Android 与 iOS](/docs/zh-cn/guides/mobile/) —— 原生应用:前置条件、如何组装,以及只在真机上才咬人的那些事。
- [微信小游戏](/docs/zh-cn/guides/wechat/) —— 分包布局与平台差异。
- [资源](/docs/zh-cn/guides/assets/) —— cook 步骤如何打包与内容寻址资产。
- [性能剖析与诊断](/docs/zh-cn/guides/profiling/) —— 发布前检查帧时间与 draw call。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
new file mode 100644
index 000000000..aef7fdbe4
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
@@ -0,0 +1,192 @@
+---
+title: Android 与 iOS
+description: 把 Estella 项目打包成真正的原生移动应用——arm64 构建,经内嵌 Dawn(Metal / Vulkan)渲染,而不是 WebView。工具链前置条件、导出、组装应用,以及只在真机上才会咬人的那些事。
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+**Android** 和 **iOS** 把你的项目打包成**真正的原生应用**:引擎的 C++ 核心编译到 arm64,
+经内嵌的 [Dawn](https://dawn.googlesource.com/dawn) 渲染(WebGPU → iOS 上是 **Metal**、
+Android 上是 **Vulkan**),游戏脚本跑在内嵌的 JS 引擎
+([QuickJS-ng](https://github.com/quickjs-ng/quickjs))上。它**不是** WebView,
+也不是网页构建的壳——这个进程里没有浏览器。
+
+创作模型和其他任何目标完全一致。同样的场景、同样的组件、同样的 TypeScript。
+项目里没有任何东西是"移动端专用"的。
+
+<Aside type="caution" title="Pre-1.0——需要引擎源码检出">
+ 和 Web / 桌面 / 微信 / Playable 不同,移动目标**并不是编辑器下载包里自带齐全的**。
+ 组装可安装的应用需要先从引擎源码检出把原生宿主构建一次,再加上该平台自己的工具链
+ (见[前置条件](#前置条件))。编辑器在任何安装下都仍然能导出应用的*内容*——那一半从来不需要工具链。
+</Aside>
+
+## 两个平台,一套运行时
+
+Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们经由完全不同的工具链打包
+(Android SDK + NDK 对 Xcode)——一行说不清该运行什么、这台机器能不能运行、
+以及包会出在哪里。
+
+它们确实共享**同一套运行时和同一份导出载荷**。引擎、SDK 和游戏运行时都住在应用二进制里,
+所以导出写出的是应用**内容**——你的场景、脚本和烘焙后的资产——而不是像 `dist-web/`
+那样可直接运行的包。
+
+| | Android | iOS |
+|---|---|---|
+| 图形 | Vulkan(经 Dawn) | Metal(经 Dawn) |
+| 导出产物 | `dist-android/` | `dist-ios/` |
+| 组装工具 | `aapt2` + `apksigner`(Android SDK/NDK) | Xcode |
+| 组装所需系统 | 任意桌面系统 | **仅 macOS** |
+| 结果 | 一个已签名的 `.apk` | 一个可打开、签名并运行的 Xcode 工程 |
+
+## 前置条件
+
+打包对话框区分**两类**缺失的前置条件,二者严重程度并不相同:
+
+- 缺**引擎运行时**意味着根本产不出包。
+- 缺**原生工具链**则不然。导出照样把应用内容写出来;只有最后的组装步骤需要工具链,
+ 而**那一步可以在另一台机器上跑**——编辑器在 Windows 上时,iOS 构建本来就得如此。
+
+![打包项目对话框选中 Android 目标,提示未找到 Android SDK](../../../../assets/guides/zh/build-mobile.png)
+
+*打包项目 → **移动 → Android**。警告会点名缺的是哪一块,并说清它到底挡住了多少:内容无论如何都会写出来。*
+
+<Steps>
+
+1. **把原生宿主构建一次。** Dawn 和 QuickJS 体量数 GB、又是独立项目,所以是按需拉取而不是
+ vendored 进来。一次性的构建配方(以及确切的 `cmake` 调用)见
+ [`native/README.md`](https://github.com/esengine/estella/blob/master/native/README.md)。
+
+2. **装好平台工具链。**
+ - *Android* —— Android SDK + **NDK r28**。编辑器通过 `ANDROID_HOME` 或
+ Android Studio 的默认安装位置找到它。
+ - *iOS* —— **装有 Xcode 的 macOS**。Apple 不为其他操作系统提供工具链,
+ 所以对话框直说,而不是假装可以。
+
+3. **看对话框。** 探测通过之前,该目标那一行会一直带着警告三角,面板里会点名缺什么。
+
+</Steps>
+
+## 导出
+
+<Steps>
+
+1. **文件 → Build…**,在**移动**分组下选 **Android** 或 **iOS**。
+2. 选构建配置和输出目录(默认 `dist-android` / `dist-ios`)。这里不提供 source map——
+ 没有浏览器 devtools 来消费它。
+3. 和其他目标一样检查**构建场景**列表。
+4. **Package**。导出会烘焙资产、打包脚本,写出应用内容,外加一份携带应用身份的
+ `app.config.json`。
+
+</Steps>
+
+然后围绕这份内容组装应用:
+
+```bash
+# Android —— 写出已签名的 APK(未用 --keystore 指定时用 debug keystore)
+node build-tools/cli.js native --package --content dist-android
+
+# iOS(在 Mac 上)—— 围绕内容写出 Xcode 工程
+node build-tools/cli.js native --target ios --package --content dist-ios
+```
+
+<Aside type="tip" title="iOS:导出可以直接帮你写出 Xcode 工程">
+ 当引擎已经在同一台机器上为 iOS 构建过时,**导出本身**就会生成 Xcode 工程——生成它不需要
+ 编译器(引擎是预构建的 `.xcframework`,应用外壳只是一个 `main.m` 加一份 plist),
+ 所以它属于导出流程,而不该藏在一条你得自己找到的命令后面。打开它,选好签名 Team,Run。
+ 如果这台机器从未为 iOS 构建过引擎,导出仍会写出内容,并告诉你哪条命令能补上缺的那块。
+</Aside>
+
+## 应用身份
+
+原生应用有一些引擎永远不读的系统级属性——运行时转不动手机,而应用商店会永久沿用 bundle id
+——所以它们是写给"组装应用的人"看的,位置在 **项目设置 → 打包**:
+
+| 设置 | 它会变成什么 |
+|---|---|
+| **应用 ID** | Android 的 manifest package 和 iOS 的 bundle id(反向域名)。留空则按项目名推导;正式发布的应用应当自己指定。 |
+| **Android 版本号** | Google Play 用来排序构建的整数,每次上传都必须递增。用户看到的版本号来自项目版本。 |
+| **朝向** | *项目设置 → 显示 → 朝向*,一个项目级设置,所有目标都遵守。不设则跟随设计分辨率的宽高比。 |
+
+导出把这些写进内容旁边的 `app.config.json`——刻意**不**放进 `game.config.json`,
+后者才是运行时读的那份。
+
+## 真机上跑得起来的东西
+
+**全部。** 移动目标编译整份引擎源码清单;在网页端以独立 WebAssembly side module 发布的
+三个子系统(Box2D、Spine 运行时、MPEG-1 视频解码器)在这里是**编进应用二进制**的——
+设备没有动态链接这套故事,也没有理由要有。`app.sideModules` 仍然如实作答,
+所以运行时自己的特性门控和浏览器里表现一致。
+
+| 子系统 | 真机上 |
+|---|---|
+| 精灵、瓦片地图、粒子、后处理 | 原生(Dawn) |
+| 文本、位图字体、富文本 | 与网页端相同的图集与排版;字形从系统字体栅格化 |
+| 物理(Box2D) | 编译进包;跨工作线程求解 |
+| Spine | 编译进包——每个二进制一个运行时版本(`-DESTELLA_SPINE_VERSION`) |
+| 视频 | 编译进包(构建时 cook,真机解码) |
+| 音频 | 原生混音器([miniaudio](https://miniaud.io/))—— CoreAudio / AAudio |
+| 文本输入 | 平台**软键盘**就是输入框的编辑面 |
+| 网络 | 系统网络栈(`NSURLSession` / `HttpURLConnection`) |
+| 压缩纹理 | KTX2 转码到设备支持的格式(ASTC → ETC2 → BC),含 mip 链 |
+| 生命周期 | `onShow` / `onHide` 与系统内存警告都能到达应用 |
+
+万一将来某个构建*真的*砍掉了某个子系统,导出会点名它——连同用到它的场景——
+而不是悄悄发出一个缺了半个场景的包。
+
+## 只在真机上才咬人的那些事
+
+这些是你第一次做真机构建前值得知道的差异。每一条都至少发过一次坏包,
+因为编辑器直接从磁盘伺服项目,根本不会察觉。
+
+### 只有代码点名的资产会被剔除
+
+构建发布的是它能从入口场景**可达**的东西。对场景点名的一切来说这是对的——
+但对**只在代码里**点名的东西它是瞎的:富文本标记里的纹理、按 url 播放的音频、
+按路径 spawn 的预制体。这些会被剔除,而你第一次听说这件事,
+是手机上一个没声的按钮或一张缺失的图。
+
+在**内容浏览器**里标记这个文件夹:右键 → **交付方式 → 总是打进构建**。
+它会把 `alwaysInclude` 写进那份已经在决定本地 / 分包 / 远端交付的
+`.esengine/asset-groups.json`:
+
+```json
+{
+ "version": "1.0",
+ "groups": {
+ "markup-images": {
+ "folder": "assets/textures",
+ "mode": "local",
+ "alwaysInclude": true
+ }
+ }
+}
+```
+
+默认关闭,这是刻意的——正是可达性分析拦住了"什么都往包里塞"。
+见[资源](/docs/zh-cn/guides/assets/#只有代码点名的资产)。
+
+### 为内存最紧张的平台单独调纹理
+
+逐资产的**导入设置**每个平台一个页签,移动目标也在其中——所以一张纹理可以为手机压得比
+网页端更狠,而不用动源 PNG。见[资源](/docs/zh-cn/guides/assets/)。
+
+### 你的游戏脚本是解释执行的
+
+引擎以原生全速运行;**只有你的游戏脚本**跑在 QuickJS 上,它没有 JIT
+(Apple 的规则不留别的选项,Android 这边保持一致而不是分叉)。
+用 TypeScript 写的逐实体循环,是这里比浏览器里明显更贵的那一样东西——
+热路径上优先用引擎自己的系统和批量 API,而不是手写逐实体迭代。
+
+### 安装后的第一次启动
+
+在设备上解析 SDK bundle 要约 14 秒,而编译缓存要等一次启动付过账才存在——
+那次启动恰好就是刚装完的那一次。所以**字节码是随应用一起构建**的,跟着资产一起走:
+全新安装到第一帧从 14.4 秒变成约 0.6 秒。这是尽力而为(它需要构建机上的编译器);
+没有编译器的机器照样产出可用的应用,只是首次运行时再编译,和以前一样。
+
+## 另见
+
+- [构建与导出](/docs/zh-cn/guides/build-export/) —— 所有目标、cook 选项与打包对话框。
+- [资源](/docs/zh-cn/guides/assets/) —— 可达性剔除、交付分组与导入设置。
+- [屏幕与设计分辨率](/docs/zh-cn/core-concepts/screen/) —— 为手机的宽高比做设计。
+- [`native/README.md`](https://github.com/esengine/estella/blob/master/native/README.md) —— 宿主架构与完整构建配方。
diff --git a/docs/astro/src/content/docs/zh-cn/index.mdx b/docs/astro/src/content/docs/zh-cn/index.mdx
index 7166a5440..b66aafd8d 100644
--- a/docs/astro/src/content/docs/zh-cn/index.mdx
+++ b/docs/astro/src/content/docs/zh-cn/index.mdx
@@ -3,7 +3,7 @@ title: Estella
description: 由 WebAssembly 与 ECS 驱动的高性能 2D 游戏引擎,带可视化编辑器。
template: splash
hero:
- tagline: 一个高性能 2D 游戏引擎——TypeScript SDK、C++/WebAssembly 内核、可视化编辑器。一个项目发布到 Web、桌面、微信小游戏和 Playable 广告。
+ tagline: 一个高性能 2D 游戏引擎——TypeScript SDK、C++/WebAssembly 内核、可视化编辑器。一个项目发布到 Web、桌面、微信小游戏、Playable 广告,以及原生 Android / iOS 应用。
actions:
- text: 快速开始
link: /docs/zh-cn/getting-started/introduction/
@@ -37,7 +37,7 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
物理、瓦片地图、粒子、材质与 2D 光照、动画、Spine、音频、UI,以及一套游戏 AI 层。
</Card>
<Card title="跨平台" icon="laptop">
- 一个项目,导出到 Web、桌面、微信小游戏和单文件 Playable 广告。
+ 一个项目,导出到 Web、桌面、微信小游戏、单文件 Playable 广告,以及原生 Android / iOS 应用。
</Card>
</CardGrid>
@@ -49,5 +49,5 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
<LinkCard title="精灵与渲染" href="/docs/zh-cn/guides/sprites/" description="绘制图像——着色、尺寸、排序与分层。" />
<LinkCard title="物理" href="/docs/zh-cn/guides/physics/" description="刚体、碰撞体、关节与空间查询。" />
<LinkCard title="游戏 AI" href="/docs/zh-cn/guides/ai/" description="导航、感知、状态机、行为树。" />
- <LinkCard title="构建与导出" href="/docs/zh-cn/guides/build-export/" description="发布到 Web、桌面、微信和 Playable 广告。" />
+ <LinkCard title="构建与导出" href="/docs/zh-cn/guides/build-export/" description="发布到 Web、桌面、微信、Playable 广告、Android 与 iOS。" />
</CardGrid>