@fenglimg/cocos-state-controller 0.1.0

package/assets/script/controller/capabilities/RecordingCapability.ts

@@ -0,0 +1,69 @@
+/**
+ * RecordingCapability (Wave 2 T25).
+ *
+ * Topic 3 录制路径 (T03-T17) 已实装在 StateControllerV2 / StateSelectV2 内部.
+ * 本 capability 不重复录制逻辑, 仅作为"录制能力的对外接口":
+ *   - 暴露 isRecording(ctrl) 静态查询
+ *   - 提供 onRecordingStart/Stop hook (默认空实现, 其它 capability 可监听录制态)
+ *   - 注册到 CapabilityRegistry, 让 dispatch 走 capability 路径时, 录制态能广播给监听者
+ *
+ * 命名空间: Topic 3 数据 (snapshot, ctrlData diff) 都不写 namespace, 直接复用 ctrlData[state][prop].
+ *   - snapshot 是 StateSelectV2 实例字段, 不需要 namespace
+ *   - diff commit 写 propData[propType], 与 PropertyControl 同一份数据 (录制是"写入工具", 不是"独立存储")
+ *
+ * 后续扩展位 (Wave 3+):
+ *   - 录制历史 (回放) - 需要 $$recording$$ namespace 存 timeline
+ *   - 多片段录制 - 同上
+ */
+
+import { CapabilityRegistry } from "../CapabilityRegistry";
+import { CapabilityContext, ICapability } from "../Capability";
+import { StateErrorManager } from "../StateErrorManagerV2";
+
+export const RecordingCapability: ICapability & {
+    isRecording: (ctrl: any) => boolean
+} = {
+    name: "recording",
+
+    isRecording: (ctrl: any) => !!(ctrl && ctrl.isRecording),
+
+    onRecordingStart(ctx: CapabilityContext): void {
+        StateErrorManager.debug("RecordingCapability.onRecordingStart", {
+            component: "RecordingCapability",
+            method: "onRecordingStart",
+            params: { ctrlName: ctx.ctrl?.ctrlName },
+        });
+    },
+
+    onRecordingStop(ctx: CapabilityContext): void {
+        StateErrorManager.debug("RecordingCapability.onRecordingStop", {
+            component: "RecordingCapability",
+            method: "onRecordingStop",
+            params: { ctrlName: ctx.ctrl?.ctrlName },
+        });
+    },
+
+    onStateWillChange(ctx: CapabilityContext): void {
+        // 录制中切 state, Topic 3 的 StateSelectV2.onStateWillChange 已直接处理 diff commit,
+        // 这里仅作 capability 路径上的 log, 让其它监听者 (如 timeline / undo) 知道发生.
+        if (ctx.ctrl?.isRecording) {
+            StateErrorManager.debug("RecordingCapability.onStateWillChange (recording)", {
+                component: "RecordingCapability",
+                method: "onStateWillChange",
+                params: { fromState: ctx.fromState },
+            });
+        }
+    },
+
+    onStateChanged(ctx: CapabilityContext): void {
+        if (ctx.ctrl?.isRecording) {
+            StateErrorManager.debug("RecordingCapability.onStateChanged (recording)", {
+                component: "RecordingCapability",
+                method: "onStateChanged",
+                params: { toState: ctx.ctrl.selectedIndex },
+            });
+        }
+    },
+};
+
+CapabilityRegistry.register(RecordingCapability);

package/assets/script/controller/capabilities/RecordingCapability.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "72b134e8-bce6-4953-b17e-dab38c81ea25",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/capabilities/SelectedPageIdCapability.ts

@@ -0,0 +1,88 @@
+/**
+ * SelectedPageIdCapability (Wave 3 T06).
+ *
+ * 用稳定的 stateId 切换 controller, 解决 ctrl.selectedIndex 在 reorder/delete 后下标飘移的问题.
+ *
+ *   SelectedPageIdCapability.setStateById(ctrl, stateId) → boolean
+ *   SelectedPageIdCapability.getSelectedStateId(ctrl)    → 当前 state 的 stateId, 无效 -1
+ *   SelectedPageIdCapability.getStateIdByName(ctrl, name) → stateId | -1
+ *   SelectedPageIdCapability.listAllStates(ctrl) → [{stateId, name, index}]
+ *
+ * 不引入新的持久化字段; 全部从 _states[].stateId 派生.
+ * 切换走标准 selectedIndex setter, 自动联动 EventCapability / RecordingCapability 等.
+ *
+ * 用途:
+ *   - Panel 用 listAllStates 渲染 state 列表 + setStateById 切换
+ *   - 业务代码用 setStateById("home") 等稳定 API, 不依赖临时 index
+ */
+
+import { CapabilityRegistry } from "../CapabilityRegistry";
+import { ICapability } from "../Capability";
+
+export interface StateInfo {
+    index: number
+    stateId: number
+    name: string
+}
+
+function findIndexByStateId(ctrl: any, stateId: number): number {
+    const states = ctrl && ctrl._states;
+    if (!states) return -1;
+    for (let i = 0; i < states.length; i++) {
+        const s = states[i];
+        if (s && s.stateId === stateId) return i;
+    }
+    return -1;
+}
+
+export const SelectedPageIdCapability: ICapability & {
+    setStateById: (ctrl: any, stateId: number) => boolean
+    getSelectedStateId: (ctrl: any) => number
+    getStateIdByName: (ctrl: any, name: string) => number
+    listAllStates: (ctrl: any) => StateInfo[]
+} = {
+    name: "selectedPageId",
+
+    setStateById(ctrl: any, stateId: number): boolean {
+        if (!ctrl) return false;
+        const idx = findIndexByStateId(ctrl, stateId);
+        if (idx < 0) return false;
+        ctrl.selectedIndex = idx;
+        return true;
+    },
+
+    getSelectedStateId(ctrl: any): number {
+        if (!ctrl) return -1;
+        const idx = ctrl.selectedIndex;
+        const states = ctrl._states;
+        if (!states || idx < 0 || idx >= states.length) return -1;
+        const s = states[idx];
+        return (s && typeof s.stateId === "number") ? s.stateId : -1;
+    },
+
+    getStateIdByName(ctrl: any, name: string): number {
+        if (!ctrl) return -1;
+        const states = ctrl._states;
+        if (!states) return -1;
+        for (let i = 0; i < states.length; i++) {
+            const s = states[i];
+            if (s && s.name === name) return s.stateId;
+        }
+        return -1;
+    },
+
+    listAllStates(ctrl: any): StateInfo[] {
+        const out: StateInfo[] = [];
+        if (!ctrl) return out;
+        const states = ctrl._states;
+        if (!states) return out;
+        for (let i = 0; i < states.length; i++) {
+            const s = states[i];
+            if (!s) continue;
+            out.push({ index: i, stateId: s.stateId, name: s.name });
+        }
+        return out;
+    },
+};
+
+CapabilityRegistry.register(SelectedPageIdCapability);

package/assets/script/controller/capabilities/SelectedPageIdCapability.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "59e24f53-fefa-4f28-9ad5-af1b15ef98ba",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/capabilities.meta

@@ -0,0 +1,13 @@
+{
+  "ver": "1.1.3",
+  "uuid": "c56c1d4e-382e-4e33-9862-90c97b5d3b94",
+  "importer": "folder",
+  "isBundle": false,
+  "bundleName": "",
+  "priority": 1,
+  "compressionType": {},
+  "optimizeHotUpdate": {},
+  "inlineSpriteFrames": {},
+  "isRemoteBundle": {},
+  "subMetas": {}
+}

package/assets/script/controller/props/CtrlInspectorGroups.ts

@@ -0,0 +1,138 @@
+import { EnumStateName } from "../StateEnumV2";
+import type { StateControllerV2 } from "../StateControllerV2";
+
+const { ccclass, property } = cc._decorator;
+
+// 本文件早于 StateControllerV2 内的 cc.Enum(EnumStateName) 被 import,
+// 这里先注册一次 (idempotent), 保证回收站下拉的 @property type 能解析到枚举。
+cc.Enum(EnumStateName);
+
+/**
+ * StateControllerV2「状态操作」分组 — inspector 可折叠区域.
+ *
+ * 设计同 StateNodeProps: 自身不持状态, 仅作 inspector 视图 facade, getter/setter
+ * 全部代理到 owner (StateControllerV2) 的同名访问器 (真实逻辑仍在 controller 上,
+ * 测试 / 代码可继续走 ctrl.moveStateUp 老路径). owner 在 __preload 中注入.
+ */
+@ccclass("CtrlStateOpsGroup")
+export class CtrlStateOpsGroup {
+    public owner: StateControllerV2 = null;
+
+    @property({ displayName: "状态上移", tooltip: "将当前选中的状态上移一位" })
+    public get moveStateUp() {
+        return false;
+    }
+
+    public set moveStateUp(v: boolean) {
+        if (this.owner) this.owner.moveStateUp = v;
+    }
+
+    @property({ displayName: "状态下移", tooltip: "将当前选中的状态下移一位" })
+    public get moveStateDown() {
+        return false;
+    }
+
+    public set moveStateDown(v: boolean) {
+        if (this.owner) this.owner.moveStateDown = v;
+    }
+
+    @property({ displayName: "复制当前状态", tooltip: "以当前状态为模板复制并插入到下一位" })
+    public get duplicateCurrentState() {
+        return false;
+    }
+
+    public set duplicateCurrentState(v: boolean) {
+        if (this.owner) this.owner.duplicateCurrentState = v;
+    }
+
+    @property({ displayName: "删除当前状态", tooltip: "删除当前选中的状态并自动选择相邻状态" })
+    public get deleteCurrentState() {
+        return false;
+    }
+
+    public set deleteCurrentState(v: boolean) {
+        if (this.owner) this.owner.deleteCurrentState = v;
+    }
+}
+
+/**
+ * StateControllerV2「回收站」分组 — inspector 可折叠区域.
+ *
+ * 让"软删 → 恢复 / 彻底删除"在 inspector 内闭环 (无需插件面板). facade 同 SelectExcludeGroup:
+ *  - deletedList 只读展示回收站内容 (name + id)。
+ *  - restoreTarget / purgeTarget 下拉的动态 enumList 由 owner.refreshRecycleBinEnums 注入到本组类上;
+ *    getter 恒返 0 (sentinel "选一个…"), 选项 value 从 1 起, 选中即触发动作并自动回到 sentinel。
+ *  - purgeTarget / purgeAll 是硬删 (不可恢复), 经 owner.showDialog 弹窗二次确认。
+ */
+@ccclass("CtrlRecycleBinGroup")
+export class CtrlRecycleBinGroup {
+    public owner: StateControllerV2 = null;
+
+    @property({ type: [cc.String], readonly: true, displayName: "回收站内容", tooltip: "已移除的状态 (软删, 数据保留)。下方可恢复或彻底删除" })
+    public get deletedList(): string[] {
+        return this.owner ? this.owner.getDeletedStatesDisplay() : [];
+    }
+
+    @property({ type: EnumStateName, displayName: "↩ 恢复状态", tooltip: "选择要恢复的状态, 追加到状态列表尾部 (具体数据自动接回)" })
+    public get restoreTarget(): number {
+        return 0;
+    }
+
+    public set restoreTarget(v: number) {
+        if (this.owner) this.owner.recycleRestorePick(v);
+    }
+
+    @property({ type: EnumStateName, displayName: "🗑 彻底删除", tooltip: "选择要彻底删除的状态 (清空其数据, 不可恢复)" })
+    public get purgeTarget(): number {
+        return 0;
+    }
+
+    public set purgeTarget(v: number) {
+        if (this.owner) this.owner.recyclePurgePick(v);
+    }
+
+    @property({ type: EnumStateName, displayName: "👁 预览", tooltip: "选择一个回收态只读预览 (叠加到节点, 不改当前选中)。改选中/录制会自动退出预览" })
+    public get previewTarget(): number {
+        return 0;
+    }
+
+    public set previewTarget(v: number) {
+        if (this.owner) this.owner.recyclePreviewPick(v);
+    }
+
+    @property({ displayName: "⏹ 退出预览", tooltip: "退出回收态预览, 按快照把节点精确还原到预览前" })
+    public get exitPreviewTrigger(): boolean {
+        return this.owner ? this.owner.isPreviewing : false;
+    }
+
+    public set exitPreviewTrigger(_v: boolean) {
+        if (this.owner) this.owner.recycleExitPreview();
+    }
+
+    @property({ displayName: "清空回收站", tooltip: "彻底删除回收站内全部状态数据, 不可恢复" })
+    public get purgeAll(): boolean {
+        return false;
+    }
+
+    public set purgeAll(v: boolean) {
+        if (this.owner && v) this.owner.recyclePurgeAll();
+    }
+}
+
+/**
+ * StateControllerV2「录制」分组 — inspector 可折叠区域.
+ * recordTrigger 镜像 owner.isRecording (经 owner.recordTrigger getter), 点击 toggle 起停.
+ */
+@ccclass("CtrlRecordGroup")
+export class CtrlRecordGroup {
+    public owner: StateControllerV2 = null;
+
+    @property({ displayName: "🔴 录制", tooltip: "进入/退出录制模式. 录制中, 节点改动自动写入当前 state. 要回退整次录制用编辑器 Ctrl+Z" })
+    public get recordTrigger() {
+        return this.owner ? this.owner.recordTrigger : false;
+    }
+
+    public set recordTrigger(v: boolean) {
+        if (this.owner) this.owner.recordTrigger = v;
+    }
+}

package/assets/script/controller/props/CtrlInspectorGroups.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "84998575-9595-43f0-bacc-60043a425293",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/props/SelectInspectorGroups.ts

@@ -0,0 +1,104 @@
+import { EnumExcludeSlot } from "../StateEnumV2";
+import type { StateSelectV2 } from "../StateSelectV2";
+
+const { ccclass, property } = cc._decorator;
+
+// 本文件被 StateSelectV2 import 的时机早于 StateSelectV2 内的 cc.Enum(EnumExcludeSlot),
+// 这里先注册一次 (idempotent), 保证 addExcludeTrigger 的 @property type 能解析到枚举.
+cc.Enum(EnumExcludeSlot);
+
+/**
+ * StateSelectV2「排除管理」分组 — inspector 可折叠区域.
+ *
+ * facade 同 StateNodeProps: getter/setter 代理到 owner. 注意:
+ *  - excludedPropsDisplay getter 内含 reconcile 副作用 (owner 侧), inspector 渲染时触发.
+ *  - userExcludedProps 代理同一份 owner._userExcludedProps 数组引用 (序列化字段仍在 owner 上,
+ *    不挪路径), cocos 数组 +/- 走 setter 回写 owner.
+ *  - addExcludeTrigger 的动态 enumList 由 owner.refreshExcludeEnumLists 注入到本组类上.
+ */
+@ccclass("SelectExcludeGroup")
+export class SelectExcludeGroup {
+    public owner: StateSelectV2 = null;
+
+    @property({ displayName: "排除跟随", tooltip: "当前被排除的 prop 列表 (系统 + 用户). 系统部分不可恢复.", readonly: true })
+    public get excludedPropsDisplay(): string[] {
+        return this.owner ? this.owner.excludedPropsDisplay : [];
+    }
+
+    @property({ type: EnumExcludeSlot, displayName: "+ 添加排除", tooltip: "从当前跟随中选一个 prop 加入排除清单" })
+    public get addExcludeTrigger(): number {
+        return 0;
+    }
+
+    public set addExcludeTrigger(v: number) {
+        if (this.owner) this.owner.addExcludeTrigger = v;
+    }
+
+    @property({ type: EnumExcludeSlot, displayName: "- 恢复跟随", tooltip: "从用户排除清单选一个 prop 恢复跟随 (含 [失效] 项可在此清理)" })
+    public get removeExcludeTrigger(): number {
+        return this.owner ? this.owner.removeExcludeTrigger : 0;
+    }
+
+    public set removeExcludeTrigger(v: number) {
+        if (this.owner) this.owner.removeExcludeTrigger = v;
+    }
+
+    @property({
+        type: [cc.String],
+        displayName: "用户排除清单",
+        tooltip: "用户手动排除的 prop 列表 (除 SYSTEM_EXCLUDE 外). 用 +/- 按钮增删数组项 (不要直接编辑文本: 加项请走 '+ 添加排除' 下拉). 删项 = 重新跟随.",
+        readonly: true,
+    })
+    public get userExcludedProps(): string[] {
+        return this.owner ? this.owner._userExcludedProps : [];
+    }
+
+    public set userExcludedProps(v: string[]) {
+        if (this.owner) this.owner._userExcludedProps = v;
+    }
+}
+
+/**
+ * StateSelectV2「录制」分组 — inspector 可折叠区域.
+ * 镜像 currCtrl.isRecording, 与 StateControllerV2 录制态共享 (经 owner.recordTrigger getter/setter).
+ */
+@ccclass("SelectRecordGroup")
+export class SelectRecordGroup {
+    public owner: StateSelectV2 = null;
+
+    @property({ displayName: "🔴 录制", tooltip: "进入/退出录制模式. 录制中, 节点改动自动写入当前 state. 要回退整次录制用编辑器 Ctrl+Z" })
+    public get recordTrigger() {
+        return this.owner ? this.owner.recordTrigger : false;
+    }
+
+    public set recordTrigger(v: boolean) {
+        if (this.owner) this.owner.recordTrigger = v;
+    }
+}
+
+/**
+ * StateSelectV2「值搬运」分组 — inspector 可折叠区域.
+ * 节点级局部操作: 当前 state ↔ 下一 state 的值数据 (不改 state 数量 / 选中).
+ */
+@ccclass("SelectValueOpsGroup")
+export class SelectValueOpsGroup {
+    public owner: StateSelectV2 = null;
+
+    @property({ displayName: "⇄ 与下一 state 交换值", tooltip: "把本节点当前 state 的值数据与下一 state 互换 (仅本节点, 不改 state 数量/选中)" })
+    public get swapValueWithNext(): boolean {
+        return false;
+    }
+
+    public set swapValueWithNext(v: boolean) {
+        if (this.owner) this.owner.swapValueWithNext = v;
+    }
+
+    @property({ displayName: "⎘ 复制值到下一 state", tooltip: "把本节点当前 state 的值数据深拷到下一 state (仅本节点, 不改 state 数量/选中)" })
+    public get copyValueToNext(): boolean {
+        return false;
+    }
+
+    public set copyValueToNext(v: boolean) {
+        if (this.owner) this.owner.copyValueToNext = v;
+    }
+}

package/assets/script/controller/props/SelectInspectorGroups.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "8cfbf985-091c-4440-9f05-00b317e4a671",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}