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 EstellaContext.cpp
* @brief Instance-based engine context implementation
*
* @author ESEngine Team
* @date 2026
*/
#include "EstellaContext.hpp"
#include "Log.hpp"
#ifdef ES_PLATFORM_WEB
#include "../renderer/rhi/GLDevice.hpp" // WebGL2 backend — web platform only
#endif
#include "../renderer/frame/RenderContext.hpp"
#include "../renderer/frame/RenderFrame.hpp"
#include "../renderer/draw/ImmediateDraw.hpp"
#include "../renderer/draw/CustomGeometry.hpp"
#include "../renderer/plugins/SpritePlugin.hpp"
#include "../renderer/plugins/UIElementPlugin.hpp"
#ifdef ES_ENABLE_BITMAP_TEXT
#include "../renderer/plugins/TextPlugin.hpp"
#endif
#include "../renderer/plugins/ShapePlugin.hpp"
#include "../renderer/plugins/MeshPlugin.hpp"
// The engine's one random stream, registered unconditionally below: a core type
// that reached this file only through a particle header, so turning particles
// off stopped the CORE from compiling.
#include "RandomSource.hpp"
#ifdef ES_ENABLE_PARTICLES
#include "../renderer/plugins/ParticlePlugin.hpp"
#include "../particle/ParticleSystem.hpp"
#endif
#include "../renderer/plugins/TrailPlugin.hpp"
#include "../trail/TrailSystem.hpp"
#include "../springbone/SpringBoneSystem.hpp"
#ifdef ES_ENABLE_TILEMAP
#include "../renderer/plugins/TilemapRenderPlugin.hpp"
#include "../tilemap/TilemapSystem.hpp"
#endif
#include "../resource/ResourceManager.hpp"
#include "../ecs/TransformSystem.hpp"
#include "../ui/UISystem.hpp"
#include "../animation/TweenSystem.hpp"
#ifdef ES_PLATFORM_WEB
#include <emscripten/html5.h>
#endif
namespace esengine {
EstellaContext::EstellaContext() {
// Logic systems must exist even for headless apps that never call init()
// (e.g. tooling / tests that drive UI layout without a GL context). Without
// this, the binding's require<UISystem>() returned a null reference and ran
// against wasm address 0 — silent memory corruption masked by the fact that
// address 0 is valid linear memory. See registerLogicSystems().
registerLogicSystems();
}
void EstellaContext::registerLogicSystems() {
// Idempotent: the constructor and initSubsystems both call this, and a
// shutdown()+init() cycle clears services_ and re-registers. UISystem is the
// membership sentinel for the whole logic-system set.
if (services_.getService<ecs::UISystem>()) return;
// Before the systems that draw from it: a consumer takes its stream at
// registration, so the seed has to be the engine's before anyone asks.
auto randomSource = makeUnique<RandomSource>();
// A seed the SDK set before this context existed (see setPendingRandomSeed).
if (u32 pending = 0; takePendingRandomSeed(pending)) randomSource->reseed(pending);
services_.registerOwned<RandomSource>(std::move(randomSource));
#ifdef ES_ENABLE_PARTICLES
services_.registerOwned<particle::ParticleSystem>(makeUnique<particle::ParticleSystem>());
services_.getService<particle::ParticleSystem>()->reseedFrom(*services_.getService<RandomSource>());
#endif
services_.registerOwned<trail::TrailSystem>(makeUnique<trail::TrailSystem>());
services_.registerOwned<springbone::SpringBoneSystem>(makeUnique<springbone::SpringBoneSystem>());
services_.registerOwned<ecs::TransformSystem>(makeUnique<ecs::TransformSystem>());
services_.registerOwned<ecs::UISystem>(makeUnique<ecs::UISystem>());
services_.registerOwned<animation::TweenSystem>(makeUnique<animation::TweenSystem>());
#ifdef ES_ENABLE_TILEMAP
// Chunk data and tile queries do not need a renderer. Register here once so
// later renderer initialization also retains maps loaded by headless tooling.
services_.registerOwned<tilemap::TilemapSystem>(makeUnique<tilemap::TilemapSystem>());
#endif
}
EstellaContext::~EstellaContext() {
if (state_.initialized) {
shutdown();
}
}
#ifdef ES_PLATFORM_WEB
// The WebGL2 entry: takes an emscripten context handle and drives the GLDevice
// backend. A native build has no WebGL — it enters through init(Unique<GfxDevice>)
// with an injected WebGPUDevice instead, so this overload compiles out entirely.
bool EstellaContext::init(int webglContextHandle) {
return init(webglContextHandle, false);
}
bool EstellaContext::init(int webglContextHandle, bool ownsContext) {
if (state_.initialized) {
ES_LOG_WARN("EstellaContext already initialized");
return true;
}
EMSCRIPTEN_RESULT result = emscripten_webgl_make_context_current(
static_cast<EMSCRIPTEN_WEBGL_CONTEXT_HANDLE>(webglContextHandle));
if (result != EMSCRIPTEN_RESULT_SUCCESS) {
ES_LOG_ERROR("Failed to make WebGL context current: {}", result);
return false;
}
state_.webgl_context = webglContextHandle;
state_.owns_webgl_context = ownsContext;
initSubsystems(makeUnique<GLDevice>());
return true;
}
#endif // ES_PLATFORM_WEB
bool EstellaContext::init(Unique<GfxDevice> device) {
if (state_.initialized) {
ES_LOG_WARN("EstellaContext already initialized");
return true;
}
if (!device) {
ES_LOG_ERROR("EstellaContext::init: no device");
return false;
}
initSubsystems(std::move(device));
return true;
}
void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {
// The device arrives first: ResourceManager (the GPU-resource factory) and
// every other renderer subsystem borrow this single device. Which backend
// it is was decided at the platform edge (init overloads).
auto* gfxDevicePtr = gfxDevice.get();
// The one place a device loss becomes visible. Logged whether or not
// anything above the engine is listening: a loss nobody recorded is the
// black screen with no explanation.
gfxDevicePtr->setDeviceLostHandler([](const GfxDeviceLostInfo& info) {
ES_LOG_ERROR("{}", gfxFormatDeviceLost(info));
});
services_.registerOwned<GfxDevice>(std::move(gfxDevice));
auto resourceManager = makeUnique<resource::ResourceManager>();
resourceManager->init(*gfxDevicePtr);
services_.registerOwned<resource::ResourceManager>(std::move(resourceManager));
auto renderContext = makeUnique<RenderContext>(*gfxDevicePtr);
renderContext->init();
// Materials name their textures by resource handle and resolve them per draw,
// so the store needs the manager that owns the pool.
renderContext->materials().setResourceManager(services_.getService<resource::ResourceManager>());
services_.registerOwned<RenderContext>(std::move(renderContext));
// GPU state is owned by the device: pipelines (setPipeline) carry program/blend/depth/
// stencil/cull, so there is no separate per-App state tracker to wire up here.
// GPU-independent logic systems (Transform/UI/Tween/Tilemap) are registered here too
// for the shutdown()+init() re-init path; the constructor already registered
// them for the headless/first-use path. Idempotent, so this is a no-op when
// they are already present.
registerLogicSystems();
auto* rm = services_.getService<resource::ResourceManager>();
auto* rc = services_.getService<RenderContext>();
auto immediateDraw = makeUnique<ImmediateDraw>(*gfxDevicePtr, *rc, *rm);
immediateDraw->init();
auto* immediateDrawPtr = immediateDraw.get();
services_.registerOwned<ImmediateDraw>(std::move(immediateDraw));
services_.registerOwned<GeometryManager>(makeUnique<GeometryManager>());
auto renderFrame = makeUnique<RenderFrame>(*gfxDevicePtr, *rc, *rm);
renderFrame->setPresentedOverlayDraw(immediateDrawPtr);
renderFrame->addPlugin(std::make_unique<SpritePlugin>());
renderFrame->addPlugin(std::make_unique<UIElementPlugin>());
#ifdef ES_ENABLE_BITMAP_TEXT
renderFrame->addPlugin(std::make_unique<TextPlugin>());
#endif
renderFrame->addPlugin(std::make_unique<ShapePlugin>());
renderFrame->addPlugin(std::make_unique<MeshPlugin>());
{
auto trailPlugin = std::make_unique<TrailPlugin>();
trailPlugin->setTrailSystem(services_.getService<trail::TrailSystem>());
renderFrame->addPlugin(std::move(trailPlugin));
}
#ifdef ES_ENABLE_TILEMAP
{
auto tilemapPlugin = std::make_unique<TilemapRenderPlugin>();
tilemapPlugin->setTilemapSystem(services_.getService<tilemap::TilemapSystem>());
renderFrame->addPlugin(std::move(tilemapPlugin));
}
#endif
#ifdef ES_ENABLE_PARTICLES
{
auto particlePlugin = std::make_unique<ParticlePlugin>();
particlePlugin->setParticleSystem(services_.getService<particle::ParticleSystem>());
renderFrame->addPlugin(std::move(particlePlugin));
}
#endif
renderFrame->init(state_.viewport_width, state_.viewport_height);
services_.registerOwned<RenderFrame>(std::move(renderFrame));
#ifdef ES_ENABLE_POSTPROCESS
// ONE PostProcessPipeline per App: the postprocess_* bindings and RenderFrame
// must consult the SAME instance. Registering RenderFrame's pipeline as the
// service (borrowed — RenderFrame owns it) stops the bindings from lazily
// creating a second one, whose captures RenderFrame::begin could not see.
if (auto* pp = services_.getService<RenderFrame>()->postProcess()) {
services_.registerService<PostProcessPipeline>(pp);
}
#endif
state_.initialized = true;
// First-frame clear as a proper pass load-op (values in the desc, no sticky state).
RenderPassDesc initPass{};
initPass.clearColor = true;
initPass.clearDepth = true;
initPass.clearColorValue[0] = state_.clear_color.r;
initPass.clearColorValue[1] = state_.clear_color.g;
initPass.clearColorValue[2] = state_.clear_color.b;
initPass.clearColorValue[3] = state_.clear_color.a;
gfxDevicePtr->beginRenderPass(initPass);
gfxDevicePtr->endRenderPass(); // a pass never outlives its task (WebGPU submits here)
// ...and neither does the image it drew to. A browser expires the swapchain
// texture at the end of the task that acquired it, so a frame that found this
// one still held would reuse it and submit a destroyed texture.
gfxDevicePtr->endFrame();
ES_LOG_INFO("EstellaContext initialized");
}
void EstellaContext::shutdown() {
if (!state_.initialized) return;
#ifdef ES_PLATFORM_WEB
const auto webglCtx = static_cast<EMSCRIPTEN_WEBGL_CONTEXT_HANDLE>(state_.webgl_context);
const bool ownsWebglContext = state_.owns_webgl_context;
const auto previousContext = emscripten_webgl_get_current_context();
// GL object deletion uses the current context, including subsystem destructors.
// Another engine instance may have made its own context current since our init.
if (webglCtx > 0 && previousContext != webglCtx) {
emscripten_webgl_make_context_current(webglCtx);
}
#endif
if (auto* rf = tryGet<RenderFrame>()) rf->shutdown();
if (auto* id = tryGet<ImmediateDraw>()) id->shutdown();
if (auto* rc = tryGet<RenderContext>()) rc->shutdown();
if (auto* rm = tryGet<resource::ResourceManager>()) rm->shutdown();
services_.clear();
state_ = EngineState{};
#ifdef ES_PLATFORM_WEB
if (webglCtx > 0 && ownsWebglContext) {
emscripten_webgl_destroy_context(webglCtx);
}
if (webglCtx > 0 && previousContext != webglCtx) {
emscripten_webgl_make_context_current(previousContext);
}
#endif
ES_LOG_INFO("EstellaContext shutdown");
}
} // namespace esengine