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): Controllers panel v2 — inherited rows, page chips, cascade renames, gear settings

esengine88695060f91e
diff --git a/desktop/src/controller/controllerModel.ts b/desktop/src/controller/controllerModel.ts
index 1a04731ee..2012d8698 100644
--- a/desktop/src/controller/controllerModel.ts
+++ b/desktop/src/controller/controllerModel.ts
@@ -19,6 +19,38 @@ export function readControllers(id: EntityId): ControllerState[] {
return d?.controllers ?? [];
}
+export interface ResolvedController {
+ ctrl: ControllerState;
+ /** Entity that declares the controller (page edits target this id). */
+ owner: EntityId;
+ ownerName: string;
+ /** Declared on an ancestor rather than the queried entity itself. */
+ inherited: boolean;
+}
+
+/**
+ * Every controller visible from `id` — its own plus each ancestor's, nearest
+ * declaration winning on a name clash (the same rule the runtime resolves gears
+ * by). This is what lets the Controllers panel keep showing (and switching) the
+ * root's controllers while a geared leaf is selected.
+ */
+export function resolveControllers(id: EntityId): ResolvedController[] {
+ const out: ResolvedController[] = [];
+ const seen = new Set<string>();
+ let cur: EntityId | null = id;
+ while (cur != null) {
+ const e = SceneModel.entityBySource(cur);
+ if (!e) break;
+ for (const ctrl of readControllers(cur)) {
+ if (seen.has(ctrl.name)) continue;
+ seen.add(ctrl.name);
+ out.push({ ctrl, owner: cur, ownerName: e.name, inherited: cur !== id });
+ }
+ cur = (e.parent as EntityId | null) ?? null;
+ }
+ return out;
+}
+
export function readGearBindings(id: EntityId): GearBinding[] {
const d = SceneModel.entityBySource(id)?.components.find((c) => c.type === 'UIGear')?.data as UIGearData | undefined;
return d?.bindings ?? [];
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 618e88881..13b8753c7 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, ControllerState, UIControllerData, GearBinding, UIGearData } from 'esengine';
+import type { SceneData, PrefabData, ControllerState, UIControllerData, GearBinding, GearTween, 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';
@@ -1223,9 +1223,12 @@ export class SceneCommandsImpl {
// 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).
+ // → write + one undo step). Controller/page renames and page removal CASCADE into
+ // the gear bindings that resolve to the edited controller (nearest-ancestor rule,
+ // so a shadowing same-name controller lower in the tree keeps its gears), all in
+ // one undo step. Removing a whole controller deliberately does NOT cascade: an
+ // orphaned gear goes inert (getControllerPage → null) and re-resolves if the
+ // controller is re-declared on an ancestor — the "move it up the tree" workflow.
private controllersOf(id: EntityId): ControllerState[] {
const d = this.model.entityBySource(id)?.components.find((c) => c.type === 'UIController')?.data as UIControllerData | undefined;
@@ -1269,11 +1272,103 @@ export class SceneCommandsImpl {
removeControllerPage(id: EntityId, name: string, page: string): void {
const cur = this.controllersOf(id);
- this.writeControllers(id, 'Remove Page', cur.map((c) => {
+ const ctrl = cur.find((c) => c.name === name);
+ if (!ctrl || !ctrl.pages.includes(page) || ctrl.pages.length <= 1) return;
+ const next = 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 };
+ });
+ // Strip the page's authored values from resolving gears so re-adding a page
+ // with the same name later starts clean instead of reviving stale values.
+ this.recordControllerCascade('Remove Page', id, next, name, (b) => {
+ if (b.controller !== name || !(page in b.pages)) return b;
+ const pages = { ...b.pages };
+ delete pages[page];
+ return { ...b, pages };
+ });
+ }
+
+ renameController(id: EntityId, from: string, to: string): void {
+ const name = to.trim();
+ const cur = this.controllersOf(id);
+ if (!name || name === from) return;
+ if (!cur.some((c) => c.name === from) || cur.some((c) => c.name === name)) return;
+ const next = cur.map((c) => (c.name === from ? { ...c, name } : c));
+ this.recordControllerCascade('Rename Controller', id, next, from,
+ (b) => (b.controller === from ? { ...b, controller: name } : b));
+ }
+
+ renameControllerPage(id: EntityId, ctrlName: string, from: string, to: string): void {
+ const page = to.trim();
+ const cur = this.controllersOf(id);
+ const ctrl = cur.find((c) => c.name === ctrlName);
+ if (!page || page === from || !ctrl || !ctrl.pages.includes(from) || ctrl.pages.includes(page)) return;
+ const next = cur.map((c) => (c.name !== ctrlName ? c : {
+ ...c,
+ pages: c.pages.map((p) => (p === from ? page : p)),
+ current: c.current === from ? page : c.current,
}));
+ this.recordControllerCascade('Rename Page', id, next, ctrlName, (b) => {
+ if (b.controller !== ctrlName || !(from in b.pages)) return b;
+ const pages = { ...b.pages };
+ pages[page] = pages[from]!;
+ delete pages[from];
+ return { ...b, pages };
+ });
+ }
+
+ /** Entity ids in `rootId`'s subtree (inclusive) that carry a UIGear. */
+ private subtreeWithGears(rootId: EntityId): EntityId[] {
+ const out: EntityId[] = [];
+ const stack: EntityId[] = [rootId];
+ while (stack.length > 0) {
+ const id = stack.pop()!;
+ const e = this.model.entityBySource(id);
+ if (!e) continue;
+ if (e.components.some((c) => c.type === 'UIGear')) out.push(id);
+ for (const child of e.children) stack.push(child as EntityId);
+ }
+ return out;
+ }
+
+ /** Whether the nearest declaration of controller `name` from `entityId` is `ownerId`. */
+ private resolvesTo(entityId: EntityId, ownerId: EntityId, name: string): boolean {
+ let cur: EntityId | null = entityId;
+ while (cur != null) {
+ if (this.controllersOf(cur).some((c) => c.name === name)) return cur === ownerId;
+ cur = (this.model.entityBySource(cur)?.parent as EntityId | null) ?? null;
+ }
+ return false;
+ }
+
+ /**
+ * Write `nextControllers` on the owner AND rewrite every resolving gear binding
+ * in its subtree through `editBinding`, as ONE undo step — the shared engine
+ * behind rename/remove-page cascades.
+ */
+ private recordControllerCascade(
+ label: string,
+ ownerId: EntityId,
+ nextControllers: ControllerState[],
+ name: string,
+ editBinding: (b: GearBinding) => GearBinding,
+ ): void {
+ const beforeCtrls = this.controllersOf(ownerId);
+ const gearEdits: Array<{ id: EntityId; before: GearBinding[]; after: GearBinding[] }> = [];
+ for (const gid of this.subtreeWithGears(ownerId)) {
+ if (!this.resolvesTo(gid, ownerId, name)) continue;
+ const before = this.gearBindingsOf(gid);
+ const after = before.map(editBinding);
+ if (!valueEqual(before, after)) gearEdits.push({ id: gid, before, after });
+ }
+ if (valueEqual(beforeCtrls, nextControllers) && gearEdits.length === 0) return;
+ const apply = (ctrls: ControllerState[], pick: 'before' | 'after') => {
+ this.model.setField(ownerId, 'UIController', 'controllers', structuredClone(ctrls));
+ for (const g of gearEdits) this.model.setField(g.id, 'UIGear', 'bindings', structuredClone(g[pick]));
+ };
+ apply(nextControllers, 'after');
+ this.history.record(label, () => apply(nextControllers, 'after'), () => apply(beforeCtrls, 'before'));
}
moveControllerPage(id: EntityId, name: string, from: number, to: number): void {
@@ -1319,6 +1414,20 @@ export class SceneCommandsImpl {
this.writeGearBindings(id, 'Remove Gear',
cur.filter((b) => !(b.controller === controller && b.component === component && b.property === property)));
}
+
+ /** Set (or clear, with undefined) one gear binding's page-change transition. Undoable. */
+ setGearTween(id: EntityId, controller: string, component: string, property: string, tween?: GearTween): void {
+ const cur = this.gearBindingsOf(id);
+ const next = cur.map((b) => {
+ if (b.controller !== controller || b.component !== component || b.property !== property) return b;
+ if (!tween) {
+ const { tween: _removed, ...rest } = b;
+ return rest as GearBinding;
+ }
+ return { ...b, tween: { ...tween } };
+ });
+ this.writeGearBindings(id, 'Set Gear Transition', next);
+ }
}
/** The app's default-session commands. Other sessions construct their own SceneCommandsImpl(model, history). */
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 4418534bb..5864c5f15 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -32,8 +32,10 @@ export type AnyComp = Parameters<WorldT['has']>[1];
// — Presentation policy (editor-side, not engine schema) —
-// Structural/relationship components that drive the tree, not the inspector.
-const HIDDEN_COMPONENTS = new Set(['Parent', 'Children', 'Name']);
+// Structural/relationship components that drive the tree, not the inspector —
+// plus UIController/UIGear, whose authoring surface is the Controllers panel and
+// the Details gear dots (their array-of-object data has no generic field control).
+const HIDDEN_COMPONENTS = new Set(['Parent', 'Children', 'Name', 'UIController', 'UIGear']);
// Components whose enable flag drives the entity's RENDER visibility (the Outliner
// eye + hidden state). Disabling a non-render component (physics, audio, a script)
// turns that behaviour off without hiding the entity. Light2D/ShadowCaster2D belong
diff --git a/desktop/src/i18n/messages/controllers.ts b/desktop/src/i18n/messages/controllers.ts
index 830c52dc2..0596231ca 100644
--- a/desktop/src/i18n/messages/controllers.ts
+++ b/desktop/src/i18n/messages/controllers.ts
@@ -32,8 +32,27 @@ export const controllerMessages = defineMessages({
'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.removePage': { en: 'Remove this page (clears its gear values)', zh: '删除此页(清除其绑定值)' },
+ 'ctrl.addInteraction': {
+ en: 'Add a $interaction controller (pointer-driven button states)',
+ zh: '添加 $interaction 控制器(指针驱动的按钮状态)',
+ },
+ 'ctrl.interactionTitle': {
+ en: 'Built-in pointer controller — the name is fixed',
+ zh: '内置指针控制器——名称固定',
+ },
+ 'ctrl.renameHint': { en: 'Double-click to rename (gears follow)', zh: '双击重命名(绑定会跟随更新)' },
+ 'ctrl.inheritedFrom': { en: 'Inherited from an ancestor', zh: '继承自祖先实体' },
+ 'ctrl.chipHint': {
+ en: 'Click to preview · double-click to rename · drag to reorder',
+ zh: '单击预览 · 双击重命名 · 拖拽排序',
+ },
+ 'ctrl.gearsTitle': { en: 'Gears on this entity', zh: '此实体的绑定' },
+ 'ctrl.gearPagesSuffix': { en: ' pages', zh: ' 页' },
'ctrl.gearBind': { en: 'Gear this field to the active controller', zh: '将该字段绑定到活动控制器' },
+ 'ctrl.gearSettings': { en: 'Gear settings (transition / unbind)', zh: '绑定设置(过渡 / 解绑)' },
'ctrl.gearUnbind': { en: 'Remove gear (unbind from controller)', zh: '移除绑定(从控制器解绑)' },
+ 'ctrl.gearDuration': { en: 'Duration (s)', zh: '时长(秒)' },
+ 'ctrl.gearEasing': { en: 'Easing', zh: '缓动' },
});
diff --git a/desktop/src/panels/ControllersPanel.tsx b/desktop/src/panels/ControllersPanel.tsx
index 778c6c0c2..4096a7bce 100644
--- a/desktop/src/panels/ControllersPanel.tsx
+++ b/desktop/src/panels/ControllersPanel.tsx
@@ -1,27 +1,28 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file ControllersPanel — author UIController "pages" for the selected UI root.
+ * @file ControllersPanel — author UIController "pages" for the selected UI entity.
*
- * 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).
+ * Controllers resolve self → ancestors (resolveControllers), so selecting a geared
+ * leaf still shows — and can switch — the root's controllers, matching the runtime
+ * rule; inherited rows carry the owner's name and edits target the owner entity.
+ * Page chips select on click, rename on double-click, delete on the hover ×, and
+ * reorder by drag; renames cascade into resolving gear bindings (SceneCommands).
+ * 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.
*/
-import { useEffect, useState, useSyncExternalStore } from 'react';
-import { Circle, Plus, Minus, Trash2 } from 'lucide-react';
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { Circle, CornerLeftUp, MousePointerClick, Plus, Trash2, X } from 'lucide-react';
+import { INTERACTION_CONTROLLER, INTERACTION_PAGES } from 'esengine';
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 { resolveControllers, readGearBindings, type ResolvedController } from '@/controller/controllerModel';
import { t } from '@/i18n';
import type { EntityId } from '@/types';
-import type { ControllerState } from 'esengine';
export function ControllersPanel() {
const selectedId = useSelection((s) => s.selectedId);
@@ -33,14 +34,15 @@ export function ControllersPanel() {
const [newCtrl, setNewCtrl] = useState('');
const entity = selectedId != null ? SceneModel.entityBySource(selectedId) : null;
- const controllers = selectedId != null ? readControllers(selectedId) : [];
+ const controllers = selectedId != null ? resolveControllers(selectedId) : [];
+ const gears = selectedId != null ? readGearBindings(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.
+ // Default the active controller to the first one resolvable from this entity.
useEffect(() => {
if (controllers.length === 0) return;
- if (!activeController || !controllers.some((c) => c.name === activeController)) {
- setActiveController(controllers[0].name);
+ if (!activeController || !controllers.some((c) => c.ctrl.name === activeController)) {
+ setActiveController(controllers[0]!.ctrl.name);
}
}, [controllers, activeController, setActiveController]);
@@ -59,6 +61,12 @@ export function ControllersPanel() {
setNewCtrl('');
};
+ const hasInteraction = controllers.some((c) => c.ctrl.name === INTERACTION_CONTROLLER);
+ const addInteraction = () => {
+ SceneCommands.addController(selectedId, INTERACTION_CONTROLLER, [...INTERACTION_PAGES]);
+ setActiveController(INTERACTION_CONTROLLER);
+ };
+
return (
<div className="ctrl-panel">
<div className="ctrl-head">
@@ -77,17 +85,39 @@ export function ControllersPanel() {
{controllers.length === 0 && <div className="ctrl-hint">{t('ctrl.hintAdd')}</div>}
<div className="ctrl-list">
- {controllers.map((c) => (
+ {controllers.map((rc) => (
<ControllerRow
- key={c.name}
- entityId={selectedId}
- ctrl={c}
- active={c.name === activeController}
- onActivate={() => setActiveController(c.name)}
+ key={`${rc.owner}:${rc.ctrl.name}`}
+ resolved={rc}
+ active={rc.ctrl.name === activeController}
+ onActivate={() => setActiveController(rc.ctrl.name)}
/>
))}
</div>
+ {gears.length > 0 && (
+ <div className="ctrl-gears">
+ <div className="ctrl-gears-title">{t('ctrl.gearsTitle')}</div>
+ {gears.map((b) => (
+ <div key={`${b.controller}:${b.component}.${b.property}`} className="ctrl-gear-row">
+ <span className="ctrl-gear-field">{b.component}.{b.property}</span>
+ <span className="ctrl-gear-meta">
+ ← {b.controller} · {Object.keys(b.pages).length}{t('ctrl.gearPagesSuffix')}
+ {b.tween ? ` · ${b.tween.duration}s` : ''}
+ </span>
+ <button
+ type="button"
+ className="ctrl-del"
+ title={t('ctrl.gearUnbind')}
+ onClick={() => SceneCommands.removeGearBinding(selectedId, b.controller, b.component, b.property)}
+ >
+ <X size={11} />
+ </button>
+ </div>
+ ))}
+ </div>
+ )}
+
<div className="ctrl-add">
<input
className="ctrl-input"
@@ -99,50 +129,104 @@ export function ControllersPanel() {
<button type="button" className="ctrl-btn" title={t('ctrl.addController')} onClick={addController}>
<Plus size={13} />
</button>
+ <button
+ type="button"
+ className="ctrl-btn"
+ title={t('ctrl.addInteraction')}
+ disabled={hasInteraction}
+ onClick={addInteraction}
+ >
+ <MousePointerClick size={13} />
+ </button>
</div>
</div>
);
}
-function ControllerRow({
- entityId, ctrl, active, onActivate,
-}: {
- entityId: EntityId;
- ctrl: ControllerState;
+/** Input that commits on Enter/blur and cancels on Escape — chip/name renames. */
+function InlineEdit({ initial, className, onCommit, onCancel }: {
+ initial: string;
+ className?: string;
+ onCommit: (value: string) => void;
+ onCancel: () => void;
+}) {
+ const [text, setText] = useState(initial);
+ const committed = useRef(false);
+ const commit = () => {
+ if (committed.current) return;
+ committed.current = true;
+ onCommit(text);
+ };
+ return (
+ <input
+ className={`ctrl-input sm${className ? ` ${className}` : ''}`}
+ value={text}
+ autoFocus
+ onFocus={(e) => e.target.select()}
+ onChange={(e) => setText(e.target.value)}
+ onBlur={commit}
+ onKeyDown={(e) => {
+ if (e.key === 'Enter') commit();
+ if (e.key === 'Escape') { committed.current = true; onCancel(); }
+ }}
+ onClick={(e) => e.stopPropagation()}
+ />
+ );
+}
+
+function ControllerRow({ resolved, active, onActivate }: {
+ resolved: ResolvedController;
active: boolean;
onActivate: () => void;
}) {
+ const { ctrl, owner, ownerName, inherited } = resolved;
const [newPage, setNewPage] = useState('');
+ const [renaming, setRenaming] = useState(false);
+ const isInteraction = ctrl.name === INTERACTION_CONTROLLER;
+
const addPage = () => {
const p = newPage.trim();
if (!p) return;
- SceneCommands.addControllerPage(entityId, ctrl.name, p);
+ SceneCommands.addControllerPage(owner, 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>
+ {renaming ? (
+ <InlineEdit
+ initial={ctrl.name}
+ onCommit={(v) => { setRenaming(false); SceneCommands.renameController(owner, ctrl.name, v); }}
+ onCancel={() => setRenaming(false)}
+ />
+ ) : (
+ <span
+ className="ctrl-name"
+ title={isInteraction ? t('ctrl.interactionTitle') : t('ctrl.renameHint')}
+ onDoubleClick={() => { if (!isInteraction) setRenaming(true); }}
+ >
+ {ctrl.name}
+ </span>
+ )}
+ {inherited && (
+ <span className="ctrl-owner" title={t('ctrl.inheritedFrom')}>
+ <CornerLeftUp size={10} />
+ {ownerName}
+ </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); }}
+ onClick={(e) => { e.stopPropagation(); SceneCommands.removeController(owner, 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>
+ <PageChips ownerId={owner} ctrlName={ctrl.name} pages={ctrl.pages} current={ctrl.current} />
<div className="ctrl-page-edit" onClick={(e) => e.stopPropagation()}>
<input
@@ -155,16 +239,74 @@ function ControllerRow({
<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>
);
}
+
+/**
+ * The page selector: click selects (live-previews via the edit-mode gear-apply
+ * pass), double-click renames in place, the hover × deletes (kept while >1 pages),
+ * and dragging a chip reorders the controller's page list.
+ */
+function PageChips({ ownerId, ctrlName, pages, current }: {
+ ownerId: EntityId;
+ ctrlName: string;
+ pages: string[];
+ current: string;
+}) {
+ const [renameIdx, setRenameIdx] = useState<number | null>(null);
+ const dragFrom = useRef<number | null>(null);
+ const [dropIdx, setDropIdx] = useState<number | null>(null);
+
+ return (
+ <div className="ctrl-chips" onClick={(e) => e.stopPropagation()}>
+ {pages.map((page, i) => renameIdx === i ? (
+ <InlineEdit
+ key={`edit-${page}`}
+ initial={page}
+ className="chip-edit"
+ onCommit={(v) => { setRenameIdx(null); SceneCommands.renameControllerPage(ownerId, ctrlName, page, v); }}
+ onCancel={() => setRenameIdx(null)}
+ />
+ ) : (
+ <span
+ key={page}
+ draggable
+ className={
+ `ctrl-chip${page === current ? ' on' : ''}${dropIdx === i ? ' drop' : ''}`
+ }
+ title={t('ctrl.chipHint')}
+ onClick={() => SceneCommands.setControllerPage(ownerId, ctrlName, page)}
+ onDoubleClick={() => setRenameIdx(i)}
+ onDragStart={(e) => { dragFrom.current = i; e.dataTransfer.effectAllowed = 'move'; }}
+ onDragOver={(e) => { e.preventDefault(); setDropIdx(i); }}
+ onDragLeave={() => setDropIdx((d) => (d === i ? null : d))}
+ onDrop={(e) => {
+ e.preventDefault();
+ setDropIdx(null);
+ const from = dragFrom.current;
+ dragFrom.current = null;
+ if (from != null && from !== i) SceneCommands.moveControllerPage(ownerId, ctrlName, from, i);
+ }}
+ onDragEnd={() => { dragFrom.current = null; setDropIdx(null); }}
+ >
+ {page}
+ {pages.length > 1 && (
+ <button
+ type="button"
+ className="ctrl-chip-x"
+ title={t('ctrl.removePage')}
+ onClick={(e) => {
+ e.stopPropagation();
+ SceneCommands.removeControllerPage(ownerId, ctrlName, page);
+ }}
+ >
+ <X size={9} />
+ </button>
+ )}
+ </span>
+ ))}
+ </div>
+ );
+}
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 70ecbde8c..a0570b912 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
-import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from 'react';
+import type { KeyboardEvent as ReactKeyboardEvent, MouseEvent as ReactMouseEvent, ReactNode } from 'react';
import {
Box,
Camera,
@@ -41,7 +41,7 @@ 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 { isGeared, controllerCurrentPage, readModelField, readGearBindings } from '@/controller/controllerModel';
import { useOutliner } from '@/outliner/OutlinerController';
import { isFolderUnder, folderName } from '@/outliner/folders';
import { EngineHost } from '@/engine/EngineHost';
@@ -52,8 +52,8 @@ import { InspectorClipboard } from '@/engine/inspectorClipboard';
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, GearValue } from 'esengine';
+import { DimensionUnit, AnchorAxis, detectAnchor, UIPositionType, parseLocaleTable, EasingType } from 'esengine';
+import type { SceneData, InputMapAsset, ActionType, Binding, LocaleTableAsset, PluralCategory, GearValue, GearTween } 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';
@@ -887,24 +887,108 @@ function fieldWriter(entities: EntityId[], comp: string, field: InspectorField,
return { apply, begin, end };
}
+// Curated page-change easings for the gear popover, name → EasingType value.
+const GEAR_EASINGS = [
+ 'Linear', 'EaseOutQuad', 'EaseInOutQuad', 'EaseOutCubic',
+ 'EaseInOutCubic', 'EaseOutBack', 'EaseOutElastic', 'EaseOutBounce',
+] as const;
+type GearEasingName = (typeof GEAR_EASINGS)[number];
+
+/**
+ * Settings for one bound gear: page-change transition (duration 0 = snap, else
+ * duration + easing tween) and the unbind action — opened from a bound gear dot
+ * so unbinding is a deliberate second step, not a destructive dot toggle.
+ */
+function GearPopover({ anchor, onClose, entity, controller, component, property }: {
+ anchor: DOMRect;
+ onClose: () => void;
+ entity: EntityId;
+ controller: string;
+ component: string;
+ property: string;
+}) {
+ useSyncExternalStore(SceneStore.subscribe, SceneStore.getRevision);
+ const binding = readGearBindings(entity).find(
+ (b) => b.controller === controller && b.component === component && b.property === property);
+ const tween = binding?.tween;
+ const duration = tween?.duration ?? 0;
+ const [durText, setDurText] = useState(String(duration));
+
+ if (!binding) return null;
+
+ const setTween = (next?: GearTween) =>
+ SceneCommands.setGearTween(entity, controller, component, property, next);
+ const commitDuration = () => {
+ const d = Math.max(0, parseFloat(durText) || 0);
+ setDurText(String(d));
+ if (d === duration) return;
+ setTween(d > 0 ? { easing: tween?.easing ?? EasingType.EaseOutQuad, duration: d } : undefined);
+ };
+ const easingName: GearEasingName =
+ GEAR_EASINGS.find((n) => EasingType[n] === (tween?.easing ?? EasingType.Linear)) ?? 'Linear';
+
+ return (
+ <Popover anchor={anchor} width={210} onClose={onClose} className="gear-pop">
+ <div className="gear-pop-title">{controller} · {component}.{property}</div>
+ <div className="gear-pop-row">
+ <span className="gear-pop-label">{t('ctrl.gearDuration')}</span>
+ <input
+ type="number"
+ className="gear-pop-num"
+ min={0}
+ step={0.05}
+ value={durText}
+ onChange={(e) => setDurText(e.target.value)}
+ onBlur={commitDuration}
+ onKeyDown={(e) => { if (e.key === 'Enter') commitDuration(); }}
+ />
+ </div>
+ <div className="gear-pop-row">
+ <span className="gear-pop-label">{t('ctrl.gearEasing')}</span>
+ <Select<GearEasingName>
+ value={easingName}
+ options={GEAR_EASINGS.map((n) => ({ value: n }))}
+ onChange={(n) => setTween({ easing: EasingType[n], duration: duration > 0 ? duration : 0.15 })}
+ className="gear-pop-select"
+ ariaLabel={t('ctrl.gearEasing')}
+ />
+ </div>
+ <button
+ type="button"
+ className="gear-pop-remove"
+ onClick={() => {
+ SceneCommands.removeGearBinding(entity, controller, component, property);
+ onClose();
+ }}
+ >
+ {t('ctrl.gearUnbind')}
+ </button>
+ </Popover>
+ );
+}
+
function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp: string; field: InspectorField; write?: FieldWrite }) {
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.
+ // controller. Clicking an unbound dot binds the field (seeding the current page
+ // with its value); clicking a bound dot opens the gear popover (transition
+ // tween + unbind) instead of destructively toggling. While recording, bound
+ // dots go red — the affordance for "edits here land in the current page".
const activeController = useControllerStore((s) => s.activeController);
+ const recording = useControllerStore((s) => s.recording);
+ const gearPop = usePopover();
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 = () => {
+ const onGearClick = (e: ReactMouseEvent<HTMLButtonElement>) => {
if (!gearable || activeController == null || gearPage == null) return;
if (geared) {
- SceneCommands.removeGearBinding(gearEntity, activeController, comp, field.key);
+ gearPop.open(e.currentTarget);
} else {
const value = readModelField(gearEntity, comp, field.key);
if (value === undefined) return;
@@ -1089,14 +1173,24 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp
{gearable && (
<button
type="button"
- className={`prop-gear${geared ? ' on' : ''}`}
+ className={`prop-gear${geared ? ' on' : ''}${geared && recording ? ' rec' : ''}`}
tabIndex={-1}
- title={geared ? t('ctrl.gearUnbind') : t('ctrl.gearBind')}
- onClick={toggleGear}
+ title={geared ? t('ctrl.gearSettings') : t('ctrl.gearBind')}
+ onClick={onGearClick}
>
<Cog size={11} strokeWidth={2} />
</button>
)}
+ {gearPop.anchor && activeController != null && (
+ <GearPopover
+ anchor={gearPop.anchor}
+ onClose={gearPop.close}
+ entity={gearEntity}
+ controller={activeController}
+ component={comp}
+ property={field.key}
+ />
+ )}
</div>
<button
type="button"
diff --git a/desktop/src/theme/controllers.css b/desktop/src/theme/controllers.css
index 12a28fa7d..ce7276d1a 100644
--- a/desktop/src/theme/controllers.css
+++ b/desktop/src/theme/controllers.css
@@ -23,7 +23,26 @@
.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-owner { display: inline-flex; align-items: center; gap: 2px; font-size: 9px; color: var(--text-dim); border: 1px solid var(--border); border-radius: 3px; padding: 0 4px; }
+
+/* Page chips: click select, double-click rename, hover × delete, drag reorder. */
+.ctrl-chips { display: flex; flex-wrap: wrap; gap: 4px; min-width: 0; }
+.ctrl-chip { position: relative; display: inline-flex; align-items: center; gap: 3px; font-size: var(--fs-2xs); color: var(--text-dim); background: var(--srf-2); border: 1px solid var(--border); border-radius: var(--r-sm); padding: 2px 7px; cursor: pointer; user-select: none; transition: color var(--t-fast), border-color var(--t-fast), background var(--t-fast); }
+.ctrl-chip:hover { color: var(--text); border-color: var(--srf-5); }
+.ctrl-chip.on { color: var(--acc-fg, #fff); background: var(--acc); border-color: var(--acc); }
+.ctrl-chip.drop { border-color: var(--acc); border-style: dashed; }
+.ctrl-chip-x { display: none; align-items: center; justify-content: center; color: inherit; background: none; border: none; cursor: pointer; padding: 0; margin-left: 1px; opacity: 0.7; }
+.ctrl-chip:hover .ctrl-chip-x { display: inline-flex; }
+.ctrl-chip-x:hover { opacity: 1; }
+.ctrl-input.chip-edit { flex: 0 1 90px; }
+
+/* Gear overview: the selected entity's own bindings. */
+.ctrl-gears { display: flex; flex-direction: column; gap: 3px; }
+.ctrl-gears-title { font-size: var(--fs-2xs); font-weight: 600; color: var(--text-dim); text-transform: uppercase; letter-spacing: 0.04em; }
+.ctrl-gear-row { display: flex; align-items: center; gap: 6px; font-size: var(--fs-2xs); padding: 3px 6px; background: var(--srf-3); border: 1px solid var(--border); border-radius: var(--r-sm); min-width: 0; }
+.ctrl-gear-field { color: var(--text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.ctrl-gear-meta { color: var(--text-dim); white-space: nowrap; margin-left: auto; }
+
.ctrl-page-edit { display: flex; align-items: center; gap: 4px; }
.ctrl-add { display: flex; align-items: center; gap: 4px; }
@@ -43,3 +62,16 @@
.prop:hover .prop-gear { opacity: 0.7; }
.prop-gear:hover { opacity: 1 !important; color: var(--text); }
.prop-gear.on { opacity: 1; color: var(--acc); }
+/* Recording: bound dots go red — edits to these fields land in the current page. */
+.prop-gear.rec { color: #ff5a5a; }
+
+/* Gear settings popover (transition tween + unbind), opened from a bound dot. */
+.gear-pop { display: flex; flex-direction: column; gap: 6px; padding: 8px; }
+.gear-pop-title { font-size: var(--fs-2xs); color: var(--text-dim); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.gear-pop-row { display: flex; align-items: center; gap: 6px; }
+.gear-pop-label { flex: 0 0 auto; font-size: var(--fs-2xs); color: var(--text-dim); min-width: 52px; }
+.gear-pop-num { 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: 3px 5px; }
+.gear-pop-num:focus { border-color: var(--acc); outline: none; }
+.gear-pop-select { flex: 1 1 auto; min-width: 0; }
+.gear-pop-remove { align-self: stretch; font-size: var(--fs-2xs); color: #ff5a5a; background: var(--srf-3); border: 1px solid var(--border); border-radius: var(--r-sm); padding: 4px 6px; cursor: pointer; transition: border-color var(--t-fast); }
+.gear-pop-remove:hover { border-color: #ff5a5a; }
diff --git a/desktop/tests/controller-commands.test.ts b/desktop/tests/controller-commands.test.ts
new file mode 100644
index 000000000..e18736e6a
--- /dev/null
+++ b/desktop/tests/controller-commands.test.ts
@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file UIController / UIGear commands: rename + page-removal cascades follow the
+ * nearest-ancestor resolution rule into descendant gear bindings, as one
+ * undo step; gear tween editing round-trips.
+ */
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import { App } from 'esengine';
+import type { ESEngineModule, GearBinding } from 'esengine';
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
+
+const host = vi.hoisted(() => ({ world: null as unknown as App['world'] }));
+vi.mock('@/engine/EngineHost', () => ({
+ EngineHost: {
+ mutableWorld: () => host.world,
+ get world() {
+ return host.world;
+ },
+ getResource: () => undefined,
+ },
+}));
+
+import { EditorSession } from '@/engine/EditorSession';
+import type { SceneData } from 'esengine';
+
+const emptyScene = (): SceneData =>
+ ({ version: '1.0', name: 'test', entities: [] }) as unknown as SceneData;
+
+describe.skipIf(!HAS_WASM)('controller + gear commands (cascades)', () => {
+ let module: ESEngineModule;
+ let S: EditorSession;
+
+ beforeAll(async () => {
+ module = await loadWasmModule();
+ });
+ beforeEach(() => {
+ const app = App.new();
+ const registry = new module.Registry();
+ app.connectCpp(registry as never, module);
+ host.world = app.world;
+ S = EditorSession.create();
+ S.model.adopt(emptyScene(), new Map());
+ });
+ afterEach(() => S.dispose());
+
+ const controllersOf = (id: number) =>
+ (S.model.entityBySource(id)?.components.find((c) => c.type === 'UIController')?.data as
+ { controllers: Array<{ name: string; pages: string[]; current: string }> }).controllers;
+ const gearsOf = (id: number): GearBinding[] =>
+ (S.model.entityBySource(id)?.components.find((c) => c.type === 'UIGear')?.data as
+ { bindings: GearBinding[] }).bindings;
+
+ /** root('tab': a,b) → leaf with a colour gear on 'tab'. */
+ function makeTree() {
+ const root = S.commands.addEntity()!;
+ const leaf = S.commands.addEntity()!;
+ S.commands.setParent(leaf, root);
+ S.commands.addController(root, 'tab', ['a', 'b']);
+ S.commands.addGearBinding(leaf, {
+ controller: 'tab', component: 'UIVisual', property: 'color',
+ pages: { a: { r: 1, g: 0, b: 0, a: 1 }, b: { r: 0, g: 1, b: 0, a: 1 } },
+ });
+ return { root, leaf };
+ }
+
+ it('renameController cascades into descendant gears; one undo step reverts both', () => {
+ const { root, leaf } = makeTree();
+ S.commands.renameController(root, 'tab', 'nav');
+
+ expect(controllersOf(root)[0]!.name).toBe('nav');
+ expect(gearsOf(leaf)[0]!.controller).toBe('nav');
+
+ S.history.undo();
+ expect(controllersOf(root)[0]!.name).toBe('tab');
+ expect(gearsOf(leaf)[0]!.controller).toBe('tab');
+ });
+
+ it('renameController leaves gears that resolve to a shadowing descendant alone', () => {
+ const { root } = makeTree();
+ const mid = S.commands.addEntity()!;
+ const deep = S.commands.addEntity()!;
+ S.commands.setParent(mid, root);
+ S.commands.setParent(deep, mid);
+ S.commands.addController(mid, 'tab', ['x', 'y']);
+ S.commands.addGearBinding(deep, {
+ controller: 'tab', component: 'UIVisual', property: 'color',
+ pages: { x: { r: 0, g: 0, b: 1, a: 1 } },
+ });
+
+ S.commands.renameController(root, 'tab', 'nav');
+ // deep's gear resolves to mid's 'tab' (nearest ancestor), so it keeps its name.
+ expect(gearsOf(deep)[0]!.controller).toBe('tab');
+ });
+
+ it('renameControllerPage moves the pages entry, current, and gear page keys', () => {
+ const { root, leaf } = makeTree();
+ S.commands.setControllerPage(root, 'tab', 'b');
+ S.commands.renameControllerPage(root, 'tab', 'b', 'beta');
+
+ const ctrl = controllersOf(root)[0]!;
+ expect(ctrl.pages).toEqual(['a', 'beta']);
+ expect(ctrl.current).toBe('beta');
+ const pages = gearsOf(leaf)[0]!.pages;
+ expect(pages.beta).toEqual({ r: 0, g: 1, b: 0, a: 1 });
+ expect(pages.b).toBeUndefined();
+
+ S.history.undo();
+ expect(controllersOf(root)[0]!.pages).toEqual(['a', 'b']);
+ expect(gearsOf(leaf)[0]!.pages.b).toBeDefined();
+ });
+
+ it('removeControllerPage strips the page value from resolving gears', () => {
+ const { root, leaf } = makeTree();
+ S.commands.removeControllerPage(root, 'tab', 'b');
+
+ expect(controllersOf(root)[0]!.pages).toEqual(['a']);
+ expect(gearsOf(leaf)[0]!.pages.b).toBeUndefined();
+
+ S.history.undo();
+ expect(controllersOf(root)[0]!.pages).toEqual(['a', 'b']);
+ expect(gearsOf(leaf)[0]!.pages.b).toEqual({ r: 0, g: 1, b: 0, a: 1 });
+ });
+
+ it('refuses to remove the last page', () => {
+ const { root } = makeTree();
+ S.commands.removeControllerPage(root, 'tab', 'b');
+ S.commands.removeControllerPage(root, 'tab', 'a');
+ expect(controllersOf(root)[0]!.pages).toEqual(['a']);
+ });
+
+ it('setGearTween sets and clears the transition', () => {
+ const { leaf } = makeTree();
+ S.commands.setGearTween(leaf, 'tab', 'UIVisual', 'color', { easing: 2, duration: 0.25 });
+ expect(gearsOf(leaf)[0]!.tween).toEqual({ easing: 2, duration: 0.25 });
+
+ S.commands.setGearTween(leaf, 'tab', 'UIVisual', 'color', undefined);
+ expect(gearsOf(leaf)[0]!.tween).toBeUndefined();
+
+ S.history.undo();
+ expect(gearsOf(leaf)[0]!.tween).toEqual({ easing: 2, duration: 0.25 });
+ });
+});
diff --git a/desktop/tests/engine-commands.test.ts b/desktop/tests/engine-commands.test.ts
index 6ce3b34e0..28f3c9009 100644
--- a/desktop/tests/engine-commands.test.ts
+++ b/desktop/tests/engine-commands.test.ts
@@ -240,7 +240,7 @@ describe.skipIf(!HAS_WASM)('SceneCommands / SceneQuery (headless World)', () =>
// Model: button root + one Text label child, and NO prefab-instance link.
const rootEnt = S.model.entityBySource(root)!;
expect(rootEnt.components.map((c) => c.type)).toEqual(
- expect.arrayContaining(['UINode', 'Interactable', 'StateMachine', 'StateVisuals']),
+ expect.arrayContaining(['UINode', 'Interactable', 'UIController', 'UIGear']),
);
expect(rootEnt.children.length).toBe(1);
const label = S.model.entityBySource(rootEnt.children[0])!;
diff --git a/docs/astro/src/content/docs/guides/ui-controllers.mdx b/docs/astro/src/content/docs/guides/ui-controllers.mdx
index bd0f4f3a4..33323e645 100644
--- a/docs/astro/src/content/docs/guides/ui-controllers.mdx
+++ b/docs/astro/src/content/docs/guides/ui-controllers.mdx
@@ -96,8 +96,8 @@ controller for that field: on each page change the gear applies the page's value
The built-in controller name **`$interaction`** is driven by pointer state
(`normal` / `hover` / `pressed` / `disabled`). Give an element an `$interaction`
-controller + an `Interactable` + a gear, and it reproduces button states with no
-`StateMachine` — the unified replacement for the old state components:
+controller + an `Interactable` + a gear, and it gets its button states through the
+same mechanism as everything else — this is what `createButton` itself is made of:
```typescript
import { UIController, UIGear, interactionController, gearBinding, EasingType } from 'esengine';
@@ -120,17 +120,26 @@ label — all four states, one mechanism.
## Authoring in the editor
-Everything above can be authored visually — no code. Select a UI root and the
-**Controllers** panel (revealed in UI mode) lists its controllers:
+Everything above can be authored visually — no code. Select any UI entity and the
+**Controllers** panel (revealed in UI mode) lists every controller it can see —
+its own plus each ancestor's (inherited rows carry the owner's name), so the
+root's controllers stay switchable while you work on a geared leaf:
-- **Add a controller**, then add/remove **pages**; the page selector switches `current`
- and the viewport reflows live.
+- **Add a controller** (the pointer-button preset adds `$interaction` with its four
+ pages in one click), then manage **pages** as chips: click to preview, double-click
+ to rename, drag to reorder, and the hover × deletes — renames cascade into every
+ gear binding that resolves to the controller, and deleting a page clears its
+ recorded values.
- Click a controller to make it **active**. In the [Details](/docs/guides/editor/) panel,
every field then shows a small **gear dot** — click it to bind that field to the active
- controller (seeding the current page with the field's value).
+ controller (seeding the current page with the field's value). Click a bound dot to open
+ its settings: the page-change **transition** (duration + easing, 0 = snap) and unbind.
- Turn on **Record**: now editing a geared field writes the value into the controller's
- **current page**. Switch page, edit, switch page, edit — each page captures its own
- values. This is the fast path — "pick a page, change things, it's recorded".
+ **current page** (bound gear dots glow red while recording). Switch page, edit, switch
+ page, edit — each page captures its own values. This is the fast path — "pick a page,
+ change things, it's recorded".
+- The panel's **Gears on this entity** list shows every binding the selected entity
+ carries — field, driving controller, page count, transition — with one-click removal.
Controllers and gears are components, so they save into the scene / prefab like anything
else, and instance with it.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx
index c2679c1ba..3026a8284 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx
@@ -91,8 +91,8 @@ world.insert(card, UIGear, {
内建控制器名 **`$interaction`** 由指针状态驱动
(`normal` / `hover` / `pressed` / `disabled`)。给元素配一个 `$interaction` 控制器 +
-一个 `Interactable` + 一条绑定,它就重现出按钮状态,不需要 `StateMachine`——这是对旧状态组件的
-统一替代:
+一个 `Interactable` + 一条绑定,它就通过与其他一切相同的机制获得按钮状态——`createButton`
+本身就是这样构成的:
```typescript
import { UIController, UIGear, interactionController, gearBinding, EasingType } from 'esengine';
@@ -114,14 +114,21 @@ world.insert(btn, UIGear, {
## 在编辑器里授权
-上面的一切都能可视化授权,无需写码。选中一个 UI 根,**控制器** 面板(在 UI 模式下弹出)
-列出它的控制器:
+上面的一切都能可视化授权,无需写码。选中任意 UI 实体,**控制器** 面板(在 UI 模式下弹出)
+列出它能看到的所有控制器——自己的加上每个祖先的(继承行标注所有者名字),所以在被绑定的
+叶子上工作时,根上的控制器依然可见、可切页:
-- **添加控制器**,再增删 **页**;页选择器切换 `current`,视口实时重排。
+- **添加控制器**(指针按钮预设一键添加带四页的 `$interaction`),页以 **chip** 管理:
+ 单击预览、双击重命名、拖拽排序、悬停 × 删除——重命名会级联进所有解析到该控制器的
+ 绑定,删页会清掉该页已录的值。
- 点击某个控制器使其 **活动**。在 [细节](/docs/guides/editor/) 面板里,每个字段旁便出现一个小的
- **gear 点**——点它把该字段绑定到活动控制器(以当前页 + 字段当前值作种子)。
-- 打开 **录制**:此时编辑一个被绑定的字段,值就写入控制器的 **当前页**。切页、改、切页、改——
- 每页各自记录自己的值。这是快捷路径——"选一页,随便改,自动录制"。
+ **gear 点**——点它把该字段绑定到活动控制器(以当前页 + 字段当前值作种子)。再点已绑定的点,
+ 打开设置:切页 **过渡**(时长 + 缓动,0 = 瞬切)与解绑。
+- 打开 **录制**:此时编辑一个被绑定的字段,值就写入控制器的 **当前页**(录制中已绑定的
+ gear 点会变红)。切页、改、切页、改——每页各自记录自己的值。这是快捷路径——
+ "选一页,随便改,自动录制"。
+- 面板的 **此实体的绑定** 列表展示所选实体携带的每条绑定——字段、驱动控制器、页数、
+ 过渡——可一键移除。
控制器和绑定都是组件,所以它们像别的东西一样存进场景 / 预制体,并随之实例化。