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
refactor(native): name the two reference hosts for what they are
esengine8034563cc0e6
diff --git a/.vscode/c_cpp_properties.json b/.vscode/c_cpp_properties.jsonindex 7fcc461b2..0a4c62b88 100644--- a/.vscode/c_cpp_properties.json+++ b/.vscode/c_cpp_properties.json@@ -14,7 +14,7 @@"${workspaceFolder}/third_party/nlohmann","${workspaceFolder}/third_party/box2d/include","${workspaceFolder}/build/quickjs_headers",- "${workspaceFolder}/native/js",+ "${workspaceFolder}/native/host_js","${workspaceFolder}/third_party","${env:ESTELLA_DAWN_DIR}/include","${env:ESTELLA_DAWN_BUILD}/gen/include",@@ -87,7 +87,7 @@"name": "Native Host (Android)","includePath": ["${workspaceFolder}/src",- "${workspaceFolder}/native/js",+ "${workspaceFolder}/native/host_js","${workspaceFolder}/third_party","${workspaceFolder}/third_party/glm","${workspaceFolder}/third_party/stb",@@ -112,7 +112,7 @@"name": "Native Host (iOS)","includePath": ["${workspaceFolder}/src",- "${workspaceFolder}/native/js",+ "${workspaceFolder}/native/host_js","${workspaceFolder}/third_party","${workspaceFolder}/third_party/glm","${workspaceFolder}/third_party/stb",diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.jsindex 741f77e64..ea9738b98 100644--- a/build-tools/tasks/native.js+++ b/build-tools/tasks/native.js@@ -120,7 +120,7 @@ async function buildAndroidHost(options) {'-DCMAKE_BUILD_TYPE=Release',// Emit build-native/compile_commands.json so editor IntelliSense (the// "Native Host" c_cpp_properties config) resolves the NDK / Dawn / QuickJS- // includes for native/js without hardcoding any machine paths.+ // includes for native/host_js without hardcoding any machine paths.'-DCMAKE_EXPORT_COMPILE_COMMANDS=ON',`-DESTELLA_DAWN_DIR=${dawnDir}`,`-DESTELLA_DAWN_BUILD=${dawnBuild}`,diff --git a/build-tools/tasks/nativePackage.js b/build-tools/tasks/nativePackage.jsindex 63973a84b..578d1c702 100644--- a/build-tools/tasks/nativePackage.js+++ b/build-tools/tasks/nativePackage.js@@ -17,14 +17,14 @@ import { requireSdk, requireNdk, buildTool, platformJar, ndkTool, ndkLibcxxShareconst HOSTS = {// The product-shaped runtime: the QuickJS host + the SDK + a game asset.js: {- manifest: 'js',+ manifest: 'host_js',library: 'libestella_js_host.so',assets: ['game.js', 'logo.png'],apk: 'estella-js-host.apk',},// The pure-C++ smoke test: one ECS scene, no JS, no assets.cpp: {- manifest: 'host',+ manifest: 'host_cpp',library: 'libestella_host.so',assets: [],apk: 'estella-host.apk',@@ -94,7 +94,7 @@ export async function packageNativeApk(options = {}) {assetsDir = path.join(staging, 'assets');await mkdir(assetsDir, { recursive: true });for (const asset of host.assets) {- await copyFile(path.join(rootDir, 'native', 'js', asset), path.join(assetsDir, asset));+ await copyFile(path.join(rootDir, 'native', 'host_js', asset), path.join(assetsDir, asset));}}diff --git a/native/CMakeLists.txt b/native/CMakeLists.txtindex 030b0a96a..c5446516e 100644--- a/native/CMakeLists.txt+++ b/native/CMakeLists.txt@@ -88,9 +88,9 @@ target_compile_definitions(esengine PUBLIC ES_ENABLE_WEBGPU) # NOT ES_PLATFORM_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.+# NativeActivity's ANativeWindow and renders one ECS scene. See host_cpp/main.cpp.if(ANDROID)- add_library(estella_host SHARED host/main.cpp)+ add_library(estella_host SHARED host_cpp/main.cpp)target_link_libraries(estella_host esengine native_app_glue android log)set_target_properties(estella_host PROPERTIES LINK_FLAGS "-u ANativeActivity_onCreate")endif()@@ -119,12 +119,12 @@ if(ESTELLA_QUICKJS_DIR)target_compile_definitions(qjs PRIVATE _GNU_SOURCE)target_compile_options(qjs PRIVATE -Wno-unused -Wno-sign-compare)- # js/host_core.cpp is the platform-independent host; each platform adds its own+ # host_js/host_core.cpp is the platform-independent host; each platform adds its own# glue TU (the event loop, the window, the packaged assets).if(ESTELLA_IOS)# Static: the thin Xcode app (native/ios) links this plus the libraries# below. -ObjC on the app keeps the Obj-C classes in main_ios.mm alive.- add_library(estella_js_host STATIC js/host_core.cpp js/main_ios.mm "${NATIVE_BINDINGS}")+ add_library(estella_js_host STATIC host_js/host_core.cpp host_js/main_ios.mm "${NATIVE_BINDINGS}")target_link_libraries(estella_js_host esengine qjs"-framework UIKit" "-framework QuartzCore" "-framework Foundation")# Merge host + engine + deps + Dawn into ONE archive, so the Xcode app is a@@ -135,12 +135,12 @@ if(ESTELLA_QUICKJS_DIR)$<TARGET_FILE:qjs> $<TARGET_FILE:yogacore> "${ESTELLA_DAWN_LIB}"COMMENT "Merging the iOS host, engine and Dawn into libestella_ios.a")else()- add_library(estella_js_host SHARED js/host_core.cpp js/main_android.cpp "${NATIVE_BINDINGS}")+ add_library(estella_js_host SHARED host_js/host_core.cpp host_js/main_android.cpp "${NATIVE_BINDINGS}")target_link_libraries(estella_js_host esengine qjs native_app_glue android log)set_target_properties(estella_js_host PROPERTIES LINK_FLAGS "-u ANativeActivity_onCreate")endif()- # js/ holds esn_shim.hpp + host_core.hpp (the generated TU includes the shim);+ # host_js/ holds esn_shim.hpp + host_core.hpp (the generated TU includes the shim);# the gen dir holds ptraccessors_js.h and the embedded SDK bundle.target_include_directories(estella_js_host PRIVATE- "${CMAKE_CURRENT_SOURCE_DIR}/js" "${ESTELLA_NATIVE_GEN_DIR}")+ "${CMAKE_CURRENT_SOURCE_DIR}/host_js" "${ESTELLA_NATIVE_GEN_DIR}")endif()diff --git a/native/README.md b/native/README.mdindex 0c5d55d94..3c3b0f375 100644--- a/native/README.md+++ b/native/README.md@@ -9,20 +9,20 @@ engine runs native (full speed), so only the game script is interpreted.This directory holds two reference hosts + the build recipe:-- **`host/`** — a pure-C++ host that renders one ECS scene (no JS). A smoke test+- **`host_cpp/`** — a pure-C++ host that renders one ECS scene (no JS). A smoke testfor the engine core on native Dawn. Android only; always built there.-- **`js/`** — the JS host: a QuickJS game script drives the engine through the+- **`host_js/`** — the JS host: a QuickJS game script drives the engine through the**real esengine SDK**. The SDK is bundled to one file(`dist/index.native.bundled.js`, installing `ESEngine`) and the game authors with`ESEngine.createNativeWorld()` — the same `World` the web build uses. Built whenyou pass `--quickjs` (this is the product-shaped runtime). It is one host with aplatform seam, not one per OS:- - `js/host_core.{hpp,cpp}` — Dawn bring-up, the `es_*` bindings, the SDK bundle+ - `host_js/host_core.{hpp,cpp}` — Dawn bring-up, the `es_*` bindings, the SDK bundleand the frame. Platform-independent; everything that differs sits behind`eshost::Platform`.- - `js/main_android.cpp` — NativeActivity, APK assets, Vulkan, the ALooper loop.- - `js/main_ios.mm` — a CAMetalLayer view, bundle assets, Metal, CADisplayLink.-- **`android/`** — the APK manifests (`host/`, `js/`), packaged by `--package`.+ - `host_js/main_android.cpp` — NativeActivity, APK assets, Vulkan, the ALooper loop.+ - `host_js/main_ios.mm` — a CAMetalLayer view, bundle assets, Metal, CADisplayLink.+- **`android/`** — the APK manifests (`host_cpp/`, `host_js/`), packaged by `--package`.- **`ios/`** — the Xcode app shell (xcodegen) that signs and packages the iOSbuild. It is only an entry point; the app lives in the static library.@@ -42,7 +42,7 @@ the tree:| 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`) |-| Host platform | `eshost::Platform` (`js/host_core.hpp`) | packaged assets, cache dir, backend, window surface + size, log — the only things the two OS glue files answer differently |+| Host platform | `eshost::Platform` (`host_js/host_core.hpp`) | packaged assets, cache dir, backend, window surface + size, log — the only things the two OS glue files answer differently |## Build (Android arm64)@@ -97,7 +97,7 @@ node build-tools/cli.js native --dawn "$DAWN" --dawn-build "$DAWN/out-android" \adb install -r build-native/estella-js-host.apk```-It runs `aapt2 link` over `native/android/<host>/AndroidManifest.xml`, stages+It runs `aapt2 link` over `native/android/host_{js,cpp}/AndroidManifest.xml`, stages`lib/arm64-v8a/{libestella*_host.so,libwebgpu_dawn.so,libc++_shared.so}` (Dawnstripped with the NDK's `llvm-strip`), packs the game and its content into`assets/` where the host's `readAsset()` looks, then `zipalign -f 4` and@@ -140,8 +140,8 @@ cd native/ios && xcodegen && open EstellaiOS.xcodeprojThen pick your Team under *Signing & Capabilities*, select your device and Run.The CMake build merges host + engine + QuickJS + Dawn into one archive(`build-native-ios/libestella_ios.a`), so the Xcode project is a signing and-packaging shell: `App/main.m` calls `EstellaRunApp()`, and the game (`js/game.js`,-`js/logo.png`) ships as bundle resources — the same project-relative paths the APK+packaging shell: `App/main.m` calls `EstellaRunApp()`, and the game (`host_js/game.js`,+`host_js/logo.png`) ships as bundle resources — the same project-relative paths the APKserves from `assets/`.## Gotchas (all resolved; each cost a build)diff --git a/native/android/host/AndroidManifest.xml b/native/android/host_cpp/AndroidManifest.xmlsimilarity index 100%rename from native/android/host/AndroidManifest.xmlrename to native/android/host_cpp/AndroidManifest.xmldiff --git a/native/android/js/AndroidManifest.xml b/native/android/host_js/AndroidManifest.xmlsimilarity index 100%rename from native/android/js/AndroidManifest.xmlrename to native/android/host_js/AndroidManifest.xmldiff --git a/native/host/main.cpp b/native/host_cpp/main.cppsimilarity index 100%rename from native/host/main.cpprename to native/host_cpp/main.cppdiff --git a/native/js/esn_shim.hpp b/native/host_js/esn_shim.hppsimilarity index 100%rename from native/js/esn_shim.hpprename to native/host_js/esn_shim.hppdiff --git a/native/js/game.js b/native/host_js/game.jssimilarity index 100%rename from native/js/game.jsrename to native/host_js/game.jsdiff --git a/native/js/host_core.cpp b/native/host_js/host_core.cppsimilarity index 100%rename from native/js/host_core.cpprename to native/host_js/host_core.cppdiff --git a/native/js/host_core.hpp b/native/host_js/host_core.hppsimilarity index 100%rename from native/js/host_core.hpprename to native/host_js/host_core.hppdiff --git a/native/js/logo.png b/native/host_js/logo.pngsimilarity index 100%rename from native/js/logo.pngrename to native/host_js/logo.pngdiff --git a/native/js/main_android.cpp b/native/host_js/main_android.cppsimilarity index 100%rename from native/js/main_android.cpprename to native/host_js/main_android.cppdiff --git a/native/js/main_ios.mm b/native/host_js/main_ios.mmsimilarity index 100%rename from native/js/main_ios.mmrename to native/host_js/main_ios.mmdiff --git a/native/ios/project.yml b/native/ios/project.ymlindex 45f35e436..f25672c23 100644--- a/native/ios/project.yml+++ b/native/ios/project.yml@@ -21,10 +21,10 @@ targets:platform: iOSsources:- path: App- - path: ../js/game.js+ - path: ../host_js/game.jsbuildPhase: resourcestype: file- - path: ../js/logo.png+ - path: ../host_js/logo.pngbuildPhase: resourcestype: filesettings: