@fenglimg/cocos-state-controller 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fenglimg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# 🎮 Cocos Creator UI状态控制器系统
+
+问题记录：
+1. 主控制器设置状态数量有问题，无法创建新状态。
+
+> 💡 灵感来源  
+> 为了实现类似FairyGUI中控制器的效果，参考了【开源分享】一个基于Fgui状态控制器（controller）的creator3.0x版本，并将3.x版本改进为2.x版本，同时加入了诸多新特性。
+
+## 📋 文档目录
+
+- [🎯 项目概述](#-项目概述)
+- [✨ 核心特性](#-核心特性)
+- [🚀 快速开始](#-快速开始)
+- [📖 详细使用指南](#-详细使用指南)
+- [🔧 版本更新说明](#-版本更新说明)
+- [📚 API文档](#-api文档)
+- [🔬 高级功能](#-高级功能)
+- [🛠️ 故障排除](#️-故障排除)
+- [🏗️ 系统架构](#️-系统架构)
+
+---
+
+## 🎯 项目概述
+
+### 🎨 适用场景
+| 场景类型 | 应用示例 | 效果展示 |
+|---------|---------|---------|
+| 按钮状态 | 普通/悬浮/按下/禁用 | 颜色、图片、缩放变化 |
+| 面板动画 | 展开/收起/淡入/淡出 | 位置、大小、透明度变化 |
+| 角色状态 | 健康/受伤/死亡/技能 | 血条、图标、文本变化 |
+| 界面布局 | 横屏/竖屏/全屏/窗口 | 位置、锚点、大小变化 |
+## 🚀 快速开始
+
+### 📁 第一步：导入文件
+
+将文件夹复制到项目中：
+
+assets/script/controller/
+├── 📄 StateController.ts      # 状态控制器核心
+├── 📄 StateSelect.ts         # 状态选择器
+├── 📄 StateEnum.ts          # 枚举定义
+├── 📄 StateErrorManager.ts  # 错误处理系统
+└── 📄 StatePropHandler.ts   # 属性处理器系统
+
+### 🎮 第二步：添加控制器
+
+> 📌 重要提示  
+> StateController 应该添加到**父节点**上，它会自动管理所有子节点的状态。
+
+1. 在需要状态控制的父节点上添加 `StateController` 组件
+2. 在属性面板中设置状态数量和名称
+3. 系统会自动创建默认状态："0" 和 "1"
+
+### 🎨 第三步：配置状态选择器
+
+1. 在需要状态变化的**子节点**上添加 `StateSelect` 组件
+2. 选择要控制的属性类型（Position、Color、Scale等）
+3. 在不同状态下设置不同的属性值
+4. 选择合适的同步模式
+
+### ✅ 第四步：测试效果
+
+在编辑器中切换 `StateController` 的 `selectedIndex`，观察子节点属性的变化。
+
+---
+
+## 📖 详细使用指南
+
+### 🎮 StateController（状态控制器）
+
+> 🔧 核心组件  
+> 负责管理整个状态组，是系统的控制中心。
+
+#### 基本属性
+| 属性名 | 类型 | 说明 | 示例值 |
+|--------|------|------|--------|
+| `ctrlName` | string | 控制器名称（必须唯一） | "MainMenuCtrl" |
+| `selectedIndex` | number | 当前选中的状态索引 | 0, 1, 2... |
+| `states` | StateValue[] | 状态列表，可动态添加删除 | ["normal", "hover", "pressed"] |
+| `previousIndex` | number | 上一个状态索引（只读） | 0 |
+
+
+#### 代码控制示例
+// 🎯 获取控制器组件
+let controller = node.getComponent(StateController);
+
+// 🔄 切换到指定状态
+controller.selectedIndex = 1;
+
+// 📝 通过状态名称切换
+controller.selectedPage = "hover";
+
+// 📊 获取当前状态信息
+let currentState = controller.selectedPage;
+let previousState = controller.previousIndex;
+
+### 🎨 StateSelect（状态选择器）
+
+> 🎯 执行组件  
+> 负责具体的状态变化，必须配合 StateController 使用。
+
+#### 支持的属性类型
+
+| 分类 | 属性类型 | 说明 | 值类型 |
+|------|----------|------|--------|
+| 节点基础 | `Active` | 显示/隐藏 | `boolean` |
+| | `Position` | 位置坐标 | `cc.Vec3` |
+| | `Euler` | 旋转角度 | `cc.Vec3` |
+| | `Scale` | 缩放比例 | `number` |
+| | `Anchor` | 锚点位置 | `cc.Vec2` |
+| | `Size` | 尺寸大小 | `cc.Size` |
+| | `Color` | 节点颜色 | `cc.Color` |
+| | `Opacity` | 透明度 | `number` |
+| 文本组件 | `Label_String` | 文本内容 | `string` |
+| | `LabelOutline_Color` | 文本描边颜色 | `cc.Color` |
+| | `Font` | 字体资源 | `cc.Font` |
+| 图片组件 | `SpriteFrame` | 图片资源 | `cc.SpriteFrame` |
+| 交互组件 | `Slider_Progress` | 滑动条进度 | `number` |
+| | `Editbox_String` | 输入框文本 | `string` |
+| 特效 | `GrayScale` | 灰度效果 | `boolean` |
+
+
+#### 🔄 属性同步模式
+
+enum SyncMode {
+    Independent = 0,  // 🔸 独立模式：每个状态属性完全独立
+    AutoSync = 1,     // 🔹 自动同步：添加/删除属性时自动同步到所有状态（推荐）
+    ManualSync = 2    // 🔺 手动同步：需要手动点击同步按钮
+}
+
+> 💡 推荐设置  
+> 对于大多数情况，建议使用 AutoSync 模式。
+
+## 📚 API文档
+
+### 🎮 StateController API
+
+#### 核心属性
+
+class StateController {
+    // 🏷️ 控制器名称
+    get ctrlName(): string;
+    set ctrlName(value: string);
+    
+    // 🎯 当前选中状态索引
+    get selectedIndex(): number;
+    set selectedIndex(value: number);
+    
+    // 📋 状态数组
+    get states(): StateValue[];
+    
+    // 📝 通过名称访问状态
+    get selectedPage(): string;
+    set selectedPage(name: string);
+    
+    // 📊 上一个状态索引（只读）
+    get previousIndex(): number;
+}
+
+#### 生命周期方法
+
+// 🔄 状态切换时自动调用，通知所有相关的StateSelect组件
+private updateState(type: EnumUpdateType, value?: number): void;
+
+### 🎨 StateSelect API
+
+#### 核心属性
+
+class StateSelect {
+    // 🎮 当前选中的控制器ID
+    get currCtrlId(): number;
+    
+    // 🎯 当前控制的属性类型
+    get propKey(): EnumPropName;
+    set propKey(value: EnumPropName);
+    
+    // 💎 当前属性值
+    get propValue(): TPropValue;
+    
+    // 🔄 属性同步模式
+    syncMode: SyncMode;
+    
+    // 📊 已修改的属性列表（只读）
+    changedProp: string[];
+}
+
+#### 操作方法
+
+// 🔄 手动同步当前属性到所有状态
+set syncCurrentProp(value: boolean);
+
+// 🗑️ 删除当前属性
+set isDeleteCurr(value: boolean);
+
+### 🛡️ 错误处理 API
+
+class StateErrorManager {
+    // 📝 统一日志输出
+    static log(level: ErrorLevel, message: string, context?: IErrorContext): void;
+    
+    // 🛡️ 优雅降级处理
+    static gracefulFallback<T>(operation: () => T, fallbackValue: T, errorMessage?: string): T;
+    
+    // ✅ 节点有效性验证
+    static validateNode(node: cc.Node, context?: IErrorContext): boolean;
+    
+    // 💬 用户友好的错误提示
+    static userFriendlyError(userMessage: string, technicalDetails?: string, context?: IErrorContext): void;
+}
+
+---
+
+## 🔬 高级功能
+
+### 🔧 自定义属性处理器
+
+如果需要支持新的属性类型，可以按以下步骤扩展：
+
+#### 1️⃣ 添加枚举值
+在 `StateEnum.ts` 中添加新的属性类型：
+export enum EnumPropName {
+    // ... 现有属性
+    Button_Interactable = 16,  // 🆕 新增：按钮可交互性
+}
+
+#### 2️⃣ 实现属性处理器
+在 `StatePropHandler.ts` 中创建处理器类：
+class ButtonInteractablePropHandler implements IPropHandler {
+    getValue(node: cc.Node) {
+        const button = node.getComponent(cc.Button);
+        return button ? button.interactable : undefined;
+    }
+    
+    setValue(node: cc.Node, value: TPropValue) {
+        const button = node.getComponent(cc.Button);
+        if (button) button.interactable = value as boolean;
+    }
+    
+    getDefaultValue(node: cc.Node) {
+        return this.getValue(node);
+    }
+}
+
+#### 3️⃣ 注册处理器
+
+PropHandlerManager.register(EnumPropName.Button_Interactable, new ButtonInteractablePropHandler());
+
+### 🎯 实际应用示例
+
+#### 📱 示例1：按钮状态控制
+
+创建一个带有 normal、hover、pressed 三种状态的按钮：
+ButtonNode (StateController)
+├── 🖼️ Background (StateSelect - SpriteFrame + Color)
+├── 🏷️ Label (StateSelect - Label_String + Color)
+└── 🎨 Icon (StateSelect - Scale + Opacity)
+
+🔧 配置步骤：
+
+1. 在 `ButtonNode` 上添加 `StateController`，设置3个状态
+2. 在 `Background` 上添加 `StateSelect`：
+   - 属性类型选择 `SpriteFrame`，设置不同状态的背景图
+   - 再添加一个选择 `Color`，设置不同的背景色调
+3. 在 `Label` 上配置文本和颜色变化
+4. 在 `Icon` 上配置缩放和透明度变化
+
+#### 📋 示例2：面板展开/收起
+
+创建一个可以展开收起的设置面板：
+
+SettingsPanel (StateController)
+├── 🎨 Background (StateSelect - Size + Opacity)
+├── 🏷️ Title (StateSelect - Position)
+├── 📝 Content (StateSelect - Active + Position)
+└── ❌ CloseButton (StateSelect - Scale + Opacity)
+
+#### 🎮 示例3：角色状态显示
+
+显示角色的不同状态（健康、受伤、死亡）：
+
+CharacterUI (StateController)
+├── ❤️ HealthBar (StateSelect - Scale + Color)
+├── 🛡️ StatusIcon (StateSelect - SpriteFrame)
+├── 📛 NameLabel (StateSelect - Color + LabelOutline_Color)
+└── 🔢 LevelText (StateSelect - Label_String)
+
+暂时无法在飞书文档外展示此内容

package/assets/script/controller/Capability.ts

@@ -0,0 +1,100 @@
+/**
+ * Capability 框架接口 (Wave 2 Step 2).
+ *
+ * 设计原则:
+ *  - Core 永远薄 (StateControllerV2 + StateSelectV2 + 数据存取 + 切换协议),
+ *    其它能力 (Recording / PropertyControl / AutoSync / Migration / Tween …) 都是 capability.
+ *  - Capability 之间通信靠 event dispatch (CapabilityRegistry.dispatch), 不直接调用.
+ *  - 数据隔离: 每个 capability 通过 ctx.namespace(propData) 读写 `$$<capName>$$` 子空间.
+ *  - 删掉所有 capability, core 仍能切 state (底线; T29/T30 验证).
+ *
+ * 三层插件结构:
+ *  - L0 内置 (本仓库 capabilities/): PropertyControl, AutoSync, Recording, Migration (占位)
+ *  - L1 官方扩展 (独立 cocos plugin): Tween, StatePreviewPanel, DiffViewer, CodeGen
+ *  - L2 第三方 (用户自写)
+ */
+
+import { EnumPropName } from "./StateEnumV2";
+import { TPropValue } from "./StatePropHandlerV2";
+
+/**
+ * 通用 dispatch context. 各 capability 自己负责从 ctx 取所需字段.
+ * 字段都可选, 由派发点 (StateControllerV2 / StateSelectV2) 决定填充哪些.
+ */
+export interface CapabilityContext {
+    /** 派发来源控制器 */
+    ctrl?: any
+    /** 涉及的 StateSelectV2 */
+    select?: any
+    /** 状态切换上下文 (StateWillChange / StateChanged) */
+    fromState?: number
+    toState?: number
+    /** prop apply 上下文 (onPropApply) */
+    propType?: EnumPropName
+    propValue?: TPropValue
+    /**
+     * W6-2b: prop 引用字符串 ("compName.propKey"), 与 propType 字段并存.
+     *  - 内置 prop (EnumPropName 数字调用): 从 EnumPropRefMap 派生 propRef. AMBIGUOUS 4 项 (Position/Anchor/Size/GrayScale) 无映射 → propRef=undefined
+     *  - 自定义 prop (string 调用): propRef = 调用方传入的字符串, propType = undefined 或 EnumPropName.Non
+     *  - capability 实现可优先用 propRef, 再 fallback propType + EnumPropRefMap 派生
+     */
+    propRef?: string
+    /** 自定义额外数据, capability 之间共享 (避免直接耦合) */
+    extra?: { [key: string]: unknown }
+    /**
+     * Capability namespace helper: 给定 propData, 返回该 capability 私有的 `$$<capName>$$` 子对象.
+     * 由 CapabilityRegistry.dispatch 注入, 调用方填 propData 即可.
+     */
+    namespace?: (propData: any, capName: string) => { [key: string]: unknown }
+}
+
+/**
+ * Capability 接口 (所有 hook 都可选).
+ *
+ * name 是 capability 命名空间唯一 key, 决定 ctx.namespace(propData, name) 拿到的 `$$<name>$$` 子空间.
+ * 同名 register 会覆盖 (后注册赢).
+ */
+export interface ICapability {
+    /** 命名空间唯一 key */
+    name: string
+
+    /** 依赖的 capability 名字列表 (可选, T20+ 启用排序时使用; 当前 Wave 2 仅文档保留) */
+    dependsOn?: string[]
+
+    /** 切 state 之前 (录制中 commit diff 等) */
+    onStateWillChange?(ctx: CapabilityContext): void
+
+    /** 切 state 之后 (录制重拍 snapshot / 其它跟随状态变化的同步) */
+    onStateChanged?(ctx: CapabilityContext): void
+
+    /**
+     * Runtime 启动初始化钩子 (Wave 3).
+     * StateControllerV2.onLoad runtime path 调用. 用于 runtime 启动时
+     * 自动跳到指定 state 等场景. 编辑期不触发.
+     */
+    onRuntimeInit?(ctx: CapabilityContext): void
+
+    /**
+     * Prop apply 钩子 (StateSelectV2.batchUpdateUI 内调用):
+     * 返回 TPropValue 则改写要 apply 的值; 返回 void / undefined 不改写.
+     */
+    onPropApply?(ctx: CapabilityContext, prop: { type: EnumPropName, value: TPropValue }): TPropValue | void
+
+    /** 录制开始 / 结束 (Recording capability 内部用) */
+    onRecordingStart?(ctx: CapabilityContext): void
+    onRecordingStop?(ctx: CapabilityContext): void
+
+    /**
+     * W6-2b: prop 接入 / 解除 钩子. togglePropertyControl(on/off) 时派发.
+     *  - ctx.propType: EnumPropName 数字 (内置 prop) 或 undefined (自定义 prop)
+     *  - ctx.propRef: string 引用 (内置 propRef 派生自 EnumPropRefMap; 自定义 propRef 直接来自调用方)
+     */
+    onPropertyControlled?(ctx: CapabilityContext): void
+    onPropertyReleased?(ctx: CapabilityContext): void
+
+    /**
+     * 版本迁移 (用于 preset / migration capability).
+     * 当前 Wave 2 不实装迁移逻辑, 仅占位接口供 MigrationCapability 实现.
+     */
+    onCtrlDataMigrate?(data: unknown, version: number): unknown
+}

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "fc28023c-8126-4423-8893-0df459da7de0",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/CapabilityRegistry.ts

@@ -0,0 +1,116 @@
+/**
+ * Capability 静态注册表 (Wave 2 Step 2).
+ *
+ * 单实例, 进程全局共享. 每个 ICapability 通过 name 标识, 同名 register 覆盖 (后注册赢).
+ *
+ * dispatch(event, ctx) 同步遍历所有 capability, 调对应 hook (缺 hook 跳过, 不抛).
+ * ctx 自动注入 namespace helper, 各 capability 用 `ctx.namespace(propData, this.name)` 拿到隔离子空间.
+ *
+ * 非阻塞设计:
+ *  - 当前 Wave 2 不引入异步 / 优先级排序 (dependsOn 仅声明用, 不影响调度);
+ *  - hook 抛异常 → 捕获 + 走 StateErrorManager.warn, 不影响其它 capability 执行.
+ */
+
+import { CapabilityContext, ICapability } from "./Capability";
+import { StateErrorManager } from "./StateErrorManagerV2";
+
+type CapEvent
+    = | "onStateWillChange"
+      | "onStateChanged"
+      | "onPropApply"
+      | "onRecordingStart"
+      | "onRecordingStop"
+      | "onRecordingCancel"
+      | "onCtrlDataMigrate"
+      | "onRuntimeInit"
+    // W6-2b: prop 接入 / 解除 dispatch (togglePropertyControl on/off 触发, payload 含 propType + propRef 双字段)
+      | "onPropertyControlled"
+      | "onPropertyReleased";
+
+/** namespace helper 注入. 给 propData 设置 / 读取 `$$<capName>$$` 子对象. */
+function namespaceHelper(propData: any, capName: string): { [key: string]: unknown } {
+    if (!propData) return {};
+    const key = `$$${capName}$$`;
+    if (propData[key] === undefined || propData[key] === null) {
+        propData[key] = {};
+    }
+    return propData[key];
+}
+
+export class CapabilityRegistry {
+    private static capabilities = new Map<string, ICapability>();
+
+    /** 注册 capability. 同名覆盖 (后注册赢). */
+    public static register(cap: ICapability): void {
+        if (!cap || !cap.name) {
+            StateErrorManager.warn("CapabilityRegistry.register: cap 缺少 name", {
+                component: "CapabilityRegistry",
+                method: "register",
+            });
+            return;
+        }
+        this.capabilities.set(cap.name, cap);
+    }
+
+    /** 卸载 capability (按 name) */
+    public static unregister(name: string): void {
+        this.capabilities.delete(name);
+    }
+
+    /** 按 name 查询 capability */
+    public static get(name: string): ICapability | undefined {
+        return this.capabilities.get(name);
+    }
+
+    /** 列出所有已注册 capability (顺序为注册顺序) */
+    public static list(): ICapability[] {
+        // ES5 compat: 不用 Array.from(iter), 改 forEach 累积
+        const out: ICapability[] = [];
+        this.capabilities.forEach(cap => out.push(cap));
+        return out;
+    }
+
+    /** 全部清空 (测试用) */
+    public static clear(): void {
+        this.capabilities.clear();
+    }
+
+    /**
+     * 派发事件. 同步执行所有已注册 capability 的对应 hook.
+     *
+     * 返回值: hook 返回值的数组 (按注册顺序). 用于 onPropApply 这类有返回值的 hook;
+     * 普通 hook 返回值为 undefined 也照样收集 (调用方可忽略).
+     */
+    public static dispatch(event: CapEvent, ctx: CapabilityContext): unknown[] {
+        // 注入 namespace helper, 避免 capability 各自实现一遍
+        if (!ctx.namespace) {
+            ctx.namespace = namespaceHelper;
+        }
+        const results: unknown[] = [];
+        // 注: 项目 tsconfig target=es5 且未开 downlevelIteration, 不能用 for-of Map.values().
+        // 改用 forEach 保证 ES5 兼容.
+        this.capabilities.forEach((cap) => {
+            const hook = (cap as any)[event] as ((...args: any[]) => any) | undefined;
+            if (typeof hook !== "function") return;
+            try {
+                let r: unknown;
+                if (event === "onPropApply") {
+                    const prop = ctx.extra && (ctx.extra as any).prop;
+                    r = hook.call(cap, ctx, prop);
+                }
+                else {
+                    r = hook.call(cap, ctx);
+                }
+                results.push(r);
+            }
+            catch (e) {
+                StateErrorManager.warn(`Capability "${cap.name}" hook "${event}" 抛异常`, {
+                    component: "CapabilityRegistry",
+                    method: "dispatch",
+                    params: { error: (e as Error).message },
+                });
+            }
+        });
+        return results;
+    }
+}

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "34257e90-cddc-4862-98d3-4cbd31eb14b3",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}