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.

feat(editor): author UI controllers + gears (panel, gear dots, record mode)

yhh38c3eda9f4f8
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index 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 run
diff --git a/desktop/src/controller/ControllerRecorder.ts b/desktop/src/controller/ControllerRecorder.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.tsx
new file mode 100644
index 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.tsx
index 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[]; comp
const 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>
<button
type="button"
className={`prop-reset${modified ? ' show' : ''}`}
diff --git a/desktop/src/store/controllerStore.ts b/desktop/src/store/controllerStore.ts
new file mode 100644
index 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.css
new file mode 100644
index 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.ts
index 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.esscene
new file mode 100644
index 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.meta
new file mode 100644
index 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
+ }
+}