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.
Estella native host (embedded Dawn + JS engine)
A native iOS/Android runtime for Estella: the same engine C++ core and the same authoring model as the web build, compiled to arm64 and rendering through an embedded Dawn (WebGPU → Metal on iOS / Vulkan on Android) — a real native app, not a WebView. Game scripts run on an embedded JS engine: V8 with its JIT where one is allowed (Android, the Windows desktop) and QuickJS-ng where it is not (iOS) — and on the desktops no V8 is pinned for yet (macOS, Linux). The engine itself runs native, full speed, on all of them.
This directory holds the host and the build recipe:
host/— the app. A JS runtime drives the engine through the real esengine SDK, bundled to one file (dist/index.native.bundled.js, installingESEngine); an editor export boots on it through the sameAppandWorldthe web build uses. One host with a platform seam, not one per OS:Host.{hpp,cpp}— the contract a platform implements (eshost::Platform) and the entry points its event loop drives: boot, the frame, lifecycle.Runtime.{hpp,cpp}— the JS runtime and the state the host shares: the environment the language does not ship (console, timers, a clock), the eval + compile cache, and the layered boot (SDK bundle → bootstrap → project).js/esjs.hpp— the engine, behind one small surface every binding (hand-written and generated) is written against: values, objects, byte buffers, functions, calls, and V8's lifetime rule (a value lives as long as the scope that made it;esjs::Refkeeps one longer).js/esjs_v8.cppandjs/esjs_quickjs.cppare the two backends; one build compiles one of them (ESTELLA_JS_ENGINE, chosen bycli native --js-engine). V8 comes prebuilt and pinned by sha256 (toolchain.manifest.json→native.v8, fetched with--fetch-deps): version 10.0.139.9 on both Windows and Android, neither with V8's sandbox, which is what lets the host hand JS zero-copy views of engine memory.bootstrap.js— the host's own JavaScript (the bridge install and the default init/update), embedded at build time. A real .js file, not a C++ literal.bindings/— thees_*surface, one TU per pillar (Ecs, Render, Assets, Audio, Net). Only what cannot be generated; see below.EsnShim.cpp+esn_shim.hpp— what the GENERATED bindings call: the engine singletons, entity round-tripping, the JS value readers.media/— glyph rasterization, KTX2 transcode, the miniaudio engine.platform/android.cpp— NativeActivity, APK assets, Vulkan, the ALooper loop.platform/ios.mm— a CAMetalLayer view, bundle assets, Metal, CADisplayLink.
android/— the APK manifest, packaged by--package.ios/— the Xcode app shell (main.m+ an Info.plist template) that signs and packages the iOS build. It is only an entry point; the app lives in the static library, and the project around it is generated.
There is no built-in demo game and no second, JS-free host. What runs is an editor export, always: a parallel content path drifts from the one every real game takes, and boot already separates the layers — the engine core, Dawn and the surface are all up (and logged) before the first line of JS runs, so a failure names its own layer.
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.
There is ONE template per platform, not one per architecture: a platform's
template carries every architecture that platform needs — iOS already did, with
the device and simulator slices inside one xcframework, and Android does with
lib/arm64-v8a (every real device) and lib/x86_64 (the emulator, which is how
anyone without a phone tries the game). Each cli native --abi <abi> run adds its
architecture and keeps the ones already there, so a package installs everywhere
without anyone choosing.
A release publishes those archives plus native-templates.json, written by
--template-index <dir> over the set — one digest per template, which is what the
editor checks a download against. The release workflow's native-templates job
runs exactly the commands below; nothing about producing a template is CI-only.
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
side modules a realm fetches. A device has no dynamic-linking story and no reason for
one, so the same C sources link straight into the host binary — all three are
vendored — and the SDK reaches them through the native wrappers EHT generates from
their binding headers. app.sideModules still answers them, so the runtime's own
gating installs physics or spine exactly as it does in a browser (see
sdk/src/ecs/nativeSideModules.ts).
Spine is the one subsystem with several releases (2.1 / 3.8 / 4.1 / 4.2 / 4.3), and
the host carries them all, as the web carries a side module per release: a skeleton
is read by the runtime it was exported from. The releases define the same names, so
each is compiled apart: spine-c with native/spine/SpineCRename<tag>.hpp
force-included (every C name it defines, prefixed es<tag>_, read off its compiled
objects by tools/spine-c-rename.mjs), the backend in namespace es::spine<tag>,
and the spine_* entry points renamed spine<tag>_* and wrapped as
es_spine<tag>_*. Desktop and iOS link every release into the host. Android builds
one libestella_spine<tag>.so per release, and a package carries only the ones its
skeletons need. After a build, node tools/spine-c-rename.mjs --verify <build dir>
reads the libraries and fails if any Spine name escaped its prefix, because such a
name would bind one release's call to another's code without a link error.
--spine 3.8,4.2 narrows the set, and the template's template.json records what
was linked.
Which runtime backend a release uses
follows from its tree: 3.8 through 4.2 vendor the pure-C runtime, 2.1 vendors it flat
and in a dialect old enough to warrant its own backend, and 4.3 replaced it with a
generated wrapper, so that one binds spine-cpp (and picks up spine's own
SkeletonRenderer with it).
Why this works (the architecture, proven on device)
The engine is portable by construction; the native seams are small and already in the tree:
| Seam | Where | What |
|---|---|---|
| Render surface | WebGPUDevice::configureSurface(NativeSurface) |
CAMetalLayer* / ANativeWindow* → WGPUSurface (commit bfc495da) |
| Instance / present | WebGPUDevice(device, instance) + present() |
host shares its instance; flips the swapchain (native-only) |
| GL gate | EstellaContext under ES_PLATFORM_WEB |
native drops the WebGL entry |
| Glyph source | Platform::matchFont + host/media/glyph_raster.cpp |
the device has no 2D canvas: the OS names a font file, stb_truetype rasterizes (the OS itself where stb cannot read the face), the engine's own sdfFromAlpha encodes |
| Bindings | python -m eht --native-output |
es_set_<C> / es_<C>_buffer from the same reflection as the web embind bindings |
| Entry points | python -m eht --native-functions |
es_renderer_*, es_uiLayout_*, es_rm_* — native wrappers (written against js/esjs.hpp) over the SAME bindings/*.hpp declarations embind registers |
| Data marshalling | sdk/src/ecs/ptrAccessors.generated.ts |
POD components are wasm32/arm64 layout-identical → the generated accessors write native component memory unchanged (via a zero-copy ArrayBuffer) |
| Host platform | eshost::Platform (host/Host.hpp) |
packaged assets, cache dir, backend, window surface + size, log — the only things the two OS glue files answer differently |
What is hand-written, and why
The es_* globals the SDK reads off globalThis are mostly GENERATED, from the
declarations embind registers on the web — so one implementation serves both
platforms, and both get its BoundarySpan validation. native/host/bindings/
holds only what has no generated form:
| Kept by hand | Why |
|---|---|
| entity + hierarchy | the web reaches the registry as an embind class; no binding header declares this surface |
| KTX2 transcode, glyph rasterization | native-only — the web decodes with WebGL2 + a wasm transcoder, and rasterizes on a 2D canvas |
| surface size, camera list, texture dimensions | their web siblings return an emscripten::val, which the boundary cannot marshal |
| assets, fetch, audio, cache, UTF-8, console/timers | the host's answer to what a browser hands the web build for free. There is nothing in the engine to generate them from |
Everything else — the frame, the UI layout, the whole texture surface, the text
batch — comes from EHT. Adding an entry point to a bindings/*.hpp is all it
takes for the device to have it.
Build (Android arm64)
Toolchain: Android SDK + NDK r28, SDK CMake ≥ 3.22 (cli native locates the SDK /
NDK / CMake automatically — ANDROID_HOME, ANDROID_NDK_HOME, or Android
Studio's default install), a JDK for the Java shim, and the SDK bundle
(pnpm --filter ./sdk build) — the host embeds it.
One-time: fetch the dependencies. Dawn, QuickJS-ng, SDL and the prebuilt V8 are
multi-GB / separate projects, PINNED in toolchain.manifest.json rather than vendored or tracked as
submodules — a --depth 1 clone of a branch makes a template unreproducible, and
Dawn fetches its own dependencies with a script anyway, so a submodule would save
nobody the fetch while putting a huge clone in front of everyone who only builds
for the web.
node build-tools/cli.js native --fetch-deps
Then build. Dawn is built for the target the first time it is needed (a few
minutes, cached in the checkout afterwards); the recipe lives in
build-tools/tasks/nativeDeps.js, so CI runs exactly what you run:
node build-tools/cli.js native # arm64-v8a, every real device
node build-tools/cli.js native --abi x86_64 # adds the emulator's
Per-ABI build trees live under build/cmake/native/<abi>/, beside the build/cmake/native/gen/
they share (the bindings, the SDK bundle and its bytecode are the same for every
architecture).
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)
Toolchain: Xcode (the Command Line Tools alone have no iPhoneOS SDK — cli native
falls back to /Applications/Xcode.app automatically), CMake ≥ 3.22 and Ninja.
No xcodegen: the Xcode project is generated directly (utils/xcodeProject.js).
Build the host, then run it from Xcode. Dawn is built for the iOS SDK on
first use (~5 min, a 19 MB static libwebgpu_dawn.a, kept in the pinned
checkout), and there is no pure-C++ reference host here — the app is the host:
pnpm --filter ./sdk build
node build-tools/cli.js native --fetch-deps # once
node build-tools/cli.js native --target ios
To run in the simulator — a different target triple, so it needs its own Dawn and its own slice:
node build-tools/cli.js native --target ios --simulator
Both slices land in build/cmake/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. 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
(build/cmake/native-ios/libestella_ios.a), so the Xcode project is a signing and
packaging shell: App/main.m calls EstellaRunApp(), and the exported project
ships as bundle resources — the same project-relative paths the APK serves from
assets/.
Shipping a project
A game comes out of the editor. Package Project → Android (or → iOS, or
exportGame({ platform: 'android' })) writes the cooked assets, both manifests,
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".
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:
node build-tools/cli.js native --package --content dist-android
node build-tools/cli.js native --target ios --package --content dist-ios
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.xmlby 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. - The launcher icon is one square PNG (Project Settings → Packaging), and the
reason
androidResources.jsexists:android:iconmust be a resource REFERENCE, so an app with its own icon needs a resource table. It is written here in both encodings —resources.arscandresources.pb, one package, onemipmap/ic_launcherentry, ids we choose — rather than having the template carry tables aapt2 built, which would put the SDK back on a build machine's path and freeze the table's shape into the release. The template ships the default icon a project without one gets. - The App Bundle (
--aab, or the checkbox in the dialog) is the same content again: the manifest re-encoded as aapt2 protobuf (androidProtoXml.js— the same parsed tree and the same resource ids as the binary XML, so the two cannot disagree), laid out underbase/, and signed as a JAR (jarSign.js). Play takes it; nothing else does, since a bundle is not installable. - 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/--certsign 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
to play the game. Identity, version and orientation are properties the OS owns
(the engine can letterbox, but it cannot rotate a phone), so they are settled once
from the project and read by whoever assembles the app:
| app.config.json | Android | iOS |
|---|---|---|
id |
manifest package |
PRODUCT_BUNDLE_IDENTIFIER |
name |
android:label |
CFBundleDisplayName |
version / versionCode |
versionName / versionCode |
MARKETING_VERSION / CURRENT_PROJECT_VERSION |
orientation |
android:screenOrientation (sensorLandscape / sensorPortrait) |
UISupportedInterfaceOrientations |
Which is why native/android/host/AndroidManifest.xml.in and
native/ios/App/Info.plist.in are templates: the concrete files are generated per
project. A static manifest is why every project installed over the last one under
one name — now two projects from one checkout are two apps on the phone, each
locked to the orientation its design resolution implies. The application id comes
from Project Settings → Packaging → Application ID, or is derived from the project
name when unset (sensorLandscape / sensorPortrait rather than the hard values,
so a phone held the other way up still works).
game.config.json is what the host boots, through ESEngine.initNativeGame;
without one it says so and stops, rather than falling back to something a real
game never runs. A project's own scripts (defineComponent / defineSystem)
bundle to scripts.js and evaluate before the scene loads, bound to the host's
SDK instance.
Gotchas (all resolved; each cost a build)
- Dawn cross-compile wants a host
protoc—-DDAWN_BUILD_PROTOBUF=OFF. - CMake 4.x rejects old deps — use the NDK-blessed SDK CMake 3.22.
wgpuInstanceWaitAnywith a timeout needs the instance created withWGPUInstanceFeatureName_TimedWaitAny, else "no adapter".ALooper_pollAllis gone in NDK 28 — useALooper_pollOnce.configureSwapchainmust useCompositeAlphaMode::Auto, notOpaque— a native Vulkan surface (Adreno) rejects Opaque outright.- MIUI blocks
adb installon a locked screen — unlock + allow USB install. It also blocksadb shell input keyevent, so a dozing screen cannot be woken from the host: a screenshot then reads back all black and the frame loop is legitimately stopped (the surface is gone). Unlock before you conclude anything about rendering. aapt2 link -A <dir>on Windows writes nested asset paths with backslashes (assets/assets\scenes\x), and a zip entry name must use forward slashes — soAAssetManagercannot open anything in a subdirectory. The packaging step addsassets/withjarinstead, which writes them correctly.- Xcode ships the iPhoneOS SDK without the device platform components, so
the CMake build works while
xcodebuildrejects every iOS destination ("iOS X.Y is not installed"). Install it under Xcode → Settings → Components. Without it you can still verify the link by hand:xcrun --sdk iphoneos clang -arch arm64 -mios-version-min=17.0 native/ios/App/main.m build/cmake/native-ios/libestella_ios.a -ObjC -lc++ -framework UIKit -framework Metal -framework QuartzCore -framework Foundation -framework IOSurface -framework CoreGraphics -o /tmp/EstellaiOS
Status
Android is proven on device (Snapdragon 8 Elite / Adreno 830) running an
editor export: the camera-follow example, packaged with Package Project →
Android and shipped by --package --content, renders its world at a
vsync-locked 120 fps and boots in ~57 ms (Dawn + EstellaContext 35 ms, then the
SDK bundle off its bytecode cache).
iOS runs in the simulator at a steady 60 fps, booting in ~20 ms off the bytecode cache; an exported project loads from its cooked content and renders. Not yet run on a physical device, which needs your signing.
The engine core + render path are proven on device. The host runs the real
SDK: ESEngine.createNativeApp() returns the same App + World the web build
uses, connected to the native core through the generated registry + memory
backend; the host binds only what cannot be generated (see above), and the rest —
the frame, the UI layout, the texture surface, the text batch — reaches the engine
through wrappers over the same declarations embind registers.
System bindings landing incrementally through the real SDK surfaces:
- Input (Stage B) — host touch → the SDK's
inputPlugin→ theInputresource (device-verified). - Assets (Stage B) —
ESEngine.Assets.loadTexture(path)runs the SAME asset pipeline the web build uses: the platform decodes the image (bridge.loadImagePixels) and the native ResourceManager (createNativeResourceManager) uploads the bytes directly — no wasm heap — through the engine's OWNrm_createTextureEx, the same entry point embind exposes to the web. Cooked-asset import settings (filter / wrap, from a scene'stextureImporterSettings) flow through the shared runtime loader into that one implementation, so pixel-art stays crisp on device by the same code that keeps it crisp in a browser. - Audio (Stage C) —
ESEngine.Audio.playSFX/playTrackruns the SAME Audio API the web build uses. The engine is miniaudio (CoreAudio on iOS, AAudio/OpenSL on Android): it decodes and mixes natively, so nothing per-sample runs in JS — the no-JIT budget forbids that.NativeAudioBackendis a thin SDK shell over the host'ses_audio*engine (native_audio.cpp), mirroring the WeChat backend over InnerAudioContext;mixeris null (per-voice volume/pan/rate/loop, no JS DSP graph). The engine is playback-only (no microphone). Bound only when a device comes up, so a host without one stays silent (the Null backend). Simulator-verified: a clip decodes and plays (isPlaying true). - Lifecycle (Stage C) — the glue pushes foreground/background (
eshost::setVisible) → the SDK's Lifecycle plugin auto-pauses the game, and the host suspends/resumes the audio device natively (correct even while the JS tick is paused). Memory pressure (eshost::memoryWarning, iOSdidReceiveMemoryWarning/ AndroidAPP_CMD_LOW_MEMORY) → the SDK's residency caches trim (the audio buffer cache). Simulator-verified across a background/foreground cycle. - Networking —
bridge.fetchruns a real HTTP request throughes_fetch(Platform::startFetch): iOSNSURLSession, Android a JNIHttpURLConnectionon a detached thread — the OS owns the TLS stack, so this is one seam that legitimately differs per platform. Replies cross back thread-safely (deliverFetch) and run on the JS thread in the frame loop. This is what remote asset groups and hot-update need. Simulator- verified (an HTTPS GET returns bytes and a 200); the Android path needs a device retest. - Text (Stage C) — the same
Textcomponent, glyph atlas, layout and batching the web build runs. Only the two ends cross the seam: the device has no 2D canvas to rasterize a glyph on, so the host does it (es_rasterizeGlyph→glyph_raster.cpp: the OS names the font file, stb_truetype rasterizes the outline, and the engine's OWNtext::sdfFromAlphaencodes the field, so the shared SDF shader samples identically encoded tiles on both platforms); and there is no wasm heap to marshal the laid-out quads through, so the host takes the typed arrays and callsRenderFrame::submitTextBatchitself (es_submitTextBatch, run fromes_jsPreFlushbetween collecting the scene and flushing it — where the web pipeline runs the same callbacks). Picking the font file is the only per-OS part: Android'sAFontMatcherand iOS's Core Text, both of which fall back per codepoint, so CJK resolves without a hard-coded path. Device-verified on Android (Latin + CJK, SDF). The C++BitmapTextpath compiles natively too (ES_ENABLE_BITMAP_TEXTis on — nothing insrc/esengine/textneeds freetype or msdfgen). - KTX2 / compressed textures —
Assets.loadTextureon a.ktx2path transcodes with the host's vendored basis_universal (es_createTextureKTX2→ktx2_decode.cpp) to the best format the device supports (ASTC → ETC2 → BC, RGBA32 fallback) and uploads the compressed blocks through the engine's now-realWebGPUDevice::createCompressedTexture— 4–8× less VRAM than RGBA8. The web KTX2 path (WebGL2 + wasm transcoder) is untouched. Simulator-verified (a 64×64 KTX2 sprite renders); base mip only for now.
Remaining: hardening on a physical device (audio output, the background/foreground
transition, Android's miniaudio audio + JNI fetch paths), and the subsystems this build
still leaves out — tilemaps, particles and post-processing (their ES_ENABLE_* sources),
plus physics / Spine / video, which ship as emscripten side modules with no native
counterpart yet. An export names them: Package Project → Mobile warns about any of them
a scene uses rather than shipping a package that quietly renders half of it (the gaps are
declared in desktop/src/project/targetSupport.ts, checked against this CMakeLists by
pipeline/tests/target-support.test.ts).