Framework

AI 工具使用约定

Codex / AI 工具生成本项目业务代码时必须遵守：

• 获取 AssetProperty 使用点访问：FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab.ShopLayer，不要使用 ["ShopLayer"]。
• LayerController 不查找节点或组件；节点/组件引用定义在对应 FW.Layer 中，节点用 FWPropertyNode，组件用 FWPropertyComponent，变量名与节点名一致。
• 默认不要在业务层调用 invoke()，除非用户明确要求。
• 新增业务 bundle 必须提供 FW.Registry 注册表，并在文件末尾调用 FW.Framework.addRegistry()；bundleName 和 addRegistry() 的 key 必须一致，统一使用小写 bundle 名。
• 不需要require对应的Registry
• Layer脚本不需要挂载到任何节点

Registry 示例：

import { RegisterAssetConfig } from "../config/RegisterAssetConfig";
import { RegisterLogic } from "../logic/RegisterLogic";

export class RegisterRegistry extends FW.Registry {
  bundleName = "register";
  logic: FW.Newable<FW.Logic> = RegisterLogic;
  config: FW.Newable<FW.AssetConfig> = RegisterAssetConfig;
}

FW.Framework.addRegistry("register", RegisterRegistry);

assets/framework 是面向 Cocos Creator 2.x 的自写业务框架，核心目标是把业务模块、UI Layer、资源、事件、网络、定时器、对象池和异步流程统一到 FW 全局命名空间下管理。

本 README 只做快速总览。详细开发规范请阅读 assets/framework/docs/ 下的文档。

核心入口

框架初始化后会创建全局 FW：

• FW.Framework：依赖注入容器，负责注册和获取业务组件。
• FW.Entry：业务统一入口，聚合所有管理器。
• FW.Log：统一日志输出。
• FW.SystemDefine：框架枚举。
• FW.EventDefine：系统事件枚举。

业务代码应优先通过 FW.Entry 使用框架能力，不要直接 new 框架管理器。

主要模块

| 模块 | 说明 | | --------------------- | --------------------------------------------------- | | FW.Registry | bundle 注册表，声明 Logic/Data/Config/Sender/Handle | | FW.FrameworkBase | 业务基类，提供依赖获取、性能记录和错误包装 | | FW.Logic | 业务流程 | | FW.Data | 业务数据 | | FW.AssetConfig | 资源配置 | | FW.LayerController | UI Layer 控制器 | | FW.Entry.resMgr | bundle 和资源加载/释放 | | FW.Entry.layerMgr | UI Layer 打开、关闭、队列和栈 | | FW.Entry.uiMgr | UI 事件注册、节点查找、按钮状态 | | FW.Entry.evtMgr | 框架事件总线 | | FW.Entry.timeMgr | 游戏生命周期定时器 | | FW.Entry.promiseMgr | 可取消、超时、重试的 Promise | | FW.Entry.socketMgr | Socket 连接管理 | | FW.Entry.objectMgr | 对象池 | | FW.Entry.taskMgr | 分帧任务 |

推荐业务结构

新增业务功能时，推荐按 bundle 拆分：

assets/<bundle>/
  script/config/<Bundle>AssetConfig.ts
  script/data/<Bundle>Data.ts
  script/logic/<Bundle>Logic.ts
  script/<Bundle>Registry.ts
  script/controller/<Feature>/<Bundle><Feature>LayerController.ts
  script/layer/<Feature>/<Bundle><Feature>Layer.ts
  res/prefab/layer/<Bundle><Feature>Layer.prefab

命名必须保留框架后缀，例如 ShopLogic、ShopData、ShopAssetConfig、ShopSender、ShopHandle。框架会根据类名和 bundle 名自动推断依赖。

UI 开发约定

UI 页面、弹窗、常驻面板应使用 FW.LayerController：

await FW.Entry.layerMgr.openAsync({
  type: ShopLayerController,
  args: { tab: "hot" },
});

LayerController 中：

• 使用 this.find() 查找节点。
• 使用 this.cc() 绑定按钮事件。
• 使用 this.fw() 监听框架事件。
• 使用 this.close() 关闭 Layer。
• 通过 layerAssetProperty 指向 AssetConfig 中的 prefab。

不要在业务代码中绕过 layerMgr 直接 cc.instantiate 业务弹窗。

资源开发约定

资源统一写入 FW.AssetConfig：

preLoad = {
  prefab: {
    ShopLayer: {
      bundle: "shop",
      path: "prefab/ShopLayer",
      type: cc.Prefab,
      priorityLoaded: true,
      autoRelease: true,
    },
  },
};

加载资源时使用：

const prefab = await FW.Entry.resMgr.loadAsset<cc.Prefab>(assetProperty);

不要在业务代码中散落硬编码资源路径，也不要在资源未加载时调用 getAsset()。

事件和异步

框架事件：

FW.Entry.evtMgr.dispatch("SHOP_GOODS_CHANGED", goods);
FW.Entry.evtMgr.register("SHOP_GOODS_CHANGED", this.renderGoods, this);

定时器：

FW.Entry.timeMgr.schedule(this.tick, 1, cc.macro.REPEAT_FOREVER, this);
FW.Entry.timeMgr.unSchedule(this);

异步流程：

const result = await this.invoke(
  FW.Entry.resMgr.loadAssetData(assetProperty),
  "loadAsset",
);

invoke() 会记录性能并统一输出错误。调用方必须处理返回 undefined 的情况。

cocos-mcp 协作

使用 cocos-mcp 做 UI 自动化时：

1. 先用 cocos_mcp_diagnose 检查连接。
2. 用 scene_get_tree 获取真实节点路径。
3. 用 asset_query 或 asset_resolve 确认资源。
4. 用 ui_create_tree 或 ui_create_node 创建 UI。
5. 用 ui_set_sprite_frame 绑定图片。
6. 需要复用时用 prefab_create_from_node 生成 prefab。
7. 运行时事件优先写在 LayerController 中，不强行用编辑器 clickEvents。

MCP 节点路径必须使用绝对路径，例如 /Canvas/ShopLayer/CloseButton。

Codex 使用原则

Codex 在本项目中新增功能时必须遵守：

• 不修改框架内部源码，除非用户明确要求维护框架。
• 优先复用 FW.Entry、FW.FrameworkBase、FW.LayerController。
• UI 功能走 LayerController + prefab + AssetConfig。
• 业务流程放 Logic，业务状态放 Data。
• 网络协议放 Sender/Handle。
• 资源路径集中在 AssetConfig。
• 事件、定时器、Promise、对象池全部使用框架 API。
• CocosCreator组件事件统一使用 FW.Entry.uiMgr.register注册
• 自定义事件统一使用 FW.Entry.evtMgr.register

详细文档

• FRAMEWORK_OVERVIEW.md：框架整体架构。
• FRAMEWORK_USAGE.md：业务使用方式。
• FRAMEWORK_API.md：常用 API 速查。
• FRAMEWORK_PATTERNS.md：新增功能模式和禁止事项。
• FRAMEWORK_EXAMPLES.md：可复制代码示例。
• CODEX_GUIDE.md：Codex 长期开发规范。
• MCP_INTEGRATION.md：cocos-mcp 自动化流程。
• UI_DEVELOPMENT_GUIDE.md：UI 开发规范。
• ERROR_HANDLING.md：错误处理和生命周期清理。