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.

refactor(ui): collapse the 10 UI concept plugins into one declarative UIPlugin (REARCH_GUI F6)

esengine774479551bae
diff --git a/sdk/src/ui/DragPlugin.ts b/sdk/src/ui/DragPlugin.ts
deleted file mode 100644
index 70616c7fe..000000000
--- a/sdk/src/ui/DragPlugin.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file ui/DragPlugin.ts
- * @brief Back-compat shim — the drag plugin moved to the input concept module
- * (REARCH_GUI P0). Re-exported here to keep the public symbol +
- * existing imports stable until REARCH_GUI P4.
- */
-export { DragPlugin, dragPlugin } from './input/drag';
diff --git a/sdk/src/ui/FocusPlugin.ts b/sdk/src/ui/FocusPlugin.ts
deleted file mode 100644
index 37221f7c2..000000000
--- a/sdk/src/ui/FocusPlugin.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file ui/FocusPlugin.ts
- * @brief Back-compat shim — the focus plugin moved to the input concept module
- * (REARCH_GUI P0). Re-exported here to keep the public symbol +
- * existing imports stable until REARCH_GUI P4.
- */
-export { FocusPlugin, focusPlugin } from './input/focus';
diff --git a/sdk/src/ui/SafeAreaPlugin.ts b/sdk/src/ui/SafeAreaPlugin.ts
deleted file mode 100644
index 4b7b98f27..000000000
--- a/sdk/src/ui/SafeAreaPlugin.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file ui/SafeAreaPlugin.ts
- * @brief Back-compat shim — the SafeArea plugin moved into the layout
- * concept module (REARCH_GUI P0). Re-exported here to keep the
- * public symbol + existing imports stable until REARCH_GUI P4.
- */
-export {
- SafeAreaPlugin,
- safeAreaPlugin,
- type SafeAreaInsets,
-} from './layout/safe-area';
diff --git a/sdk/src/ui/UIInteractionPlugin.ts b/sdk/src/ui/UIInteractionPlugin.ts
deleted file mode 100644
index d8557b1df..000000000
--- a/sdk/src/ui/UIInteractionPlugin.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file ui/UIInteractionPlugin.ts
- * @brief Back-compat shim — the hit-test + UI event plugin moved to the input
- * concept module (REARCH_GUI P0). Re-exported here to keep the public
- * symbol + existing imports stable until REARCH_GUI P4.
- */
-export { UIInteractionPlugin, uiInteractionPlugin } from './input/interaction';
diff --git a/sdk/src/ui/UILayoutPlugin.ts b/sdk/src/ui/UILayoutPlugin.ts
deleted file mode 100644
index 9430b893c..000000000
--- a/sdk/src/ui/UILayoutPlugin.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file ui/UILayoutPlugin.ts
- * @brief Back-compat shim — the Yoga layout driver moved into the layout
- * concept module (REARCH_GUI P0). Re-exported here to keep the
- * public symbol + existing imports stable until REARCH_GUI P4.
- */
-export { UILayoutPlugin, uiLayoutPlugin } from './layout/layout';
diff --git a/sdk/src/ui/UIMaskPlugin.ts b/sdk/src/ui/UIMaskPlugin.ts
deleted file mode 100644
index a826b575d..000000000
--- a/sdk/src/ui/UIMaskPlugin.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file ui/UIMaskPlugin.ts
- * @brief Back-compat shim — the UIMask registration plugin moved to the render
- * concept module (REARCH_GUI P0). Re-exported here to keep the public
- * symbol + existing imports stable until REARCH_GUI P4.
- */
-export { UIMaskPlugin, uiMaskPlugin } from './render/mask';
diff --git a/sdk/src/ui/UIRenderOrderPlugin.ts b/sdk/src/ui/UIRenderOrderPlugin.ts
deleted file mode 100644
index 543fd349d..000000000
--- a/sdk/src/ui/UIRenderOrderPlugin.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file ui/UIRenderOrderPlugin.ts
- * @brief Back-compat shim — the UI render-order pass moved to the render
- * concept module (REARCH_GUI P0). Re-exported here to keep the public
- * symbol + existing imports stable until REARCH_GUI P4.
- */
-export { UIRenderOrderPlugin, uiRenderOrderPlugin } from './render/render-order';
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index b26504c5c..89447f86c 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -253,9 +253,13 @@ export {
type ScreenRect,
} from './uiMath';
-// ─── Legacy plugins / resources still in ui/ ────────────────────────────────
+// ─── Plugins (composed UI pipeline + the concept plugins it builds) ─────────
-export { UIMaskPlugin, uiMaskPlugin } from './UIMaskPlugin';
+// REARCH_GUI F6: `uiPlugin` is the single declarative UI pipeline. The concept
+// plugins below remain exported for granular/advanced wiring.
+export { UIPlugin, uiPlugin } from './ui-plugin';
+
+export { UIMaskPlugin, uiMaskPlugin } from './render/mask';
export {
UICameraInfo,
@@ -267,9 +271,9 @@ export {
type UILayoutGenerationData,
} from './UILayoutGeneration';
-export { UILayoutPlugin, uiLayoutPlugin } from './UILayoutPlugin';
+export { UILayoutPlugin, uiLayoutPlugin } from './layout/layout';
-export { UIInteractionPlugin, uiInteractionPlugin } from './UIInteractionPlugin';
+export { UIInteractionPlugin, uiInteractionPlugin } from './input/interaction';
export {
TextInput,
@@ -278,18 +282,18 @@ export {
export { TextInputPlugin, textInputPlugin } from './TextInputPlugin';
-export { DragPlugin, dragPlugin } from './DragPlugin';
+export { DragPlugin, dragPlugin } from './input/drag';
-export { FocusPlugin, focusPlugin } from './FocusPlugin';
+export { FocusPlugin, focusPlugin } from './input/focus';
export {
SafeArea,
type SafeAreaData,
} from './SafeArea';
-export { SafeAreaPlugin, safeAreaPlugin } from './SafeAreaPlugin';
+export { SafeAreaPlugin, safeAreaPlugin } from './layout/safe-area';
-export { UIRenderOrderPlugin, uiRenderOrderPlugin } from './UIRenderOrderPlugin';
+export { UIRenderOrderPlugin, uiRenderOrderPlugin } from './render/render-order';
// Property Path Utilities
export {
diff --git a/sdk/src/ui/ui-plugin.ts b/sdk/src/ui/ui-plugin.ts
new file mode 100644
index 000000000..f457b1c3b
--- /dev/null
+++ b/sdk/src/ui/ui-plugin.ts
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ui/ui-plugin.ts
+ * @brief UIPlugin — the single declarative UI pipeline (REARCH_GUI F6).
+ *
+ * Composes the formerly separate concept plugins (layout, mask, safe-area,
+ * text, interaction, behavior, drag, focus, text-input, render-order) into one
+ * plugin so the app's plugin list carries a single UI entry instead of ten
+ * hand-ordered ones. System *execution* order is still defined declaratively by
+ * each system's runAfter/runBefore labels; composition only fixes *build* order
+ * so resources exist before their readers (UIInteraction inserts UIEvents before
+ * UIBehavior reads it at build). The concept plugins stay individually exported
+ * for granular/advanced wiring (e.g. a layout-only test harness).
+ */
+import type { App, Plugin } from '../app';
+import type { Entity } from '../types';
+
+import { uiLayoutPlugin } from './layout/layout';
+import { uiMaskPlugin } from './render/mask';
+import { safeAreaPlugin } from './layout/safe-area';
+import { textPlugin } from './text/plugin';
+import { uiInteractionPlugin } from './input/interaction';
+import { uiBehaviorPlugin } from './plugin';
+import { dragPlugin } from './input/drag';
+import { focusPlugin } from './input/focus';
+import { textInputPlugin } from './TextInputPlugin';
+import { uiRenderOrderPlugin } from './render/render-order';
+
+import type { UIEventQueue } from './core/events';
+import type { ListView } from './collection/list-view';
+import type { ScrollContainer } from './collection/scroll-container';
+
+export class UIPlugin implements Plugin {
+ name = 'ui';
+
+ build(app: App): void {
+ // Build order is dependency-ordered (not execution order): layout first
+ // (it owns the layout resources), then interaction before behavior so
+ // the shared UIEvents resource exists when behavior reads it at build.
+ uiLayoutPlugin.build(app);
+ uiMaskPlugin.build(app);
+ safeAreaPlugin.build(app);
+ textPlugin.build(app);
+ uiInteractionPlugin.build(app);
+ uiBehaviorPlugin.build(app);
+ dragPlugin.build(app);
+ focusPlugin.build(app);
+ textInputPlugin.build(app);
+ uiRenderOrderPlugin.build(app);
+ }
+
+ /** Shared UI event bus (delegates to the behavior layer). */
+ get events(): UIEventQueue {
+ return uiBehaviorPlugin.events;
+ }
+
+ registerListView(list: ListView<unknown>): void {
+ uiBehaviorPlugin.registerListView(list);
+ }
+
+ unregisterListView(list: ListView<unknown>): void {
+ uiBehaviorPlugin.unregisterListView(list);
+ }
+
+ attachScrollContainer(entity: Entity, container: ScrollContainer): void {
+ uiBehaviorPlugin.attachScrollContainer(entity, container);
+ }
+
+ detachScrollContainer(entity: Entity): void {
+ uiBehaviorPlugin.detachScrollContainer(entity);
+ }
+}
+
+export const uiPlugin = new UIPlugin();
diff --git a/sdk/src/uiPlugins.ts b/sdk/src/uiPlugins.ts
index 52f8b4615..b7c8da495 100644
--- a/sdk/src/uiPlugins.ts
+++ b/sdk/src/uiPlugins.ts
@@ -1,24 +1,9 @@
// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { textPlugin } from './ui/text/plugin';
-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 { dragPlugin } from './ui/DragPlugin';
-import { focusPlugin } from './ui/FocusPlugin';
-import { safeAreaPlugin } from './ui/SafeAreaPlugin';
-import { uiRenderOrderPlugin } from './ui/UIRenderOrderPlugin';
+import { uiPlugin } from './ui/ui-plugin';
import type { Plugin } from './app';
-// `textPlugin` now renders the Text component via the dynamic SDF glyph atlas
-// (REARCH_GUI P1.4d); the legacy Canvas2D-per-entity path is retired. The
-// Image→UIRenderer copy plugin is gone too — UIVisual is drawn directly (F4).
-export const uiPlugins: Plugin[] = [
- textPlugin, uiMaskPlugin, uiLayoutPlugin,
- uiInteractionPlugin, uiBehaviorPlugin, dragPlugin,
- textInputPlugin,
- focusPlugin, safeAreaPlugin,
- uiRenderOrderPlugin,
-];
+// REARCH_GUI F6: the ten hand-ordered UI concept plugins are now composed into
+// one declarative `uiPlugin`. The concept plugins remain individually exported
+// (from their modules) for granular wiring.
+export const uiPlugins: Plugin[] = [uiPlugin];
diff --git a/sdk/src/webAppFactory.ts b/sdk/src/webAppFactory.ts
index 59ae89a89..ed40f1a2a 100644
--- a/sdk/src/webAppFactory.ts
+++ b/sdk/src/webAppFactory.ts
@@ -16,16 +16,19 @@ import { SpinePlugin, WebSpineWasmProvider } from './spine';
import type { SpineWasmProvider } from './spine';
export { uiPlugins };
+// REARCH_GUI F6: the single composed UI pipeline; the concept plugins below are
+// re-exported for granular/advanced wiring.
+export { uiPlugin, UIPlugin } from './ui/ui-plugin';
export { textPlugin, TextPlugin } from './ui/text/plugin';
-export { uiMaskPlugin, UIMaskPlugin } from './ui/UIMaskPlugin';
-export { uiInteractionPlugin, UIInteractionPlugin } from './ui/UIInteractionPlugin';
-export { uiLayoutPlugin, UILayoutPlugin } from './ui/UILayoutPlugin';
-export { uiRenderOrderPlugin, UIRenderOrderPlugin } from './ui/UIRenderOrderPlugin';
+export { uiMaskPlugin, UIMaskPlugin } from './ui/render/mask';
+export { uiInteractionPlugin, UIInteractionPlugin } from './ui/input/interaction';
+export { uiLayoutPlugin, UILayoutPlugin } from './ui/layout/layout';
+export { uiRenderOrderPlugin, UIRenderOrderPlugin } from './ui/render/render-order';
export { textInputPlugin, TextInputPlugin } from './ui/TextInputPlugin';
-export { dragPlugin, DragPlugin } from './ui/DragPlugin';
-export { focusPlugin, FocusPlugin } from './ui/FocusPlugin';
-export { safeAreaPlugin, SafeAreaPlugin } from './ui/SafeAreaPlugin';
+export { dragPlugin, DragPlugin } from './ui/input/drag';
+export { focusPlugin, FocusPlugin } from './ui/input/focus';
+export { safeAreaPlugin, SafeAreaPlugin } from './ui/layout/safe-area';
export { PhysicsPlugin, PhysicsEvents, Physics, loadPhysicsModule } from './physics';
export { AnimationPlugin, animationPlugin } from './animation';
diff --git a/sdk/tests/ui-components.test.ts b/sdk/tests/ui-components.test.ts
index 0e3687e61..f51e09b62 100644
--- a/sdk/tests/ui-components.test.ts
+++ b/sdk/tests/ui-components.test.ts
@@ -18,8 +18,8 @@ import { FlexContainer, FlexDirection, JustifyContent, AlignItems } from '../src
import { Interactable } from '../src/ui/behavior/interactable';
import { UIInteraction } from '../src/ui/behavior/interactable';
import { UICameraInfo } from '../src/ui/UICameraInfo';
-import { uiLayoutPlugin } from '../src/ui/UILayoutPlugin';
-import { uiRenderOrderPlugin } from '../src/ui/UIRenderOrderPlugin';
+import { uiLayoutPlugin } from '../src/ui/layout/layout';
+import { uiRenderOrderPlugin } from '../src/ui/render/render-order';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
diff --git a/sdk/tests/ui-layout-integration.test.ts b/sdk/tests/ui-layout-integration.test.ts
index 6f8cf38c9..6aaf87391 100644
--- a/sdk/tests/ui-layout-integration.test.ts
+++ b/sdk/tests/ui-layout-integration.test.ts
@@ -13,8 +13,8 @@ import { App } from '../src/app';
import { UINode, type UINodeData } from '../src/ui/core/ui-node';
import { Canvas } from '../src/component';
import { UICameraInfo } from '../src/ui/UICameraInfo';
-import { uiLayoutPlugin } from '../src/ui/UILayoutPlugin';
-import { uiRenderOrderPlugin } from '../src/ui/UIRenderOrderPlugin';
+import { uiLayoutPlugin } from '../src/ui/layout/layout';
+import { uiRenderOrderPlugin } from '../src/ui/render/render-order';
import { Transform, Sprite } from '../src/component';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
diff --git a/sdk/tests/ui-plugins.test.ts b/sdk/tests/ui-plugins.test.ts
index 73f258923..6355c6909 100644
--- a/sdk/tests/ui-plugins.test.ts
+++ b/sdk/tests/ui-plugins.test.ts
@@ -1,25 +1,28 @@
// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file Guards that the default UI plugin set wires the behavior layer.
+ * @file Guards the single composed UI pipeline (REARCH_GUI F6).
*
- * 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.
+ * The ten formerly-separate UI concept plugins are composed into one `uiPlugin`
+ * (see ui/ui-plugin.ts). It builds UIInteraction before UIBehavior because the
+ * behavior layer reads the UIEvents resource (inserted by UIInteraction) at
+ * build time — the wrong order would leave the entire UI behavior layer dead.
+ * Full build-order + tick behavior is exercised end-to-end by the createWebApp
+ * path (headless render verification); this pins the default plugin set shape.
*/
import { describe, expect, it } from 'vitest';
import { uiPlugins } from '../src/uiPlugins';
+import { uiPlugin } from '../src/ui/ui-plugin';
describe('default uiPlugins', () => {
- it('includes the UI behavior layer (uiBehavior)', () => {
- expect(uiPlugins.some((p) => p.name === 'uiBehavior')).toBe(true);
+ it('is the single composed UI pipeline', () => {
+ expect(uiPlugins).toEqual([uiPlugin]);
+ expect(uiPlugin.name).toBe('ui');
});
- 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);
+ it('exposes the behavior-layer event bus via delegation', () => {
+ // The getter delegates to the internal behavior plugin; before build it
+ // throws rather than returning a half-wired bus.
+ expect(() => uiPlugin.events).toThrow();
});
});