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: the mobile guide no longer opens with an SDK install
esengine6d18e39f24de
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 01a8ac0df..b993ecf8d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,19 @@ published separately; it ships inside the editor.### Added+- **Android: Package Project hands back a signed APK, with no Android SDK.** With+ the Android runtime template installed, the editor compiles the manifest to+ binary XML, writes the aligned zip and signs it with **APK Signature Scheme v2**+ — so packaging needs no aapt2, no zipalign, no apksigner and no JDK, on whatever+ OS the editor is running on. Signing uses a development key generated on first+ use (an RSA key and a self-signed certificate in PEM, inspectable with+ `openssl`); `--key`/`--cert` sign with your own. Native libraries now ship+ **uncompressed and 16 KiB-aligned** (`extractNativeLibs=false`), which the OS+ maps straight out of the package — a smaller install, and the posture Android+ 15's page size wants. Each of the three formats is verified against an+ implementation that is not ours: the signature by a from-spec Python verifier,+ the manifest by androguard and its resource ids by AOSP's own table, the archive+ by a real `unzip`.- **iOS runtime templates — shipping to a phone no longer needs the enginesources.** A native app's compiled half (the engine, Dawn, QuickJS, the linked-inBox2D / Spine / video runtimes) carries no project data, so it is now built oncediff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/guides/mobile.mdxindex 243da8d38..d779daf0e 100644--- a/docs/astro/src/content/docs/guides/mobile.mdx+++ b/docs/astro/src/content/docs/guides/mobile.mdx@@ -15,20 +15,20 @@ 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 samecomponents, 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 type="note" title="One download per editor version">+ The engine's compiled half is not in the editor download — it is a **runtime+ template** you install once per editor version (see+ [Prerequisites](#prerequisites)), because most projects never ship to a phone and+ it is tens of megabytes. With one installed, packaging needs no engine sources+ and no Android SDK; iOS additionally needs Xcode, which only Apple can supply.</Aside>## Two platforms, one runtimeAndroid 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.+are assembled into entirely different things — a signed `.apk` here, an Xcode+project there — and only one of them can be finished on any OS. One row could not+tell you whether this machine can finish the job, or what comes out.They do share **one runtime and one export payload**. The engine, the SDK and thegame runtime all live in the app binary, so what an export writes is app@@ -39,7 +39,7 @@ package the way `dist-web/` is.|---|---|---|| Graphics | Vulkan (via Dawn) | Metal (via Dawn) || Export output | `dist-android/` | `dist-ios/` |-| Assembled by | `aapt2` + `apksigner` (Android SDK/NDK) | Xcode |+| Assembled by | the editor (no Android SDK) | the editor, then Xcode || Assembly host OS | any desktop OS | **macOS only** || Result | a signed `.apk` | an Xcode project you open, sign and run |@@ -54,10 +54,6 @@ are not the same severity:content; 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.---*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. **Get the runtime for your target.**@@ -67,14 +63,11 @@ are not the same severity:against the editor's version (the SDK is compiled into the app binary), so itis one install per editor upgrade — and none of the engine's own builddependencies 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.+ - *Android* — the same, with its own template. Nothing else: the APK is+ compiled, aligned and signed by the editor, on whatever OS it is running on.++2. **Install the platform toolchain — iOS only.**+ - *Android* — none. There is no Android SDK, NDK or JDK in this path.- *iOS* — **macOS with Xcode**, and nothing else: no CMake, no Ninja, noxcodegen, no Dawn checkout. Apple ships no toolchain for other operatingsystems, so the dialog says so rather than pretending otherwise — but the@@ -99,17 +92,17 @@ are not the same severity:</Steps>-**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-# writes a signed APK (debug keystore unless --keystore says otherwise)-node build-tools/cli.js native --package --content dist-android-```+**That is the whole export.** With the runtime template installed, the output+folder holds the finished app:++- **Android** — a signed `.apk`, ready for `adb install -r` or a copy to the+ device. It is signed with a development key the editor generates on first use+ (the same standing as Android Studio's debug key: fine for a device, refused by+ every store). To sign with your own, pass `--key`/`--cert` to+ `node build-tools/cli.js native --package --content dist-android`.+- **iOS** — an Xcode project: the `.xcframework`, the app shell and a generated+ `.pbxproj`, written around your content. Open it, pick your signing team under+ *Signing & Capabilities*, and Run.<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 samediff --git a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdxindex 6e4d68b19..a749f3f03 100644--- a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx@@ -14,17 +14,17 @@ Android 上是 **Vulkan**),游戏脚本跑在内嵌的 JS 引擎创作模型和其他任何目标完全一致。同样的场景、同样的组件、同样的 TypeScript。项目里没有任何东西是"移动端专用"的。-<Aside type="caution" title="Pre-1.0——需要引擎源码检出">- 和 Web / 桌面 / 微信 / Playable 不同,移动目标**并不是编辑器下载包里自带齐全的**。- 组装可安装的应用需要先从引擎源码检出把原生宿主构建一次,再加上该平台自己的工具链- (见[前置条件](#前置条件))。编辑器在任何安装下都仍然能导出应用的*内容*——那一半从来不需要工具链。+<Aside type="note" title="每个编辑器版本装一次">+ 引擎被编译的那一半不在编辑器下载包里,而是一份**运行时模板**,每个编辑器版本装一次+ (见[前置条件](#前置条件))——因为绝大多数项目从不发到手机上,而它有几十 MB。+ 装好之后,打包既不需要引擎源码,也不需要 Android SDK;iOS 另需 Xcode,那只有 Apple 能提供。</Aside>## 两个平台,一套运行时-Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们经由完全不同的工具链打包-(Android SDK + NDK 对 Xcode)——一行说不清该运行什么、这台机器能不能运行、-以及包会出在哪里。+Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们被组装成的东西完全不同——+这边是已签名的 `.apk`,那边是 Xcode 工程——而且只有其中一个能在任意系统上收尾。+一行说不清这台机器能不能把活干完,也说不清出来的是什么。它们确实共享**同一套运行时和同一份导出载荷**。引擎、SDK 和游戏运行时都住在应用二进制里,所以导出写出的是应用**内容**——你的场景、脚本和烘焙后的资产——而不是像 `dist-web/`@@ -34,7 +34,7 @@ Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们经由完|---|---|---|| 图形 | Vulkan(经 Dawn) | Metal(经 Dawn) || 导出产物 | `dist-android/` | `dist-ios/` |-| 组装工具 | `aapt2` + `apksigner`(Android SDK/NDK) | Xcode |+| 组装方 | 编辑器(不需要 Android SDK) | 编辑器,然后 Xcode || 组装所需系统 | 任意桌面系统 | **仅 macOS** || 结果 | 一个已签名的 `.apk` | 一个可打开、签名并运行的 Xcode 工程 |@@ -46,10 +46,6 @@ Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们经由完- 缺**原生工具链**则不然。导出照样把应用内容写出来;只有最后的组装步骤需要工具链,而**那一步可以在另一台机器上跑**——编辑器在 Windows 上时,iOS 构建本来就得如此。---*打包项目 → **移动 → Android**。警告会点名缺的是哪一块,并说清它到底挡住了多少:内容无论如何都会写出来。*-<Steps>1. **拿到该目标的运行时。**@@ -57,13 +53,11 @@ Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们经由完iOS 那一行提供*从文件安装…*,指向本版本发布页里的归档即可。它与编辑器版本**精确匹配**(SDK 是编译进应用二进制的),所以每次升级编辑器装一次——引擎自己那一堆构建依赖一样都不用装。- - *Android* —— 宿主目前仍需从引擎源码构建。Dawn 和 QuickJS 体量数 GB、又是独立项目,- 所以是按需拉取而不是 vendored 进来;一次性的构建配方见- [`native/README.md`](https://github.com/esengine/estella/blob/master/native/README.md)。+ - *Android* —— 同理,装它自己的模板。此外别无所需:APK 的编译、对齐与签名都由编辑器+ 在它所运行的任何操作系统上完成。-2. **装好平台工具链。**- - *Android* —— Android SDK + **NDK r28**。编辑器通过 `ANDROID_HOME` 或- Android Studio 的默认安装位置找到它。+2. **装好平台工具链——只有 iOS 需要。**+ - *Android* —— 不需要。这条路径上没有 Android SDK、NDK 或 JDK。- *iOS* —— **装有 Xcode 的 macOS**,仅此而已:不需要 CMake、Ninja、xcodegen,也不需要 Dawn 源码。Apple 不为其他操作系统提供工具链,所以对话框直说,而不是假装可以——但导出照样会写出一份完整的工程,你可以拷到 Mac 上打开。@@ -85,16 +79,14 @@ Android 和 iOS 是**两个目标而不是一个"Mobile"**,因为它们经由完</Steps>-**iOS 到这一步就完事了**:装好运行时模板后,输出目录本身*就是*一个 Xcode 工程——-`.xcframework`、应用外壳和生成好的 `.pbxproj` 都已围绕你的内容写出。打开它,在-*Signing & Capabilities* 下选好签名 Team,Run。+**导出到这一步就完事了。** 装好运行时模板后,输出目录里放的就是成品应用:-Android 还需要再跑一条命令来组装:--```bash-# 写出已签名的 APK(未用 --keystore 指定时用 debug keystore)-node build-tools/cli.js native --package --content dist-android-```+- **Android** —— 一个已签名的 `.apk`,可直接 `adb install -r` 或拷到设备上。它由编辑器+ 首次使用时生成的开发密钥签名(与 Android Studio 的 debug key 同等地位:装设备够用,+ 任何应用商店都不收)。要用你自己的密钥,给+ `node build-tools/cli.js native --package --content dist-android` 传 `--key`/`--cert`。+- **iOS** —— 一个 Xcode 工程:`.xcframework`、应用外壳和生成好的 `.pbxproj` 都已围绕你的+ 内容写出。打开它,在 *Signing & Capabilities* 下选好签名 Team,Run。<Aside type="tip" title="导出为什么能不带编译器就做到这些">应用被编译的那一半不含任何项目数据——每个游戏装的都是同一份引擎二进制,而导出只有内容。diff --git a/native/README.md b/native/README.mdindex 4371b5c30..9a2f57dfe 100644--- a/native/README.md+++ b/native/README.md@@ -152,23 +152,10 @@ drift from its source):Paths may also come from `ESTELLA_DAWN_DIR` / `ESTELLA_DAWN_BUILD` /`ESTELLA_QUICKJS_DIR`. Output: `build-native/libestella_js_host.so`.-**Package a signed APK** by adding `--package` — the Android counterpart of what-Xcode does for `native/ios`, and still no gradle (a NativeActivity has no Java):--```sh-node build-tools/cli.js native --dawn "$DAWN" --dawn-build "$DAWN/out-android" \- --quickjs "$QJS" --package --content dist-android-adb install -r build-native/estella-js-host.apk-```--It runs `aapt2 link` over `native/android/host/AndroidManifest.xml` to produce the-base APK from the manifest, then adds the payload with `jar`:-`lib/arm64-v8a/{libestella*_host.so,libwebgpu_dawn.so,libc++_shared.so}` (Dawn-stripped with the NDK's `llvm-strip`) and the exported project under `assets/`,-where the host's `readAsset()` looks. Then `zipalign -f 4` and `apksigner sign`.-Signing uses the Android debug keystore — created on first use — unless you pass-`--keystore`. The JDK those steps need is located the way the SDK and NDK are-(`JAVA_HOME`, or the one Android Studio bundles); `--jdk <dir>` overrides.+The build emits this machine's Android runtime template on the way out (the+`.so` payload, the Java shim's `classes.dex`, the SDK bytecode and the manifest+template); packaging a game then reads that template and needs none of the tools+above. See *Shipping a project*.## Build (iOS arm64)@@ -233,23 +220,34 @@ the 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 tworows 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:+**Neither target needs a toolchain to package.** With the runtime template+installed, the export finishes the job: Android gets a signed APK, iOS an Xcode+project (the xcframework, the app shell and a generated `.pbxproj` written around+the content, open-and-Run). The CLI does the same from a content dir someone sent+you — no Android SDK, no JDK, no Xcode for the Android one:```sh+node build-tools/cli.js native --package --content dist-androidnode 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-```+An APK is a compiled manifest, four kinds of file in a zip, and a signature, so+all three formats are written directly (`build-tools/utils/{androidBinaryXml,zip,apk}.js`):++* **AndroidManifest.xml** is compiled to binary XML here. The platform resolves a+ framework attribute by its RESOURCE ID rather than its name — a wrong id is+ ignored, not rejected — so the ids are pinned against AOSP's `public.xml` by a+ test rather than trusted.+* **Native libraries are stored, 16 KiB-aligned**, with `extractNativeLibs=false`:+ the OS maps them out of the package, which halves the install and is the posture+ Android 15's page size wants.+* **Signing is APK Signature Scheme v2** (minSdk 26 is well past the API 24 that+ introduced it, so v1's PKCS#7 would be dead weight), with an RSA key and a+ self-signed certificate in PEM under `<data>/android-keys`, generated on first+ use. `--key`/`--cert` sign with your own. A second, independent implementation+ of the scheme (`build-tools/tests/verify-apk.py`, Python stdlib only) verifies+ what we write, because checking our own signature with our own code proves+ nothing.An export for a native target writes a second file beside the content:`app.config.json` — the app's **identity**, as opposed to what the runtime needs