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
// 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 = ®istry;
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