Android & iOS

Android and iOS package your project as a real native app: the engine’s C++ core compiled to arm64, rendering through an embedded Dawn (WebGPU → Metal on iOS, Vulkan on Android), with your game scripts running on an embedded JS engine (QuickJS-ng). 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.

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), 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.

Two platforms, one runtime

Android and iOS are offered as two targets, not one “Mobile”, because they 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 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	the editor (no Android SDK)	the editor, then Xcode
Assembly host OS	any desktop OS	macOS only
Result	a signed .apk, or an Android Studio project	an Xcode project you open, sign and run

Android offers both because it can: the editor assembles a package outright, and it can also write the Gradle project that package would have been built from. Pick the project under Output in the Android section when the game needs to add an SDK, a permission or an Activity of its own — that is the same shape iOS has always had, where Xcode does the assembling.

What a packaged game runs on

	Android	iOS
Minimum OS	Android 10 (API 29)	iOS 17.0
Declared target	API 33	—
CPU	arm64-v8a (every real device) + x86_64 (the emulator)	arm64 device + simulator slice
GPU	Vulkan 1.0.3 required — declared required="true", so a device without it does not see the app on Play	Metal

Android’s floor is 29 because the engine’s font path calls AFontMatcher_create, which is API 29 — below that there is nothing to fall back to. It was declared as 26 through v0.37.0, which was a claim rather than a capability: those builds install on Android 10 and 11 and then fail to start, because the NDK was told to build against a higher API and turned every guarded symbol into a load-time requirement. Nothing that ran on v0.37.0 stops running on v0.38.0 — the number now says what was always true.

Note

The Vulkan requirement follows from the runtime: the engine renders through Dawn, and Dawn’s Android backend is Vulkan. There is no GLES fallback path in a packaged game. It is declared in the manifest, so Play filters on it rather than letting an incapable device install and fail.

Prerequisites

The Package dialog distinguishes two kinds of missing prerequisite, and they are not the same severity:

• 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.

1. Get the runtime for your target. Install the runtime template: the engine, prebuilt for arm64 and published with each release. The target’s row offers Download — or Install from file… if you already have the archive (offline, a mirror, a company share). It is matched exactly against the editor’s version, because the SDK is compiled into the app binary, so it is one download per editor upgrade — and none of the engine’s own build dependencies come with it.

   Android needs nothing else: the APK is compiled, aligned and signed by the editor, on whatever OS it is running on.

   Where the download comes from

   Releases are mirrored to dl.estella.games, and the editor asks it before the origin — a template is hundreds of megabytes, and GitHub’s speed is not the same everywhere. The mirror is a shortcut and never an authority: every archive is checked against the size and SHA-256 the release’s index states, so a copy that is missing, stale or wrong fails that check and the download falls back to GitHub. Point the editor elsewhere — a company share, your own CDN, nothing at all — with ESTELLA_RELEASE_MIRROR (comma-separated, tried in order); each one lays a version out exactly as the release does, under v<version>/.

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, 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.

Exporting

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.

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.

  For Google Play, tick Google Play App Bundle (.aab) in the Android section: the export writes one beside the APK. Play has required a bundle rather than an APK for new apps since 2021 — it is the upload format, and cannot be installed on a device, which is why the APK is still what you test with.

• Android, with Output set to Android Studio project — an ordinary Gradle project instead of a package: your content under app/src/main/assets, the engine under app/src/main/jniLibs, the host’s Java shim as source, and an app/build.gradle.kts carrying the app’s identity. Open the folder in Android Studio and Run; add your SDKs to build.gradle.kts as you would in any Android app. Exporting again rewrites the game and leaves the build script alone, so a project that has grown an SDK survives its game being rebuilt.

• 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.

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.

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
App Icon	The launcher icon on both platforms — one project-relative square PNG (1024×1024 is ideal). Android takes it as the launcher mipmap, iOS as the asset catalog Xcode derives every size from, so nothing is resized and one image is all you keep. Left empty, the app ships Estella’s mark rather than the platform’s placeholder.
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)
DragonBones	Compiled in — one runtime, since the format is frozen
Video	Compiled in (cooked at build, decoded on device)
Audio	Native mixer (miniaudio) — 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:

{
  "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.

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.

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.1 s rather than ~10 s.

A build machine without a C compiler cannot produce it, and the app then compiles on first run instead: it still works, but that one launch spends ten seconds on a screen that a player reads as a hang. The boot record says which happened — SDK bundle: loaded from bytecode shipped with the app, or bundle: NO bytecode — so a slow first launch is a question with an answer rather than a mystery.

When something goes wrong on a device

Every launch writes a record next to the game, so a failure that only happens on someone else’s phone leaves something behind:

Android   Android/data/<your.package.id>/files/estella-boot.log
iOS       the app's Documents directory

The run before it is kept as estella-boot.prev.log — an app that dies and is opened again would otherwise replace the record of the death with a record of the retry.

estella boot record — 2026-07-29 19:07:38
device: 24129PN74C, Android 16, arm64-v8a
phase: gpu device
gpu: qualcomm Adreno (TM) 830 (adreno-8xx) — Adreno Vulkan Driver 512.800.71
phase: surface
phase: engine context
phase: js runtime
  SDK bundle: loaded from bytecode shipped with the app
phase: game script
ready in 105 ms

The phases are the useful part: the last one in the file is where a launch that never finished stopped. A launch that finished says ready in. A native crash appends the signal, the phase it happened in, and the return addresses:

FATAL SIGSEGV (bad memory access) during phase: js runtime
backtrace (symbolize against this version's unstripped libestella_js_host.so):
  0x7b41e2632c  /data/app/.../libestella_js_host.so+0x1e32c

Those addresses resolve against the unstripped libestella_js_host.so for that engine version (llvm-addr2line -e libestella_js_host.so 0x1e32c); the copy inside the APK is stripped.

To read it off an Android device:

adb shell cat /sdcard/Android/data/<your.package.id>/files/estella-boot.log
adb pull /sdcard/Android/data/<your.package.id>/files/estella-boot.log

Caution

That path is for you, not for a player: since Android 11 an app’s Android/data is closed to file managers and to the system Files app, and adb shell reaches it only because that user is in the ext_data_rw group.

When a game crashes, the next launch publishes the record where a player can get at it — Android/media/<your.package.id>/, which a file manager lists, falling back to Download/. The file is named estella-crash-<date>.log, and the new run’s own record says where it went:

previous run CRASHED; its record was copied to
  /storage/emulated/0/Android/media/com.example.game/estella-crash-20260729-190738.log

So the instruction to give someone who reports a crash is: open the game once more, then send the newest estella-crash-*.log from that folder. Only crashes are published — a launch that finished leaves nothing there.

While a device is attached, the same lines are in logcat:

adb logcat --pid=$(adb shell pidof <your.package.id>)

See also

• Building & Exporting — every target, the cook options, and the Package dialog.
• Assets — reachability culling, delivery groups, and import settings.
• Screen & Design Resolution — designing for a phone’s aspect.
• native/README.md — the host’s architecture and the full build recipe.