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
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.tsdeleted file mode 100644index 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.tsdeleted file mode 100644index 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.tsdeleted file mode 100644index 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.tsdeleted file mode 100644index 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.tsdeleted file mode 100644index 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.tsdeleted file mode 100644index 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.tsdeleted file mode 100644index 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.tsindex 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 Utilitiesexport {diff --git a/sdk/src/ui/ui-plugin.ts b/sdk/src/ui/ui-plugin.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 '../srcimport { 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.tsindex 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.tsindex 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();});});