rougelike-demo/client/.github/instructions/development-plan.md

Cocos3.x 项目开发规划

项目概述

本项目是一个 Cocos Creator 3.x 的 3D Roguelike 游戏项目,需要实现网络通信、状态机管理和应用状态流转等核心功能。

📐 开发规范

代码组织规范

1. 模块 README.md: 每个功能模块目录下创建 README.md 文档,详细说明模块的使用方法
2. 不创建 index.ts: 不需要为每个模块创建统一导出的 index.ts 文件,直接导入具体文件
3. 按需导入: 使用时直接从具体文件导入,例如:

   import { NetManager } from './Framework/Net/NetManager';
   import { NetConfig } from './Framework/Net/NetConfig';
   

4. 文档分层管理:
   • 项目级文档放在 .github/instructions 目录
   • 模块级文档放在模块目录的 README.md
5. 模块归属规范:
   • Framework/ 目录用于存放通用框架和工具类(FSM、Net、ResMgr、UI基类等)
   • App/ 目录用于存放应用层业务模块(AppStatus、Login、Game等)
   • 业务UI组件必须归属到 App/ 对应的业务模块下,例如:
     • 登录UI: App/Login/UILogin.ts
     • 游戏UI: App/Game/UIGame.ts

文件命名规范

• 使用 PascalCase 命名 TypeScript 类文件: NetManager.ts, AppStatusBoot.ts
• 配置/常量文件也使用 PascalCase: NetConfig.ts, NetEvent.ts
• 一个文件一个主要类,文件名与类名保持一致

---

📊 项目进度总览

最后更新: 2025-12-14 (Game 模块已完成)

模块	进度	状态	文档
Framework/FSM	100%	✅ 已完成	查看文档
Framework/Net	100%	✅ 已完成	查看文档
Framework/ResMgr	100%	✅ 已完成	查看文档
Framework/UI	100%	✅ 已完成	查看文档
App/AppStatus	100%	✅ 已完成	查看文档
App/Login	100%	✅ 已完成	查看文档
App/Game	100%	✅ 已完成	查看文档
Boot启动组件	100%	✅ 已完成	-

图例: ⬜ 未开始 | 🟡 进行中 | ✅ 已完成 | ⏸️ 已暂停

---

一、目录结构规划

assets/scripts/
├── Framework/           # 框架和通用工具类目录
│   ├── FSM/            # 状态机模块 ✅
│   │   ├── IState.ts
│   │   ├── BaseState.ts
│   │   ├── FSM.ts
│   │   └── README.md   # 详细文档
│   ├── Net/            # 网络通信模块 ✅
│   │   ├── NetManager.ts
│   │   ├── PlatformAdapter.ts
│   │   ├── NetConfig.ts
│   │   ├── NetEvent.ts
│   │   └── README.md   # 详细文档
│   ├── ResMgr/         # 资源管理模块 ✅
│   │   ├── ResMgr.ts
│   │   ├── ResConfig.ts
│   │   └── README.md   # 详细文档
│   └── UI/             # UI基类和管理器 ✅
│       ├── UIBase.ts
│       ├── UIMgr.ts
│       └── README.md   # 详细文档
├── App/                # 应用层代码(业务模块)
│   ├── AppStatus/      # 应用状态机 ✅
│   │   ├── AppStatusManager.ts
│   │   ├── AppStatusBoot.ts
│   │   ├── AppStatusLogin.ts
│   │   ├── AppStatusGame.ts
│   │   └── README.md   # 详细文档
│   ├── Login/          # 登录模块 ✅
│   │   ├── UILogin.ts
│   │   └── README.md   # 详细文档
│   └── Game/           # 游戏模块 (待开发)
│       └── ...
└── Boot/               # 启动组件 ✅
    └── Boot.ts

---

二、模块概览

Framework 模块(框架层)

2.1 状态机模块 (FSM) ✅

• 职责: 通用的有限状态机框架
• 核心类: IState, BaseState, FSM
• 详细文档: Framework/FSM/README.md

2.2 网络通信模块 (Net) ✅

• 职责: 基于 TSRPC 的网络通信层,支持多平台
• 核心类: NetManager, PlatformAdapter, NetConfig, NetEvent
• 详细文档: Framework/Net/README.md

2.3 资源管理模块 (ResMgr) ✅

• 职责: 统一的资源加载管理器
• 核心类: ResMgr, ResConfig
• 详细文档: Framework/ResMgr/README.md

2.4 UI 系统 (UI) ✅

• 职责: UI 管理系统,管理 UI 生命周期
• 核心类: UIBase, UIMgr
• 详细文档: Framework/UI/README.md

App 模块(应用层)

2.5 应用状态机 (AppStatus) ✅

• 职责: 管理应用的整体状态流转
• 核心类: AppStatusManager, AppStatusBoot, AppStatusLogin, AppStatusGame
• 状态流转: Boot → Login → Game
• 详细文档: App/AppStatus/README.md

2.6 登录模块 (Login) ✅

• 职责: 用户登录功能,包括登录界面和业务逻辑
• 核心类: UILogin
• 详细文档: App/Login/README.md

启动组件

2.7 Boot 启动组件 ✅

• 职责: 应用入口点,挂载到场景节点上启动应用
• 文件: Boot/Boot.ts
• 使用: 挂载到 main.scene 的 Boot 节点上

---

三、快速开始

3.1 启动应用

1. 在 Cocos Creator 中打开 main.scene
2. 创建一个空节点,命名为 "Boot"
3. 将 Boot.ts 脚本挂载到 Boot 节点上
4. 运行游戏,应用将自动启动

3.2 状态流转

启动游戏
    ↓
Boot 组件 start()
    ↓
AppStatusManager.start()
    ↓
Boot 状态(初始化网络并连接服务器)
    ↓
Login 状态(显示登录界面)
    ↓
用户登录
    ↓
Game 状态(进入游戏世界)

3.3 核心使用示例

网络通信

import { NetManager } from './Framework/Net/NetManager';
import { serviceProto } from '../Shared/protocols/serviceProto';

const netManager = NetManager.getInstance();
netManager.setServiceProto(serviceProto);
netManager.init({ serverUrl: 'http://localhost:3000' });
await netManager.connect();

// 调用 API
const result = await netManager.callApi('Login', { account: 'player123' });

资源加载

import { ResMgr } from './Framework/ResMgr/ResMgr';
import { Prefab } from 'cc';

const prefab = await ResMgr.getInstance().load('resources', 'prefabs/Player', Prefab);

UI 管理

import { UIMgr } from './Framework/UI/UIMgr';
import { UILogin } from './App/Login/UILogin';

await UIMgr.getInstance().load(UILogin);

---

四、开发指南

4.1 创建新模块

1. 在对应目录下创建模块文件
2. 创建 README.md 文档
3. 在 development-plan.md 中更新进度

4.2 创建新的业务 UI

1. 在 App/ 下创建业务模块目录(如 App/Game/)
2. 创建 UI 类继承 UIBase
3. 实现 onGetUrl() 方法
4. 在 Cocos Creator 中创建对应的预制体

4.3 添加新的应用状态

1. 在 App/AppStatus/ 创建新状态类,继承 BaseState
2. 在 AppStatusManager 中注册新状态
3. 更新状态流转逻辑

---

五、协议同步

5.1 同步服务端协议

npm run sync-shared

5.2 使用协议

import { serviceProto } from '../Shared/protocols/serviceProto';
import { ReqLogin, ResLogin } from '../Shared/protocols/PtlLogin';

netManager.setServiceProto(serviceProto);
const result = await netManager.callApi<ReqLogin, ResLogin>('Login', { ... });

---

六、下一步开发计划

6.1 游戏逻辑模块 (优先级: 高) ✅ 已完成

• 创建 App/Game 目录
• 实现角色控制器 (PlayerController)
• 实现角色移动 (WASD 控制)
• 实现其他玩家显示和同步 (RemotePlayer)
• 实现世界管理器 (World)
• 实现聊天系统 UI

6.2 游戏机制 (优先级: 中)

• 敌人 AI 系统
• 战斗系统
• 地图生成(Roguelike)
• 物品和装备系统

6.3 优化和完善 (优先级: 低)

• 性能优化
• 资源预加载
• 音效和音乐
• 粒子特效

---

七、注意事项

1. 模块文档: 每个模块的详细使用说明请查看对应的 README.md
2. 协议同步: 开发前确保运行 npm run sync-shared 同步最新协议
3. 资源路径: UI 资源路径与代码中的 onGetUrl() 返回值保持一致
4. 状态切换: 使用 AppStatusManager 统一管理所有状态切换
5. 错误处理: 网络请求和资源加载都要做好错误处理

---

八、变更日志

2025-12-14

• ✅ 完成文档重构,将详细文档迁移到模块目录
• ✅ 更新代码组织规范,允许模块目录创建 README.md
• ✅ 创建 Framework 各模块的 README.md
• ✅ 创建 App 各模块的 README.md
• ✅ 精简 development-plan.md,保留概览和索引
• ✅ 完成 Game 模块开发
  • ✅ 实现 World 世界管理器
  • ✅ 实现 PlayerController 本地玩家控制器
  • ✅ 实现 RemotePlayer 远程玩家同步
  • ✅ 实现 UIGame 游戏主界面
  • ✅ 更新 AppStatusGame 状态
  • ✅ 接入网络协议 (MsgPlayerJoin, MsgPlayerMove, PtlMove)
  • ✅ 创建 Game 模块文档