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
build(native): first-class native (embedded-Dawn) target, single-sourced with web
yhh753051232d03
diff --git a/CMakeLists.txt b/CMakeLists.txtindex 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_HEADERSdiff --git a/build-tools/cli.js b/build-tools/cli.jsindex 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.jsnew file mode 100644index 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.cmakenew file mode 100644index 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.txtnew file mode 100644index 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.mdnew file mode 100644index 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.xmlnew file mode 100644index 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.cppnew file mode 100644index 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 = ®istry;+ 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);+ }+}