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.

22.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Host.cpp
 * @brief   Boot, the frame, and the lifecycle signals — the entry points a
 *          platform's event loop drives (see Host.hpp).
 * @details What is left in C++ once the engine is native and the game is the real
 *          SDK: bring Dawn up, hand the engine its device, start the JS runtime,
 *          and then, each frame, let the SDK's App tick and flip the swapchain. The
 *          frame itself belongs to the SDK — its render system resolves the
 *          scene's cameras and drives RenderFrame through the generated
 *          es_renderer_* bindings, the same code path the web build takes.
 *
 * @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 "esengine/bindings/ActiveContext.hpp"   // g_activeContext — the context the generated bindings act on
#include "Bench.hpp"
#include "PackagedConfig.hpp"
#include "Shot.hpp"
#if defined(ESTELLA_DESKTOP)
#include "steam/SteamApi.hpp"
#endif
#include "esengine/core/Log.hpp"
#include "esengine/core/World.hpp"
#include "esengine/ecs/TransformSystem.hpp"
#include "esengine/renderer/frame/RenderContext.hpp"
#include "esengine/renderer/frame/RenderFrame.hpp"
#include "esengine/resource/ShaderParser.hpp"

#include <glm/gtc/matrix_transform.hpp>

#include <chrono>

using namespace esengine;

namespace eshost {
namespace {

/** Dawn returns strings as pointer+length, with WGPU_STRLEN meaning "null-terminated". */
std::string svText(const WGPUStringView& v) {
    return v.data ? std::string(v.data, v.length == WGPU_STRLEN ? strlen(v.data) : v.length)
                  : std::string();
}

/** Has the SDK's render pipeline taken over the frame? It declares itself through
 *  `es_jsOwnsFrame` (see HOST_FLAGS in the SDK's nativeBindings) once installed. */
bool jsOwnsFrame(HostState& h) {
    esjs::Enter enter;
    return esjs::toBool(esjs::get(esjs::global(), "es_jsOwnsFrame"));
}

/** The clear colour of the host's fallback pass. A game's own clear colour comes
 *  from its Canvas, through the SDK's pipeline; this only paints the frames where
 *  that pipeline is not installed. */
constexpr glm::vec4 kFallbackClear{0.07f, 0.08f, 0.12f, 1.0f};

/** One full-viewport pass, for a host build whose renderer bindings are absent.
 *  A shipped app never takes this path (they are generated); it exists so such a
 *  build shows the scene rather than a blank surface. */
void fallbackFrame(HostState& h) {
    auto& ctx = *h.ctx;
    ctx.require<RenderContext>().setFrameTime((f32)h.frame / 60.0f, (u32)h.w, (u32)h.h);
    World world{*h.registry, ctx.services(), 1.0f / 60.0f};
    ctx.require<ecs::TransformSystem>().update(world);
    const glm::mat4 vp = glm::ortho(0.0f, h.w, 0.0f, h.h);
    auto& rf = ctx.require<RenderFrame>();
    rf.begin(vp, 0, RenderFrame::PassClear{true, true, kFallbackClear});
    // One domain here. The screen/world split exists so a frame can draw the two
    // through different projections, and this frame has no SDK to say what the
    // screen is — so partitioning would take UI out of the only pass there is.
    rf.setScreenDomain(nullptr);
    rf.collectAll(*h.registry);
    rf.flush();
    rf.end();
}

/** One cleared frame, presented — the host's own colour, since the game's lives
 *  on a Canvas that does not exist yet. */
void paintBootFrame(HostState& h) {
    if (!h.gfx || !h.ctx) return;
    auto& rf = h.ctx->require<RenderFrame>();
    rf.begin(glm::ortho(0.0f, h.w, 0.0f, h.h), 0, RenderFrame::PassClear{true, true, kFallbackClear});
    rf.end();
    h.gfx->present();
}

/** Ask Dawn for an adapter and a device on the platform's backend, enabling the
 *  block-compression families this adapter supports (a device rejects a format it
 *  did not opt into, even when the adapter advertises it). */
bool createDevice(HostState& h) {
    WGPUInstanceFeatureName feats[] = {WGPUInstanceFeatureName_TimedWaitAny};
    WGPUInstanceDescriptor idesc = {};
    idesc.requiredFeatureCount = 1;
    idesc.requiredFeatures = feats;
    h.instance = wgpuCreateInstance(&idesc);

    WGPURequestAdapterOptions opts = {};
    opts.backendType = h.platform->backend();
    auto onAdapter = [](WGPURequestAdapterStatus s, WGPUAdapter ad, WGPUStringView, void* u, void*) {
        if (s == WGPURequestAdapterStatus_Success) *static_cast<WGPUAdapter*>(u) = ad; };
    WGPURequestAdapterCallbackInfo aci = {};
    aci.mode = WGPUCallbackMode_WaitAnyOnly; aci.callback = onAdapter; aci.userdata1 = &h.adapter;
    WGPUFutureWaitInfo af = {wgpuInstanceRequestAdapter(h.instance, &opts, aci), 0};
    wgpuInstanceWaitAny(h.instance, 1, &af, UINT64_MAX);
    if (!h.adapter) { ESHOST_LOGE("no adapter"); return false; }

    // Timestamps feed the engine's GPU frame timer (renderer_getGpuTimeMs, the
    // profiler's GPU track); without them a device reports -1 for every frame.
    WGPUFeatureName compFeats[4];
    size_t compCount = 0;
    for (WGPUFeatureName f : {WGPUFeatureName_TextureCompressionETC2,
                              WGPUFeatureName_TextureCompressionASTC,
                              WGPUFeatureName_TextureCompressionBC,
                              WGPUFeatureName_TimestampQuery}) {
        if (wgpuAdapterHasFeature(h.adapter, f)) compFeats[compCount++] = f;
    }
    auto onDevice = [](WGPURequestDeviceStatus s, WGPUDevice d, WGPUStringView, void* u, void*) {
        if (s == WGPURequestDeviceStatus_Success) *static_cast<WGPUDevice*>(u) = d; };
    WGPUDeviceDescriptor dd = {};
    dd.requiredFeatureCount = compCount;
    dd.requiredFeatures = compCount ? compFeats : nullptr;
    // Without this, a validation failure is silent: WebGPU does not throw, the
    // offending call is dropped, and all that reaches anyone is a black frame.
    dd.uncapturedErrorCallbackInfo.callback =
        [](WGPUDevice const*, WGPUErrorType type, WGPUStringView message, void*, void*) {
            const std::string text = svText(message);
            ESHOST_LOGE("WebGPU: %s", text.c_str());
            // An out-of-memory or internal error is the device telling us it is
            // finished; the backend decides which kinds end it.
            if (hostAlive() && host().gfx) {
                host().gfx->reportUncapturedError(static_cast<uint32_t>(type), text.c_str());
            }
        };
    // Device loss can only be subscribed to HERE — WebGPU takes the callback in
    // the descriptor that creates the device, and there is no way to attach one
    // afterwards. A device created without it loses itself in silence.
    dd.deviceLostCallbackInfo.mode = WGPUCallbackMode_AllowSpontaneous;
    dd.deviceLostCallbackInfo.callback =
        [](WGPUDevice const*, WGPUDeviceLostReason reason, WGPUStringView message, void*, void*) {
            const std::string text = svText(message);
            ESHOST_LOGE("WebGPU device lost (%d): %s", (int)reason, text.c_str());
            if (hostAlive() && host().gfx) {
                host().gfx->notifyDeviceLost(
                    WebGPUDevice::reasonFromWgpu(static_cast<uint32_t>(reason)),
                    text, "Dawn device-lost callback");
            }
        };
    WGPURequestDeviceCallbackInfo dci = {};
    dci.mode = WGPUCallbackMode_WaitAnyOnly; dci.callback = onDevice; dci.userdata1 = &h.device;
    WGPUFutureWaitInfo df = {wgpuAdapterRequestDevice(h.adapter, &dd, dci), 0};
    wgpuInstanceWaitAny(h.instance, 1, &df, UINT64_MAX);
    if (!h.device) { ESHOST_LOGE("no device"); return false; }
    return true;
}

/**
 * Record which GPU this is.
 *
 * The first question about a failure that happens on someone else's phone and
 * not on yours, and the one a log without it cannot answer. Dawn knows it as
 * soon as the adapter exists.
 */
void logAdapter(HostState& h) {
    if (!h.adapter) return;
    WGPUAdapterInfo info = {};
    if (wgpuAdapterGetInfo(h.adapter, &info) != WGPUStatus_Success) return;
    bootNote("gpu: %s %s (%s) — %s", svText(info.vendor).c_str(), svText(info.device).c_str(),
             svText(info.architecture).c_str(), svText(info.description).c_str());
    // The class, for the bench: a ceiling on what a frame spends drawing is one
    // number on a GPU and another on a rasterizer that draws on the CPU it times.
    benchNoteAdapter(info.adapterType == WGPUAdapterType_DiscreteGPU ? "discrete"
                     : info.adapterType == WGPUAdapterType_IntegratedGPU ? "integrated"
                     : info.adapterType == WGPUAdapterType_CPU ? "cpu" : "unknown");
    wgpuAdapterInfoFreeMembers(info);
}

}  // namespace

bool bindSurface() {
    HostState& h = host();
    u32 w = 0, hh = 0;
    h.platform->surfaceSize(w, hh);
    h.w = (f32)w;
    h.h = (f32)hh;
    // Before configureSurface, always: the copy usage is part of the swapchain's
    // configuration, so asking afterwards would silently do nothing.
    h.gfx->setSurfaceReadback(shotWanted());
    // A benched frame must not be quantised to the panel's refresh — see Bench.hpp.
    h.gfx->setPresentUncapped(benchWanted());
    framePacer().setUnbounded(benchWanted());   // nor held to the pacer's floor
    if (!h.gfx->configureSurface(h.platform->surface(), w, hh)) {
        ESHOST_LOGE("configureSurface failed");
        return false;
    }
    h.surfaceReady = true;
    return true;
}

void surfaceLost() {
    if (!hostAlive()) return;
    host().surfaceReady = false;
    // The next frame is the first of a new run of them. Without this the game is
    // handed however long the app spent backgrounded — clamped, but still a
    // quarter-second jump the moment it comes back.
    host().haveLastFrame = false;
}

bool booted() { return hostAlive() && host().ready; }

FramePacer& framePacer() {
    static FramePacer pacer;
    return pacer;
}

std::chrono::steady_clock::duration untilFrameDue(bool floor) {
    return framePacer().untilDue(std::chrono::steady_clock::now(), floor);
}

bool surfaceBound() { return hostAlive() && host().surfaceReady; }

bool boot(Platform& platform) {
    createHost(platform);
    HostState& h = host();

    // The engine logs to stdout/stderr, which a browser shows and a phone throws
    // away — so on a device every ES_LOG_ERROR it ever wrote went nowhere, and a
    // renderer that refused to draw said so to no one. Forward it to the
    // platform's log, so there is ONE log wherever the engine runs.
    esengine::Log::addSink([](const esengine::LogEntry& entry) {
        hostLog(entry.level >= esengine::LogLevel::Error, "[engine] %s", entry.message.c_str());
    });

    // Opened before anything can fail, so a launch that dies in the GPU bring-up
    // still leaves a file saying so. Every ESHOST_LOG from here on lands in it.
    openBootLog(platform.logDir());
    installCrashHandler();
    bootNote("device: %s", platform.describe().c_str());
    // If the run before this one died, put its record where the player can find
    // it — the copy is made now, on a healthy launch, because a signal handler
    // may not copy files.
    if (const std::string at = publishPreviousCrash(platform.publicDirs()); !at.empty()) {
        ESHOST_LOGE("the previous run crashed — its record is at %s", at.c_str());
        bootNote("previous run CRASHED; its record was copied to %s", at.c_str());
    }
    if (!bootLogPath().empty()) ESHOST_LOGI("boot record: %s", bootLogPath().c_str());

    const double t0 = nowMs();
    bootPhase("gpu device");
    if (!createDevice(h)) return false;
    logAdapter(h);

    auto device = makeUnique<WebGPUDevice>(h.device, h.instance, h.adapter);
    h.gfx = device.get();
    bootPhase("surface");
    if (!bindSurface()) return false;

    static EstellaContext context;
    h.ctx = &context;
    // The binding entry points (the generated es_* wrappers call the same ones
    // embind does) reach the engine through activeCtx(); install ours, exactly as
    // the web entry does at initRenderer. Without this they would act on the
    // fallback context and render into a different engine than the host presents.
    g_activeContext = &context;
    context.state().viewport_width = (i32)h.w;
    context.state().viewport_height = (i32)h.h;
    bootPhase("engine context");
    // Before the first shader compiles, as the web declares it before its renderer starts (PackagedConfig.hpp).
    {
        const std::vector<u8> config = platform.readAsset("game.config.json");
        resource::ShaderParser::setLinearColorSpace(packagedConfigIsLinear(
            std::string_view(reinterpret_cast<const char*>(config.data()), config.size())));
    }
    if (!context.init(std::move(device))) { ESHOST_LOGE("context.init failed"); return false; }

    static ecs::Registry registry;
    h.registry = &registry;
    ESHOST_LOGI("boot ms — Dawn instance/adapter/device + EstellaContext: %.0f", nowMs() - t0);
    ESHOST_LOGI("audio: %s", h.audio.init() ? "native engine up (miniaudio)" : "no device — silent");

    // Paint the surface before the slow part. Until the game's first frame the
    // window holds whatever was there — black — which is also what a process that
    // died leaves behind; they are the same picture for as long as boot takes, and
    // on a first launch that has to compile the SDK bundle that is seconds. One
    // filled frame is the difference between "starting" and "gone".
    paintBootFrame(h);

    bootPhase("js runtime");
    initRuntime(h);
    bootPhase("game script");
    if (!runPackagedGame(h)) return false;
    h.ready = true;
    bootReady(nowMs() - t0);
    ESHOST_LOGI("real SDK up (%dx%d) — esengine World over native Dawn", (int)h.w, (int)h.h);
    return true;
}

void frame(long long vsyncNanos) {
    if (!booted()) return;
    HostState& h = host();
    // Skipping is normal (the screen is off, the window is going away) and being
    // stuck in it is not, and the two look the same from outside: no frames.
    if (!h.surfaceReady) {
        if (!h.surfaceSkipReported) {
            h.surfaceSkipReported = true;
            ESHOST_LOGI("no surface bound — skipping frames until one is");
        }
        return;
    }
    if (h.surfaceSkipReported) {
        h.surfaceSkipReported = false;
        ESHOST_LOGI("surface bound again — drawing resumes");
    }
    // Past the point where a frame can be skipped, so what is timed below is a
    // frame that actually happened (see Bench.hpp), and what the pacer counts too.
    benchFrameBegin();
    framePacer().frameStarted(std::chrono::steady_clock::now());

    // A window can change size without being recreated: a rotation, an insets
    // change (the system bars leaving on the frame after launch), a layout on
    // iOS. The bound size is what the swapchain is configured to AND what the
    // camera maps a touch through, so a stale one both stretches the picture and
    // puts every hit test a proportion of a screen away from the finger.
    u32 liveW = 0, liveH = 0;
    h.platform->surfaceSize(liveW, liveH);
    if (liveW > 0 && liveH > 0 && ((f32)liveW != h.w || (f32)liveH != h.h)) {
        ESHOST_LOGI("surface resized: %dx%d -> %dx%d", (int)h.w, (int)h.h, (int)liveW, (int)liveH);
        if (!bindSurface()) return;
    }

    // How much time actually passed, not how much we wish had. A host is stepped
    // by the display — CADisplayLink on iOS, its own present elsewhere — so the
    // rate is the panel's, and a fixed 1/60 is only right on a 60 Hz one. A 120 Hz
    // phone ran this game at 2.02x real speed for exactly that reason, which reads
    // as "the animations are too fast" rather than as a clock bug.
    //
    // Same policy as the web loop (App's rAF path): clamp the delta, because the
    // alternative to a long frame is a game that teleports through it. The ceiling
    // matches App.maxDeltaTime — one number, so a game behaves the same after a
    // stall wherever it runs.
    constexpr double kMaxDelta = 0.25;
    constexpr double kFirstFrameDelta = 1.0 / 60.0;
    // The vsync being drawn for when the display supplied one — the web loop's rule too (rAF's timestamp, not callback
    // entry); otherwise the steady clock as the frame starts.
    const auto nowAt = vsyncNanos > 0
        ? std::chrono::steady_clock::time_point(std::chrono::nanoseconds(vsyncNanos))
        : std::chrono::steady_clock::now();
    double deltaSeconds = kFirstFrameDelta;
    if (h.haveLastFrame) {
        deltaSeconds = std::chrono::duration<double>(nowAt - h.lastFrameAt).count();
        if (deltaSeconds > kMaxDelta) deltaSeconds = kMaxDelta;
        if (deltaSeconds < 0.0) deltaSeconds = 0.0;   // a clock that went backwards
    }
    h.lastFrameAt = nowAt;
    h.haveLastFrame = true;
    // A shot steps at a fixed rate too, so "frame 90" is the same moment of the
    // game on every host (Shot.hpp); a bench at its own, so two builds move the
    // same distance and can be held against each other. The bench's rate wins.
    deltaSeconds = benchDelta(shotDelta(deltaSeconds));

    // Booked before the game renders, because the copy is served from inside the
    // renderer's own endFrame (see Shot.hpp).
    shotBeforeFrame(*h.gfx, h.frame, (u32)h.w, (u32)h.h);

    benchUpdateBegin();
    {
        esjs::Enter enter;
        const esjs::Val dt = esjs::number(deltaSeconds);
        callJs(h, "update", 1, &dt);
    }
    benchUpdateEnd();
    benchPumpBegin();
    pumpJs(h);   // run the App tick's async systems and any timers they set
    benchPumpEnd();

    const AudioEngine::Health audio = h.audio.maintain();
    if (audio.attempt > 0) {
        hostLog(!audio.started, "audio: no sound for %.0f ms, %s the device (attempt %d)%s",
                audio.silentMs, audio.rebuilt ? "rebuilt" : "restarted", audio.attempt,
                audio.started ? "" : ", which failed");
    }
    if (audio.recovered) hostLog(false, "audio: sound is back");

    h.audio.pumpEnded([&h](int voiceId) {
        esjs::Enter enter;
        const esjs::Val arg = esjs::int32(voiceId);
        callJs(h, "es_onNativeAudioEnded", 1, &arg);
    });

    // Run the callbacks for any HTTP replies that landed since last frame, then
    // let their .then() continuations run.
    drainFetches(h);
    drainSockets(h);
    drainTextEditor(h);
    drainNativeChannel(h);
    pumpJs(h);

    // app.tick above ran the SDK's render system, which resolved the scene's
    // cameras and drove RenderFrame through the es_renderer_* bindings. What is
    // left here is what only a host can do: flip the swapchain.
    if (!jsOwnsFrame(h)) fallbackFrame(h);
#if defined(ESTELLA_DESKTOP)
    // Steam's callbacks, once per frame: without them the client never learns the
    // game is alive and the overlay never opens.
    steam().pump();
#endif
    // Guarded, not just no-op'd: a shipped frame should not pay a lookup for a
    // measurement it never asked for.
    if (benchWanted()) {
        if (auto* benched = h.ctx->tryGet<RenderFrame>()) {
            const auto& st = benched->stats();
            benchNoteDraws(st.draw_calls, st.sprites);
        }
    }
    benchBeforePresent();
    h.gfx->present();
    if (shotAfterPresent(*h.gfx)) h.quitRequested = true;
    if (benchFrameEnd()) h.quitRequested = true;
    // What the frame DREW, not only that one happened: a capture is one flat colour
    // whether nothing was submitted or it was submitted into a view nothing is in.
    // Reported on a ramp, not only every 120th: the runs worth explaining are the
    // SHORT ones, and the last line printed is then how far the loop got.
    const auto n = ++h.frame;
    if (n == 1 || n == 2 || n == 5 || n == 10 || n == 30 || n == 60 || n % 120 == 0) {
        if (auto* rf = h.ctx->tryGet<RenderFrame>()) {
            const auto& st = rf->stats();
            ESHOST_LOGI("real-SDK frame %llu — %u draw(s), %u tri, %u sprite, %u mesh, %u text, %u culled",
                        (unsigned long long)h.frame, st.draw_calls, st.triangles, st.sprites,
                        st.meshes, st.text, st.culled);
        } else {
            ESHOST_LOGI("real-SDK frame %llu", (unsigned long long)h.frame);
        }
    }
}

bool quitRequested() { return hostAlive() && host().quitRequested; }

// Push one host touch to the game's es_onNativeTouch(type,id,x,y), which fans it
// out to the NativeBridge's registered listener.
void touch(int type, int id, float x, float y) {
    if (!booted()) return;
    HostState& h = host();
    esjs::Enter enter;
    const esjs::Val args[4] = {
        esjs::int32(type), esjs::int32(id),
        esjs::number(x), esjs::number(y),
    };
    callJs(h, "es_onNativeTouch", 4, args);
}

void pointer(int type, int button, float x, float y) {
    if (!booted()) return;
    HostState& h = host();
    esjs::Enter enter;
    const esjs::Val args[4] = {
        esjs::int32(type), esjs::int32(button),
        esjs::number(x), esjs::number(y),
    };
    callJs(h, "es_onNativePointer", 4, args);
}

void wheel(float dx, float dy) {
    if (!booted()) return;
    HostState& h = host();
    esjs::Enter enter;
    const esjs::Val args[2] = {esjs::number(dx), esjs::number(dy)};
    callJs(h, "es_onNativeWheel", 2, args);
}

void key(bool down, const char* code) {
    if (!booted() || !code || !code[0]) return;
    HostState& h = host();
    esjs::Enter enter;
    const esjs::Val args[2] = {esjs::boolean(down), esjs::string(code)};
    callJs(h, "es_onNativeKey", 2, args);
}

// The app went to background (visible=false) or returned. Suspend/resume the
// audio device at the native layer — correct even while the JS tick is paused —
// then push the signal to JS, where the Lifecycle plugin auto-pauses the game.
void setVisible(bool visible) {
    if (!booted()) return;
    HostState& h = host();
    if (visible) h.audio.resumeAll(); else h.audio.suspendAll();
    {
        esjs::Enter enter;
        const esjs::Val arg = esjs::boolean(visible);
        callJs(h, "es_onNativeVisibility", 1, &arg);
    }
    pumpJs(h);
}

// OS memory pressure — let the SDK's residency caches drop evictable entries
// (the audio buffer cache trims). Held buffers keep playing; only re-fetch cost
// returns for evicted ones.
void memoryWarning() {
    if (!booted()) return;
    callJs(host(), "es_onNativeMemoryWarning", 0, nullptr);
    pumpJs(host());
}

}  // namespace eshost