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.

fix: headless engine context + always-on require() guard; wire UI behavior layer

esengine113f96f1c603
diff --git a/sdk/src/uiPlugins.ts b/sdk/src/uiPlugins.ts
index 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.ts
new file mode 100644
index 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.cpp
index 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-byte
namespace 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.cpp
index 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_TIMELINE
services_.registerOwned<animation::TimelineSystem>(makeUnique<animation::TimelineSystem>());
diff --git a/src/esengine/core/EstellaContext.hpp b/src/esengine/core/EstellaContext.hpp
index 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.hpp
index 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;
}