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.

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.json
index 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.js
index 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.js
index 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, ndkLibcxxShare
const 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.txt
index 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.md
index 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 test
for 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 when
you pass `--quickjs` (this is the product-shaped runtime). It is one host with a
platform 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 bundle
and 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 iOS
build. 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}` (Dawn
stripped 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.xcodeproj
Then 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 APK
serves from `assets/`.
## Gotchas (all resolved; each cost a build)
diff --git a/native/android/host/AndroidManifest.xml b/native/android/host_cpp/AndroidManifest.xml
similarity index 100%
rename from native/android/host/AndroidManifest.xml
rename to native/android/host_cpp/AndroidManifest.xml
diff --git a/native/android/js/AndroidManifest.xml b/native/android/host_js/AndroidManifest.xml
similarity index 100%
rename from native/android/js/AndroidManifest.xml
rename to native/android/host_js/AndroidManifest.xml
diff --git a/native/host/main.cpp b/native/host_cpp/main.cpp
similarity index 100%
rename from native/host/main.cpp
rename to native/host_cpp/main.cpp
diff --git a/native/js/esn_shim.hpp b/native/host_js/esn_shim.hpp
similarity index 100%
rename from native/js/esn_shim.hpp
rename to native/host_js/esn_shim.hpp
diff --git a/native/js/game.js b/native/host_js/game.js
similarity index 100%
rename from native/js/game.js
rename to native/host_js/game.js
diff --git a/native/js/host_core.cpp b/native/host_js/host_core.cpp
similarity index 100%
rename from native/js/host_core.cpp
rename to native/host_js/host_core.cpp
diff --git a/native/js/host_core.hpp b/native/host_js/host_core.hpp
similarity index 100%
rename from native/js/host_core.hpp
rename to native/host_js/host_core.hpp
diff --git a/native/js/logo.png b/native/host_js/logo.png
similarity index 100%
rename from native/js/logo.png
rename to native/host_js/logo.png
diff --git a/native/js/main_android.cpp b/native/host_js/main_android.cpp
similarity index 100%
rename from native/js/main_android.cpp
rename to native/host_js/main_android.cpp
diff --git a/native/js/main_ios.mm b/native/host_js/main_ios.mm
similarity index 100%
rename from native/js/main_ios.mm
rename to native/host_js/main_ios.mm
diff --git a/native/ios/project.yml b/native/ios/project.yml
index 45f35e436..f25672c23 100644
--- a/native/ios/project.yml
+++ b/native/ios/project.yml
@@ -21,10 +21,10 @@ targets:
platform: iOS
sources:
- path: App
- - path: ../js/game.js
+ - path: ../host_js/game.js
buildPhase: resources
type: file
- - path: ../js/logo.png
+ - path: ../host_js/logo.png
buildPhase: resources
type: file
settings: