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.

20.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Runtime.cpp
 * @brief   The JS runtime the host owns: the environment the language does not
 *          ship, the binding installation, and the boot of the SDK + game.
 * @details A JS engine is a language, not a runtime — no console, no timers, no
 *          clock. Those are the host's job and they live here, beside the eval
 *          helpers and the compile cache that makes a ~700 KB SDK bundle load in
 *          milliseconds instead of seconds. The engine itself (V8, or QuickJS
 *          where no JIT is allowed) is behind js/esjs.hpp.
 *
 *          Three layers are stacked here, in order: the SDK bundle (embedded,
 *          installs `ESEngine`), bootstrap.js (embedded, installs the bridge and
 *          the default init/update), and the packaged project (read off the
 *          device).
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#include "Bindings.hpp"
#include "BootLog.hpp"

#include "esn_shim.hpp"          // esn_register / esn_register_functions
#include "esengine_bundle.h"     // the real SDK, bundled: installs globalThis.ESEngine
#include "host_bootstrap.h"      // bootstrap.js, embedded

#include "SpineTags.generated.hpp"  // ES_SPINE_TAGS(X): the Spine releases this host carries

#if defined(__ANDROID__)
#include <dlfcn.h>
#endif

#include <chrono>
#include <cstdarg>
#include <cstdio>
#include <cstring>
#include <ctime>

using namespace esengine;

// PhysX's copy of the 3D physics surface (es_physx3d_*), generated beside the
// host's own wrappers. Where PhysX is linked into this binary (a desktop host) it
// is registered directly; an Android host ships it as libestella_physx.so, which
// only a PhysX project's package carries (see loadPhysXLibrary).
void esn_register_functions_physx3d(esjs::Val global);

// Every Spine release this host was built with, each under its own prefix
// (es_spine38_*, es_spine42_*; native/CMakeLists.txt). Linked in everywhere but
// Android, where each is a library a package carries only if its skeletons need it.
#if !defined(__ANDROID__)
#define ES_SPINE_DECLARE(tag) void esn_register_functions_spine##tag(esjs::Val global);
ES_SPINE_TAGS(ES_SPINE_DECLARE)
#undef ES_SPINE_DECLARE
#endif

namespace eshost {

// =============================================================================
// The state singleton
// =============================================================================

namespace {
HostState* g_host = nullptr;
}

HostState& host() { return *g_host; }
bool hostAlive() { return g_host != nullptr; }

void createHost(Platform& platform) {
    static HostState state;
    g_host = &state;
    state.platform = &platform;
    state.cacheDir = platform.cacheDir();
    state.dataDir = platform.dataDir();
}

void hostLog(bool error, const char* fmt, ...) {
    char buf[1024];
    va_list args;
    va_start(args, fmt);
    vsnprintf(buf, sizeof(buf), fmt, args);
    va_end(args);
    if (g_host && g_host->platform) g_host->platform->log(error, buf);
    // …and into the boot record, so what a developer reads over a cable and what
    // a player can send are the same lines.
    bootLogLine(error, buf);
}

double nowMs() {
    // steady_clock, as the frame delta already uses (Host.cpp): monotonic on every
    // platform and needing no per-OS spelling, where clock_gettime needed one.
    const auto since = std::chrono::steady_clock::now().time_since_epoch();
    return std::chrono::duration<double, std::milli>(since).count();
}

// =============================================================================
// Value readers
// =============================================================================

void readByteSource(esjs::Val v, std::vector<u8>& out) {
    // An ArrayBuffer or any view of one (texture pixels, audio clip bytes, cache
    // writes) is read straight out of the engine's memory…
    esjs::Bytes bytes;
    if (esjs::bytesOf(v, &bytes)) {
        out.assign(bytes.data, bytes.data + bytes.size);
        return;
    }
    // …and a plain JS number array element by element.
    const uint32_t len = esjs::isObject(v) ? esjs::lengthOf(v) : 0;
    out.resize(len);
    esjs::Scope scope;
    for (uint32_t i = 0; i < len; ++i) out[i] = static_cast<u8>(esjs::toInt32(esjs::getAt(v, i)));
}

// =============================================================================
// The environment an engine does not ship: console, timers, a clock
// =============================================================================

namespace {

#if defined(__ANDROID__) && !defined(ES_ENABLE_PHYSX)
/**
 * PhysX, on Android, is a library of its own: 4.9 MB per ABI that a project on
 * Jolt should not download. The export packs libestella_physx.so into lib/<abi>/
 * only for a project whose 3D solver is PhysX, and the app's linker namespace
 * finds it there by its bare name. It links against this host for the engine
 * surface and the heap, and registers its es_physx3d_* wrappers when called.
 *
 * Absent is the normal case, not an error: the SDK then answers a PhysX project
 * with Jolt and says so (sdk/src/ecs/bridge/nativeSideModules.ts).
 */
void loadPhysXLibrary(esjs::Val global) {
    void* lib = dlopen("libestella_physx.so", RTLD_NOW | RTLD_LOCAL);
    if (lib == nullptr) return;
    using Register = void (*)(esjs::Val*);
    auto reg = reinterpret_cast<Register>(dlsym(lib, "estella_physx_register"));
    if (reg == nullptr) {
        ESHOST_LOGE("libestella_physx.so has no estella_physx_register: %s", dlerror());
        return;
    }
    reg(&global);
    ESHOST_LOGI("PhysX loaded (libestella_physx.so)");
}
#endif

#if defined(__ANDROID__)
/**
 * The Spine releases this package carries. The export packs libestella_spine<tag>.so
 * into lib/<abi>/ for each release the project's skeletons were exported from, and
 * the app's linker namespace finds it by its bare name; a release no skeleton uses
 * is simply not there, which is the normal case, not an error.
 */
void loadSpineLibrary(esjs::Val global, const char* file) {
    void* lib = dlopen(file, RTLD_NOW | RTLD_LOCAL);
    if (lib == nullptr) return;
    using Register = void (*)(esjs::Val*);
    auto reg = reinterpret_cast<Register>(dlsym(lib, "estella_spine_register"));
    if (reg == nullptr) {
        ESHOST_LOGE("%s has no estella_spine_register: %s", file, dlerror());
        return;
    }
    reg(&global);
    ESHOST_LOGI("Spine loaded (%s)", file);
}
#endif

void registerSpine(esjs::Val global) {
#if defined(__ANDROID__)
#define ES_SPINE_REGISTER(tag) loadSpineLibrary(global, "libestella_spine" #tag ".so");
#else
#define ES_SPINE_REGISTER(tag) esn_register_functions_spine##tag(global);
#endif
    ES_SPINE_TAGS(ES_SPINE_REGISTER)
#undef ES_SPINE_REGISTER
}

esjs::Val consoleWrite(const esjs::Args& a, bool error) {
    std::string line;
    for (int i = 0; i < a.size(); ++i) {
        if (!line.empty()) line += ' ';
        line += esjs::toString(a[i]);
    }
    hostLog(error, "%s", line.c_str());
    return esjs::undefined();
}
esjs::Val js_consoleLog(const esjs::Args& a) { return consoleWrite(a, false); }
esjs::Val js_consoleError(const esjs::Args& a) { return consoleWrite(a, true); }

esjs::Val addTimer(const esjs::Args& a, bool repeat) {
    if (!esjs::isFunction(a[0])) return esjs::int64(0);
    double delay = a.size() > 1 ? esjs::toNumber(a[1]) : 0;
    if (!(delay >= 0)) delay = 0;                      // also catches NaN
    HostState& h = host();
    const int64_t id = h.nextTimerId++;
    // A zero-delay interval would fire forever within one pump; clamp as browsers do.
    h.timers.push_back(Timer{id, nowMs() + delay, repeat ? (delay > 1 ? delay : 1) : 0, esjs::Ref(a[0])});
    return esjs::int64(id);
}
esjs::Val js_setTimeout(const esjs::Args& a) { return addTimer(a, false); }
esjs::Val js_setInterval(const esjs::Args& a) { return addTimer(a, true); }
esjs::Val js_clearTimer(const esjs::Args& a) {
    const int64_t id = esjs::toInt64(a[0]);
    HostState& h = host();
    for (auto it = h.timers.begin(); it != h.timers.end(); ++it) {
        if (it->id != id) continue;
        h.timers.erase(it);
        break;
    }
    return esjs::undefined();
}

esjs::Val js_performanceNow(const esjs::Args&) { return esjs::number(nowMs()); }

/** Fire the timers that came due. Callbacks may add or clear timers, so they run
 *  off a snapshot — each holding its own reference, so a callback that clears its
 *  own interval does not release the function it is running. */
void pumpTimers(HostState& h) {
    const double now = nowMs();
    std::vector<esjs::Ref> due;
    for (auto it = h.timers.begin(); it != h.timers.end();) {
        if (it->due > now) { ++it; continue; }
        if (it->interval > 0) {
            due.emplace_back(it->fn.get());
            it->due = now + it->interval;
            ++it;
        } else {
            due.push_back(std::move(it->fn));
            it = h.timers.erase(it);
        }
    }
    for (esjs::Ref& fn : due) {
        esjs::Scope scope;
        esjs::call(fn.get(), esjs::undefined(), 0, nullptr, "timer callback");
    }
}

// FNV-1a of the bundle — a changed SDK invalidates its compile cache.
uint64_t hashBytes(const char* p, size_t n) {
    uint64_t h = 1469598103934665603ull;
    for (size_t i = 0; i < n; i++) { h ^= (uint8_t)p[i]; h *= 1099511628211ull; }
    return h;
}

/**
 * The payload of a [8-byte hash][cache] blob, if its hash is the one we want. A
 * blob that does not match is simply not used — the caller falls through to the
 * next source and ultimately to compiling.
 */
bool cachePayload(const std::vector<u8>& blob, uint64_t want, const char* origin,
                  const u8** data, size_t* size) {
    // Every rejection says why. Falling back to a compile is CORRECT but can cost
    // seconds of black screen on an interpreter's first launch, so a build that
    // shipped a cache the host then declined has to be able to say so — silence
    // here is how such a build passes for a working one.
    if (blob.empty()) return false;
    if (blob.size() <= sizeof(uint64_t)) {
        ESHOST_LOGI("SDK bundle: ignoring %s — %zu bytes is not a [hash][cache] blob", origin, blob.size());
        return false;
    }
    uint64_t got = 0;
    std::memcpy(&got, blob.data(), sizeof(got));
    if (got != want) {
        ESHOST_LOGI("SDK bundle: ignoring %s — built against a different bundle "
                    "(%016llx, want %016llx)", origin,
                    (unsigned long long)got, (unsigned long long)want);
        return false;
    }
    *data = blob.data() + sizeof(got);
    *size = blob.size() - sizeof(got);
    return true;
}

std::vector<u8> readFile(const std::string& path) {
    std::vector<u8> blob;
    FILE* f = path.empty() ? nullptr : fopen(path.c_str(), "rb");
    if (!f) return blob;
    fseek(f, 0, SEEK_END);
    const long sz = ftell(f);
    fseek(f, 0, SEEK_SET);
    if (sz > 0) {
        blob.resize((size_t)sz);
        if (fread(blob.data(), 1, blob.size(), f) != blob.size()) blob.clear();
    }
    fclose(f);
    return blob;
}

/**
 * Evaluate the SDK bundle, skipping the compile whenever a cache for it exists.
 * On an interpreter that compile is the black screen after an install (~14 s for
 * the ~700 KB bundle on a phone); on a JIT it is far less, but still not nothing.
 * Two sources, in order of how early they are available:
 *
 *   1. A cache built with the app (`assets/esengine.native.<tag>`), so the FIRST
 *      launch is already fast. Present only where the build machine can produce
 *      one for the engine the device runs.
 *   2. The cache this device wrote on an earlier launch.
 *
 * With neither, the source is compiled — and the cache written on the way out, so
 * the second source works next time. Every blob is tagged with a hash of the
 * bundle it was built from, so a stale one is skipped rather than trusted; the
 * engine checks its own build on top. File: [8-byte hash][cache].
 */
bool evalCachedScript(HostState& h, const char* src, size_t srcLen, const char* filename,
                      const std::string& cachePath, const std::string& shippedAsset) {
    const uint64_t want = hashBytes(src, srcLen);
    const u8* data = nullptr;
    size_t size = 0;
    const char* origin = nullptr;

    const std::vector<u8> shipped = readAsset(h, shippedAsset.c_str());
    const std::vector<u8> cached = readFile(cachePath);
    if (cachePayload(shipped, want, "the cache shipped with the app", &data, &size)) {
        origin = "the cache shipped with the app";
    } else if (cachePayload(cached, want, "the cache this device wrote", &data, &size)) {
        origin = "the cache this device wrote";
    }

    if (!origin) bootNote("bundle: no compile cache — compiling on device, expect a slower first launch");
    esjs::CacheUse use = esjs::CacheUse::None;
    std::string why;
    std::vector<u8> fresh;
    const bool ok = esjs::runCached(std::string_view(src, srcLen), filename, data, size,
                                    &use, &why, cachePath.empty() ? nullptr : &fresh);
    if (use == esjs::CacheUse::Used) {
        ESHOST_LOGI("SDK bundle: loaded from %s", origin);
        bootNote("bundle: %s", origin);
    } else if (use == esjs::CacheUse::Rejected) {
        ESHOST_LOGE("SDK bundle: %s did not load (%s) — compiled instead", origin, why.c_str());
        bootNote("bundle: %s rejected — compiled on device", origin);
    }
    if (!fresh.empty()) {
        if (FILE* f = fopen(cachePath.c_str(), "wb")) {
            fwrite(&want, sizeof(want), 1, f);
            fwrite(fresh.data(), 1, fresh.size(), f);
            fclose(f);
            ESHOST_LOGI("SDK bundle: compiled + cached (%zu bytes)", fresh.size());
        }
    }
    return ok;
}

void engineLog(bool error, const char* message) { hostLog(error, "%s", message); }

}  // namespace

// =============================================================================
// Eval helpers
// =============================================================================

void evalJs(HostState&, const std::string& src, const char* name) {
    esjs::Enter enter;
    esjs::run(src, name);
}

void callJs(HostState&, const char* fn, int argc, const esjs::Val* argv) {
    esjs::Enter enter;
    const esjs::Val global = esjs::global();
    const esjs::Val f = esjs::get(global, fn);
    if (esjs::isFunction(f)) esjs::call(f, global, argc, argv, fn);
}

void pumpJs(HostState& h) {
    esjs::Enter enter;
    esjs::pumpMicrotasks();
    pumpTimers(h);
    esjs::pumpMicrotasks();
    esjs::pumpEngine();
}

void bindGlobal(esjs::Val global, const char* name, esjs::NativeFn fn, int argc) {
    esjs::setFunction(global, name, fn, argc);
}

// =============================================================================
// Bring-up
// =============================================================================

void initRuntime(HostState& h) {
    const double t0 = nowMs();
#if defined(ESJS_V8_SNAPSHOT_ASSET)
    // This V8 keeps its startup snapshot outside the library, and an isolate made
    // without it dies on the spot ("Failed to deserialize the V8 snapshot blob").
    const std::vector<u8> snapshot = readAsset(h, ESJS_V8_SNAPSHOT_ASSET);
    if (snapshot.empty()) {
        ESHOST_LOGE("JS engine: the package carries no %s — the V8 runtime cannot start",
                    ESJS_V8_SNAPSHOT_ASSET);
    }
    esjs::setStartupSnapshot(snapshot.data(), snapshot.size());
#endif
    esjs::init(engineLog, nullptr);
    ESHOST_LOGI("JS engine: %s%s", esjs::engineName().c_str(), esjs::hasJit() ? " (JIT)" : " (interpreter)");
    bootNote("engine: %s", esjs::engineName().c_str());

    esjs::Enter enter;
    const esjs::Val global = esjs::global();
    esjs::set(global, "W", esjs::number(h.w));
    esjs::set(global, "H", esjs::number(h.h));
    esjs::set(global, "S", esjs::number(h.w < h.h ? h.w : h.h));

    // The host environment the SDK expects but an engine (a language, not a
    // runtime) does not provide: console, timers and a monotonic clock. Without
    // them a rejected promise is silent and the asset cache's setTimeout throws.
    const esjs::Val console = esjs::object();
    for (const char* name : {"log", "info", "debug", "trace"}) esjs::setFunction(console, name, js_consoleLog, 1);
    for (const char* name : {"warn", "error"}) esjs::setFunction(console, name, js_consoleError, 1);
    esjs::set(global, "console", console);

    bindGlobal(global, "setTimeout", js_setTimeout, 2);
    bindGlobal(global, "setInterval", js_setInterval, 2);
    bindGlobal(global, "clearTimeout", js_clearTimer, 1);
    bindGlobal(global, "clearInterval", js_clearTimer, 1);
    const esjs::Val perf = esjs::object();
    esjs::setFunction(perf, "now", js_performanceNow, 0);
    esjs::set(global, "performance", perf);

    // The es_* surface, one pillar at a time (see Bindings.hpp). The heap comes
    // first: it is what the generated entry points marshal buffers through.
    registerHeapBindings(h, global);
    registerEcsBindings(h, global);
    registerRenderBindings(h, global);
    registerAssetBindings(h, global);
    registerAudioBindings(h, global);
    registerInputBindings(h, global);
#if defined(ESTELLA_DESKTOP)
    registerSteamBindings(h, global);
#endif
#if defined(ESTELLA_DESKTOP) || defined(__ANDROID__)
    // Where a package can carry compiled systems: a desktop app beside its
    // executable, an APK in lib/<abi>/ (the system linker finds it by name).
    // Without these the SDK falls back to the wasm install, which a native core
    // cannot serve — every @compiled system then stays interpreted.
    registerAotBindings(h, global);
#endif
    registerNetBindings(h, global);
    registerDeviceBindings(h, global);
    registerTextEditorBindings(h, global);
    registerChannelBindings(h, global);

    // The generated halves: per-component accessors, then the engine's binding
    // entry points — both from the same reflection the web's embind bindings come
    // from, so the SDK reaches the engine by the same names on either platform.
    esn_register(global);
    esn_register_functions(global);
    registerSpine(global);
#if defined(ES_ENABLE_PHYSX)
    esn_register_functions_physx3d(global);
#elif defined(__ANDROID__)
    loadPhysXLibrary(global);
#endif

    // Layer 1: the real SDK bundle, embedded — installs `ESEngine`.
    const double tCtx = nowMs();
    const std::string cacheName = std::string("esengine.native.") + esjs::cacheTag();
    const std::string cachePath = h.cacheDir.empty() ? std::string() : (h.cacheDir + "/" + cacheName);
    evalCachedScript(h, kSdkBundleJS, kSdkBundleSize, "esengine.native.js", cachePath, cacheName);
    const double tBundle = nowMs();

    // Layer 2: the host bootstrap — the bridge over the es_* bindings, and the
    // default init/update that boots a packaged project.
    evalJs(h, kHostBootstrapJS, "bootstrap.js");
    ESHOST_LOGI("boot ms — engine + bindings: %.0f | SDK bundle eval: %.0f", tCtx - t0, tBundle - tCtx);
}

bool runPackagedGame(HostState& h) {
    // Layer 3: the game. The package IS an editor export — game.config.json,
    // the manifests, the cooked assets and the scenes — which boots through the
    // bootstrap's default init/update. There is no second way in: a hand-written
    // script would be a parallel content path that drifts from the one every real
    // game takes. The project's own scripts must register their components BEFORE
    // the scene loads, so they run first.
    const double t0 = nowMs();
    if (readAsset(h, "game.config.json").empty()) {
        ESHOST_LOGE("nothing to run: no game.config.json. Package a project "
                    "(Package Project -> Android / iOS) and ship it with "
                    "`cli native --content <dir>`.");
        return false;
    }
    std::vector<u8> scripts = readAsset(h, "scripts.js");
    if (!scripts.empty()) {
        evalJs(h, std::string(reinterpret_cast<const char*>(scripts.data()), scripts.size()),
               "scripts.js");
    }
    const double tScripts = nowMs();
    callJs(h, "init", 0, nullptr);
    pumpJs(h);
    ESHOST_LOGI("boot ms — project scripts: %.0f | init(): %.0f", tScripts - t0, nowMs() - tScripts);
    return true;
}

}  // namespace eshost