@fenglimg/cocos-state-controller 0.1.0

package/assets/script/controller/StateSelectV2.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "845f5fa8-3f01-449c-a02f-28a89724b718",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

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

@@ -0,0 +1,30 @@
+/**
+ * AutoSyncCapability (Wave 2 T23).
+ *
+ * 把现有的 StateSelectV2.autoSyncEnabled (硬编码 true) 抽成 capability:
+ *  - 切 state 时, 是否保持 inspector 上当前选中的 propKey (autoSync ON, 当前默认行为)
+ *  - 还是改用切到的 state 的 lastProp (autoSync OFF)
+ *
+ * 当前 Wave 2 不主动改 StateSelectV2 内的引用 (autoSyncEnabled 仍是 true), 仅暴露 capability
+ * 接口 + isEnabled() 静态查询, 为 Panel / Wave 3 接管时切换做准备.
+ *
+ * 命名空间: 配置存放在静态字段, 不写入 ctrlData 任何 namespace (这是全局开关, 不分 state).
+ */
+
+import { CapabilityRegistry } from "../CapabilityRegistry";
+import { ICapability } from "../Capability";
+
+let _enabled = true;
+
+export const AutoSyncCapability: ICapability & {
+    isEnabled: () => boolean
+    setEnabled: (v: boolean) => void
+} = {
+    name: "autoSync",
+    isEnabled: () => _enabled,
+    setEnabled: (v: boolean) => {
+        _enabled = !!v;
+    },
+};
+
+CapabilityRegistry.register(AutoSyncCapability);

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "71ecf54c-1335-488c-aa4d-63bc4bc7384e",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

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

@@ -0,0 +1,144 @@
+/**
+ * EventCapability (Wave 3 T02).
+ *
+ * runtime 事件订阅 capability. 让代码通过 capability 接口订阅 controller 的 state 切换:
+ *
+ *   EventCapability.on(ctrl, "stateChanged", cb)
+ *   EventCapability.off(ctrl, "stateChanged", cb)
+ *   EventCapability.once(ctrl, "stateChanged", cb)
+ *
+ * payload: { ctrl, fromState, toState, fromName, toName }
+ *
+ * 实装路径:
+ *   - StateControllerV2.selectedIndex.setter 已 dispatch("onStateChanged", ...)
+ *   - EventCapability.onStateChanged hook 在被 dispatch 时, 查 ctrl-local listener Map 并 fanout
+ *   - listener 存在 WeakMap<ctrl, Map<eventName, Set<cb>>>
+ *
+ * 命名空间: 不写 ctrlData (运行期 listener 不持久化), 仅内存里维持订阅表.
+ *
+ * 内存安全: 提供 clear(ctrl) 供 ctrl.onDestroy 调用; 用 WeakMap 保证 ctrl GC 后自动释放.
+ */
+
+import { CapabilityRegistry } from "../CapabilityRegistry";
+import { CapabilityContext, ICapability } from "../Capability";
+import { StateErrorManager } from "../StateErrorManagerV2";
+
+export type EventName = "stateChanged";
+
+export interface StateChangedPayload {
+    ctrl: any
+    fromState: number
+    toState: number
+    fromName: string | null
+    toName: string | null
+}
+
+type Listener = (payload: StateChangedPayload) => void;
+
+const listenerMap: WeakMap<object, Map<EventName, Listener[]>> = new WeakMap();
+const onceFlag: WeakSet<Listener> = new WeakSet();
+
+function getOrInitListeners(ctrl: object, event: EventName): Listener[] {
+    let perCtrl = listenerMap.get(ctrl);
+    if (!perCtrl) {
+        perCtrl = new Map();
+        listenerMap.set(ctrl, perCtrl);
+    }
+    let arr = perCtrl.get(event);
+    if (!arr) {
+        arr = [];
+        perCtrl.set(event, arr);
+    }
+    return arr;
+}
+
+function stateNameAt(ctrl: any, idx: number): string | null {
+    const states = ctrl && ctrl._states;
+    if (!states || idx < 0 || idx >= states.length) return null;
+    const s = states[idx];
+    return (s && s.name) ? s.name : null;
+}
+
+export const EventCapability: ICapability & {
+    on: (ctrl: any, event: EventName, cb: Listener) => void
+    off: (ctrl: any, event: EventName, cb: Listener) => void
+    once: (ctrl: any, event: EventName, cb: Listener) => void
+    clear: (ctrl: any) => void
+    listenerCount: (ctrl: any, event: EventName) => number
+} = {
+    name: "event",
+
+    on(ctrl: any, event: EventName, cb: Listener): void {
+        if (!ctrl || typeof cb !== "function") return;
+        getOrInitListeners(ctrl, event).push(cb);
+    },
+
+    off(ctrl: any, event: EventName, cb: Listener): void {
+        if (!ctrl) return;
+        const perCtrl = listenerMap.get(ctrl);
+        if (!perCtrl) return;
+        const arr = perCtrl.get(event);
+        if (!arr) return;
+        const i = arr.indexOf(cb);
+        if (i >= 0) arr.splice(i, 1);
+    },
+
+    once(ctrl: any, event: EventName, cb: Listener): void {
+        if (!ctrl || typeof cb !== "function") return;
+        const wrapper: Listener = (payload) => {
+            EventCapability.off(ctrl, event, wrapper);
+            cb(payload);
+        };
+        onceFlag.add(wrapper);
+        getOrInitListeners(ctrl, event).push(wrapper);
+    },
+
+    clear(ctrl: any): void {
+        if (!ctrl) return;
+        listenerMap.delete(ctrl);
+    },
+
+    listenerCount(ctrl: any, event: EventName): number {
+        const perCtrl = listenerMap.get(ctrl);
+        if (!perCtrl) return 0;
+        const arr = perCtrl.get(event);
+        return arr ? arr.length : 0;
+    },
+
+    onStateChanged(ctx: CapabilityContext): void {
+        const ctrl = ctx.ctrl;
+        if (!ctrl) return;
+        const perCtrl = listenerMap.get(ctrl);
+        if (!perCtrl) return;
+        const arr = perCtrl.get("stateChanged");
+        if (!arr || arr.length === 0) return;
+
+        const fromState = (ctx.fromState === undefined || ctx.fromState === null) ? -1 : ctx.fromState;
+        const toState = (ctx.toState === undefined || ctx.toState === null) ? ctrl.selectedIndex : ctx.toState;
+        const payload: StateChangedPayload = {
+            ctrl,
+            fromState,
+            toState,
+            fromName: stateNameAt(ctrl, fromState),
+            toName: stateNameAt(ctrl, toState),
+        };
+
+        // 拷贝快照 避免 listener 内部 off 改动遍历中数组
+        const snapshot = arr.slice();
+        for (let i = 0; i < snapshot.length; i++) {
+            const cb = snapshot[i];
+            try {
+                cb(payload);
+            }
+            catch (e) {
+                StateErrorManager.warn("EventCapability listener 抛异常", {
+                    component: "EventCapability",
+                    method: "onStateChanged",
+                    params: { error: (e as Error).message },
+                });
+            }
+        }
+    },
+};
+
+CapabilityRegistry.register(EventCapability);

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "ad31b829-6b84-4698-9c60-b2a1523b1b47",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

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

@@ -0,0 +1,94 @@
+/**
+ * MigrationCapability (Wave 4 T01 实装).
+ *
+ * 数据版本迁移框架. 用途:
+ *   - prefab 反序列化时, 老格式 _ctrlData → 当前格式
+ *   - 未来字段重命名 / 结构调整, 不破坏老 scene
+ *
+ * 使用方式:
+ *   MigrationCapability.registerStep(1, function(data){
+ *       data.newField = computeFromOld(data);
+ *       delete data.oldField;
+ *       return data;
+ *   });
+ *   // 反序列化路径自动调:
+ *   const upgraded = MigrationCapability.migrate(oldData, oldVersion, MigrationCapability.CURRENT_VERSION);
+ *
+ * step(fromVersion) 表示 "把版本 N 的数据升到版本 N+1". migrate() 按 from 升序依次跑.
+ *
+ * 错误兜底: step 抛异常 → 停止后续, 返回最后一个成功的中间结果 (尽力升级而非崩盘).
+ *
+ * 当前 CURRENT_VERSION = 1 (基线). 未来真要改数据格式时, ++ 并注册对应 step.
+ */
+
+import { CapabilityRegistry } from "../CapabilityRegistry";
+import { ICapability } from "../Capability";
+import { StateErrorManager } from "../StateErrorManagerV2";
+
+type MigrationStep = (data: unknown) => unknown;
+
+const steps: Map<number, MigrationStep> = new Map();
+
+export const MigrationCapability: ICapability & {
+    CURRENT_VERSION: number
+    registerStep: (fromVersion: number, fn: MigrationStep) => void
+    migrate: (data: unknown, fromVersion: number, toVersion: number) => unknown
+    clearSteps: () => void
+} = {
+    name: "migration",
+    CURRENT_VERSION: 1,
+
+    registerStep(fromVersion: number, fn: MigrationStep): void {
+        if (typeof fn !== "function") return;
+        steps.set(fromVersion, fn);
+    },
+
+    clearSteps(): void {
+        steps.clear();
+    },
+
+    migrate(data: unknown, fromVersion: number, toVersion: number): unknown {
+        if (fromVersion === toVersion) return data;
+        if (fromVersion > toVersion) {
+            StateErrorManager.warn("MigrationCapability.migrate: fromVersion > toVersion, 不支持降级", {
+                component: "MigrationCapability",
+                method: "migrate",
+                params: { fromVersion, toVersion },
+            });
+            return data;
+        }
+
+        const sortedKeys: number[] = [];
+        steps.forEach((_, k) => {
+            sortedKeys.push(k);
+        });
+        sortedKeys.sort((a, b) => a - b);
+
+        let current: unknown = data;
+        for (let i = 0; i < sortedKeys.length; i++) {
+            const v = sortedKeys[i];
+            if (v < fromVersion) continue;
+            if (v >= toVersion) break;
+            const step = steps.get(v);
+            if (!step) continue;
+            try {
+                current = step(current);
+            }
+            catch (e) {
+                StateErrorManager.warn(`MigrationCapability step(v=${v}) 抛异常, 停止后续`, {
+                    component: "MigrationCapability",
+                    method: "migrate",
+                    params: { fromVersion, toVersion, failedStepFrom: v, error: (e as Error).message },
+                });
+                return current;
+            }
+        }
+        return current;
+    },
+
+    onCtrlDataMigrate(data: unknown, version: number): unknown {
+        return MigrationCapability.migrate(data, version, MigrationCapability.CURRENT_VERSION);
+    },
+};
+
+CapabilityRegistry.register(MigrationCapability);

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "5a264b19-fefc-4ecf-abbe-91669bdded54",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

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

@@ -0,0 +1,157 @@
+/**
+ * MultiCtrlBindingCapability (Wave 5 T02).
+ *
+ * 声明式跨 ctrl 状态联动: ctrlA 切到 stateId X → ctrlB 自动切到 stateId Y.
+ *
+ *   addBinding(sourceCtrl, sourceStateId, targetCtrl, targetStateId) → boolean
+ *   removeBinding(sourceCtrl, sourceStateId, targetCtrl) → boolean
+ *   listBindings(sourceCtrl) → [{sourceStateId, targetCtrl, targetStateId}]
+ *   clearAllBindings(sourceCtrl)
+ *
+ * 内部用 EventCapability.on 监听 source 切换, 命中 sourceStateId 后走
+ * SelectedPageIdCapability.setStateById 切 target.
+ *
+ * 重要约束:
+ *  - 同 (source, sourceStateId, target) 重复 add 覆盖
+ *  - 循环防护: 当 binding 正在 dispatch, 嵌套触发的子 binding 跳过 (一帧只允许 1 跳传播深度).
+ *    A → B → A 不会死循环.
+ *  - clearAllBindings 解 EventCapability listener, 避免 listener 泄漏
+ *
+ * 数据存储: 进程级 Map<sourceCtrl, Map<sourceStateId, Map<targetCtrl, {targetStateId, listenerHandle}>>>.
+ * sourceCtrl / targetCtrl 用 WeakMap 持有避免泄漏. (内层 Map 用普通 Map 因 key 是 number/object 混合.)
+ */
+
+import { CapabilityRegistry } from "../CapabilityRegistry";
+import { ICapability } from "../Capability";
+import { StateErrorManager } from "../StateErrorManagerV2";
+import { EventCapability, StateChangedPayload } from "./EventCapability";
+import { SelectedPageIdCapability } from "./SelectedPageIdCapability";
+
+interface BindingEntry {
+    targetStateId: number
+    target: object
+}
+
+interface SourceListener {
+    /** sourceStateId → list of bindings */
+    byState: Map<number, BindingEntry[]>
+    /** EventCapability 注册的回调引用 (用于卸载) */
+    listener: (payload: StateChangedPayload) => void
+}
+
+const sourceMap: WeakMap<object, SourceListener> = new WeakMap();
+
+/** 循环防护: 当正在 dispatch binding, 后续切换不再触发 binding. 单帧 boolean 即可. */
+let dispatching = false;
+
+function ensureSourceListener(sourceCtrl: any): SourceListener {
+    let entry = sourceMap.get(sourceCtrl);
+    if (entry) return entry;
+
+    const byState = new Map<number, BindingEntry[]>();
+
+    const listener: (payload: StateChangedPayload) => void = function (payload) {
+        if (dispatching) return;
+        const sId = SelectedPageIdCapability.getSelectedStateId(payload.ctrl);
+        const bindings = byState.get(sId);
+        if (!bindings || bindings.length === 0) return;
+
+        dispatching = true;
+        try {
+            for (let i = 0; i < bindings.length; i++) {
+                const b = bindings[i];
+                try {
+                    SelectedPageIdCapability.setStateById(b.target, b.targetStateId);
+                }
+                catch (e) {
+                    StateErrorManager.warn("MultiCtrlBinding setStateById 异常", {
+                        component: "MultiCtrlBindingCapability",
+                        method: "dispatch",
+                        params: { error: (e as Error).message, targetStateId: b.targetStateId },
+                    });
+                }
+            }
+        }
+        finally {
+            dispatching = false;
+        }
+    };
+
+    entry = { byState, listener };
+    sourceMap.set(sourceCtrl, entry);
+    EventCapability.on(sourceCtrl, "stateChanged", listener);
+    return entry;
+}
+
+export interface BindingDescriptor {
+    sourceStateId: number
+    targetCtrl: any
+    targetStateId: number
+}
+
+export const MultiCtrlBindingCapability: ICapability & {
+    addBinding: (source: any, sourceStateId: number, target: any, targetStateId: number) => boolean
+    removeBinding: (source: any, sourceStateId: number, target: any) => boolean
+    listBindings: (source: any) => BindingDescriptor[]
+    clearAllBindings: (source: any) => void
+} = {
+    name: "multiCtrlBinding",
+    dependsOn: ["event", "selectedPageId"],
+
+    addBinding(source: any, sourceStateId: number, target: any, targetStateId: number): boolean {
+        if (!source || !target) return false;
+        if (typeof sourceStateId !== "number" || typeof targetStateId !== "number") return false;
+
+        const entry = ensureSourceListener(source);
+        let bindings = entry.byState.get(sourceStateId);
+        if (!bindings) {
+            bindings = [];
+            entry.byState.set(sourceStateId, bindings);
+        }
+        // 覆盖同 target 的旧 binding
+        const existIdx = bindings.findIndex(b => b.target === target);
+        if (existIdx >= 0) {
+            bindings[existIdx] = { targetStateId, target };
+        }
+        else {
+            bindings.push({ targetStateId, target });
+        }
+        return true;
+    },
+
+    removeBinding(source: any, sourceStateId: number, target: any): boolean {
+        if (!source || !target) return false;
+        const entry = sourceMap.get(source);
+        if (!entry) return false;
+        const bindings = entry.byState.get(sourceStateId);
+        if (!bindings) return false;
+        const idx = bindings.findIndex(b => b.target === target);
+        if (idx < 0) return false;
+        bindings.splice(idx, 1);
+        if (bindings.length === 0) entry.byState.delete(sourceStateId);
+        return true;
+    },
+
+    listBindings(source: any): BindingDescriptor[] {
+        if (!source) return [];
+        const entry = sourceMap.get(source);
+        if (!entry) return [];
+        const out: BindingDescriptor[] = [];
+        entry.byState.forEach((bindings, sId) => {
+            bindings.forEach((b) => {
+                out.push({ sourceStateId: sId, targetCtrl: b.target, targetStateId: b.targetStateId });
+            });
+        });
+        return out;
+    },
+
+    clearAllBindings(source: any): void {
+        if (!source) return;
+        const entry = sourceMap.get(source);
+        if (!entry) return;
+        EventCapability.off(source, "stateChanged", entry.listener);
+        sourceMap.delete(source);
+    },
+};
+
+CapabilityRegistry.register(MultiCtrlBindingCapability);

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "c020eda3-f325-4b59-a53c-9ef540b33a76",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

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

@@ -0,0 +1,124 @@
+/**
+ * PropertyControlCapability (Wave 2 T21).
+ *
+ * 把现有的 StatePropertyControlService 包装成一个 capability, 让"prop 可用性 / 受控状态判断"
+ * 成为可独立挂载/卸载的能力, 而非 StateSelectV2 紧耦合.
+ *
+ * 现状: StateSelectV2 的 isPropertyAvailable / isPropertyControlled 调 PropertyControlService
+ *      静态方法. 本 capability 暴露同样的静态 API + 自注册到 Registry. 既不破现有调用,
+ *      又让 panel / 第三方能力可以通过 CapabilityRegistry.get("propertyControl") 拿到.
+ *
+ * 命名空间: 使用 `$$controlledProps$$` (沿用历史 key, 向后兼容). 不改名为 `$$propertyControl$$`
+ *          避免老 scene 数据反序列化丢失 — 这是 PLN-002 R3 的应对策略.
+ */
+
+import { CapabilityRegistry } from "../CapabilityRegistry";
+import { CapabilityContext, ICapability } from "../Capability";
+import { EnumPropName } from "../StateEnumV2";
+import { PropertyControlService } from "../StatePropertyControlService";
+import { ENUM_TO_PROPREF, PROPREF_TO_ENUM } from "../EnumPropRefMap";
+
+/**
+ * PropertyControlCapability — 静态工具风格 (不持实例状态), 同时实现 ICapability 接口.
+ * 暴露三个核心查询方法 (同 PropertyControlService); StateSelectV2 现有调用保持不变.
+ *
+ * W6-2b: 增加 propRef 解析工具 + onPropertyControlled / onPropertyReleased hook stub.
+ *   hook 当前仅做日志, 不写 ctrlData (实际数据写入仍在 StateSelectV2.addPropertyControl 路径).
+ *   propRef 优先, fallback propType + ENUM_TO_PROPREF 派生.
+ */
+class PropertyControlCapabilityImpl implements ICapability {
+    public readonly name = "propertyControl";
+
+    /** 节点上是否可以使用某 prop 类型. (代理到 PropertyControlService) */
+    public static isPropertyAvailable(node: cc.Node, propType: EnumPropName): boolean {
+        return PropertyControlService.isPropertyAvailable(node, propType);
+    }
+
+    /** propData 中某 prop 是否标记为受控. */
+    public static isPropertyControlled(propData: any, propType: EnumPropName): boolean {
+        return PropertyControlService.isPropertyControlled(propData, propType);
+    }
+
+    /** 列出当前节点上所有可用的 prop. */
+    public static scanAvailableProperties(node: cc.Node): EnumPropName[] {
+        return PropertyControlService.scanAvailableProperties(node);
+    }
+
+    /** 注册第三方组件 prop 类型 (PropertyControlService.registerComponentProp 的代理) */
+    public static registerComponentProp(propType: EnumPropName, check: (node: cc.Node) => boolean): void {
+        PropertyControlService.registerComponentProp(propType, check);
+    }
+
+    /**
+     * W6-2b: 从 ctx 解析 propRef. 优先用 ctx.propRef, fallback ctx.propType + ENUM_TO_PROPREF.
+     * 返回 undefined 表示既无 propRef 又无可派生 propType (e.g. AMBIGUOUS Position/Anchor/Size/GrayScale).
+     */
+    public static resolvePropRef(ctx: CapabilityContext): string | undefined {
+        if (typeof ctx.propRef === "string" && ctx.propRef.length > 0) return ctx.propRef;
+        if (typeof ctx.propType === "number" && ctx.propType > 0) {
+            return ENUM_TO_PROPREF[ctx.propType];
+        }
+        return undefined;
+    }
+
+    /**
+     * W6-2b: 从 ctx 解析 propType (反向). 优先用 ctx.propType, fallback ctx.propRef + PROPREF_TO_ENUM.
+     * 返回 undefined 表示自定义 prop (无 EnumPropName 映射).
+     */
+    public static resolvePropType(ctx: CapabilityContext): EnumPropName | undefined {
+        if (typeof ctx.propType === "number" && ctx.propType > 0) return ctx.propType;
+        if (typeof ctx.propRef === "string") {
+            const mapped = PROPREF_TO_ENUM[ctx.propRef];
+            if (mapped !== undefined) return mapped as EnumPropName;
+        }
+        return undefined;
+    }
+}
+
+/**
+ * 导出对象 (不是类) — 让 PropertyControlCapability.name === "propertyControl",
+ * 避免 JS function.name 默认返回类名 "PropertyControlCapabilityImpl" 的陷阱.
+ *
+ * 该对象同时是 ICapability 单例 (注册到 Registry) 和静态工具命名空间.
+ *
+ * W6-2b: 加 resolvePropRef / resolvePropType 静态工具 + onPropertyControlled / onPropertyReleased
+ *   hook 占位 (优先用 ctx.propRef, fallback propType).
+ */
+export const PropertyControlCapability: ICapability & {
+    isPropertyAvailable: typeof PropertyControlCapabilityImpl.isPropertyAvailable
+    isPropertyControlled: typeof PropertyControlCapabilityImpl.isPropertyControlled
+    scanAvailableProperties: typeof PropertyControlCapabilityImpl.scanAvailableProperties
+    registerComponentProp: typeof PropertyControlCapabilityImpl.registerComponentProp
+    resolvePropRef: typeof PropertyControlCapabilityImpl.resolvePropRef
+    resolvePropType: typeof PropertyControlCapabilityImpl.resolvePropType
+} = {
+    name: "propertyControl",
+    isPropertyAvailable: PropertyControlCapabilityImpl.isPropertyAvailable,
+    isPropertyControlled: PropertyControlCapabilityImpl.isPropertyControlled,
+    scanAvailableProperties: PropertyControlCapabilityImpl.scanAvailableProperties,
+    registerComponentProp: PropertyControlCapabilityImpl.registerComponentProp,
+    resolvePropRef: PropertyControlCapabilityImpl.resolvePropRef,
+    resolvePropType: PropertyControlCapabilityImpl.resolvePropType,
+
+    // W6-2b: onPropertyControlled hook — 优先 propRef, fallback propType + ENUM_TO_PROPREF 派生
+    onPropertyControlled(ctx: CapabilityContext): void {
+        // hook 不做实际数据写入 (那是 StateSelectV2.addPropertyControl 的职责),
+        // 仅消费 ctx 验证 propRef + propType 双字段并存的契约 — 让下游 capability
+        // (e.g. Recording / Tween) 能用 propRef 做 propRef-aware 逻辑.
+        const propRef = PropertyControlCapabilityImpl.resolvePropRef(ctx);
+        const propType = PropertyControlCapabilityImpl.resolvePropType(ctx);
+        // no-op: 仅契约消费. 留出 propRef + propType 给 downstream capability 用.
+        void propRef;
+        void propType;
+    },
+
+    onPropertyReleased(ctx: CapabilityContext): void {
+        const propRef = PropertyControlCapabilityImpl.resolvePropRef(ctx);
+        const propType = PropertyControlCapabilityImpl.resolvePropType(ctx);
+        void propRef;
+        void propType;
+    },
+};
+
+// 自注册 — 模块被 require 即生效
+CapabilityRegistry.register(PropertyControlCapability);

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "b8464be1-ab8a-48b4-a96a-8ac2a15fa496",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}