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: shipping to iOS no longer starts with cloning the engine
esengine4e317d7654e2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 (withkeybindings, palette and menu entries), dock panels, Inspector sections,viewport gizmos and tools, asset types, entity templates, settings, anddiff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/guides/mobile.mdxindex 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 theyare 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'scontent; only the final assembly needs the toolchain, and **that step can run onanother 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 theprobe 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 identitydiff --git a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdxindex 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.mdindex 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 recipefetches them, the way Dawn fetches its own deps. Nothing here is compiled by theweb/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-loadedOn 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 applinks — 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 andthe game runtime all ship inside the app binary. Both platforms write the SAMEpayload; 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: