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.

fix(editor): a gear-driven field shows what applies, and edits reach it

yhh8d43a6a87889
diff --git a/desktop/src/controller/ControllerRecorder.ts b/desktop/src/controller/ControllerRecorder.ts
index aca3d8ecc..72c9560a0 100644
--- a/desktop/src/controller/ControllerRecorder.ts
+++ b/desktop/src/controller/ControllerRecorder.ts
@@ -2,16 +2,21 @@
// 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.
+ * @brief Route a field edit into the gear page it belongs to.
*
* Mirrors TimelineRecorder's edit-hook shape: one hook on the single SceneCommands
- * field-edit door. When recording is armed and the edited entity resolves the
- * active controller, the edited value is stored under the controller's current
- * page — into the field's existing gear binding, or AUTO-KEY: a field with no
- * binding yet gears itself on the spot (whole-field, seeded with the edit). So
- * "record → switch page → change things" just works, no per-field opt-in dance;
- * the Details gear dot remains the explicit path (and the settings door).
+ * field-edit door. Two rules, and the first is not conditional on anything:
+ *
+ * 1. A field a gear ALREADY drives takes its edit into that binding's own
+ * controller + current page. Always. The component value underneath is dead —
+ * gear-apply overwrites it every time the page changes — so writing there and
+ * nowhere else is how "I changed it and nothing happened" used to happen.
+ * 2. A field NOT yet geared is left alone, unless recording is armed: then
+ * AUTO-KEY gears it on the spot (whole-field, seeded with the edit, other pages
+ * left sparse). So "record → switch page → change things" still just works.
+ *
+ * That leaves recording responsible for exactly one thing — creating bindings —
+ * rather than also being the switch that decides whether existing ones respond.
* 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.
*/
@@ -65,23 +70,32 @@ class ControllerRecorderImpl {
value: InspectorFieldValue,
): boolean {
const { recording, activeController } = useControllerStore.getState();
- if (!recording || !activeController) 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);
+ const bindings = readGearBindings(sourceId);
+ // Does a gear ALREADY drive this field? If so the edit belongs in its page, and
+ // that is true whether or not recording is armed and whichever controller the
+ // strip has selected — the binding names its own. Without this, editing a driven
+ // field wrote a value the gear overwrote on the next frame: the edit landed, and
+ // nothing anyone could see ever changed.
+ const alreadyDriven = bindings.some(
+ (b) => b.component === compName && (b.property === key || b.property.startsWith(`${key}.`)),
+ );
+ if (!alreadyDriven && (!recording || !activeController)) return false;
+
// A new burst on a different entity flushes the previous one first.
if (this.burst && this.burst.entity !== sourceId) this.flush();
- const bindings = readGearBindings(sourceId);
const next = clone(bindings);
let wrote = 0;
for (const b of next) {
- if (b.controller !== activeController || b.component !== compName) continue;
+ if (b.component !== compName) continue;
if (b.property !== key && !b.property.startsWith(`${key}.`)) continue;
+ // Each binding's OWN controller decides which page this lands in.
+ const page = controllerCurrentPage(sourceId, b.controller);
+ if (page == null) continue;
const gv = gearValueFor(modelValue, b.property, key);
if (gv == null) continue;
b.pages[page] = gv;
@@ -90,7 +104,9 @@ class ControllerRecorderImpl {
if (wrote === 0) {
// Auto-key: recording an un-geared field gears it on the spot, seeding the
// current page with the edited value (other pages stay unauthored/sparse).
- if (modelValue == null) return false;
+ if (!recording || !activeController || modelValue == null) return false;
+ const page = controllerCurrentPage(sourceId, activeController);
+ if (page == null) return false;
next.push({
controller: activeController,
component: compName,
diff --git a/desktop/src/controller/controllerModel.ts b/desktop/src/controller/controllerModel.ts
index 2012d8698..93fc29c7a 100644
--- a/desktop/src/controller/controllerModel.ts
+++ b/desktop/src/controller/controllerModel.ts
@@ -96,3 +96,38 @@ export function readModelField(id: EntityId, component: string, property: string
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);
}
+
+/** A field a gear writes, and the value that actually reaches the component. */
+export interface DrivenField {
+ binding: GearBinding;
+ /** Controller driving it (the binding's own — not whatever the strip selected). */
+ controller: string;
+ /** That controller's current page, or null if it no longer resolves. */
+ page: string | null;
+ /** What `page` authors for this field. `undefined` = that page leaves it alone. */
+ pageValue: unknown;
+}
+
+/**
+ * The gear binding that drives (component, property) on `id`, or null.
+ *
+ * Asked of the DATA. Being driven is a fact about the scene — a binding exists —
+ * not about whatever the Controllers strip happens to have selected, and reading it
+ * from the strip is how a driven field came to look like an ordinary one: the
+ * component still holds a value, Details showed it, and the gear overwrote it every
+ * frame with the page's. Editing it changed nothing anyone could see.
+ *
+ * The first match wins if two controllers claim one field — the same order the
+ * runtime's apply loop walks, so the editor shows what the game will do.
+ */
+export function drivenField(id: EntityId, component: string, property: string): DrivenField | null {
+ const binding = readGearBindings(id).find((b) => b.component === component && b.property === property);
+ if (!binding) return null;
+ const page = controllerCurrentPage(id, binding.controller);
+ return {
+ binding,
+ controller: binding.controller,
+ page,
+ pageValue: page != null ? binding.pages[page] : undefined,
+ };
+}
diff --git a/desktop/src/i18n/messages/controllers.ts b/desktop/src/i18n/messages/controllers.ts
index 8f7b60734..dc91c477b 100644
--- a/desktop/src/i18n/messages/controllers.ts
+++ b/desktop/src/i18n/messages/controllers.ts
@@ -54,6 +54,12 @@ export const controllerMessages = defineMessages({
'ctrl.gearBind': { en: 'Gear this field to the active controller', zh: '将该字段绑定到活动控制器' },
'ctrl.gearSettings': { en: 'Gear settings (transition / unbind)', zh: '绑定设置(过渡 / 解绑)' },
+ // Names the page, because "driven, and by WHICH state" is what turns a field
+ // that seems to ignore your edits into one that explains itself.
+ 'ctrl.gearDrivenBy': {
+ en: 'Driven by {controller} · {page} — edits go to that page',
+ zh: '由 {controller} · {page} 驱动 —— 编辑将写入该页',
+ },
'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/Details.tsx b/desktop/src/panels/Details.tsx
index cac4a8dec..e18a09d3f 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -62,7 +62,7 @@ import { usePrefabConflicts } from '@/store/prefabConflicts';
import { useEditorStore } from '@/store/editorStore';
import { useControllerStore } from '@/store/controllerStore';
import { useInspectorCollapse, isSectionCollapsed } from '@/store/inspectorCollapse';
-import { isGeared, controllerCurrentPage, readModelField, readGearBindings, resolveControllers } from '@/controller/controllerModel';
+import { controllerCurrentPage, drivenField, readComponentData, readModelField, readGearBindings, resolveControllers } from '@/controller/controllerModel';
import { useOutliner } from '@/outliner/OutlinerController';
import { isFolderUnder, folderName } from '@/outliner/folders';
import { EngineHost } from '@/engine/EngineHost';
@@ -75,7 +75,7 @@ import { sourceById, createFromSource } from '@/engine/entitySources';
import { PlayInspect } from '@/engine/PlayInspect';
import { DimensionUnit, AnchorAxis, detectAnchorAxes, UIPositionType, FlexDirection, FlexWrap, JustifyContent, AlignItems, INTERACTION_CONTROLLER, INTERACTION_PAGES, parseLocaleTable, EasingType, BUILTIN_SHADER_TEMPLATES, INVALID_ENTITY } from 'esengine';
import type { SceneData, InputMapAsset, ActionType, Binding, LocaleTableAsset, PluralCategory, GearValue, GearTween, MaterialAssetData } from 'esengine';
-import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba, dynamicEnumOptions, boxGroupsFor, isRequiredEmpty, type BoxGroupDef } from '@/engine/schema';
+import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba, dynamicEnumOptions, boxGroupsFor, isRequiredEmpty, inspectorFields, type BoxGroupDef } from '@/engine/schema';
import { inspectorRegistry, buildContributedSection, isInfoRow } from '@/plugins/inspector';
import { localizePlugin } from '@/plugins/localize';
import type { AssetInspectorContribution, ComponentInspectorContribution } from '@/plugins/types';
@@ -1275,12 +1275,22 @@ function useGearDot(entities: EntityId[], comp: string, key: string, write?: Fie
const recording = useControllerStore((s) => s.recording);
const gearPop = usePopover();
const gearEntity = entities[0];
- const gearPage = entities.length === 1 && !write && activeController != null
+ const single = entities.length === 1 && !write;
+
+ // A DRIVEN field always shows its dot, whatever the strip has selected: being
+ // driven is a fact about the scene, and hiding the only sign of it is what let a
+ // driven field pass for an ordinary one — you could edit it and watch nothing
+ // happen. The strip still decides where a NEW binding would go, so the
+ // bind-on-click affordance keeps needing an active controller.
+ const driven = single ? drivenField(gearEntity, comp, key) : null;
+ const gearPage = single && activeController != null
? controllerCurrentPage(gearEntity, activeController)
: null;
- const gearable = gearPage != null && activeController != null;
- const geared = gearable && isGeared(gearEntity, activeController, comp, key);
- if (!gearable || activeController == null || gearPage == null) return null;
+ const bindable = gearPage != null && activeController != null;
+ if (!driven && !bindable) return null;
+
+ const controller = driven?.controller ?? activeController!;
+ const geared = driven != null;
const onGearClick = (e: ReactMouseEvent<HTMLButtonElement>) => {
e.stopPropagation();
@@ -1288,7 +1298,7 @@ function useGearDot(entities: EntityId[], comp: string, key: string, write?: Fie
gearPop.open(e.currentTarget);
} else {
const value = readModelField(gearEntity, comp, key);
- if (value === undefined) return;
+ if (value === undefined || activeController == null || gearPage == null) return;
SceneCommands.addGearBinding(gearEntity, {
controller: activeController,
component: comp,
@@ -1298,13 +1308,21 @@ function useGearDot(entities: EntityId[], comp: string, key: string, write?: Fie
}
};
+ // Naming the page is the whole point of the title: "driven, and by which state"
+ // is what turns a surprise into an explanation.
+ const title = geared
+ ? (driven!.page != null
+ ? t('ctrl.gearDrivenBy', { controller: driven!.controller, page: driven!.page })
+ : t('ctrl.gearSettings'))
+ : t('ctrl.gearBind');
+
return (
<>
<button
type="button"
className={`prop-gear${geared ? ' on' : ''}${geared && recording ? ' rec' : ''}`}
tabIndex={-1}
- title={geared ? t('ctrl.gearSettings') : t('ctrl.gearBind')}
+ title={title}
onClick={onGearClick}
>
<Cog size={11} strokeWidth={2} />
@@ -1314,7 +1332,7 @@ function useGearDot(entities: EntityId[], comp: string, key: string, write?: Fie
anchor={gearPop.anchor}
onClose={gearPop.close}
entity={gearEntity}
- controller={activeController}
+ controller={controller}
component={comp}
property={key}
/>
@@ -1323,7 +1341,36 @@ function useGearDot(entities: EntityId[], comp: string, key: string, write?: Fie
);
}
-function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp: string; field: InspectorField; write?: FieldWrite }) {
+/**
+ * Swap in the value a gear will actually apply.
+ *
+ * A driven field's own component value is dead — gear-apply overwrites it from the
+ * current page — so showing it means showing a number that has no effect on
+ * anything. Reads through the SAME `inspectorFields` conversion the row was built
+ * with (by patching the page value into a copy of the component data) rather than
+ * re-deriving colour/vector shapes here, so the two can never disagree.
+ *
+ * Kept in this panel because buildInspector is a pure model reader with no business
+ * knowing about controllers — and this panel already renders the gear dot.
+ */
+function drivenFieldValue(
+ entities: EntityId[],
+ comp: string,
+ field: InspectorField,
+ write?: FieldWrite,
+): InspectorField {
+ if (entities.length !== 1 || write) return field;
+ const driven = drivenField(entities[0], comp, field.key);
+ if (!driven || driven.pageValue === undefined) return field;
+ const data = readComponentData(entities[0], comp);
+ if (!data) return field;
+ const patched = inspectorFields(comp, { ...data, [field.key]: driven.pageValue })
+ .find((f) => f.key === field.key);
+ return patched ? { ...field, value: patched.value } : field;
+}
+
+function FieldRow({ entities, comp, field: rawField, write }: { entities: EntityId[]; comp: string; field: InspectorField; write?: FieldWrite }) {
+ const field = drivenFieldValue(entities, comp, rawField, write);
const mixed = field.mixed === true;
const { apply, begin, end, cancel } = fieldWriter(entities, comp, field, write);
const gearDot = useGearDot(entities, comp, field.key, write);