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
feat(editor): author UI controllers + gears (panel, gear dots, record mode)
yhh38c3eda9f4f8
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsxindex 0e4183374..f7d7006a4 100644--- a/desktop/src/App.tsx+++ b/desktop/src/App.tsx@@ -32,6 +32,7 @@ import { PlayInspect } from '@/engine/PlayInspect';import { TimelinePreview } from '@/engine/TimelinePreview';import { FlipbookViewportPreview } from '@/engine/FlipbookViewportPreview';import { TimelineRecorder } from '@/timeline/TimelineRecorder';+import { ControllerRecorder } from '@/controller/ControllerRecorder';import { ProjectStore } from '@/project/ProjectStore';import { EditorHistory } from '@/engine/EditorHistory';import { dockApi } from '@/layout/dockApi';@@ -118,6 +119,7 @@ export function App() {TimelinePreview.attach();FlipbookViewportPreview.attach();TimelineRecorder.attach();+ ControllerRecorder.attach();}, []);// Mirror unsaved-changes state to main for the window-close quit guard, and rundiff --git a/desktop/src/controller/ControllerRecorder.ts b/desktop/src/controller/ControllerRecorder.tsnew file mode 100644index 000000000..9407c43bf--- /dev/null+++ b/desktop/src/controller/ControllerRecorder.ts@@ -0,0 +1,128 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ControllerRecorder.ts+ * @brief Record mode for UI gears — auto-write a field edit into the active+ * controller's current page.+ *+ * Mirrors TimelineRecorder: it registers one hook on the single SceneCommands+ * field-edit door. When recording is armed and the edited entity carries a UIGear+ * binding for the active controller + that field, it stores the edited value under+ * the controller's current page. Observe-only (returns false) so the scene edit+ * still lands and the gear-apply system re-projects the same value — a burst (drag)+ * coalesces into one undo step. This is the "select a page → edit geared fields →+ * auto-recorded" half of the authoring flow; the gear dot in Details opts a field in.+ */+import { useControllerStore } from '@/store/controllerStore';+import { SceneCommands, toModelValue } from '@/engine/SceneCommands';+import { EditorHistory } from '@/engine/EditorHistory';+import { controllerCurrentPage, readComponentData, readGearBindings } from './controllerModel';+import type { EntityId, InspectorFieldType, InspectorFieldValue } from '@/types';+import type { GearBinding, GearValue } from 'esengine';++const clone = <T>(v: T): T =>+ typeof structuredClone === 'function' ? structuredClone(v) : (JSON.parse(JSON.stringify(v)) as T);++/**+ * The gear value for a binding, from an edit already folded to MODEL shape by+ * toModelValue (so color = {r,g,b,a}, vec = {x,y,z}, dimension = {value,unit}).+ * A whole-field binding (property === key) stores the whole value; a sub-path+ * binding ("color.a") pulls that one scalar out of the model object.+ */+function gearValueFor(modelValue: unknown, property: string, key: string): GearValue | null {+ if (property === key) return (modelValue ?? null) as GearValue | null;+ if (modelValue != null && typeof modelValue === 'object') {+ const v = (modelValue as Record<string, unknown>)[property.slice(key.length + 1)];+ return typeof v === 'number' ? v : null;+ }+ return null;+}++class ControllerRecorderImpl {+ private attached = false;+ private burst: { entity: EntityId; before: GearBinding[] } | null = null;+ private timer: ReturnType<typeof setTimeout> | null = null;++ attach(): void {+ if (this.attached) return;+ this.attached = true;+ SceneCommands.addEditHook((sourceId, compName, key, type, value) =>+ this.onEdit(sourceId, compName, key, type, value),+ );+ // Flush the pending burst the moment recording is switched off.+ useControllerStore.subscribe(() => {+ if (!useControllerStore.getState().recording && this.timer != null) this.flush();+ });+ }++ private onEdit(+ sourceId: EntityId,+ compName: string,+ key: string,+ type: InspectorFieldType,+ value: InspectorFieldValue,+ ): boolean {+ const { recording, activeController } = useControllerStore.getState();+ if (!recording || !activeController) return false;++ const bindings = readGearBindings(sourceId);+ if (bindings.length === 0) return false;+ const page = controllerCurrentPage(sourceId, activeController);+ if (page == null) return false;+ const cur = readComponentData(sourceId, compName);+ if (!cur) return false;+ const modelValue = toModelValue(cur, type, key, value);++ // A new burst on a different entity flushes the previous one first.+ if (this.burst && this.burst.entity !== sourceId) this.flush();++ const next = clone(bindings);+ let wrote = 0;+ for (const b of next) {+ if (b.controller !== activeController || b.component !== compName) continue;+ if (b.property !== key && !b.property.startsWith(`${key}.`)) continue;+ const gv = gearValueFor(modelValue, b.property, key);+ if (gv == null) continue;+ b.pages[page] = gv;+ wrote++;+ }+ if (wrote === 0) return false;++ if (!this.burst) this.burst = { entity: sourceId, before: clone(bindings) };+ SceneCommands.setGearBindingsLive(sourceId, next); // live: reconciler → gear-apply re-projects+ this.scheduleCommit();+ return false; // observe-only — the scene edit still applies+ }++ private scheduleCommit(): void {+ if (this.timer != null) clearTimeout(this.timer);+ this.timer = setTimeout(() => this.commit(), 200);+ }++ private flush(): void {+ if (this.timer != null) {+ clearTimeout(this.timer);+ this.timer = null;+ }+ this.commit();+ }++ /** Record the whole burst (pre-burst → now) as one undo step. */+ private commit(): void {+ this.timer = null;+ const burst = this.burst;+ this.burst = null;+ if (!burst) return;+ const after = readGearBindings(burst.entity);+ const entity = burst.entity;+ const before = burst.before;+ const now = clone(after);+ EditorHistory.record(+ 'Record Gear',+ () => SceneCommands.setGearBindingsLive(entity, now),+ () => SceneCommands.setGearBindingsLive(entity, before),+ );+ }+}++export const ControllerRecorder = new ControllerRecorderImpl();diff --git a/desktop/src/controller/controllerModel.ts b/desktop/src/controller/controllerModel.tsnew file mode 100644index 000000000..1a04731ee--- /dev/null+++ b/desktop/src/controller/controllerModel.ts@@ -0,0 +1,66 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file controllerModel.ts+ * @brief Editor-side readers for UIController / UIGear scene-model data.+ *+ * The Controllers panel, the Details gear dot, and the ControllerRecorder all need+ * to read the same authored data (controllers on an entity, gear bindings, the+ * nearest controller's current page). These pure model readers live here so those+ * three surfaces resolve controllers identically — mirroring the runtime's self →+ * ancestor resolution (findControllerOwner in the SDK) over the SceneModel tree.+ */+import { SceneModel } from '@/engine/SceneModel';+import type { EntityId } from '@/types';+import type { ControllerState, GearBinding, UIControllerData, UIGearData } from 'esengine';++export function readControllers(id: EntityId): ControllerState[] {+ const d = SceneModel.entityBySource(id)?.components.find((c) => c.type === 'UIController')?.data as UIControllerData | undefined;+ return d?.controllers ?? [];+}++export function readGearBindings(id: EntityId): GearBinding[] {+ const d = SceneModel.entityBySource(id)?.components.find((c) => c.type === 'UIGear')?.data as UIGearData | undefined;+ return d?.bindings ?? [];+}++/** The nearest entity (self → ancestors) that owns a controller named `name`. */+export function findControllerOwner(id: EntityId, name: string): EntityId | null {+ let cur: EntityId | null = id;+ while (cur != null) {+ const e = SceneModel.entityBySource(cur);+ if (!e) return null;+ if (readControllers(cur).some((c) => c.name === name)) return cur;+ cur = (e.parent as EntityId | null) ?? null;+ }+ return null;+}++/** Current page of the nearest controller named `name`, or null if none resolves. */+export function controllerCurrentPage(id: EntityId, name: string): string | null {+ const owner = findControllerOwner(id, name);+ if (owner == null) return null;+ return readControllers(owner).find((c) => c.name === name)?.current ?? null;+}++/** The whole model data record of a component on an entity, or undefined. */+export function readComponentData(id: EntityId, component: string): Record<string, unknown> | undefined {+ return SceneModel.entityBySource(id)?.components.find((c) => c.type === component)?.data as Record<string, unknown> | undefined;+}++/** The raw model value of a component field (model shape, e.g. {r,g,b,a} for color). */+export function readModelField(id: EntityId, component: string, property: string): unknown {+ const data = readComponentData(id, component);+ if (!data) return undefined;+ let cur: unknown = data;+ for (const part of property.split('.')) {+ if (cur == null || typeof cur !== 'object') return undefined;+ cur = (cur as Record<string, unknown>)[part];+ }+ return cur;+}++/** Whether entity `id` has a gear binding for (controller, component, property). */+export function isGeared(id: EntityId, controller: string, component: string, property: string): boolean {+ return readGearBindings(id).some((b) => b.controller === controller && b.component === component && b.property === property);+}diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.tsindex 5a3be6044..618e88881 100644--- a/desktop/src/engine/SceneCommands.ts+++ b/desktop/src/engine/SceneCommands.ts@@ -1,6 +1,6 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import type { SceneData, PrefabData } from 'esengine';+import type { SceneData, PrefabData, ControllerState, UIControllerData, GearBinding, UIGearData } from 'esengine';import { TilemapAPI, TilemapLiveSync, UIPositionType, DimensionUnit, anchorPresetFields, type AnchorPreset } from 'esengine';import type { EntityId, InspectorFieldType, InspectorFieldValue } from '@/types';import { EditorHistory, EditorHistoryImpl } from './EditorHistory';@@ -1218,6 +1218,107 @@ export class SceneCommandsImpl {};this.history.record('Paint Tiles', () => restore(after), () => restore(before));}++ // ─── UI Controllers + Gears ────────────────────────────────────────────────+ // A UIController is a named enum of "pages" scoped to a UI root; a UIGear binds a+ // component field to per-page values. Both are plain array fields — model.setField+ // creates the component if absent, so these mirror setLayerTilesets (read → transform+ // → write + one undo step). Renames are intentionally absent: they would dangle the+ // gear references keyed by controller/page name (a cascade left for a later pass);+ // removal is safe because an orphaned gear simply goes inert (getControllerPage → null).++ private controllersOf(id: EntityId): ControllerState[] {+ const d = this.model.entityBySource(id)?.components.find((c) => c.type === 'UIController')?.data as UIControllerData | undefined;+ return d?.controllers ? structuredClone(d.controllers) : [];+ }++ private writeControllers(id: EntityId, label: string, next: ControllerState[]): void {+ const cur = this.controllersOf(id);+ if (valueEqual(cur, next)) return;+ const apply = (list: ControllerState[]) => this.model.setField(id, 'UIController', 'controllers', structuredClone(list));+ apply(next);+ this.history.record(label, () => apply(next), () => apply(cur));+ }++ addController(id: EntityId, name: string, pages: string[] = ['default']): void {+ const cur = this.controllersOf(id);+ if (!name || cur.some((c) => c.name === name)) return;+ const p = pages.length ? pages : ['default'];+ this.writeControllers(id, 'Add Controller', [...cur, { name, pages: [...p], current: p[0] }]);+ }++ removeController(id: EntityId, name: string): void {+ const cur = this.controllersOf(id);+ if (!cur.some((c) => c.name === name)) return;+ this.writeControllers(id, 'Remove Controller', cur.filter((c) => c.name !== name));+ }++ setControllerPage(id: EntityId, name: string, page: string): void {+ const cur = this.controllersOf(id);+ const ctrl = cur.find((c) => c.name === name);+ if (!ctrl || ctrl.current === page || !ctrl.pages.includes(page)) return;+ this.writeControllers(id, 'Set Page', cur.map((c) => (c.name === name ? { ...c, current: page } : c)));+ }++ addControllerPage(id: EntityId, name: string, page: string): void {+ if (!page) return;+ const cur = this.controllersOf(id);+ this.writeControllers(id, 'Add Page', cur.map((c) =>+ c.name === name && !c.pages.includes(page) ? { ...c, pages: [...c.pages, page] } : c));+ }++ removeControllerPage(id: EntityId, name: string, page: string): void {+ const cur = this.controllersOf(id);+ this.writeControllers(id, 'Remove Page', cur.map((c) => {+ if (c.name !== name) return c;+ const pages = c.pages.filter((p) => p !== page);+ return { ...c, pages, current: c.current === page ? (pages[0] ?? '') : c.current };+ }));+ }++ moveControllerPage(id: EntityId, name: string, from: number, to: number): void {+ const cur = this.controllersOf(id);+ this.writeControllers(id, 'Reorder Page', cur.map((c) => {+ if (c.name !== name || from < 0 || to < 0 || from >= c.pages.length || to >= c.pages.length) return c;+ const pages = c.pages.slice();+ const [moved] = pages.splice(from, 1);+ pages.splice(to, 0, moved);+ return { ...c, pages };+ }));+ }++ private gearBindingsOf(id: EntityId): GearBinding[] {+ const d = this.model.entityBySource(id)?.components.find((c) => c.type === 'UIGear')?.data as UIGearData | undefined;+ return d?.bindings ? structuredClone(d.bindings) : [];+ }++ private writeGearBindings(id: EntityId, label: string, next: GearBinding[]): void {+ const cur = this.gearBindingsOf(id);+ if (valueEqual(cur, next)) return;+ const apply = (list: GearBinding[]) => this.model.setField(id, 'UIGear', 'bindings', structuredClone(list));+ apply(next);+ this.history.record(label, () => apply(next), () => apply(cur));+ }++ /** Live gear-bindings write with NO history — the ControllerRecorder owns undo for a burst. */+ setGearBindingsLive(id: EntityId, next: GearBinding[]): void {+ this.model.setField(id, 'UIGear', 'bindings', structuredClone(next));+ }++ /** Add (or replace, by controller+component+property) one gear binding. Undoable. */+ addGearBinding(id: EntityId, binding: GearBinding): void {+ const cur = this.gearBindingsOf(id);+ const idx = cur.findIndex((b) =>+ b.controller === binding.controller && b.component === binding.component && b.property === binding.property);+ const next = idx >= 0 ? cur.map((b, i) => (i === idx ? binding : b)) : [...cur, binding];+ this.writeGearBindings(id, 'Add Gear', next);+ }++ removeGearBinding(id: EntityId, controller: string, component: string, property: string): void {+ const cur = this.gearBindingsOf(id);+ this.writeGearBindings(id, 'Remove Gear',+ cur.filter((b) => !(b.controller === controller && b.component === component && b.property === property)));+ }}/** The app's default-session commands. Other sessions construct their own SceneCommandsImpl(model, history). */diff --git a/desktop/src/i18n/messages/controllers.ts b/desktop/src/i18n/messages/controllers.tsnew file mode 100644index 000000000..830c52dc2--- /dev/null+++ b/desktop/src/i18n/messages/controllers.ts@@ -0,0 +1,39 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file controllers.ts — the Controllers panel + the Details gear-dot affordance.+ */+import { defineMessages } from './types';++export const controllerMessages = defineMessages({+ 'panel.controllers': { en: 'Controllers', zh: '控制器' },++ 'ctrl.title': { en: 'Controllers', zh: '控制器' },+ 'ctrl.record': { en: 'Record', zh: '录制' },+ 'ctrl.recordTitle': {+ en: 'Record: editing a geared field writes the active controller page',+ zh: '录制:编辑受控字段时写入当前控制器页',+ },+ 'ctrl.emptyNoSelection': {+ en: 'Select a UI entity to author its controllers.',+ zh: '选择一个 UI 实体来编辑它的控制器。',+ },+ 'ctrl.emptyNotUi': {+ en: 'The selected entity is not a UI element (no Canvas / UINode).',+ zh: '所选实体不是 UI 元素(没有 Canvas / UINode)。',+ },+ 'ctrl.hintAdd': {+ en: 'No controllers yet. Add one below, then gear fields to it in the Details panel.',+ zh: '还没有控制器。在下方添加一个,然后在细节面板中把字段绑定到它。',+ },+ 'ctrl.newController': { en: 'New controller name', zh: '新控制器名称' },+ 'ctrl.addController': { en: 'Add controller', zh: '添加控制器' },+ 'ctrl.active': { en: 'Active', zh: '活动' },+ 'ctrl.deleteController': { en: 'Delete controller', zh: '删除控制器' },+ 'ctrl.newPage': { en: 'New page', zh: '新建页' },+ 'ctrl.addPage': { en: 'Add page', zh: '添加页' },+ 'ctrl.removeCurrentPage': { en: 'Remove the current page', zh: '删除当前页' },++ 'ctrl.gearBind': { en: 'Gear this field to the active controller', zh: '将该字段绑定到活动控制器' },+ 'ctrl.gearUnbind': { en: 'Remove gear (unbind from controller)', zh: '移除绑定(从控制器解绑)' },+});diff --git a/desktop/src/i18n/messages/index.ts b/desktop/src/i18n/messages/index.tsindex 4506409d8..79b3cf093 100644--- a/desktop/src/i18n/messages/index.ts+++ b/desktop/src/i18n/messages/index.ts@@ -36,6 +36,7 @@ import { flipbookMessages } from './flipbook';import { mixerMessages } from './mixer';import { materialMessages } from './material';import { projectMessages } from './project';+import { controllerMessages } from './controllers';/** Every per-area module, for the uniqueness guard in i18n.test.ts. */export const messageModules = {@@ -57,6 +58,7 @@ export const messageModules = {mixer: mixerMessages,material: materialMessages,project: projectMessages,+ controllers: controllerMessages,} as const;export const editorMessages = {@@ -78,4 +80,5 @@ export const editorMessages = {...mixerMessages,...materialMessages,...projectMessages,+ ...controllerMessages,} as const;diff --git a/desktop/src/layout/DockLayout.tsx b/desktop/src/layout/DockLayout.tsxindex d0269ca83..41a438258 100644--- a/desktop/src/layout/DockLayout.tsx+++ b/desktop/src/layout/DockLayout.tsx@@ -24,6 +24,7 @@ import { FlipbookEditor } from '@/panels/FlipbookEditor';import { AudioMixerPanel } from '@/panels/AudioMixerPanel';import { TilemapPainter } from '@/panels/TilemapPainter';import { UIWidgetsPanel } from '@/panels/UIWidgetsPanel';+import { ControllersPanel } from '@/panels/ControllersPanel';import { MaterialGraphEditor } from '@/panels/MaterialGraphEditor';import { StateMachineEditor } from '@/panels/StateMachineEditor';import { BtTreeEditor } from '@/panels/BtTreeEditor';@@ -58,6 +59,7 @@ const components: Record<string, FC<IDockviewPanelProps>> = {audiomixer: (p) => panel('audiomixer', p.api, <AudioMixerPanel />),tilemap: (p) => panel('tilemap', p.api, <TilemapPainter />),uiWidgets: (p) => panel('uiWidgets', p.api, <UIWidgetsPanel />),+ controllers: (p) => panel('controllers', p.api, <ControllersPanel />),materialgraph: (p) => panel('materialgraph', p.api, <MaterialGraphEditor />),statemachine: (p) => panel('statemachine', p.api, <StateMachineEditor />),behaviortree: (p) => panel('behaviortree', p.api, <BtTreeEditor />),@@ -163,6 +165,7 @@ const PANEL_TITLES: Record<string, () => string> = {audiomixer: () => t('mix.panelTitle'),tilemap: () => t('panel.tilemap'),'ui-widgets': () => t('panel.uiWidgets'),+ controllers: () => t('panel.controllers'),materialgraph: () => t('mat.panelTitle'),statemachine: () => t('fsm.tabTitle'),behaviortree: () => t('bt.tabTitle'),diff --git a/desktop/src/main.tsx b/desktop/src/main.tsxindex e2a72d7b9..4e2343e7c 100644--- a/desktop/src/main.tsx+++ b/desktop/src/main.tsx@@ -28,6 +28,7 @@ import './theme/tileset.css';import './theme/flipbook.css';import './theme/tilemap.css';import './theme/ui-palette.css';+import './theme/controllers.css';import './theme/material.css';import './theme/nodegraph.css';import './theme/chrome.css';diff --git a/desktop/src/mode/editorModes.ts b/desktop/src/mode/editorModes.tsindex 3ce73cc98..dda4344f1 100644--- a/desktop/src/mode/editorModes.ts+++ b/desktop/src/mode/editorModes.ts@@ -59,7 +59,10 @@ const uiMode: EditorModeDef = {label: t('mode.ui'),icon: LayoutPanelTop,toolset: 'transform',- panels: [{ id: 'ui-widgets', component: 'uiWidgets', title: t('panel.uiWidgets'), side: 'left', width: 240 }],+ panels: [+ { id: 'ui-widgets', component: 'uiWidgets', title: t('panel.uiWidgets'), side: 'left', width: 240 },+ { id: 'controllers', component: 'controllers', title: t('panel.controllers'), side: 'left', width: 260 },+ ],overlays: { designFrame: true, safeArea: true, letterbox: true },suggestFor: (s) => s.hasComponent('Canvas') || s.hasComponent('UINode'),};diff --git a/desktop/src/panels/ControllersPanel.tsx b/desktop/src/panels/ControllersPanel.tsxnew file mode 100644index 000000000..778c6c0c2--- /dev/null+++ b/desktop/src/panels/ControllersPanel.tsx@@ -0,0 +1,170 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ControllersPanel — author UIController "pages" for the selected UI root.+ *+ * Lists the selected entity's controllers; each has a page selector that sets the+ * controller's `current` (the gear-apply system, which ticks in edit mode, then+ * reflows every geared element live). Clicking a controller makes it "active" — the+ * Details gear dots bind fields to it, and record mode captures edits into its+ * current page. Data lives on the entities (UIController); this panel is just the+ * authoring surface. Renames are out of scope (they'd dangle gear references).+ */+import { useEffect, useState, useSyncExternalStore } from 'react';+import { Circle, Plus, Minus, Trash2 } from 'lucide-react';+import { useSelection } from '@/store/selectionStore';+import { useControllerStore } from '@/store/controllerStore';+import { SceneStore } from '@/engine/SceneStore';+import { SceneModel } from '@/engine/SceneModel';+import { SceneCommands } from '@/engine/SceneCommands';+import { readControllers } from '@/controller/controllerModel';+import { Segmented } from '@/components/Segmented';+import { t } from '@/i18n';+import type { EntityId } from '@/types';+import type { ControllerState } from 'esengine';++export function ControllersPanel() {+ const selectedId = useSelection((s) => s.selectedId);+ useSyncExternalStore(SceneStore.subscribe, SceneStore.getRevision);+ const activeController = useControllerStore((s) => s.activeController);+ const setActiveController = useControllerStore((s) => s.setActiveController);+ const recording = useControllerStore((s) => s.recording);+ const toggleRecording = useControllerStore((s) => s.toggleRecording);+ const [newCtrl, setNewCtrl] = useState('');++ const entity = selectedId != null ? SceneModel.entityBySource(selectedId) : null;+ const controllers = selectedId != null ? readControllers(selectedId) : [];+ const isUi = !!entity?.components.some((c) => c.type === 'Canvas' || c.type === 'UINode' || c.type === 'UIController');++ // Default the active controller to the first one available on this entity.+ useEffect(() => {+ if (controllers.length === 0) return;+ if (!activeController || !controllers.some((c) => c.name === activeController)) {+ setActiveController(controllers[0].name);+ }+ }, [controllers, activeController, setActiveController]);++ if (selectedId == null || !entity) {+ return <div className="ctrl-empty">{t('ctrl.emptyNoSelection')}</div>;+ }+ if (!isUi) {+ return <div className="ctrl-empty">{t('ctrl.emptyNotUi')}</div>;+ }++ const addController = () => {+ const name = newCtrl.trim();+ if (!name) return;+ SceneCommands.addController(selectedId, name);+ setActiveController(name);+ setNewCtrl('');+ };++ return (+ <div className="ctrl-panel">+ <div className="ctrl-head">+ <span className="ctrl-title">{t('ctrl.title')}</span>+ <button+ type="button"+ className={`ctrl-rec${recording ? ' on' : ''}`}+ title={t('ctrl.recordTitle')}+ onClick={toggleRecording}+ >+ <Circle size={10} fill="currentColor" />+ {t('ctrl.record')}+ </button>+ </div>++ {controllers.length === 0 && <div className="ctrl-hint">{t('ctrl.hintAdd')}</div>}++ <div className="ctrl-list">+ {controllers.map((c) => (+ <ControllerRow+ key={c.name}+ entityId={selectedId}+ ctrl={c}+ active={c.name === activeController}+ onActivate={() => setActiveController(c.name)}+ />+ ))}+ </div>++ <div className="ctrl-add">+ <input+ className="ctrl-input"+ placeholder={t('ctrl.newController')}+ value={newCtrl}+ onChange={(e) => setNewCtrl(e.target.value)}+ onKeyDown={(e) => { if (e.key === 'Enter') addController(); }}+ />+ <button type="button" className="ctrl-btn" title={t('ctrl.addController')} onClick={addController}>+ <Plus size={13} />+ </button>+ </div>+ </div>+ );+}++function ControllerRow({+ entityId, ctrl, active, onActivate,+}: {+ entityId: EntityId;+ ctrl: ControllerState;+ active: boolean;+ onActivate: () => void;+}) {+ const [newPage, setNewPage] = useState('');+ const addPage = () => {+ const p = newPage.trim();+ if (!p) return;+ SceneCommands.addControllerPage(entityId, ctrl.name, p);+ setNewPage('');+ };++ return (+ <div className={`ctrl-row${active ? ' active' : ''}`} onClick={onActivate}>+ <div className="ctrl-row-head">+ <span className="ctrl-name">{ctrl.name}</span>+ {active && <span className="ctrl-badge">{t('ctrl.active')}</span>}+ <button+ type="button"+ className="ctrl-del"+ title={t('ctrl.deleteController')}+ onClick={(e) => { e.stopPropagation(); SceneCommands.removeController(entityId, ctrl.name); }}+ >+ <Trash2 size={12} />+ </button>+ </div>++ <div className="ctrl-pages">+ <Segmented+ value={ctrl.current}+ options={ctrl.pages.map((p) => ({ value: p, label: p }))}+ onChange={(p) => SceneCommands.setControllerPage(entityId, ctrl.name, p)}+ ariaLabel={ctrl.name}+ />+ </div>++ <div className="ctrl-page-edit" onClick={(e) => e.stopPropagation()}>+ <input+ className="ctrl-input sm"+ placeholder={t('ctrl.newPage')}+ value={newPage}+ onChange={(e) => setNewPage(e.target.value)}+ onKeyDown={(e) => { if (e.key === 'Enter') addPage(); }}+ />+ <button type="button" className="ctrl-btn sm" title={t('ctrl.addPage')} onClick={addPage}>+ <Plus size={11} />+ </button>+ <button+ type="button"+ className="ctrl-btn sm"+ title={t('ctrl.removeCurrentPage')}+ disabled={ctrl.pages.length <= 1}+ onClick={() => SceneCommands.removeControllerPage(entityId, ctrl.name, ctrl.current)}+ >+ <Minus size={11} />+ </button>+ </div>+ </div>+ );+}diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsxindex bdec4af3d..70ecbde8c 100644--- a/desktop/src/panels/Details.tsx+++ b/desktop/src/panels/Details.tsx@@ -10,6 +10,7 @@ import {ChevronRight,Circle,Code2,+ Cog,Component as ComponentIcon,Copy,ClipboardPaste,@@ -39,6 +40,8 @@ import { baseName, assetTypeOf, IMAGE_RE } from '@/project/assetMeta';import { revealAsset } from '@/project/assetReveal';import { useSelection } from '@/store/selectionStore';import { useEditorStore } from '@/store/editorStore';+import { useControllerStore } from '@/store/controllerStore';+import { isGeared, controllerCurrentPage, readModelField } from '@/controller/controllerModel';import { useOutliner } from '@/outliner/OutlinerController';import { isFolderUnder, folderName } from '@/outliner/folders';import { EngineHost } from '@/engine/EngineHost';@@ -50,7 +53,7 @@ import { SceneCommands, toModelValue } from '@/engine/SceneCommands';import { ENTITY_SOURCES, createFromSource } from '@/engine/entitySources';import { PlayInspect } from '@/engine/PlayInspect';import { DimensionUnit, AnchorAxis, detectAnchor, UIPositionType, parseLocaleTable } from 'esengine';-import type { SceneData, InputMapAsset, ActionType, Binding, LocaleTableAsset, PluralCategory } from 'esengine';+import type { SceneData, InputMapAsset, ActionType, Binding, LocaleTableAsset, PluralCategory, GearValue } from 'esengine';import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba, dynamicEnumOptions, boxGroupsFor, isRequiredEmpty, type BoxGroupDef } from '@/engine/schema';import * as imap from '@/project/inputMapDoc';import * as ldoc from '@/project/localeTableDoc';@@ -888,6 +891,32 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; compconst mixed = field.mixed === true;const { apply, begin, end } = fieldWriter(entities, comp, field, write);+ // Gear dot: only for a single authored entity that resolves the active+ // controller. Clicking binds this field to that controller (seeding the current+ // page with the field's current value); clicking again unbinds it.+ const activeController = useControllerStore((s) => s.activeController);+ const gearEntity = entities[0];+ const gearPage = entities.length === 1 && !write && activeController != null+ ? controllerCurrentPage(gearEntity, activeController)+ : null;+ const gearable = gearPage != null && activeController != null;+ const geared = gearable && isGeared(gearEntity, activeController, comp, field.key);+ const toggleGear = () => {+ if (!gearable || activeController == null || gearPage == null) return;+ if (geared) {+ SceneCommands.removeGearBinding(gearEntity, activeController, comp, field.key);+ } else {+ const value = readModelField(gearEntity, comp, field.key);+ if (value === undefined) return;+ SceneCommands.addGearBinding(gearEntity, {+ controller: activeController,+ component: comp,+ property: field.key,+ pages: { [gearPage]: value as GearValue },+ });+ }+ };+// Plain numbers + angles scrub from the label; vectors from their axis tabs; a// slider owns its own drag so its label stays inert.const isScalar = (field.type === 'number' && !field.slider) || field.type === 'angle';@@ -1055,7 +1084,20 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp>{field.label}</span>- <div className="prop-value">{control}</div>+ <div className="prop-value">+ {control}+ {gearable && (+ <button+ type="button"+ className={`prop-gear${geared ? ' on' : ''}`}+ tabIndex={-1}+ title={geared ? t('ctrl.gearUnbind') : t('ctrl.gearBind')}+ onClick={toggleGear}+ >+ <Cog size={11} strokeWidth={2} />+ </button>+ )}+ </div><buttontype="button"className={`prop-reset${modified ? ' show' : ''}`}diff --git a/desktop/src/store/controllerStore.ts b/desktop/src/store/controllerStore.tsnew file mode 100644index 000000000..c49ae4fa0--- /dev/null+++ b/desktop/src/store/controllerStore.ts@@ -0,0 +1,30 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { create } from 'zustand';++/**+ * Transient UI state for the Controllers panel + gear authoring. Like+ * sequencerStore, this is view state only — the controller/gear DATA lives on the+ * entities (UIController / UIGear components). `activeController` is the controller+ * a gear dot binds to and that record mode captures into; `recording` arms the+ * ControllerRecorder so editing a geared field writes the active page's value.+ */+interface ControllerUiState {+ /** The controller (by name) that gear dots bind to and record targets. */+ activeController: string | null;+ setActiveController: (name: string | null) => void;++ /** Record mode: editing a geared field auto-writes the active controller's current page. */+ recording: boolean;+ toggleRecording: () => void;+ setRecording: (on: boolean) => void;+}++export const useControllerStore = create<ControllerUiState>((set) => ({+ activeController: null,+ setActiveController: (activeController) => set({ activeController }),++ recording: false,+ toggleRecording: () => set((s) => ({ recording: !s.recording })),+ setRecording: (recording) => set({ recording }),+}));diff --git a/desktop/src/theme/controllers.css b/desktop/src/theme/controllers.cssnew file mode 100644index 000000000..12a28fa7d--- /dev/null+++ b/desktop/src/theme/controllers.css@@ -0,0 +1,45 @@+/* SPDX-License-Identifier: Apache-2.0 */+/* SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team */++/* Controllers panel (ControllersPanel): author UIController pages + record mode. */+.ctrl-panel { padding: 8px; display: flex; flex-direction: column; gap: 8px; height: 100%; overflow-y: auto; }+.ctrl-empty { padding: 16px 12px; font-size: var(--fs-2xs); color: var(--text-dim); line-height: 1.5; text-align: center; }+.ctrl-hint { font-size: var(--fs-2xs); color: var(--text-dim); line-height: 1.4; padding: 0 2px; }++.ctrl-head { display: flex; align-items: center; justify-content: space-between; }+.ctrl-title { font-size: var(--fs-xs); font-weight: 600; color: var(--text); }+.ctrl-rec { display: inline-flex; align-items: center; gap: 5px; padding: 3px 8px; font-size: var(--fs-2xs); color: var(--text-dim); background: var(--srf-3); border: 1px solid var(--border); border-radius: var(--r-sm); cursor: pointer; transition: color var(--t-fast), border-color var(--t-fast); }+.ctrl-rec:hover { color: var(--text); }+.ctrl-rec.on { color: #ff5a5a; border-color: #ff5a5a; }++.ctrl-list { display: flex; flex-direction: column; gap: 6px; }+.ctrl-row { display: flex; flex-direction: column; gap: 6px; padding: 8px; background: var(--srf-3); border: 1px solid var(--border); border-radius: var(--r-sm); cursor: pointer; transition: border-color var(--t-fast); }+.ctrl-row:hover { border-color: var(--srf-5); }+.ctrl-row.active { border-color: var(--acc); }++.ctrl-row-head { display: flex; align-items: center; gap: 6px; }+.ctrl-name { font-size: var(--fs-xs); font-weight: 600; color: var(--text); }+.ctrl-badge { font-size: 9px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--acc); border: 1px solid var(--acc); border-radius: 3px; padding: 0 4px; }+.ctrl-del { margin-left: auto; display: inline-flex; color: var(--text-dim); background: none; border: none; cursor: pointer; padding: 2px; border-radius: 3px; }+.ctrl-del:hover { color: #ff5a5a; background: var(--srf-4); }++.ctrl-pages { min-width: 0; overflow-x: auto; }+.ctrl-page-edit { display: flex; align-items: center; gap: 4px; }++.ctrl-add { display: flex; align-items: center; gap: 4px; }+.ctrl-input { flex: 1 1 auto; min-width: 0; font-size: var(--fs-2xs); color: var(--text); background: var(--srf-2); border: 1px solid var(--border); border-radius: var(--r-sm); padding: 4px 6px; }+.ctrl-input.sm { padding: 3px 5px; }+.ctrl-input:focus { border-color: var(--acc); outline: none; }+.ctrl-btn { display: inline-flex; align-items: center; justify-content: center; color: var(--text); background: var(--srf-3); border: 1px solid var(--border); border-radius: var(--r-sm); cursor: pointer; padding: 4px 6px; transition: background var(--t-fast); }+.ctrl-btn.sm { padding: 3px 5px; }+.ctrl-btn:hover:not(:disabled) { background: var(--srf-4); border-color: var(--acc); }+.ctrl-btn:disabled { opacity: 0.4; cursor: default; }++/* The gear dot injected inside each Details field's .prop-value (flex column),+ after the control — marks the field geared to the active controller. It only+ renders while a controller is active, so it's faintly visible by default (a+ discoverable "you can gear this" hint), brighter on hover, accent when geared. */+.prop-gear { flex: 0 0 auto; display: inline-flex; align-items: center; justify-content: center; color: var(--text-dim); background: none; border: none; cursor: pointer; padding: 0; opacity: 0.35; transition: opacity var(--t-fast), color var(--t-fast); }+.prop:hover .prop-gear { opacity: 0.7; }+.prop-gear:hover { opacity: 1 !important; color: var(--text); }+.prop-gear.on { opacity: 1; color: var(--acc); }diff --git a/desktop/tests/editor-mode.test.ts b/desktop/tests/editor-mode.test.tsindex 45bb94b3d..cc42288c2 100644--- a/desktop/tests/editor-mode.test.ts+++ b/desktop/tests/editor-mode.test.ts@@ -52,9 +52,10 @@ describe('editor-mode registry + derivation', () => {expect(EDITOR_MODES[EDITOR_MODES.length - 1].id).toBe('scene');});- it('UI mode reveals the widget palette panel on entry', () => {+ it('UI mode reveals the widget palette + controllers panels on entry', () => {expect(EDITOR_MODE_BY_ID.ui.panels).toEqual([expect.objectContaining({ component: 'uiWidgets', side: 'left' }),+ expect.objectContaining({ component: 'controllers', side: 'left' }),]);});diff --git a/examples/ui-controller/assets/scenes/authoring.esscene b/examples/ui-controller/assets/scenes/authoring.esscenenew file mode 100644index 000000000..fbd08534a--- /dev/null+++ b/examples/ui-controller/assets/scenes/authoring.esscene@@ -0,0 +1,82 @@+{+ "version": "1.0",+ "name": "Authoring",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Canvas",+ "parent": null,+ "children": [2, 4],+ "components": [+ { "type": "Transform", "data": {} },+ { "type": "Canvas", "data": { "designResolution": { "x": 800, "y": 600 }, "scaleMode": 2 } },+ { "type": "UINode", "data": {} },+ { "type": "UIController", "data": { "controllers": [ { "name": "theme", "pages": ["sky", "rose"], "current": "sky" } ] } }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "Title",+ "parent": 1,+ "children": [],+ "components": [+ { "type": "Transform", "data": {} },+ { "type": "UINode", "data": {+ "position": 1, "width": { "value": 620, "unit": 0 },+ "insetLeft": { "value": 50, "unit": 1 }, "marginLeft": { "value": -310, "unit": 0 },+ "insetTop": { "value": 40, "unit": 0 }, "height": { "value": 40, "unit": 0 } } },+ { "type": "Text", "data": {+ "content": "Editor-authored controller — switch the theme page in the Controllers panel",+ "fontSize": 17, "color": { "r": 0.9, "g": 0.92, "b": 0.96, "a": 1 }, "align": 1, "verticalAlign": 1 } }+ ],+ "visible": true+ },+ {+ "id": 4,+ "name": "ThemeCard",+ "parent": 1,+ "children": [5],+ "components": [+ { "type": "Transform", "data": {} },+ { "type": "UINode", "data": {+ "position": 1, "width": { "value": 440, "unit": 0 }, "height": { "value": 220, "unit": 0 },+ "insetLeft": { "value": 50, "unit": 1 }, "marginLeft": { "value": -220, "unit": 0 },+ "insetTop": { "value": 160, "unit": 0 } } },+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.28, "g": 0.55, "b": 0.85, "a": 1 } } },+ { "type": "UIGear", "data": { "bindings": [+ { "controller": "theme", "component": "UIVisual", "property": "color",+ "pages": { "sky": { "r": 0.28, "g": 0.55, "b": 0.85, "a": 1 }, "rose": { "r": 0.87, "g": 0.38, "b": 0.5, "a": 1 } },+ "tween": { "easing": 5, "duration": 0.2 } } ] } }+ ],+ "visible": true+ },+ {+ "id": 5,+ "name": "CardLabel",+ "parent": 4,+ "children": [],+ "components": [+ { "type": "Transform", "data": {} },+ { "type": "UINode", "data": {+ "position": 1, "insetLeft": { "value": 20, "unit": 0 }, "insetRight": { "value": 20, "unit": 0 },+ "insetTop": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 } } },+ { "type": "Text", "data": {+ "content": "This card's colour is a UIGear bound to the \"theme\" controller.",+ "fontSize": 16, "wordWrap": true, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "align": 1, "verticalAlign": 1 } }+ ],+ "visible": true+ }+ ]+}diff --git a/examples/ui-controller/assets/scenes/authoring.esscene.meta b/examples/ui-controller/assets/scenes/authoring.esscene.metanew file mode 100644index 000000000..749d27fa2--- /dev/null+++ b/examples/ui-controller/assets/scenes/authoring.esscene.meta@@ -0,0 +1,8 @@+{+ "uuid": "68b5eca6-68ce-41ad-8093-6290f86f5974",+ "version": "2.0",+ "type": "scene",+ "importer": {+ "autoMigrate": true+ }+}