A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsindex 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.tsindex 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: stringexport 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.tsindex 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.tsxindex 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?: Fieconst 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?: FiegearPop.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 (<><buttontype="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?: Fieanchor={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);