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): record mode auto-keys — an un-geared field gears itself when edited

esenginec31bbabfd03e
diff --git a/desktop/src/controller/ControllerRecorder.ts b/desktop/src/controller/ControllerRecorder.ts
index 9407c43bf..aca3d8ecc 100644
--- a/desktop/src/controller/ControllerRecorder.ts
+++ b/desktop/src/controller/ControllerRecorder.ts
@@ -5,13 +5,15 @@
* @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.
+ * 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).
+ * 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.
*/
import { useControllerStore } from '@/store/controllerStore';
import { SceneCommands, toModelValue } from '@/engine/SceneCommands';
@@ -65,8 +67,6 @@ class ControllerRecorderImpl {
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);
@@ -76,6 +76,7 @@ class ControllerRecorderImpl {
// 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) {
@@ -86,7 +87,17 @@ class ControllerRecorderImpl {
b.pages[page] = gv;
wrote++;
}
- if (wrote === 0) return false;
+ 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;
+ next.push({
+ controller: activeController,
+ component: compName,
+ property: key,
+ pages: { [page]: modelValue as GearValue },
+ });
+ }
if (!this.burst) this.burst = { entity: sourceId, before: clone(bindings) };
SceneCommands.setGearBindingsLive(sourceId, next); // live: reconciler → gear-apply re-projects
diff --git a/desktop/src/i18n/messages/controllers.ts b/desktop/src/i18n/messages/controllers.ts
index 0596231ca..749e9d302 100644
--- a/desktop/src/i18n/messages/controllers.ts
+++ b/desktop/src/i18n/messages/controllers.ts
@@ -11,8 +11,8 @@ export const controllerMessages = defineMessages({
'ctrl.title': { en: 'Controllers', zh: '控制器' },
'ctrl.record': { en: 'Record', zh: '录制' },
'ctrl.recordTitle': {
- en: 'Record: editing a geared field writes the active controller page',
- zh: '录制:编辑受控字段时写入当前控制器页',
+ en: 'Record: edits write into the active controller’s current page (un-geared fields gear themselves)',
+ zh: '录制:编辑写入活动控制器的当前页(未绑定的字段会自动绑定)',
},
'ctrl.emptyNoSelection': {
en: 'Select a UI entity to author its controllers.',
diff --git a/docs/astro/src/content/docs/guides/ui-controllers.mdx b/docs/astro/src/content/docs/guides/ui-controllers.mdx
index 33323e645..eaf13f9bc 100644
--- a/docs/astro/src/content/docs/guides/ui-controllers.mdx
+++ b/docs/astro/src/content/docs/guides/ui-controllers.mdx
@@ -134,10 +134,10 @@ root's controllers stay switchable while you work on a geared leaf:
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). 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** (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".
+- Turn on **Record**: now every edit writes into the controller's **current page** —
+ a field with no gear yet gears itself automatically (auto-key), and 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.
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 3026a8284..49a2c2177 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
@@ -124,9 +124,9 @@ world.insert(btn, UIGear, {
- 点击某个控制器使其 **活动**。在 [细节](/docs/guides/editor/) 面板里,每个字段旁便出现一个小的
**gear 点**——点它把该字段绑定到活动控制器(以当前页 + 字段当前值作种子)。再点已绑定的点,
打开设置:切页 **过渡**(时长 + 缓动,0 = 瞬切)与解绑。
-- 打开 **录制**:此时编辑一个被绑定的字段,值就写入控制器的 **当前页**(录制中已绑定的
- gear 点会变红)。切页、改、切页、改——每页各自记录自己的值。这是快捷路径——
- "选一页,随便改,自动录制"。
+- 打开 **录制**:此时每次编辑都写入控制器的 **当前页**——还没绑定的字段会当场自动
+ 绑定(auto-key),录制中已绑定的 gear 点会变红。切页、改、切页、改——每页各自记录
+ 自己的值。这是快捷路径——"选一页,随便改,自动录制"。
- 面板的 **此实体的绑定** 列表展示所选实体携带的每条绑定——字段、驱动控制器、页数、
过渡——可一键移除。