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
fix: headless engine context + always-on require() guard; wire UI behavior layer
esengine113f96f1c603
diff --git a/sdk/src/uiPlugins.ts b/sdk/src/uiPlugins.tsindex 4616d128c..039c71599 100644--- a/sdk/src/uiPlugins.ts+++ b/sdk/src/uiPlugins.ts@@ -1,6 +1,7 @@import { textPlugin } from './ui/TextPlugin';import { uiMaskPlugin } from './ui/UIMaskPlugin';import { uiInteractionPlugin } from './ui/UIInteractionPlugin';+import { uiBehaviorPlugin } from './ui/plugin';import { uiLayoutPlugin } from './ui/UILayoutPlugin';import { textInputPlugin } from './ui/TextInputPlugin';import { imagePlugin } from './ui/ImagePlugin';@@ -14,7 +15,7 @@ import type { Plugin } from './app';export const uiPlugins: Plugin[] = [textPlugin, uiMaskPlugin, uiLayoutPlugin,imagePlugin,- uiInteractionPlugin, dragPlugin, scrollViewPlugin,+ uiInteractionPlugin, uiBehaviorPlugin, dragPlugin, scrollViewPlugin,textInputPlugin,focusPlugin, safeAreaPlugin,uiRenderOrderPlugin,diff --git a/sdk/tests/ui-plugins.test.ts b/sdk/tests/ui-plugins.test.tsnew file mode 100644index 000000000..ba8a96c65--- /dev/null+++ b/sdk/tests/ui-plugins.test.ts@@ -0,0 +1,23 @@+/**+ * @file Guards that the default UI plugin set wires the behavior layer.+ *+ * Regression: uiBehaviorPlugin (interactable state machine, state-visual+ * application, list-view + scroll-wheel) existed and was exported but was never+ * added to `uiPlugins`, so createWebApp never registered it and the entire UI+ * behavior layer silently never ticked. This pins it into the default set.+ */+import { describe, expect, it } from 'vitest';+import { uiPlugins } from '../src/uiPlugins';++describe('default uiPlugins', () => {+ it('includes the UI behavior layer (uiBehavior)', () => {+ expect(uiPlugins.some((p) => p.name === 'uiBehavior')).toBe(true);+ });++ it('orders the behavior layer after its UIInteraction dependency', () => {+ const interaction = uiPlugins.findIndex((p) => p.name === 'uiInteraction');+ const behavior = uiPlugins.findIndex((p) => p.name === 'uiBehavior');+ expect(interaction).toBeGreaterThanOrEqual(0);+ expect(behavior).toBeGreaterThan(interaction);+ });+});diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex b1a06552b..eadd596df 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -66,7 +66,15 @@ static_assert(sizeof(void*) == 4, "EM_JS pointer passing assumes wasm32 (4-bytenamespace esengine {static EngineContext& legacyCtx() { return EngineContext::instance(); }-static EstellaContext& ctx() { return activeCtx(); }+static EstellaContext& ctx() {+ // The active context is installed by initRenderer (g_activeContext). Headless+ // callers — tooling/tests that drive UI layout/hit-test without a GL context+ // — never set it; fall back to the process singleton (whose constructor+ // registers the GPU-independent logic systems) rather than dereferencing+ // nullptr through activeCtx(). GPU services stay absent there, so the+ // renderer bindings' tryGet<>() returns null exactly as before.+ return g_activeContext ? activeCtx() : legacyCtx().context();+}#define g_initialized (ctx().state().initialized)#define g_resourceManager (ctx().tryGet<resource::ResourceManager>())diff --git a/src/esengine/core/EstellaContext.cpp b/src/esengine/core/EstellaContext.cppindex eba81a65e..2d8ded954 100644--- a/src/esengine/core/EstellaContext.cpp+++ b/src/esengine/core/EstellaContext.cpp@@ -52,7 +52,24 @@ namespace esengine {// needs local instance for non-web. For now we create a fresh system.#endif-EstellaContext::EstellaContext() = default;+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;+ services_.registerOwned<ecs::TransformSystem>(makeUnique<ecs::TransformSystem>());+ services_.registerOwned<ecs::UISystem>(makeUnique<ecs::UISystem>());+ services_.registerOwned<animation::TweenSystem>(makeUnique<animation::TweenSystem>());+}EstellaContext::~EstellaContext() {if (state_.initialized) {@@ -105,9 +122,11 @@ void EstellaContext::initSubsystems() {auto* statePtr = stateTracker.get();services_.registerOwned<StateTracker>(std::move(stateTracker));- services_.registerOwned<ecs::TransformSystem>(makeUnique<ecs::TransformSystem>());- services_.registerOwned<ecs::UISystem>(makeUnique<ecs::UISystem>());- services_.registerOwned<animation::TweenSystem>(makeUnique<animation::TweenSystem>());+ // GPU-independent logic systems (Transform/UI/Tween) 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();#ifdef ES_ENABLE_TIMELINEservices_.registerOwned<animation::TimelineSystem>(makeUnique<animation::TimelineSystem>());diff --git a/src/esengine/core/EstellaContext.hpp b/src/esengine/core/EstellaContext.hppindex 45db1234c..e8661e754 100644--- a/src/esengine/core/EstellaContext.hpp+++ b/src/esengine/core/EstellaContext.hpp@@ -54,6 +54,13 @@ public:private:void initSubsystems();+ /**+ * Register the GPU-independent ECS logic systems (Transform/UI/Tween).+ * Called from the constructor *and* initSubsystems so they exist even for+ * headless apps that never call init() — otherwise require<UISystem>() etc.+ * return a null reference (silent wasm address-0 corruption). Idempotent.+ */+ void registerLogicSystems();ServiceRegistry services_;EngineState state_;diff --git a/src/esengine/core/ServiceRegistry.hpp b/src/esengine/core/ServiceRegistry.hppindex ac1835edd..8f216ab12 100644--- a/src/esengine/core/ServiceRegistry.hpp+++ b/src/esengine/core/ServiceRegistry.hpp@@ -104,15 +104,12 @@ public:template<typename T>T& require() {T* svc = getService<T>();- // NOTE: this is the natural home for ES_VERIFY_FATAL (a missing required- // service has no safe T& to return, and *nullptr silently corrupts wasm- // address 0 rather than faulting). Deferred: turning it on surfaces- // ~33 existing call paths (UI layout/scrollview tests) that invoke- // require() on services they never register and "work" only via that- // null-address tolerance. Those callers must register/guard their- // services first; until then keep the debug-only assert to avoid- // destabilizing them. See foundation-audit follow-up.- ES_ASSERT(svc != nullptr, "Required service not registered");+ // No safe T& to return if the service is missing — returning *nullptr is+ // a silent wasm address-0 corruption, not a fault. require() means "must+ // exist": abort with a clear diagnostic instead. (The UI logic systems+ // this used to trip on are now registered unconditionally via+ // EstellaContext::registerLogicSystems, so no normal path hits this.)+ ES_VERIFY_FATAL(svc != nullptr, "Required service not registered");return *svc;}