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.

feat(native): host runs the real App + touch input; game.js is an APK asset

yhh51a7459e36f3
diff --git a/native/js/game.js b/native/js/game.js
new file mode 100644
index 000000000..cdd8e4fd6
--- /dev/null
+++ b/native/js/game.js
@@ -0,0 +1,41 @@
+// Demo game — pure game logic, loaded at runtime from the APK's assets/ (NOT
+// compiled into the C++ host). It authors through the real SDK exactly like a web
+// game: ESEngine.createNativeApp + world.spawn/insert + the Input resource. The
+// host provides `ESEngine` (SDK bundle), the `es_*` globals, the frame constants
+// W/H/S, and the platform bridge `__esNativeBridge`.
+//
+// A sprite follows the touch; a shape orbits — proof the real App runs on device.
+
+var app, world, input, follower, orbit, t = 0.0;
+
+function init() {
+ es_setClear(0.07, 0.08, 0.12);
+ app = ESEngine.createNativeApp(globalThis.__esNativeBridge, globalThis);
+ app.tick(0); // sync through finishPlugins: binds input + inserts Input
+ world = app.world;
+ input = app.getResource(ESEngine.Input);
+
+ var tex = es_createTexture(2, 2, [
+ 255, 0, 0, 255, 0, 255, 0, 255,
+ 0, 0, 255, 255, 255, 255, 0, 255 ]);
+
+ follower = world.spawn();
+ world.insert(follower, ESEngine.Transform, { position: { x: W * 0.5, y: H * 0.5, z: 0 } });
+ world.insert(follower, ESEngine.Sprite, {
+ texture: tex, color: { r: 1, g: 1, b: 1, a: 1 }, size: { x: S * 0.2, y: S * 0.2 } });
+
+ orbit = world.spawn();
+ world.insert(orbit, ESEngine.Transform, { position: { x: W * 0.5, y: H * 0.75, z: 0 } });
+ world.insert(orbit, ESEngine.ShapeRenderer, {
+ shapeType: 0, color: { r: 1, g: 0.2, b: 0.9, a: 1 }, size: { x: S * 0.12, y: S * 0.12 } });
+}
+
+function update(dt) {
+ t += dt;
+ app.tick(dt); // run the App loop (host pumps its async jobs)
+ // Follow the touch. Android touch is top-left origin; the world is y-up.
+ var p = input.getMousePosition();
+ world.insert(follower, ESEngine.Transform, { position: { x: p.x, y: H - p.y, z: 0 } });
+ world.insert(orbit, ESEngine.Transform, {
+ position: { x: W * 0.5 + Math.cos(t * 1.2) * S * 0.3, y: H * 0.75, z: 0 } });
+}
diff --git a/native/js/main.cpp b/native/js/main.cpp
index 490e4beba..55f02d2de 100644
--- a/native/js/main.cpp
+++ b/native/js/main.cpp
@@ -1,23 +1,27 @@
-// Estella native JS host — the REAL SDK, driving the native C++ engine.
-//
-// The game script authors through the actual esengine TS SDK (bundled to one JS
-// file, dist/index.native.bundled.js, loaded here as `ESEngine`): createNativeWorld
-// returns the same World class the web build uses, connected to the native core via
-// the generated bindings. spawn / insert / query run in QuickJS; the components land
-// in the native C++ ECS, which this host renders. No wasm — the engine is native.
+// Estella native JS host — a thin C++ shell that runs the REAL SDK. Three layers,
+// only this one is C++:
+// 1. This host (native/js/main.cpp): boots Dawn, installs the es_* native
+// bindings as globals, feeds Android touch to JS, reads the APK, and renders.
+// 2. The SDK bundle (dist/index.native.bundled.js, embedded): the actual esengine
+// TS SDK — createNativeApp / World / Input — installed as `ESEngine`. Not here.
+// 3. The game (assets/game.js, an APK asset loaded at runtime): developer content.
+// It calls ESEngine.createNativeApp(__esNativeBridge) and authors the scene.
+// NOT compiled into the host — it ships as an asset, like a real game.
//
// The host installs the native side of the registry contract as globals:
// * entity + hierarchy (hand-written here): es_createEntity / es_destroyEntity /
// es_setParent / es_hasParent / es_removeParent / es_hasChildren / es_getChildren
// * per-component (EHT-generated, esn_register): es_set_<C> / es_<C>_buffer /
// es_<C>_has / es_<C>_remove
-// * resources (hand-written): es_createTexture, es_setClear
+// * resources + assets (hand-written): es_createTexture, es_setClear, es_readAsset
// createNativeRegistry + NativeMemoryProvider inside the SDK bundle read these off
// globalThis. Entity ids are the native Entity's raw u32 (round-tripped via
// Entity::fromRaw), so hierarchy queries return ids the SDK recognises.
#include <android_native_app_glue.h>
#include <android/log.h>
+#include <android/input.h>
+#include <android/asset_manager.h>
#include <android/native_window.h>
#include "esn_shim.hpp" // quickjs + the esn_* plumbing decls (+ esn_register)
@@ -35,6 +39,7 @@
#include <glm/gtc/matrix_transform.hpp>
#include <cstring>
+#include <string>
#include <vector>
#define LOG_TAG "EstellaSDK"
@@ -43,33 +48,33 @@
using namespace esengine;
-// The game script — authored entirely against the real SDK (ESEngine.*). Same API
-// the web build exposes; only the game logic is interpreted, the engine runs native.
-static const char* kGameScript = R"JS(
-var world, moving, orbit;
-function init() {
- es_setClear(0.07, 0.08, 0.12);
- world = ESEngine.createNativeWorld();
- var tex = es_createTexture(2, 2, [
- 255, 0, 0, 255, 0, 255, 0, 255,
- 0, 0, 255, 255, 255, 255, 0, 255 ]);
- moving = world.spawn();
- world.insert(moving, ESEngine.Transform, { position: { x: W * 0.5, y: H * 0.62, z: 0 } });
- world.insert(moving, ESEngine.Sprite, {
- texture: tex, color: { r: 1, g: 1, b: 1, a: 1 }, size: { x: S * 0.42, y: S * 0.42 } });
- orbit = world.spawn();
- world.insert(orbit, ESEngine.Transform, { position: { x: W * 0.5, y: H * 0.42, z: 0 } });
- world.insert(orbit, ESEngine.ShapeRenderer, {
- shapeType: 0, color: { r: 1, g: 0.2, b: 0.9, a: 1 }, size: { x: S * 0.26, y: S * 0.26 } });
-}
-var t = 0.0;
-function update(dt) {
- t += dt;
- world.insert(moving, ESEngine.Transform, {
- position: { x: W * 0.5 + Math.sin(t * 1.6) * S * 0.5, y: H * 0.62, z: 0 } });
- world.insert(orbit, ESEngine.Transform, {
- position: { x: W * 0.5 + Math.cos(t * 1.2) * S * 0.3, y: H * 0.42 + Math.sin(t * 1.2) * S * 0.14, z: 0 } });
-}
+// Host platform bootstrap — HOST code, not game. It fans host touch out to the SDK
+// listener and builds the NativeBridge from the host's es_* capabilities. The game
+// (game.js, loaded from the APK's assets/) then calls createNativeApp(__esNativeBridge).
+static const char* kBootstrapJS = R"JS(
+globalThis.es_onNativeTouch = function (type, id, x, y) {
+ var l = globalThis.__esInputListener;
+ if (!l) return;
+ if (type === 0) l.onTouchStart(id, x, y);
+ else if (type === 1) l.onTouchMove(id, x, y);
+ else if (type === 2) l.onTouchEnd(id);
+ else l.onTouchCancel(id);
+};
+globalThis.__esNativeBridge = {
+ readFile: function (path) {
+ var b = es_readAsset(path);
+ return b ? Promise.resolve(b) : Promise.reject(new Error('asset not found: ' + path));
+ },
+ fileExists: function (path) { return Promise.resolve(es_readAsset(path) != null); },
+ fetch: function () { return Promise.resolve({ ok: false, status: 404 }); },
+ loadImagePixels: function () { return Promise.reject(new Error('image decode not wired')); },
+ getStorageItem: function () { return null; },
+ setStorageItem: function () {},
+ removeStorageItem: function () {},
+ storageKeys: function () { return []; },
+ registerInput: function (l) { globalThis.__esInputListener = l; return function () { globalThis.__esInputListener = null; }; },
+ devicePixelRatio: function () { return 1; },
+};
)JS";
namespace {
@@ -83,6 +88,7 @@ struct App {
ecs::Registry* registry = nullptr;
JSRuntime* rt = nullptr;
JSContext* js = nullptr;
+ AAssetManager* assets = nullptr; // APK assets/ — the game + its content
glm::vec4 clear{0.07f, 0.08f, 0.12f, 1.0f};
f32 w = 0, h = 0;
bool ready = false; // engine + JS booted once
@@ -201,6 +207,32 @@ JSValue js_createTexture(JSContext* ctx, JSValueConst, int, JSValueConst* argv)
return JS_NewInt64(ctx, (int64_t)handle.id());
}
+// Read an APK asset (assets/<path>) fully into a buffer; empty if missing. This is
+// the native NativeBridge.readFile capability — a packaged (project-relative) file.
+std::vector<u8> readAsset(App& a, const char* path) {
+ std::vector<u8> out;
+ if (!a.assets) return out;
+ AAsset* asset = AAssetManager_open(a.assets, path, AASSET_MODE_BUFFER);
+ if (!asset) return out;
+ off_t len = AAsset_getLength(asset);
+ if (len > 0) {
+ out.resize((size_t)len);
+ AAsset_read(asset, out.data(), (size_t)len);
+ }
+ AAsset_close(asset);
+ return out;
+}
+
+// es_readAsset(path) -> ArrayBuffer | null. Backs the bridge's readFile.
+JSValue js_readAsset(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {
+ const char* path = JS_ToCString(ctx, argv[0]);
+ if (!path) return JS_NULL;
+ std::vector<u8> bytes = readAsset(*g_app, path);
+ JS_FreeCString(ctx, path);
+ if (bytes.empty()) return JS_NULL;
+ return JS_NewArrayBufferCopy(ctx, bytes.data(), bytes.size());
+}
+
void logJsError(JSContext* ctx, const char* where) {
JSValue e = JS_GetException(ctx);
const char* s = JS_ToCString(ctx, e);
@@ -225,6 +257,32 @@ void callJs(App& a, const char* fn, int argc, JSValue* argv) {
JS_FreeValue(a.js, global);
}
+// Drain QuickJS's microtask queue. app.tick() is async: its synchronous prefix
+// (finishPlugins, resource inserts) runs on call, but the systems run in jobs.
+void pumpJobs(App& a) {
+ JSContext* c;
+ while (JS_ExecutePendingJob(a.rt, &c) > 0) { /* ran a job */ }
+}
+
+// Push one Android touch to the game's es_onNativeTouch(type,id,x,y), which fans it
+// out to the NativeBridge's registered listener. type: 0 start / 1 move / 2 end / 3 cancel.
+void dispatchTouch(App& a, int type, int id, float x, float y) {
+ JSValue global = JS_GetGlobalObject(a.js);
+ JSValue fn = JS_GetPropertyStr(a.js, global, "es_onNativeTouch");
+ if (JS_IsFunction(a.js, fn)) {
+ JSValue args[4] = {
+ JS_NewInt32(a.js, type), JS_NewInt32(a.js, id),
+ JS_NewFloat64(a.js, x), JS_NewFloat64(a.js, y),
+ };
+ JSValue r = JS_Call(a.js, fn, global, 4, args);
+ if (JS_IsException(r)) logJsError(a.js, "es_onNativeTouch");
+ JS_FreeValue(a.js, r);
+ for (JSValue& v : args) JS_FreeValue(a.js, v);
+ }
+ JS_FreeValue(a.js, fn);
+ JS_FreeValue(a.js, global);
+}
+
void bindGlobal(App& a, JSValue global, const char* name, JSCFunction* fn, int argc) {
JS_SetPropertyStr(a.js, global, name, JS_NewCFunction(a.js, fn, name, argc));
}
@@ -246,18 +304,26 @@ void initJS(App& a) {
bindGlobal(a, global, "es_removeParent", js_removeParent, 1);
bindGlobal(a, global, "es_hasChildren", js_hasChildren, 1);
bindGlobal(a, global, "es_getChildren", js_getChildren, 1);
- // Resources + clear.
+ // Resources + clear + asset reads.
bindGlobal(a, global, "es_setClear", js_setClear, 3);
bindGlobal(a, global, "es_createTexture", js_createTexture, 3);
+ bindGlobal(a, global, "es_readAsset", js_readAsset, 1);
// Per-component bindings (EHT-generated): es_set_<C> / es_<C>_buffer / _has / _remove.
esn_register(a.js, global);
JS_FreeValue(a.js, global);
- // The real SDK bundle installs globalThis.ESEngine; then the game script runs.
+ // Layers: the real SDK bundle (engine, embedded) installs ESEngine; the host
+ // bootstrap (host platform glue) installs the NativeBridge; the game (an APK
+ // asset, developer content) authors on top.
evalJs(a, kSdkBundleJS, "esengine.native.js");
- evalJs(a, kGameScript, "game.js");
+ evalJs(a, kBootstrapJS, "bootstrap.js");
+ std::vector<u8> game = readAsset(a, "game.js");
+ if (game.empty()) { LOGE("game.js asset missing from the APK"); return; }
+ std::string src(reinterpret_cast<const char*>(game.data()), game.size());
+ evalJs(a, src.c_str(), "game.js");
callJs(a, "init", 0, nullptr);
- LOGI("game script init() ran on the real SDK World");
+ pumpJobs(a);
+ LOGI("game.js (APK asset) init() ran on the real SDK App");
}
void renderScene(App& a) {
@@ -266,6 +332,7 @@ void renderScene(App& a) {
JSValue dt = JS_NewFloat64(a.js, 1.0 / 60.0);
callJs(a, "update", 1, &dt);
JS_FreeValue(a.js, dt);
+ pumpJobs(a); // run the App tick's async systems
ctx.require<RenderContext>().setFrameTime((f32)a.frame / 60.0f, (u32)a.w, (u32)a.h);
World world{*a.registry, ctx.services(), 1.0f / 60.0f};
@@ -337,6 +404,25 @@ void initEngine(App& a, ANativeWindow* window) {
LOGI("real SDK up (%dx%d) — esengine World over native Dawn", (int)a.w, (int)a.h);
}
+int32_t onInput(android_app* app, AInputEvent* ev) {
+ App* a = static_cast<App*>(app->userData);
+ if (!a->ready || AInputEvent_getType(ev) != AINPUT_EVENT_TYPE_MOTION) return 0;
+ const int32_t action = AMotionEvent_getAction(ev) & AMOTION_EVENT_ACTION_MASK;
+ const float x = AMotionEvent_getX(ev, 0);
+ const float y = AMotionEvent_getY(ev, 0);
+ int type;
+ switch (action) {
+ case AMOTION_EVENT_ACTION_DOWN:
+ case AMOTION_EVENT_ACTION_POINTER_DOWN: type = 0; break;
+ case AMOTION_EVENT_ACTION_MOVE: type = 1; break;
+ case AMOTION_EVENT_ACTION_UP:
+ case AMOTION_EVENT_ACTION_POINTER_UP: type = 2; break;
+ default: type = 3; break;
+ }
+ dispatchTouch(*a, type, 0, x, y);
+ return 1;
+}
+
void onAppCmd(android_app* app, int32_t cmd) {
App* a = static_cast<App*>(app->userData);
switch (cmd) {
@@ -362,8 +448,10 @@ void onAppCmd(android_app* app, int32_t cmd) {
void android_main(android_app* app) {
App a;
g_app = &a;
+ a.assets = app->activity->assetManager; // APK assets/ (game.js + content)
app->userData = &a;
app->onAppCmd = onAppCmd;
+ app->onInputEvent = onInput;
while (true) {
int events;
android_poll_source* source;