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.

build(native): first-class native (embedded-Dawn) target, single-sourced with web

yhh753051232d03
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 79051b2aa..1feb6f695 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -44,76 +44,12 @@ add_subdirectory(third_party)
# ESEngine Library
# =============================================================================
-set(ESENGINE_SOURCES
- src/esengine/core/EstellaContext.cpp
- src/esengine/core/Log.cpp
- src/esengine/resource/ResourceManager.cpp
- src/esengine/resource/ShaderParser.cpp
- src/esengine/renderer/RenderContext.cpp
- src/esengine/renderer/Shader.cpp
- src/esengine/renderer/DrawParams.cpp
- src/esengine/renderer/Buffer.cpp
- src/esengine/renderer/Texture.cpp
- src/esengine/renderer/Framebuffer.cpp
- src/esengine/renderer/RenderFrame.cpp
- src/esengine/renderer/RenderFrameMask.cpp
- src/esengine/renderer/RenderFrameSubmit.cpp
- src/esengine/renderer/FrameCapture.cpp
- src/esengine/renderer/RenderTarget.cpp
- src/esengine/renderer/ImmediateDraw.cpp
- src/esengine/renderer/CustomGeometry.cpp
- src/esengine/renderer/GLDevice.cpp
- src/esengine/renderer/TransientBufferPool.cpp
- src/esengine/renderer/DrawList.cpp
- src/esengine/renderer/BatchBuilder.cpp
- src/esengine/renderer/MaterialStore.cpp
- src/esengine/renderer/LightStore.cpp
- src/esengine/renderer/plugins/BatchPlugin.cpp
- src/esengine/renderer/plugins/SpritePlugin.cpp
- src/esengine/renderer/plugins/UIElementPlugin.cpp
- src/esengine/renderer/plugins/TextPlugin.cpp
- src/esengine/renderer/plugins/ShapePlugin.cpp
- src/esengine/renderer/plugins/MeshPlugin.cpp
- src/esengine/renderer/plugins/TrailPlugin.cpp
- src/esengine/trail/TrailSystem.cpp
- src/esengine/platform/PathResolver.cpp
- src/esengine/animation/TweenSystem.cpp
- src/esengine/ecs/UILayoutSystem.cpp
- src/esengine/ecs/UISystem.cpp
-)
-
-if(ES_ENABLE_POSTPROCESS)
- list(APPEND ESENGINE_SOURCES
- src/esengine/renderer/PostProcessPipeline.cpp
- )
-endif()
-
-if(ES_ENABLE_WEBGPU)
- list(APPEND ESENGINE_SOURCES
- src/esengine/renderer/webgpu/WebGPUDevice.cpp
- )
-endif()
-
-if(ES_ENABLE_TILEMAP)
- list(APPEND ESENGINE_SOURCES
- src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
- src/esengine/tilemap/TilemapSystem.cpp
- )
-endif()
-
-if(ES_ENABLE_PARTICLES)
- list(APPEND ESENGINE_SOURCES
- src/esengine/renderer/plugins/ParticlePlugin.cpp
- src/esengine/particle/Particle.cpp
- src/esengine/particle/ParticleSystem.cpp
- )
-endif()
-
-
- list(APPEND ESENGINE_SOURCES
- src/esengine/text/BitmapFont.cpp
- src/esengine/text/SdfGenerator.cpp
- )
+# The engine source list lives in one place — cmake/ESEngineSources.cmake — shared
+# with the native build (native/CMakeLists.txt) so the two never drift. It appends
+# the sources the ES_* options select (GLDevice is web/WeChat only; text is under
+# ES_ENABLE_BITMAP_TEXT).
+set(ESENGINE_ROOT ${CMAKE_CURRENT_SOURCE_DIR})
+include(ESEngineSources)
set(ESENGINE_HEADERS
diff --git a/build-tools/cli.js b/build-tools/cli.js
index a2756b284..6910c16e4 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -11,6 +11,7 @@ import * as logger from './utils/logger.js';
import { checkEnvironment } from './utils/emscripten.js';
import { runEht } from './tasks/eht.js';
import { buildWasm, buildWasmParallel, cleanWasm } from './tasks/wasm.js';
+import { buildNative } from './tasks/native.js';
import { buildSdk, cleanSdk } from './tasks/sdk.js';
import { syncToDesktop } from './tasks/sync.js';
import { startWatch } from './tasks/watch.js';
@@ -156,6 +157,29 @@ program
}
});
+program
+ .command('native')
+ .description('Build the native (embedded-Dawn) host for Android arm64')
+ .option('--dawn <dir>', 'Dawn source dir (or ESTELLA_DAWN_DIR); see native/README.md')
+ .option('--dawn-build <dir>', 'Dawn arm64 build dir (or ESTELLA_DAWN_BUILD)')
+ .option('--abi <abi>', 'Android ABI', 'arm64-v8a')
+ .option('--platform <platform>', 'Android platform', 'android-33')
+ .option('-v, --verbose', 'Verbose output', false)
+ .action(async (options) => {
+ logger.setVerbose(options.verbose);
+ try {
+ await buildNative({
+ dawn: options.dawn,
+ dawnBuild: options.dawnBuild,
+ abi: options.abi,
+ platform: options.platform,
+ });
+ } catch (err) {
+ logger.error(err.message);
+ process.exit(1);
+ }
+ });
+
program
.command('sdk')
.description('Build SDK only')
diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.js
new file mode 100644
index 000000000..be6676734
--- /dev/null
+++ b/build-tools/tasks/native.js
@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// The native (embedded-Dawn) host build — the arm64 sibling of the emscripten
+// wasm build. It drives native/CMakeLists.txt through the NDK toolchain, sharing
+// cmake/ESEngineSources.cmake with the web build so the engine source list never
+// drifts. Dawn is fetched + built separately (see native/README.md); pass its
+// paths via --dawn / --dawn-build or ESTELLA_DAWN_DIR / ESTELLA_DAWN_BUILD.
+
+import path from 'path';
+import { existsSync, readdirSync } from 'fs';
+import { mkdir } from 'fs/promises';
+import config from '../build.config.js';
+import * as logger from '../utils/logger.js';
+import { runCommand, getCpuCount } from '../utils/emscripten.js';
+
+function androidSdk() {
+ const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+ if (sdk && existsSync(sdk)) return sdk;
+ // Android Studio's default install location.
+ const dflt = path.join(process.env.LOCALAPPDATA || process.env.HOME || '', 'Android', 'Sdk');
+ return existsSync(dflt) ? dflt : null;
+}
+
+function newest(dir) {
+ if (!existsSync(dir)) return null;
+ const entries = readdirSync(dir).sort();
+ return entries.length ? path.join(dir, entries[entries.length - 1]) : null;
+}
+
+// Prefer the NDK-bundled CMake (>= 3.22, ships ninja) over whatever is on PATH —
+// CMake 4.x rejects the pre-3.5 minimums in some transitive deps.
+function sdkCmake(sdk) {
+ const cmakeRoot = newest(path.join(sdk, 'cmake'));
+ if (!cmakeRoot) return { cmake: 'cmake', ninja: null };
+ const bin = path.join(cmakeRoot, 'bin');
+ const exe = process.platform === 'win32' ? '.exe' : '';
+ return { cmake: path.join(bin, 'cmake' + exe), ninja: path.join(bin, 'ninja' + exe) };
+}
+
+export async function buildNative(options = {}) {
+ const { abi = 'arm64-v8a', platform = 'android-33' } = options;
+ const rootDir = config.paths.root;
+
+ const sdk = androidSdk();
+ if (!sdk) throw new Error('Android SDK not found. Set ANDROID_HOME (install via Android Studio).');
+ const ndk = newest(path.join(sdk, 'ndk'));
+ if (!ndk) throw new Error(`No NDK under ${sdk}/ndk. Install one via Android Studio's SDK Manager.`);
+ const toolchain = path.join(ndk, 'build', 'cmake', 'android.toolchain.cmake');
+
+ const dawnDir = options.dawn || process.env.ESTELLA_DAWN_DIR;
+ const dawnBuild = options.dawnBuild || process.env.ESTELLA_DAWN_BUILD;
+ if (!dawnDir || !dawnBuild) {
+ throw new Error('Dawn not configured. Pass --dawn <src> --dawn-build <arm64 build>, or set '
+ + 'ESTELLA_DAWN_DIR / ESTELLA_DAWN_BUILD. Build Dawn per native/README.md.');
+ }
+
+ const { cmake, ninja } = sdkCmake(sdk);
+ const buildDir = path.join(rootDir, 'build-native');
+ await mkdir(buildDir, { recursive: true });
+
+ logger.step(`Configuring native host (${abi}, ${platform})...`);
+ const configureArgs = [
+ '-S', path.join(rootDir, 'native'),
+ '-B', buildDir,
+ '-G', 'Ninja',
+ `-DCMAKE_TOOLCHAIN_FILE=${toolchain}`,
+ `-DANDROID_ABI=${abi}`,
+ `-DANDROID_PLATFORM=${platform}`,
+ '-DANDROID_STL=c++_shared',
+ '-DCMAKE_BUILD_TYPE=Release',
+ `-DESTELLA_DAWN_DIR=${dawnDir}`,
+ `-DESTELLA_DAWN_BUILD=${dawnBuild}`,
+ ];
+ if (ninja) configureArgs.push(`-DCMAKE_MAKE_PROGRAM=${ninja}`);
+ await runCommand(cmake, configureArgs, { cwd: rootDir });
+
+ logger.step('Building native host...');
+ await runCommand(cmake, ['--build', buildDir, '-j', String(getCpuCount())], { cwd: rootDir });
+
+ logger.success(`Native host: ${path.join('build-native', 'libestella_host.so')}`);
+}
diff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmake
new file mode 100644
index 000000000..eca6d1e3d
--- /dev/null
+++ b/cmake/ESEngineSources.cmake
@@ -0,0 +1,80 @@
+# Single source of truth for the engine's C++ source list.
+#
+# Both the web/emscripten build (root CMakeLists.txt) and the native build
+# (native/CMakeLists.txt) `include()` this file, so the two can never drift — the
+# same reflection-generated bindings, the same shaders, and now the same source
+# list. The caller sets ESENGINE_ROOT (repo root) and the ES_* feature options;
+# this appends the sources those options select into ESENGINE_SOURCES.
+
+set(ESENGINE_SOURCES
+ ${ESENGINE_ROOT}/src/esengine/core/EstellaContext.cpp
+ ${ESENGINE_ROOT}/src/esengine/core/Log.cpp
+ ${ESENGINE_ROOT}/src/esengine/resource/ResourceManager.cpp
+ ${ESENGINE_ROOT}/src/esengine/resource/ShaderParser.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/RenderContext.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/Shader.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/DrawParams.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/Buffer.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/Texture.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/Framebuffer.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/RenderFrame.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/RenderFrameMask.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/RenderFrameSubmit.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/FrameCapture.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/RenderTarget.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/ImmediateDraw.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/CustomGeometry.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/TransientBufferPool.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/DrawList.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/BatchBuilder.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/MaterialStore.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/LightStore.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/plugins/BatchPlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/plugins/SpritePlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/plugins/UIElementPlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/plugins/ShapePlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/plugins/MeshPlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/plugins/TrailPlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/trail/TrailSystem.cpp
+ ${ESENGINE_ROOT}/src/esengine/platform/PathResolver.cpp
+ ${ESENGINE_ROOT}/src/esengine/animation/TweenSystem.cpp
+ ${ESENGINE_ROOT}/src/esengine/ecs/UILayoutSystem.cpp
+ ${ESENGINE_ROOT}/src/esengine/ecs/UISystem.cpp
+)
+
+# WebGL2 (GLES3) backend — the web/WeChat platform only. A native build renders
+# through the WebGPU backend on embedded Dawn, so it drops GLDevice entirely.
+if(ES_BUILD_WEB OR ES_BUILD_WXGAME)
+ list(APPEND ESENGINE_SOURCES ${ESENGINE_ROOT}/src/esengine/renderer/GLDevice.cpp)
+endif()
+
+if(ES_ENABLE_WEBGPU)
+ list(APPEND ESENGINE_SOURCES ${ESENGINE_ROOT}/src/esengine/renderer/webgpu/WebGPUDevice.cpp)
+endif()
+
+if(ES_ENABLE_POSTPROCESS)
+ list(APPEND ESENGINE_SOURCES ${ESENGINE_ROOT}/src/esengine/renderer/PostProcessPipeline.cpp)
+endif()
+
+if(ES_ENABLE_TILEMAP)
+ list(APPEND ESENGINE_SOURCES
+ ${ESENGINE_ROOT}/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/tilemap/TilemapSystem.cpp)
+endif()
+
+if(ES_ENABLE_PARTICLES)
+ list(APPEND ESENGINE_SOURCES
+ ${ESENGINE_ROOT}/src/esengine/renderer/plugins/ParticlePlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/particle/Particle.cpp
+ ${ESENGINE_ROOT}/src/esengine/particle/ParticleSystem.cpp)
+endif()
+
+# Bitmap/SDF text — freetype/msdfgen-backed. Gated so a build that omits it (e.g.
+# native, until those deps are cross-compiled) drops the whole text path; the
+# TextPlugin registration in EstellaContext is under the same ES_ENABLE_BITMAP_TEXT.
+if(ES_ENABLE_BITMAP_TEXT)
+ list(APPEND ESENGINE_SOURCES
+ ${ESENGINE_ROOT}/src/esengine/renderer/plugins/TextPlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/text/BitmapFont.cpp
+ ${ESENGINE_ROOT}/src/esengine/text/SdfGenerator.cpp)
+endif()
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
new file mode 100644
index 000000000..0e5f72f96
--- /dev/null
+++ b/native/CMakeLists.txt
@@ -0,0 +1,65 @@
+# Estella native host — the engine C++ core compiled arm64 + linked against an
+# embedded Dawn. Requires a Dawn checkout + arm64 build (see README.md):
+# -DESTELLA_DAWN_DIR=<dawn source> -DESTELLA_DAWN_BUILD=<dawn arm64 build dir>
+# Invoke through the NDK toolchain file. NOT part of the web/emscripten build.
+cmake_minimum_required(VERSION 3.22)
+project(estella_native_host C CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+if(NOT ESTELLA_DAWN_DIR OR NOT ESTELLA_DAWN_BUILD)
+ message(FATAL_ERROR "Set ESTELLA_DAWN_DIR (Dawn source) and ESTELLA_DAWN_BUILD (Dawn arm64 build). See native/README.md.")
+endif()
+
+set(REPO "${CMAKE_CURRENT_SOURCE_DIR}/..")
+set(SRC "${REPO}/src")
+set(TP "${REPO}/third_party")
+
+# Prebuilt monolithic Dawn (libwebgpu_dawn.so).
+add_library(webgpu_dawn SHARED IMPORTED)
+set_target_properties(webgpu_dawn PROPERTIES
+ IMPORTED_LOCATION "${ESTELLA_DAWN_BUILD}/src/dawn/native/libwebgpu_dawn.so")
+
+# glm + yoga (the engine's non-emscripten third-party deps).
+add_library(glm INTERFACE)
+target_include_directories(glm INTERFACE "${TP}/glm")
+target_compile_definitions(glm INTERFACE GLM_FORCE_RADIANS GLM_FORCE_DEPTH_ZERO_TO_ONE GLM_ENABLE_EXPERIMENTAL)
+
+file(GLOB_RECURSE YOGA_SOURCES "${TP}/yoga/*.cpp")
+add_library(yogacore STATIC ${YOGA_SOURCES})
+target_include_directories(yogacore PUBLIC "${TP}")
+target_compile_options(yogacore PRIVATE -Wno-unused-parameter)
+
+add_library(native_app_glue STATIC
+ "${ANDROID_NDK}/sources/android/native_app_glue/android_native_app_glue.c")
+target_include_directories(native_app_glue PUBLIC
+ "${ANDROID_NDK}/sources/android/native_app_glue")
+
+# The engine core, native arm64. The source list is the SAME single-source file the
+# web build uses (cmake/ESEngineSources.cmake) — selecting the WebGPU backend and
+# dropping GL / bitmap text / particles / tilemap / post-process for this build. The
+# bindings/ (emscripten embind) TUs are web-only and never listed there.
+set(ESENGINE_ROOT "${REPO}")
+list(APPEND CMAKE_MODULE_PATH "${REPO}/cmake")
+set(ES_ENABLE_WEBGPU ON)
+include(ESEngineSources)
+
+# BitmapFont is self-contained (no freetype/msdfgen) and ResourceManager references
+# it, so the WebGPU-only build (ES_ENABLE_BITMAP_TEXT off) still needs this one TU.
+list(APPEND ESENGINE_SOURCES ${SRC}/esengine/text/BitmapFont.cpp)
+
+add_library(esengine STATIC ${ESENGINE_SOURCES})
+
+target_include_directories(esengine PUBLIC
+ "${SRC}" "${TP}/stb"
+ "${ESTELLA_DAWN_DIR}/include" # <webgpu/webgpu.h> forwarder
+ "${ESTELLA_DAWN_BUILD}/gen/include") # generated <dawn/webgpu.h>
+target_compile_definitions(esengine PUBLIC ES_ENABLE_WEBGPU) # NOT ES_PLATFORM_WEB / ES_ENABLE_BITMAP_TEXT
+target_link_libraries(esengine PUBLIC glm yogacore webgpu_dawn)
+
+# Reference host: boots EstellaContext with an injected WebGPUDevice over the
+# NativeActivity's ANativeWindow and renders one ECS scene. See host/main.cpp.
+add_library(estella_host SHARED host/main.cpp)
+target_link_libraries(estella_host esengine native_app_glue android log)
+set_target_properties(estella_host PROPERTIES LINK_FLAGS "-u ANativeActivity_onCreate")
diff --git a/native/README.md b/native/README.md
new file mode 100644
index 000000000..4f4fb6e66
--- /dev/null
+++ b/native/README.md
@@ -0,0 +1,83 @@
+# 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](https://dawn.googlesource.com/dawn)** (WebGPU → Metal on iOS /
+Vulkan on Android) — a real native app, **not a WebView**. Game scripts run on an
+embedded JS engine ([QuickJS-ng](https://github.com/quickjs-ng/quickjs)); the
+engine runs native (full speed), so only the game script is interpreted.
+
+This directory is the reference host + build recipe. Dawn and QuickJS are **not
+vendored** (multi-GB); 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.
+
+## 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 / text gates | `EstellaContext` under `ES_PLATFORM_WEB` / `ES_ENABLE_BITMAP_TEXT` | native drops the WebGL entry + optional bitmap text |
+| Bindings | `python -m eht --native-output` | `es_set_<C>` / `es_<C>_buffer` from the same reflection as the web embind bindings |
+| 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`) |
+
+## Build (Android arm64)
+
+Toolchain: Android SDK + NDK r28 (`android.toolchain.cmake`), SDK CMake ≥ 3.22.
+
+```sh
+# 1) Fetch Dawn and build libwebgpu_dawn.so for arm64 (Vulkan).
+git clone --depth 1 https://github.com/google/dawn "$DAWN"
+python "$DAWN/tools/fetch_dawn_dependencies.py" --shallow # NOT depot_tools
+cmake -S "$DAWN" -B "$DAWN/out-android" -G Ninja \
+ -DCMAKE_TOOLCHAIN_FILE="$NDK/build/cmake/android.toolchain.cmake" \
+ -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-33 -DANDROID_STL=c++_shared \
+ -DDAWN_ENABLE_VULKAN=ON -DDAWN_ENABLE_D3D12=OFF -DDAWN_ENABLE_METAL=OFF \
+ -DDAWN_ENABLE_NULL=OFF -DDAWN_ENABLE_OPENGLES=OFF -DDAWN_ENABLE_DESKTOP_GL=OFF \
+ -DDAWN_BUILD_SAMPLES=OFF -DDAWN_BUILD_TESTS=OFF -DTINT_BUILD_TESTS=OFF \
+ -DDAWN_BUILD_PROTOBUF=OFF -DTINT_BUILD_IR_BINARY=OFF \
+ -DDAWN_BUILD_MONOLITHIC_LIBRARY=SHARED -DDAWN_FETCH_DEPENDENCIES=OFF
+cmake --build "$DAWN/out-android" --target webgpu_dawn
+
+# 2) (JS host only) Fetch QuickJS-ng — core is dtoa/libregexp/libunicode/quickjs.c.
+git clone --depth 1 https://github.com/quickjs-ng/quickjs "$QJS"
+
+# 3) (JS host only) Generate the native bindings from the same reflection source.
+python -m eht -i src/esengine/ecs/components \
+ --native-output "$BUILD/NativeBindings.generated.cpp" \
+ --native-components Transform,Sprite,ShapeRenderer,Light2D
+
+# 4) Build the host (see CMakeLists.txt in this dir).
+cmake -S native -B "$BUILD" -G Ninja \
+ -DCMAKE_TOOLCHAIN_FILE="$NDK/build/cmake/android.toolchain.cmake" \
+ -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-33 -DANDROID_STL=c++_shared \
+ -DESTELLA_DAWN_DIR="$DAWN" -DESTELLA_DAWN_BUILD="$DAWN/out-android"
+cmake --build "$BUILD"
+```
+
+Package the APK by hand (no gradle): `aapt2 link` a manifest, inject
+`lib/arm64-v8a/{libhost.so,libwebgpu_dawn.so,libc++_shared.so}` (strip Dawn with
+`llvm-strip`), `zipalign -f 4`, `apksigner sign`.
+
+## Gotchas (all resolved; each cost a build)
+
+1. Dawn cross-compile wants a host `protoc` — `-DDAWN_BUILD_PROTOBUF=OFF`.
+2. CMake 4.x rejects old deps — use the NDK-blessed SDK CMake 3.22.
+3. `wgpuInstanceWaitAny` with a timeout needs the instance created with
+ `WGPUInstanceFeatureName_TimedWaitAny`, else "no adapter".
+4. `ALooper_pollAll` is gone in NDK 28 — use `ALooper_pollOnce`.
+5. `configureSwapchain` must use `CompositeAlphaMode::Auto`, not `Opaque` — a
+ native Vulkan surface (Adreno) rejects Opaque outright.
+6. MIUI blocks `adb install` on a locked screen — unlock + allow USB install.
+
+## Status
+
+Proven end-to-end on device (Snapdragon 8 Elite / Adreno 830, 120 fps): the full
+engine renders an ECS scene, a QuickJS game script drives it through the generated
+bindings, and the real SDK `ptrAccessors` write native component memory unchanged.
+Remaining: load the full SDK bundle + a `BuiltinBridge` memory backend, more
+system bindings, and the iOS shell (the Metal surface seam is already in place).
diff --git a/native/host/AndroidManifest.xml b/native/host/AndroidManifest.xml
new file mode 100644
index 000000000..b5baef196
--- /dev/null
+++ b/native/host/AndroidManifest.xml
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.estella.host" android:versionCode="1" android:versionName="1.0">
+ <uses-sdk android:minSdkVersion="26" android:targetSdkVersion="33" />
+ <uses-feature android:name="android.hardware.vulkan.version" android:version="0x400003" android:required="true" />
+ <application android:label="EstellaHost" android:hasCode="false" android:extractNativeLibs="true">
+ <activity android:name="android.app.NativeActivity" android:label="EstellaHost" android:configChanges="orientation|keyboardHidden|screenSize|screenLayout|density" android:exported="true">
+ <meta-data android:name="android.app.lib_name" android:value="estella_host" />
+ <intent-filter><action android:name="android.intent.action.MAIN" /><category android:name="android.intent.category.LAUNCHER" /></intent-filter>
+ </activity>
+ </application>
+</manifest>
diff --git a/native/host/main.cpp b/native/host/main.cpp
new file mode 100644
index 000000000..a739ae705
--- /dev/null
+++ b/native/host/main.cpp
@@ -0,0 +1,229 @@
+// Reference native host: boots EstellaContext with every WebGPU-relevant subsystem
+// and renders one ECS scene through the production path — TransformSystem ->
+// RenderFrame.begin/collectAll/flush/end -> present. The web harness
+// (tests/renderer/webgpu_engine_bringup.cpp) gets its device from
+// emscripten_webgpu_get_device() + configureSurface("#canvas"); this host builds
+// the instance/adapter/device itself and calls
+// configureSurface(NativeSurface{AndroidWindow}). Native Dawn -> Vulkan, no wasm.
+
+#include <android_native_app_glue.h>
+#include <android/log.h>
+#include <android/native_window.h>
+
+#include "esengine/core/EstellaContext.hpp"
+#include "esengine/core/World.hpp"
+#include "esengine/ecs/Registry.hpp"
+#include "esengine/ecs/TransformSystem.hpp"
+#include "esengine/ecs/components/Transform.hpp"
+#include "esengine/ecs/components/Sprite.hpp"
+#include "esengine/ecs/components/ShapeRenderer.hpp"
+#include "esengine/ecs/components/Light2D.hpp"
+#include "esengine/renderer/RenderContext.hpp"
+#include "esengine/renderer/RenderFrame.hpp"
+#include "esengine/renderer/webgpu/WebGPUDevice.hpp"
+#include "esengine/resource/ResourceManager.hpp"
+
+#include <glm/gtc/matrix_transform.hpp>
+
+#define LOG_TAG "EstellaFrame"
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+
+using namespace esengine;
+
+namespace {
+
+struct App {
+ WGPUInstance instance = nullptr;
+ WGPUAdapter adapter = nullptr;
+ WGPUDevice device = nullptr;
+ WebGPUDevice* gfx = nullptr; // owned by context after init; raw for present()
+ EstellaContext* ctx = nullptr;
+ ecs::Registry* registry = nullptr;
+ f32 w = 0, h = 0;
+ f32 elapsed = 0.0f;
+ bool ready = false;
+ uint64_t frame = 0;
+};
+
+void onDeviceError(WGPUDevice const*, WGPUErrorType t, WGPUStringView m, void*, void*) {
+ LOGE("uncaptured error (0x%x): %.*s", (unsigned)t, (int)m.length, m.data ? m.data : "");
+}
+void onAdapter(WGPURequestAdapterStatus s, WGPUAdapter a, WGPUStringView m, void* ud1, void*) {
+ if (s == WGPURequestAdapterStatus_Success) *static_cast<WGPUAdapter*>(ud1) = a;
+ else LOGE("adapter fail: %.*s", (int)m.length, m.data ? m.data : "");
+}
+void onDevice(WGPURequestDeviceStatus s, WGPUDevice d, WGPUStringView m, void* ud1, void*) {
+ if (s == WGPURequestDeviceStatus_Success) *static_cast<WGPUDevice*>(ud1) = d;
+ else LOGE("device fail: %.*s", (int)m.length, m.data ? m.data : "");
+}
+
+void buildScene(EstellaContext& ctx, ecs::Registry& reg, f32 W, f32 H) {
+ auto& rm = ctx.require<resource::ResourceManager>();
+ const f32 s = (W < H ? W : H); // short side, for pixel sizes
+
+ // 2x2 four-colour checker (red/green/blue/yellow).
+ const u8 checker[16] = {
+ 255, 0, 0, 255, 0, 255, 0, 255,
+ 0, 0, 255, 255, 255, 255, 0, 255,
+ };
+ auto checkerTex = rm.createTexture(2, 2, ConstSpan<u8>(checker, sizeof(checker)), TextureFormat::RGBA8);
+ const u8 white[4] = {255, 255, 255, 255};
+ auto whiteTex = rm.createTexture(1, 1, ConstSpan<u8>(white, sizeof(white)), TextureFormat::RGBA8);
+
+ // Checker sprite, upper area.
+ {
+ auto e = reg.create();
+ auto& t = reg.emplace<ecs::Transform>(e);
+ t.position = {W * 0.5f, H * 0.62f, 0.0f};
+ auto& sp = reg.emplace<ecs::Sprite>(e);
+ sp.texture = checkerTex;
+ sp.size = {s * 0.5f, s * 0.5f};
+ }
+ // Magenta SDF circle, middle.
+ {
+ auto e = reg.create();
+ auto& t = reg.emplace<ecs::Transform>(e);
+ t.position = {W * 0.32f, H * 0.42f, 0.0f};
+ auto& sh = reg.emplace<ecs::ShapeRenderer>(e);
+ sh.shapeType = 0; // circle
+ sh.color = {1.0f, 0.0f, 1.0f, 1.0f};
+ sh.size = {s * 0.28f, s * 0.28f};
+ }
+ // Lit white sprite + a red point light + ambient, so lighting shows.
+ {
+ auto e = reg.create();
+ auto& t = reg.emplace<ecs::Transform>(e);
+ t.position = {W * 0.68f, H * 0.42f, 0.0f};
+ auto& sp = reg.emplace<ecs::Sprite>(e);
+ sp.texture = whiteTex;
+ sp.size = {s * 0.28f, s * 0.28f};
+ sp.lit = true;
+ }
+ {
+ auto e = reg.create();
+ auto& t = reg.emplace<ecs::Transform>(e);
+ t.position = {W * 0.68f, H * 0.42f, 0.0f};
+ auto& l = reg.emplace<ecs::Light2D>(e);
+ l.type = static_cast<i32>(ecs::Light2DType::Point);
+ l.color = {1.0f, 0.3f, 0.1f, 1.0f};
+ l.intensity = 1.5f;
+ l.radius = s * 0.5f;
+ }
+ {
+ auto e = reg.create();
+ reg.emplace<ecs::Transform>(e);
+ auto& l = reg.emplace<ecs::Light2D>(e);
+ l.type = static_cast<i32>(ecs::Light2DType::Ambient);
+ l.color = {1.0f, 1.0f, 1.0f, 1.0f};
+ l.intensity = 0.25f;
+ }
+}
+
+void renderScene(App& a) {
+ if (!a.ready) return;
+ auto& ctx = *a.ctx;
+ auto& reg = *a.registry;
+
+ a.elapsed += 1.0f / 60.0f;
+ ctx.require<RenderContext>().setFrameTime(a.elapsed, (u32)a.w, (u32)a.h);
+
+ World world{reg, ctx.services(), 1.0f / 60.0f};
+ ctx.require<ecs::TransformSystem>().update(world);
+
+ // World units are pixels, y up.
+ const glm::mat4 vp = glm::ortho(0.0f, a.w, 0.0f, a.h);
+
+ auto& rf = ctx.require<RenderFrame>();
+ rf.begin(vp, 0, RenderFrame::PassClear{true, true, glm::vec4(0.08f, 0.09f, 0.13f, 1.0f)});
+ rf.collectAll(reg);
+ rf.flush();
+ rf.end();
+
+ a.gfx->present();
+
+ if (++a.frame % 120 == 0) LOGI("engine scene frame %llu", (unsigned long long)a.frame);
+}
+
+void initEngine(App& a, ANativeWindow* window) {
+ WGPUInstanceFeatureName feats[] = {WGPUInstanceFeatureName_TimedWaitAny};
+ WGPUInstanceDescriptor idesc = {};
+ idesc.requiredFeatureCount = 1;
+ idesc.requiredFeatures = feats;
+ a.instance = wgpuCreateInstance(&idesc);
+
+ WGPURequestAdapterOptions opts = {};
+ opts.powerPreference = WGPUPowerPreference_HighPerformance;
+ opts.backendType = WGPUBackendType_Vulkan;
+ WGPURequestAdapterCallbackInfo aci = {};
+ aci.mode = WGPUCallbackMode_WaitAnyOnly;
+ aci.callback = onAdapter;
+ aci.userdata1 = &a.adapter;
+ WGPUFutureWaitInfo af = {wgpuInstanceRequestAdapter(a.instance, &opts, aci), 0};
+ wgpuInstanceWaitAny(a.instance, 1, &af, UINT64_MAX);
+ if (!a.adapter) { LOGE("no adapter"); return; }
+
+ WGPUDeviceDescriptor dd = {};
+ dd.uncapturedErrorCallbackInfo.callback = onDeviceError;
+ WGPURequestDeviceCallbackInfo dci = {};
+ dci.mode = WGPUCallbackMode_WaitAnyOnly;
+ dci.callback = onDevice;
+ dci.userdata1 = &a.device;
+ WGPUFutureWaitInfo df = {wgpuAdapterRequestDevice(a.adapter, &dd, dci), 0};
+ wgpuInstanceWaitAny(a.instance, 1, &df, UINT64_MAX);
+ if (!a.device) { LOGE("no device"); return; }
+
+ a.w = (f32)ANativeWindow_getWidth(window);
+ a.h = (f32)ANativeWindow_getHeight(window);
+
+ auto device = makeUnique<WebGPUDevice>(a.device, a.instance);
+ a.gfx = device.get(); // stays valid: context owns it, we only borrow for present()
+ if (!a.gfx->configureSurface(WebGPUDevice::NativeSurface{WebGPUDevice::NativeWindowKind::AndroidWindow, window},
+ (u32)a.w, (u32)a.h)) {
+ LOGE("configureSurface failed");
+ return;
+ }
+
+ static EstellaContext context;
+ a.ctx = &context;
+ context.state().viewport_width = (i32)a.w;
+ context.state().viewport_height = (i32)a.h;
+ if (!context.init(std::move(device))) { LOGE("context.init failed"); return; }
+
+ static ecs::Registry registry;
+ a.registry = &registry;
+ buildScene(context, registry, a.w, a.h);
+
+ a.ready = true;
+ LOGI("full engine up (%dx%d) — production render path on native Dawn", (int)a.w, (int)a.h);
+}
+
+void onAppCmd(android_app* app, int32_t cmd) {
+ App* a = static_cast<App*>(app->userData);
+ switch (cmd) {
+ case APP_CMD_INIT_WINDOW:
+ if (app->window && !a->ready) { LOGI("APP_CMD_INIT_WINDOW"); initEngine(*a, app->window); }
+ break;
+ default:
+ break;
+ }
+}
+
+} // namespace
+
+void android_main(android_app* app) {
+ App a;
+ app->userData = &a;
+ app->onAppCmd = onAppCmd;
+ while (true) {
+ int events;
+ android_poll_source* source;
+ int timeoutMs = a.ready ? 0 : -1;
+ while (ALooper_pollOnce(timeoutMs, nullptr, &events, (void**)&source) >= 0) {
+ if (source) source->process(app, source);
+ if (app->destroyRequested) return;
+ timeoutMs = 0;
+ }
+ renderScene(a);
+ }
+}