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: shipping to iOS no longer starts with cloning the engine

esengine4e317d7654e2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 735f4e0a4..01a8ac0df 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,21 @@ published separately; it ships inside the editor.
### Added
+- **iOS runtime templates — shipping to a phone no longer needs the engine
+ sources.** A native app's compiled half (the engine, Dawn, QuickJS, the linked-in
+ Box2D / Spine / video runtimes) carries no project data, so it is now built once
+ per release and shipped as a **runtime template** you install into the editor,
+ instead of every developer cloning the engine, building Dawn (multi-GB) and
+ installing a CMake/Ninja/xcodegen toolchain to package a game. **Package Project
+ → iOS** with one installed writes a complete, double-clickable Xcode project
+ around the exported content — the only thing left is Xcode itself, which Apple
+ requires. The iOS row says which template it wants and installs one from a file;
+ a template is matched **exactly** against the editor's version, because the SDK
+ bundle is compiled into the app binary. `cli native --target ios` emits the
+ template for the machine it built on (`--template-out` writes the distributable
+ archive), so an engine checkout is now only what *produces* a template, never
+ what consumes one.
+
- **Editor plugins.** Extend the editor with your own TypeScript: commands (with
keybindings, palette and menu entries), dock panels, Inspector sections,
viewport gizmos and tools, asset types, entity templates, settings, and
diff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/guides/mobile.mdx
index 286753db5..243da8d38 100644
--- a/docs/astro/src/content/docs/guides/mobile.mdx
+++ b/docs/astro/src/content/docs/guides/mobile.mdx
@@ -48,7 +48,8 @@ package the way `dist-web/` is.
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 **engine runtime** — for a mobile target, its **runtime template** —
+ 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.
@@ -59,16 +60,25 @@ are not the same severity:
<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).
+1. **Get the runtime for your target.**
+ - *iOS* — install the **runtime template**: the engine, prebuilt for arm64,
+ published with each release. The iOS row offers *Install from file…*; point it
+ at the archive from this version's release page. It is matched **exactly**
+ against the editor's version (the SDK is compiled into the app binary), so it
+ is one install per editor upgrade — and none of the engine's own build
+ dependencies come with it.
+ - *Android* — the host is still built from the engine sources for now. Dawn and
+ QuickJS are multi-GB / separate projects, so they are fetched rather than
+ vendored; the one-time recipe 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.
+ - *iOS* — **macOS with Xcode**, and nothing else: no CMake, no Ninja, no
+ xcodegen, no Dawn checkout. Apple ships no toolchain for other operating
+ systems, so the dialog says so rather than pretending otherwise — but the
+ export still writes a complete project you can carry to a Mac.
3. **Check the dialog.** The target's row carries a warning triangle until the
probe passes, and the panel names what is missing.
@@ -89,23 +99,25 @@ are not the same severity:
</Steps>
-Then assemble the app around that content:
+**On iOS that is the whole export**: with the runtime template installed, the
+output folder *is* an Xcode project — the `.xcframework`, the app shell and a
+generated `.pbxproj` are written around your content. Open it, pick your signing
+team under *Signing & Capabilities*, and Run.
+
+Android is assembled by one more command:
```bash
-# Android — writes a signed APK (debug keystore unless --keystore says otherwise)
+# 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 type="tip" title="Why the export can do this without a compiler">
+ The app's compiled half carries no project data — every game ships the same
+ engine binary, and an export is content only. So it is built once per release and
+ distributed as a template, and assembling an app is copying files and writing a
+ project file. That is why it belongs in the export rather than behind a command
+ you have to find, and why an editor with no template says exactly that instead of
+ writing a project that cannot link.
</Aside>
## App identity
diff --git a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
index aef7fdbe4..6e4d68b19 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
@@ -42,7 +42,7 @@ Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们经由完
打包对话框区分**两类**缺失的前置条件,二者严重程度并不相同:
-- 缺**引擎运行时**意味着根本产不出包。
+- 缺**引擎运行时**——对移动目标来说就是缺它的**运行时模板**——意味着根本产不出包。
- 缺**原生工具链**则不然。导出照样把应用内容写出来;只有最后的组装步骤需要工具链,
而**那一步可以在另一台机器上跑**——编辑器在 Windows 上时,iOS 构建本来就得如此。
@@ -52,15 +52,21 @@ Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们经由完
<Steps>
-1. **把原生宿主构建一次。** Dawn 和 QuickJS 体量数 GB、又是独立项目,所以是按需拉取而不是
- vendored 进来。一次性的构建配方(以及确切的 `cmake` 调用)见
- [`native/README.md`](https://github.com/esengine/estella/blob/master/native/README.md)。
+1. **拿到该目标的运行时。**
+ - *iOS* —— 安装**运行时模板**:随每个版本发布的、已为 arm64 预编译好的引擎。
+ iOS 那一行提供*从文件安装…*,指向本版本发布页里的归档即可。它与编辑器版本
+ **精确匹配**(SDK 是编译进应用二进制的),所以每次升级编辑器装一次——引擎自己
+ 那一堆构建依赖一样都不用装。
+ - *Android* —— 宿主目前仍需从引擎源码构建。Dawn 和 QuickJS 体量数 GB、又是独立项目,
+ 所以是按需拉取而不是 vendored 进来;一次性的构建配方见
+ [`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 不为其他操作系统提供工具链,
- 所以对话框直说,而不是假装可以。
+ - *iOS* —— **装有 Xcode 的 macOS**,仅此而已:不需要 CMake、Ninja、xcodegen,
+ 也不需要 Dawn 源码。Apple 不为其他操作系统提供工具链,所以对话框直说,而不是
+ 假装可以——但导出照样会写出一份完整的工程,你可以拷到 Mac 上打开。
3. **看对话框。** 探测通过之前,该目标那一行会一直带着警告三角,面板里会点名缺什么。
@@ -79,21 +85,22 @@ Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们经由完
</Steps>
-然后围绕这份内容组装应用:
+**iOS 到这一步就完事了**:装好运行时模板后,输出目录本身*就是*一个 Xcode 工程——
+`.xcframework`、应用外壳和生成好的 `.pbxproj` 都已围绕你的内容写出。打开它,在
+*Signing & Capabilities* 下选好签名 Team,Run。
+
+Android 还需要再跑一条命令来组装:
```bash
-# Android —— 写出已签名的 APK(未用 --keystore 指定时用 debug keystore)
+# 写出已签名的 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 type="tip" title="导出为什么能不带编译器就做到这些">
+ 应用被编译的那一半不含任何项目数据——每个游戏装的都是同一份引擎二进制,而导出只有内容。
+ 所以它每个版本构建一次、以模板形式分发,组装一个应用不过是拷文件加写工程文件。这正是它
+ 属于导出流程、而不该藏在一条命令后面的原因;也正因如此,没装模板的编辑器会直说这件事,
+ 而不是写出一个链接不起来的工程。
</Aside>
## 应用身份
diff --git a/native/README.md b/native/README.md
index 436e9a640..4371b5c30 100644
--- a/native/README.md
+++ b/native/README.md
@@ -41,6 +41,22 @@ Dawn and QuickJS are **not vendored** (multi-GB / separate project); the recipe
fetches them, the way Dawn fetches its own deps. Nothing here is compiled by the
web/emscripten build or CI — it is inert until you run the native build below.
+## Who this directory is for
+
+**Not the developer shipping a game.** The binaries built here carry no project
+data — `CMakeLists.txt` takes no project input, every `ES_ENABLE_*` is on, and an
+export is content only — so the compiled half is the SAME for every game. It is
+built once and shipped as a **runtime template** the editor installs
+(`build-tools/utils/nativeTemplate.js` defines what one holds and where it lives).
+Packaging a game is then: install the template, **Package Project → iOS /
+Android**.
+
+So what follows is the recipe for **producing** a template: the toolchain below is
+a build machine's problem, not a user's. Every native build emits one into this
+machine's store (`--no-template` opts out); `--template-out <dir>` also writes the
+distributable archive, and `--template-only` re-emits from an existing build
+without rebuilding.
+
### The optional runtimes are compiled IN, not side-loaded
On the web, Box2D, the Spine runtime and the MPEG-1 decoder ship as standalone wasm
@@ -198,7 +214,8 @@ node build-tools/cli.js native --target ios --simulator \
Both slices land in `build-native-ios/Estella.xcframework`, which is what the app
links — Xcode picks the one matching the toolbar. arm64 only, so an Intel Mac's
-simulator would need a third Dawn.
+simulator would need a third Dawn. The framework and the app shell are then packed
+into the iOS runtime template, which is what an editor export reads.
Then pick your Team under *Signing & Capabilities*, select your device and Run.
The CMake build merges host + engine + QuickJS + Dawn into one archive
@@ -214,17 +231,24 @@ A game comes out of the editor. **Package Project → Android** (or **→ iOS**,
the scenes and `game.config.json` — content only, since the engine, the SDK and
the game runtime all ship inside the app binary. Both platforms write the SAME
payload; what differs is the toolchain that wraps it, which is why they are two
-rows in the dialog rather than one "mobile". Pass that directory to the build and
-it becomes the app's content:
+rows in the dialog rather than one "mobile".
+
+**iOS needs nothing else.** With the runtime template installed, the export
+directory *becomes* an Xcode project — the xcframework, the app shell and a
+generated `.pbxproj` are written around the content, so it is open-and-Run. The
+CLI does the same from a content dir someone sent you:
```sh
-# Android: it becomes the APK's assets/
+node build-tools/cli.js native --target ios --package --content dist-ios
+```
+
+**Android** still assembles through the SDK's tools on a machine that has them
+(the editor-side assembler is next — see `docs/REARCH_NATIVE_DISTRIBUTION.md`):
+
+```sh
+# it becomes the APK's assets/
node build-tools/cli.js native --dawn "$DAWN" --dawn-build "$DAWN/out-android" \
--quickjs "$QJS" --package --content dist-android
-
-# iOS: it stages into native/ios/Content (a folder reference), then rebuild in Xcode
-node build-tools/cli.js native --target ios --dawn "$DAWN" \
- --dawn-build "$DAWN/out-ios" --quickjs "$QJS" --content dist-ios
```
An export for a native target writes a second file beside the content: