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
docs(mobile): the Android & iOS guide, and the target lists that stopped at four
esengine6c20766fe68a
diff --git a/README.md b/README.mdindex 5d42eb7eb..be0f02c39 100644--- a/README.md+++ b/README.md@@ -10,7 +10,7 @@[](LICENSE)[](https://github.com/esengine/estella/releases)[](https://isocpp.org/)-[]()+[]()[](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/)## Contributingdiff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.pngindex a4c8f3964..b7f24a87d 100644Binary files a/docs/astro/src/assets/guides/en/build-dialog.png and b/docs/astro/src/assets/guides/en/build-dialog.png differdiff --git a/docs/astro/src/assets/guides/en/build-mobile.png b/docs/astro/src/assets/guides/en/build-mobile.pngnew file mode 100644index 000000000..8cf04124fBinary files /dev/null and b/docs/astro/src/assets/guides/en/build-mobile.png differdiff --git a/docs/astro/src/assets/guides/zh/build-dialog.png b/docs/astro/src/assets/guides/zh/build-dialog.pngindex a3d75ce28..097ed17a3 100644Binary files a/docs/astro/src/assets/guides/zh/build-dialog.png and b/docs/astro/src/assets/guides/zh/build-dialog.png differdiff --git a/docs/astro/src/assets/guides/zh/build-mobile.png b/docs/astro/src/assets/guides/zh/build-mobile.pngnew file mode 100644index 000000000..c86b37216Binary files /dev/null and b/docs/astro/src/assets/guides/zh/build-mobile.png differdiff --git a/docs/astro/src/content/docs/getting-started/introduction.mdx b/docs/astro/src/content/docs/getting-started/introduction.mdxindex 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 ahigh-performance **C++/WebAssembly** backend. It ships with a visual editor forscene 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 JSONediting.- **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.mdxindex 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: 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 theeditor, 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 modulesOptional 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 settingsPer-target metadata lives in **Project Settings → Packaging** and is saved with theproject:+- **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 orientationOrientation 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 shipslandscape 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 runtimenode build-tools/cli.js sdk # build the SDK onlynode 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.mdxnew file mode 100644index 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.++++*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.mdxindex b1e493c71..b31c7730d 100644--- a/docs/astro/src/content/docs/index.mdx+++ b/docs/astro/src/content/docs/index.mdx@@ -3,7 +3,7 @@ title: Estelladescription: A fast 2D game engine powered by WebAssembly and ECS, with a visual editor.template: splashhero:- 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 Startedlink: /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.mdxindex 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.mdxindex 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*)。## 从编辑器导出-+-*打包对话框:选一个**平台**(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 # 只构建 SDKnode 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.mdxnew file mode 100644index 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**。警告会点名缺的是哪一块,并说清它到底挡住了多少:内容无论如何都会写出来。*++<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.mdxindex 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: Estelladescription: 由 WebAssembly 与 ECS 驱动的高性能 2D 游戏引擎,带可视化编辑器。template: splashhero:- 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>