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 Runtime.hpp
* @brief The host's INTERNAL surface: the state every part of it shares, and
* the JS plumbing the binding TUs are written against.
* @details Not part of the host's contract with a platform — that is Host.hpp.
* This is what Host.cpp and the binding TUs share: one state struct, the
* JS runtime that owns the language-level environment an engine does not
* ship (console, timers, a clock), and the value readers every binding
* needs. A binding TU includes this and nothing else of the host; the
* engine itself is behind js/esjs.hpp.
*
* @author ESEngine Team
* @date 2026
*
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
#pragma once
#include "Host.hpp"
#include "media/native_audio.hpp"
#include "js/esjs.hpp"
#include "esengine/core/EstellaContext.hpp"
#include "esengine/ecs/Registry.hpp"
#include "esengine/renderer/webgpu/WebGPUDevice.hpp"
#include <chrono>
#include <cstdint>
#include <string>
#include <unordered_map>
#include <vector>
namespace eshost {
/** A pending setTimeout / setInterval callback. An engine is only the language:
* the timers, like console, are the host's job. */
struct Timer {
int64_t id;
double due; ///< nowMs() deadline.
double interval; ///< Repeat period; 0 for a one-shot.
esjs::Ref fn;
};
/**
* Everything one running host owns. Single-instance by construction (a native app
* has one window and one JS runtime), reached through {@link host}.
*/
struct HostState {
Platform* platform = nullptr;
// — Graphics: Dawn, and the engine context drawing through it —
WGPUInstance instance = nullptr;
WGPUAdapter adapter = nullptr;
WGPUDevice device = nullptr;
esengine::WebGPUDevice* gfx = nullptr;
esengine::EstellaContext* ctx = nullptr;
esengine::ecs::Registry* registry = nullptr;
// — Script: the JS engine the SDK and the game run in (js/esjs.hpp) —
std::vector<Timer> timers;
int64_t nextTimerId = 1;
std::unordered_map<int, esjs::Ref> fetchCallbacks; ///< in-flight es_fetch id -> JS callback
int nextFetchId = 1;
std::unordered_map<int, esjs::Ref> wsCallbacks; ///< open es_wsOpen id -> JS event callback
AudioEngine audio; ///< native sound (miniaudio); silent if no device
std::string cacheDir; ///< reclaimable — SDK bytecode cache + hot-update content
std::string dataDir; ///< durable — saves and settings; survives what cacheDir does not
esengine::f32 w = 0, h = 0;
bool ready = false; ///< engine + JS booted once
bool surfaceReady = false; ///< a live window surface is bound (false while screen off)
/// Whether the skipping above has been reported. A loop that runs and draws
/// nothing reads exactly like a hung one, so each stretch of it says so once.
bool surfaceSkipReported = false;
/// The host asked its event loop to stop. Only a capture run sets it (Shot.hpp);
/// a platform whose OS owns the app's lifetime is free to ignore it.
bool quitRequested = false;
uint64_t frame = 0;
/// When the last frame was stepped, for the delta the next one reports. Unset
/// until the first frame and cleared whenever the surface goes away, so a
/// resume does not hand the game the time the app spent in the background.
std::chrono::steady_clock::time_point lastFrameAt{};
bool haveLastFrame = false;
};
/** The running host. Valid from the first line of {@link boot}; a binding can only
* run after that, so bindings dereference it without checking. */
HostState& host();
/** Whether {@link host} is usable at all — for the entry points an event loop may
* call before boot (or after a failed one). */
bool hostAlive();
/** Installs the state singleton. Called once, by boot(). */
void createHost(Platform& platform);
// =============================================================================
// Logging — the platform's log sink, printf-shaped
// =============================================================================
void hostLog(bool error, const char* fmt, ...);
#define ESHOST_LOGI(...) ::eshost::hostLog(false, __VA_ARGS__)
#define ESHOST_LOGE(...) ::eshost::hostLog(true, __VA_ARGS__)
// =============================================================================
// The JS runtime
// =============================================================================
/** Monotonic milliseconds — the host clock behind performance.now() and timers. */
double nowMs();
/**
* Bring up the JS engine with the environment the SDK expects but the language
* does not provide (console, timers, performance), install every es_* binding,
* then evaluate the SDK bundle and bootstrap.js. Leaves the packaged project's own
* scripts and init() to {@link runPackagedGame}.
*/
void initRuntime(HostState& h);
/** Evaluate the packaged project (scripts.js, then init()). Returns false when the
* package carries no export to run — already logged. */
bool runPackagedGame(HostState& h);
/** Bind one global function. */
void bindGlobal(esjs::Val global, const char* name, esjs::NativeFn fn, int argc);
/** Evaluate a global script; exceptions are logged, not propagated. Opens its own
* {@link esjs::Enter}. */
void evalJs(HostState& h, const std::string& src, const char* name);
/** Call a global function by name; missing is a no-op, exceptions are logged.
* Opens its own {@link esjs::Enter}, which the caller's argument values must
* already be inside. */
void callJs(HostState& h, const char* fn, int argc, const esjs::Val* argv);
/** One turn of the host's event loop: microtasks, then timers, then whatever
* microtasks those timers queued. */
void pumpJs(HostState& h);
// =============================================================================
// Value readers shared by the binding TUs
// =============================================================================
/**
* Read a byte source into @p out, whatever shape the SDK handed over: a raw
* ArrayBuffer (audio clip bytes, cache writes), a typed-array view (texture
* pixels), or a plain JS number array.
*/
void readByteSource(esjs::Val v, std::vector<esengine::u8>& out);
/** A packaged, project-relative file. Empty when missing or before boot. */
std::vector<esengine::u8> readAsset(HostState& h, const char* path);
} // namespace eshost