@fenglimg/cocos-state-controller 0.1.0

package/assets/script/controller/EnumPropRefMap.ts

@@ -0,0 +1,232 @@
+/**
+ * W6-2a EnumPropName ↔ propRef 双向映射 (内部边界用).
+ *
+ * W6-2a 内部 Recording 计算路径走 propRef 字符串 (与 W6-1 PrefabIntrospection.listTrackableProps
+ * 返回值同 shape), 但外部 API 签名仍是 EnumPropName 数字 (togglePropertyControl 等). 双 key 存储:
+ *   - 内置 prop (能映射到 EnumPropName 数字) → ctrlData[ctrlId][state][数字 key]
+ *   - 自定义 prop (无映射) → ctrlData[ctrlId][state][string propRef key]
+ *
+ * 映射数据源: assets/script/controller/StatePropHandler.ts 的 register(...) 调用. 每条 enum 映射到
+ * (getValue/setValue) 实际操作的 cc.Node 字段或 (cc.Component, fieldName).
+ *
+ * AMBIGUOUS 项 (复合字段, 无法一一映射): Position (x/y/z), Anchor (anchorX/anchorY),
+ * Size (width/height), GrayScale (材质 stub) — 这些 EnumPropName 仍走老路径 (写数字 key),
+ * 不在本映射表里. 自定义 prop 走 string key 路径不受影响.
+ */
+
+import { EnumPropName } from "./StateEnumV2";
+
+/**
+ * EnumPropName 数字 → propRef 字符串.
+ * 注意: 不含 AMBIGUOUS 项. listEnumMappablePropRefs() 用此表过滤已被内置路径覆盖的 propRef.
+ */
+export const ENUM_TO_PROPREF: { [enumVal: number]: string } = {
+    // ---- cc.Node 内置字段 ----
+    [EnumPropName.Active]: "cc.Node.active",
+    [EnumPropName.Color]: "cc.Node.color",
+    [EnumPropName.Opacity]: "cc.Node.opacity",
+    [EnumPropName.Euler]: "cc.Node.eulerAngles",
+    [EnumPropName.Scale]: "cc.Node.scale",
+
+    // ---- cc.Label ----
+    [EnumPropName.LabelString]: "cc.Label.string",
+    [EnumPropName.LabelFontSize]: "cc.Label.fontSize",
+    [EnumPropName.LabelLineHeight]: "cc.Label.lineHeight",
+    [EnumPropName.LabelSpacingX]: "cc.Label.spacingX",
+    [EnumPropName.LabelWrapEnable]: "cc.Label.enableWrapText",
+    [EnumPropName.Font]: "cc.Label.font",
+
+    // ---- cc.LabelOutline ----
+    [EnumPropName.LabelOutlineColor]: "cc.LabelOutline.color",
+
+    // ---- cc.Sprite ----
+    [EnumPropName.SpriteFrame]: "cc.Sprite.spriteFrame",
+    [EnumPropName.SpriteFillRange]: "cc.Sprite.fillRange",
+
+    // ---- 其他单字段组件 ----
+    [EnumPropName.SliderProgress]: "cc.Slider.progress",
+    [EnumPropName.EditboxString]: "cc.EditBox.string",
+    [EnumPropName.ButtonInteractable]: "cc.Button.interactable",
+    [EnumPropName.ProgressBarProgress]: "cc.ProgressBar.progress",
+    [EnumPropName.ToggleIsChecked]: "cc.Toggle.isChecked",
+    [EnumPropName.RichTextString]: "cc.RichText.string",
+    [EnumPropName.ScrollViewEnabled]: "cc.ScrollView.enabled",
+    [EnumPropName.MaskEnabled]: "cc.Mask.enabled",
+
+    // ---- cc.Widget ----
+    [EnumPropName.WidgetEnabled]: "cc.Widget.enabled",
+    [EnumPropName.WidgetAlignMode]: "cc.Widget.alignMode",
+    [EnumPropName.WidgetIsAlignTop]: "cc.Widget.isAlignTop",
+    [EnumPropName.WidgetIsAlignBottom]: "cc.Widget.isAlignBottom",
+    [EnumPropName.WidgetIsAlignLeft]: "cc.Widget.isAlignLeft",
+    [EnumPropName.WidgetIsAlignRight]: "cc.Widget.isAlignRight",
+    [EnumPropName.WidgetIsAlignHorizontalCenter]: "cc.Widget.isAlignHorizontalCenter",
+    [EnumPropName.WidgetIsAlignVerticalCenter]: "cc.Widget.isAlignVerticalCenter",
+    [EnumPropName.WidgetTop]: "cc.Widget.top",
+    [EnumPropName.WidgetBottom]: "cc.Widget.bottom",
+    [EnumPropName.WidgetLeft]: "cc.Widget.left",
+    [EnumPropName.WidgetRight]: "cc.Widget.right",
+    [EnumPropName.WidgetHorizontalCenter]: "cc.Widget.horizontalCenter",
+    [EnumPropName.WidgetVerticalCenter]: "cc.Widget.verticalCenter",
+
+    // ---- AMBIGUOUS — 不在主映射表 (W6-2c2: 改走 AMBIGUOUS_ENUM_TO_PROPREF 单一 propRef 整体存) ----
+    // EnumPropName.Position (2): 老 PropHandler 行为 n.position = vec3 整体写, 用单一 propRef 'cc.Node.position'
+    // EnumPropName.Anchor (8): 老 PropHandler 行为 n.setAnchorPoint(vec2) 整体写, 用 'cc.Node.anchorPoint'
+    // EnumPropName.Size (9): 老 PropHandler 行为 n.setContentSize(size) 整体写, 用 'cc.Node.contentSize'
+    // EnumPropName.GrayScale (15): cocos 2.x 走材质 stub, 无单一字段, 进 LEGACY_DROPPED_ENUMS 静默丢
+};
+
+/**
+ * W6-2c2: AMBIGUOUS 复合 prop → propRef 整体存映射 (Position/Anchor/Size 三项).
+ *
+ * 设计依据 (StatePropHandler.ts): 老 PropHandler 对这三项都是整体读写
+ *   - Position handler: `n.position = vec3` (整 Vec3)
+ *   - Anchor handler:   `n.setAnchorPoint(vec2)` (整 Vec2)
+ *   - Size handler:     `n.setContentSize(size)` (整 Size)
+ * 所以 W6-2c2 把这三项数据以"单一 propRef 整体存"方式落到 ctrlData, 跟老行为一致.
+ *
+ * 与 ENUM_TO_PROPREF 的区别: 内置 prop 36 项可以从 cc.Node[fieldName] 直接读,
+ * AMBIGUOUS 3 项是 cocos 复合字段无法走 fieldName 路径但能整体读写.
+ * 两表合并由 enumToPropRef() 提供.
+ */
+export const AMBIGUOUS_ENUM_TO_PROPREF: { [enumVal: number]: string } = {
+    [EnumPropName.Position]: "cc.Node.position",
+    [EnumPropName.Anchor]: "cc.Node.anchorPoint",
+    [EnumPropName.Size]: "cc.Node.contentSize",
+};
+
+/**
+ * W6-2c2: 合并 helper — ENUM_TO_PROPREF 36 项 + AMBIGUOUS 3 项 = 39 项 EnumPropName → propRef 映射.
+ *
+ * 用于:
+ *   - migrateLegacyCtrlData: 数字 key → string propRef key 迁移
+ *   - StateSelectV2.readPropByEnum / writePropByEnum: 双 key 读写桥
+ *
+ * 未命中 (e.g. GrayScale=15) 返回 undefined, 调用方按需处理.
+ */
+export function enumToPropRef(propType: number): string | undefined {
+    return ENUM_TO_PROPREF[propType] !== undefined
+        ? ENUM_TO_PROPREF[propType]
+        : AMBIGUOUS_ENUM_TO_PROPREF[propType];
+}
+
+/**
+ * propRef 字符串 → EnumPropName 数字 (反向). 用于 W6-2c 删 EnumPropName 时把老 number key
+ * 改写成 string key (本 task 不删, 仅占位提供反查能力).
+ *
+ * 含 36 条 (AMBIGUOUS 4 条不在内, 不影响内置 prop 走老路径).
+ */
+export const PROPREF_TO_ENUM: { [propRef: string]: number } = (function () {
+    const out: { [k: string]: number } = {};
+    for (const k of Object.keys(ENUM_TO_PROPREF)) {
+        const num = Number(k);
+        if (Number.isFinite(num)) out[ENUM_TO_PROPREF[num]] = num;
+    }
+    // W6-2c2: AMBIGUOUS 3 项也加入反查 ('cc.Node.position' → Position 等)
+    for (const k of Object.keys(AMBIGUOUS_ENUM_TO_PROPREF)) {
+        const num = Number(k);
+        if (Number.isFinite(num)) out[AMBIGUOUS_ENUM_TO_PROPREF[num]] = num;
+    }
+    return out;
+})();
+
+/**
+ * 已经被 EnumPropName 老路径覆盖的 propRef 集合 (即在 ENUM_TO_PROPREF 值集合中).
+ * 用于 __preload 中筛选"剩余自定义 propRef"——从 listTrackableProps 结果减去这些, 剩下的
+ * 走 string key 路径接入.
+ */
+export function isEnumMappedPropRef(propRef: string): boolean {
+    return PROPREF_TO_ENUM[propRef] !== undefined;
+}
+
+/**
+ * W6-2c1: 已废弃的 EnumPropName 数字常量列表 (无对应 propRef, 老 .fire 内若有该 enum 的数据应静默丢).
+ *
+ * - GrayScale (15): cocos 2.x 走材质 stub, 无单一字段; 已无运行时支持. 老场景里若历史误设的
+ *   GrayScale 数据存在 _ctrlData 中, __preload 时由 migrateLegacyCtrlData 静默清掉.
+ *
+ * c2 加 ENUM_TO_PROPREF 36 项迁移路径 (number → string key) 时, 也优先检查此列表
+ * (避免误迁废弃 enum). c1 范围: 仅此一项, 不动 ENUM_TO_PROPREF / AMBIGUOUS.
+ */
+export const LEGACY_DROPPED_ENUMS: number[] = [EnumPropName.GrayScale];
+
+/**
+ * W6-axis-decomp X 方案: AMBIGUOUS 复合 propRef → 子项拆解函数.
+ *
+ * 设计动机: W6-2a 双轨设计 ("Position" 整体 propRef + cc.Node.x/y/z 子项 propRef) 在 cc.Node 复合字段上
+ * 存在固有冲突 — 用户排子项 cc.Node.x 只断 propRef 字符串路径, 但整体 "cc.Node.position" 路径仍跟踪 →
+ * 切 state 时 x 跟着 Vec3 整体被恢复. X 方案: 彻底废弃整体路径, 让 cc.Node.x/y/z 子项独立接入.
+ *
+ * 拆解三项 (其它 cc.Node 字段如 Euler/Color 仍走整体, 因为没拆分的对应子项 EnumPropName):
+ *   - 'cc.Node.position' (Vec3) → x/y/z 三子项
+ *   - 'cc.Node.anchorPoint' (Vec2) → anchorX/anchorY 两子项
+ *   - 'cc.Node.contentSize' (Size) → width/height 两子项
+ *
+ * 调用方: migrateLegacyCtrlData — 检测 propData 内层有整体 Vec3/Vec2/Size 值时调拆解, 升级为多子项 key.
+ *
+ * 守卫: 值必须形似 Vec3 ({x,y,z}) / Vec2 ({x,y}) / Size ({width,height}). string/null/undefined 不动
+ * (e.g. W6.legacyMigration.test.ts 的 "stub-pos" 字符串 stub 不应被解构, 保持兼容).
+ */
+export const AMBIGUOUS_DECOMPOSE: { [propRef: string]: (value: any) => Array<[string, any]> | null } = {
+    "cc.Node.position": (v: any) => {
+        if (!v || typeof v !== "object") return null;
+        if (typeof v.x !== "number" || typeof v.y !== "number" || typeof v.z !== "number") return null;
+        return [
+            ["cc.Node.x", v.x],
+            ["cc.Node.y", v.y],
+            ["cc.Node.z", v.z],
+        ];
+    },
+    "cc.Node.anchorPoint": (v: any) => {
+        if (!v || typeof v !== "object") return null;
+        if (typeof v.x !== "number" || typeof v.y !== "number") return null;
+        return [
+            ["cc.Node.anchorX", v.x],
+            ["cc.Node.anchorY", v.y],
+        ];
+    },
+    "cc.Node.contentSize": (v: any) => {
+        if (!v || typeof v !== "object") return null;
+        if (typeof v.width !== "number" || typeof v.height !== "number") return null;
+        return [
+            ["cc.Node.width", v.width],
+            ["cc.Node.height", v.height],
+        ];
+    },
+    // cocos 2.x cc.Node.scale 是 Vec3 (有 scaleX/scaleY/scaleZ 子项 getter/setter)
+    "cc.Node.scale": (v: any) => {
+        if (v == null) return null;
+        // scale 可能是 number (uniform scale) 或 Vec3
+        if (typeof v === "number") {
+            return [
+                ["cc.Node.scaleX", v],
+                ["cc.Node.scaleY", v],
+                ["cc.Node.scaleZ", v],
+            ];
+        }
+        if (typeof v !== "object") return null;
+        if (typeof v.x !== "number" || typeof v.y !== "number") return null;
+        return [
+            ["cc.Node.scaleX", v.x],
+            ["cc.Node.scaleY", v.y],
+            ["cc.Node.scaleZ", typeof v.z === "number" ? v.z : 1],
+        ];
+    },
+    // cocos 2.x cc.Node.eulerAngles 是 Vec3 (rotationX/rotationY 子项, z 不常用)
+    "cc.Node.eulerAngles": (v: any) => {
+        if (!v || typeof v !== "object") return null;
+        if (typeof v.x !== "number" || typeof v.y !== "number") return null;
+        return [
+            ["cc.Node.rotationX", v.x],
+            ["cc.Node.rotationY", v.y],
+        ];
+    },
+};
+
+/**
+ * W6-axis-decomp: 判断 propRef 是否是 AMBIGUOUS 整体 propRef (可拆解为子项).
+ * 用于 autoOptInCustomComponentProps 跳过整体 propRef 接入 (只接入 listTrackableProps 内的 x/y/z 子项).
+ */
+export function isAmbiguousAggregatePropRef(propRef: string): boolean {
+    return AMBIGUOUS_DECOMPOSE[propRef] !== undefined;
+}

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "2fb11dc9-b4af-430c-84c0-518129982f13",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/NestedCtrlData.ts

@@ -0,0 +1,199 @@
+/**
+ * W6 数据模型 (新): 嵌套 ctrlData 结构 + 按 cocos type 分发的 clone/eq helper
+ *
+ * 与 W5 之前的 EnumPropName 表驱动模型并行存在 — W6-1 仅引入, W6-2 才切换。
+ *
+ * 设计要点:
+ *   - TNestedProp: 内层 propRef (e.g. "cc.Sprite.spriteFrame") -> value
+ *   - TNestedCtrl: 外层 ctrlId -> { $$default$$?, [state]: TNestedProp }
+ *   - cloneValueByType / eqValueByType: 按 cocos type 分发, 与 StatePropHandler 的 eqVec3/eqColor 等等价
+ */
+
+/** 单个 prop 的值集合 (propRef 字符串 -> any) */
+export type TNestedProp = { [propRef: string]: any };
+
+/**
+ * 单个控制器在一个挂载节点上的嵌套数据.
+ *   $$default$$ — 节点首次接入控制器时拍下的"基准值"
+ *   [stateIndex] — 各 state 下的 override
+ */
+export type TNestedCtrlEntry = {
+    $$default$$?: TNestedProp
+    [state: number]: TNestedProp
+};
+
+/** 多控制器嵌套结构: ctrlId -> Entry */
+export type TNestedCtrl = { [ctrlId: number]: TNestedCtrlEntry };
+
+// ============================== 内省辅助 ==============================
+
+/**
+ * 探测 cocos type, 返回标准化字符串. 用于 clone/eq 分发.
+ *
+ * cocos 2.x 在 getClassAttrs 里的 type 取值:
+ *   - 函数构造器 (cc.Color/cc.Vec3/cc.Vec2/cc.Size/cc.Quat 等)
+ *   - 字符串 "Number" / "String" / "Boolean" / "Object" / "Enum"
+ *   - undefined (没标 type, 走值本身的运行时类型判定)
+ */
+function isVecLike(t: any): t is "Vec2" | "Vec3" | "Color" | "Size" | "Quat" {
+    if (typeof t !== "function") return false;
+    const ccL = (globalThis as any).cc;
+    if (!ccL) return false;
+    return t === ccL.Vec3 || t === ccL.Vec2 || t === ccL.Color || t === ccL.Size || t === ccL.Quat;
+}
+
+// ============================== clone ==============================
+
+/**
+ * 按 cocos type 分发深拷:
+ *   - cc.Color/Vec3/Vec2/Size/Quat 走构造器深拷
+ *   - 基础类型 (Number/String/Boolean) 直传
+ *   - asset (cc.SpriteFrame/cc.Font 等) 引用直传
+ *   - undefined/null 直传
+ */
+export function cloneValueByType(value: any, cocosType: any): any {
+    if (value === undefined || value === null) return value;
+    const ccL = (globalThis as any).cc;
+    if (ccL && typeof cocosType === "function") {
+        if (cocosType === ccL.Color) {
+            const c = value as cc.Color;
+            return ccL.color(c.r, c.g, c.b, c.a);
+        }
+        if (cocosType === ccL.Vec3) {
+            const v = value as cc.Vec3;
+            return ccL.v3(v.x, v.y, v.z);
+        }
+        if (cocosType === ccL.Vec2) {
+            const v = value as cc.Vec2;
+            return ccL.v2(v.x, v.y);
+        }
+        if (cocosType === ccL.Size) {
+            const s = value as cc.Size;
+            return ccL.size(s.width, s.height);
+        }
+        if (ccL.Quat && cocosType === ccL.Quat) {
+            const q = value as cc.Quat;
+            return new ccL.Quat(q.x, q.y, q.z, q.w);
+        }
+        // 其余 function-typed (Asset 等) 引用直传
+        return value;
+    }
+    // W6-axis-decomp: cocosType 未知 (cc.Node 内置 native 字段在 listTrackableProps 返回 cocosType=undefined),
+    // 但值可能是 Color/Vec3/Vec2/Size/Quat 实例 — 此时也要深拷, 否则 baseline snapshot 和节点共享引用,
+    // 节点 mutate 时 baseline 跟着改 → diff 永远命中"等" → dirty 检测漏报 (反向 bug).
+    if (ccL && value && typeof value === "object") {
+        if (ccL.Color && value instanceof ccL.Color) {
+            const c = value as cc.Color;
+            return ccL.color(c.r, c.g, c.b, c.a);
+        }
+        if (ccL.Vec3 && value instanceof ccL.Vec3) {
+            const v = value as cc.Vec3;
+            return ccL.v3(v.x, v.y, v.z);
+        }
+        if (ccL.Vec2 && value instanceof ccL.Vec2) {
+            const v = value as cc.Vec2;
+            return ccL.v2(v.x, v.y);
+        }
+        if (ccL.Size && value instanceof ccL.Size) {
+            const s = value as cc.Size;
+            return ccL.size(s.width, s.height);
+        }
+        if (ccL.Quat && value instanceof ccL.Quat) {
+            const q = value as cc.Quat;
+            return new ccL.Quat(q.x, q.y, q.z, q.w);
+        }
+    }
+    // 基础类型 / 未知 type — 引用 (基础类型按值传) 直传
+    return value;
+}
+
+// ============================== eq ==============================
+
+/**
+ * 按 cocos type 分发等值判定. 与 cloneValueByType 的 type 集合对齐.
+ *
+ * 规则:
+ *   - 双侧均为 nil (undefined/null) 视为相等
+ *   - 一侧 nil 视为不等
+ *   - Color/Vec3/Vec2/Size/Quat 字段比
+ *   - 其余走 strict ===
+ */
+export function eqValueByType(a: any, b: any, cocosType: any): boolean {
+    const aNil = a === undefined || a === null;
+    const bNil = b === undefined || b === null;
+    if (aNil && bNil) return true;
+    if (aNil !== bNil) return false;
+
+    const ccL = (globalThis as any).cc;
+    if (ccL && typeof cocosType === "function") {
+        if (cocosType === ccL.Color) {
+            const ac = a as cc.Color;
+            const bc = b as cc.Color;
+            return ac.r === bc.r && ac.g === bc.g && ac.b === bc.b && ac.a === bc.a;
+        }
+        if (cocosType === ccL.Vec3) {
+            const av = a as cc.Vec3;
+            const bv = b as cc.Vec3;
+            return av.x === bv.x && av.y === bv.y && av.z === bv.z;
+        }
+        if (cocosType === ccL.Vec2) {
+            const av = a as cc.Vec2;
+            const bv = b as cc.Vec2;
+            return av.x === bv.x && av.y === bv.y;
+        }
+        if (cocosType === ccL.Size) {
+            const as_ = a as cc.Size;
+            const bs = b as cc.Size;
+            return as_.width === bs.width && as_.height === bs.height;
+        }
+        if (ccL.Quat && cocosType === ccL.Quat) {
+            const aq = a as cc.Quat;
+            const bq = b as cc.Quat;
+            return aq.x === bq.x && aq.y === bq.y && aq.z === bq.z && aq.w === bq.w;
+        }
+    }
+    // W6-axis-decomp: cocosType 未知 (e.g. cc.Node 内置 native 字段在 listTrackableProps 里 cocosType=undefined),
+    // 但若任一侧是 cc 复合对象 (Color/Vec3/Vec2/Size/Quat), 按该类型字段结构比 —— 另一侧可能是老 .fire
+    // 反序列化后的普通对象 (#U7) 或不同 frame/getter 的同值对象, strict !== 会引起 false-positive dirty.
+    if (ccL && a && b && typeof a === "object" && typeof b === "object") {
+        // #U7: 以"任一侧是 cc 实例"判定复合类型, 另一侧只要有同形字段即按字段比 (实例 vs 普通对象同值判等).
+        const instType = (x: any): string | null => {
+            if (ccL.Color && x instanceof ccL.Color) return "Color";
+            if (ccL.Quat && x instanceof ccL.Quat) return "Quat";
+            if (ccL.Vec3 && x instanceof ccL.Vec3) return "Vec3";
+            if (ccL.Vec2 && x instanceof ccL.Vec2) return "Vec2";
+            if (ccL.Size && x instanceof ccL.Size) return "Size";
+            return null;
+        };
+        const t = instType(a) || instType(b);
+        const has = (x: any, keys: string[]) => keys.every(k => typeof (x as any)[k] === "number");
+        if (t === "Color" && has(a, ["r", "g", "b"]) && has(b, ["r", "g", "b"])) {
+            return a.r === b.r && a.g === b.g && a.b === b.b && ((a.a ?? 255) === (b.a ?? 255));
+        }
+        if (t === "Quat" && has(a, [
+            "x", "y", "z", "w",
+        ]) && has(b, [
+            "x", "y", "z", "w",
+        ])) {
+            return a.x === b.x && a.y === b.y && a.z === b.z && a.w === b.w;
+        }
+        if (t === "Vec3" && has(a, ["x", "y", "z"]) && has(b, ["x", "y", "z"])) {
+            return a.x === b.x && a.y === b.y && a.z === b.z;
+        }
+        if (t === "Vec2" && has(a, ["x", "y"]) && has(b, ["x", "y"])) {
+            return a.x === b.x && a.y === b.y;
+        }
+        if (t === "Size" && has(a, ["width", "height"]) && has(b, ["width", "height"])) {
+            return a.width === b.width && a.height === b.height;
+        }
+    }
+    // #U4: NaN === NaN 在 JS 为 false → 两侧均为 NaN 视为相等, 避免持续 dirty 误判 + 重复写.
+    if (typeof a === "number" && typeof b === "number" && Number.isNaN(a) && Number.isNaN(b)) {
+        return true;
+    }
+    // 基础类型 / asset 引用 / 未知 — strict ===
+    return a === b;
+}
+
+// 抑制 isVecLike 未使用警告 (保留供 W6-2/W6-3 复用)
+void isVecLike;

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "b9e67f2c-d4ef-49aa-b600-8c4a8de14a3d",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/PrefabIntrospection.ts

@@ -0,0 +1,151 @@
+/**
+ * W6 数据模型基线 (基础设施): prefab 内省, 用于枚举一个节点上"可追踪"的 prop 集合.
+ *
+ * 走 cocos 2.4.x 引擎自己用的元数据:
+ *   - (ctor as any).__props__: ctor 的 @property / native 字段名数组
+ *   - cc.Class.Attr.getClassAttrs(ctor): 每个 prop 的 visible / serializable / type / hasGetter / hasSetter 等
+ *
+ * 输出 listTrackableProps(node) 返回 [{compName, propKey, propRef, cocosType, visible, serializable, readonly}].
+ *
+ * 过滤规则:
+ *   - 跳过 _ 开头的内部存储字段 (cocos 2.x 用 `_xxx` + getter/setter 模式, 上层 `xxx` 才是 user-facing)
+ *   - 跳过 attrs[propKey + "$_$visible"] === false 的字段 (cocos 明确标记不显示)
+ *   - 跳过 SYSTEM_EXCLUDE 黑名单 (cc.Widget.target / _alignFlags / cc.Animation.defaultClip 等)
+ *   - readonly = hasGetter === true 且 hasSetter !== true (只读 getter 不可写)
+ *
+ * 共存阶段: W6-1 仅引入, W6-2 切换到取代 PropHandlerManager.listRegisteredPropTypes 的扫描路径.
+ */
+
+/** 单条可追踪 prop 描述 */
+export interface TrackableProp {
+    /** 组件类名 (cc.Node / cc.Sprite / W6TestComp 等) */
+    compName: string
+    /** 字段名 (active / spriteFrame / heatLevel 等) */
+    propKey: string
+    /** propRef = compName + "." + propKey, 是 NestedCtrlData 的 key */
+    propRef: string
+    /** cocos getClassAttrs 返回的 type — 函数构造器 or "Number"/"String"/"Boolean"/"Object"/"Enum"/undefined */
+    cocosType: any
+    /** inspector 可见性 (false=不可见) */
+    visible: boolean
+    /** prefab 序列化标记 */
+    serializable: boolean
+    /** 只读 (getter only, 无 setter) */
+    readonly: boolean
+}
+
+/**
+ * 系统黑名单 — 这些 prop 即使可见也不参与 state 切换 (引擎内部状态 / 资源关联).
+ *
+ * 选取理由:
+ *   - cc.Widget.target: 节点引用, prefab 实例化时不稳定
+ *   - cc.Widget._alignFlags: 内部对齐 bitmask
+ *   - cc.Animation.defaultClip / currentClip: 资源引用, 应通过 play() 切换
+ *   - cc.ParticleSystem.file: 粒子配置资源
+ *   - cc.AudioSource.clip: 音频资源
+ *   - cc.Node.rotation / rotationX / rotationY: cocos 2.1.0 起废弃, 读写会触发 cc.warn (使用 angle / eulerAngles 替代)
+ *   - cc.Node.name / cc.Node.uuid: 节点身份标识, 非视觉状态, 不应随 state 切换 (uuid 实例化时还会变)
+ */
+export const SYSTEM_EXCLUDE: string[] = [
+    "cc.Widget.target",
+    "cc.Widget.alignFlags",
+    "cc.Animation.defaultClip",
+    "cc.Animation.currentClip",
+    "cc.ParticleSystem.file",
+    "cc.AudioSource.clip",
+    "cc.Node.rotation",
+    "cc.Node.rotationX",
+    "cc.Node.rotationY",
+    "cc.Node.name",
+    "cc.Node.uuid",
+];
+
+const EXCLUDE_SET = new Set(SYSTEM_EXCLUDE);
+
+/**
+ * 取构造器类名:
+ *   - 内置 cc 类 (cc.Sprite/cc.Widget 等): cc.js.getClassName(ctor) 返回 "cc.Sprite"
+ *   - 自定义 @ccclass 类: 返回 @ccclass("Name") 注册名
+ *   - fallback: ctor.name
+ */
+function getCompName(ctor: any): string {
+    const ccL = (globalThis as any).cc;
+    if (ccL && ccL.js && typeof ccL.js.getClassName === "function") {
+        const cn = ccL.js.getClassName(ctor);
+        if (typeof cn === "string" && cn.length > 0) return cn;
+    }
+    // cocos 2.x 也把 @ccclass 注册名写到 ctor.__classname__ (某些版本)
+    const cnAlt = (ctor as any).__classname__;
+    if (typeof cnAlt === "string" && cnAlt.length > 0) return cnAlt;
+    if (ctor && ctor.name) return ctor.name;
+    return "UnknownClass";
+}
+
+/**
+ * 枚举一个 ctor 上的可追踪 prop. 不递归父类 (cocos __props__ 已合并继承链).
+ */
+function enumPropsForCtor(ctor: any, compName: string): TrackableProp[] {
+    const out: TrackableProp[] = [];
+    const props = (ctor as any).__props__ as string[] | undefined;
+    if (!Array.isArray(props)) return out;
+    const ccL = (globalThis as any).cc;
+    const attrs = ccL && ccL.Class && ccL.Class.Attr && ccL.Class.Attr.getClassAttrs
+        ? ccL.Class.Attr.getClassAttrs(ctor)
+        : {};
+    for (const propKey of props) {
+        // 跳过下划线内部字段
+        if (propKey.startsWith("_")) continue;
+        const propRef = `${compName}.${propKey}`;
+        // 跳过系统黑名单
+        if (EXCLUDE_SET.has(propRef)) continue;
+        const visAttr = attrs[`${propKey}$_$visible`];
+        // 跳过显式 visible:false
+        if (visAttr === false) continue;
+        const serAttr = attrs[`${propKey}$_$serializable`];
+        const typeAttr = attrs[`${propKey}$_$type`];
+        const hasGetter = attrs[`${propKey}$_$hasGetter`];
+        const hasSetter = attrs[`${propKey}$_$hasSetter`];
+        const readonly = hasGetter === true && hasSetter !== true;
+        out.push({
+            compName,
+            propKey,
+            propRef,
+            cocosType: typeAttr,
+            // visible 默认 true (undefined 视为可见), 已在上面排除了 false
+            visible: visAttr !== false,
+            // serializable 默认 true, 显式 false 才标 false
+            serializable: serAttr !== false,
+            readonly,
+        });
+    }
+    return out;
+}
+
+/**
+ * 列出节点上所有可追踪的 prop:
+ *   - cc.Node 类的 user-facing 字段 (active/x/y/scale/color/opacity/anchorX 等)
+ *   - 节点 _components 上每个 cc.Component 子类的 @property 字段
+ *
+ * 顺序: 先 cc.Node, 再按 _components 顺序.
+ */
+export function listTrackableProps(node: cc.Node): TrackableProp[] {
+    if (!node) return [];
+    const ccL = (globalThis as any).cc;
+    const out: TrackableProp[] = [];
+
+    // 1) cc.Node 自身
+    out.push(...enumPropsForCtor(ccL.Node, "cc.Node"));
+
+    // 2) 节点上每个组件
+    const comps = (node as any)._components as cc.Component[] | undefined;
+    if (Array.isArray(comps)) {
+        for (const comp of comps) {
+            if (!comp) continue;
+            const ctor = (comp as any).constructor;
+            const compName = getCompName(ctor);
+            out.push(...enumPropsForCtor(ctor, compName));
+        }
+    }
+
+    return out;
+}

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "0630d1ba-daeb-49ee-b72d-31e05be3df89",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/Props.meta

@@ -0,0 +1,13 @@
+{
+  "ver": "1.1.3",
+  "uuid": "44eae133-0ac8-44e5-a80f-b27d248cbdbb",
+  "importer": "folder",
+  "isBundle": false,
+  "bundleName": "",
+  "priority": 1,
+  "compressionType": {},
+  "optimizeHotUpdate": {},
+  "inlineSpriteFrames": {},
+  "isRemoteBundle": {},
+  "subMetas": {}
+}