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. **按需导入**: 使用时直接从具体文件导入,例如:
   ```typescript
   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% | ✅ 已完成 | [查看文档](../../assets/scripts/Framework/FSM/README.md) |
| Framework/Net | 100% | ✅ 已完成 | [查看文档](../../assets/scripts/Framework/Net/README.md) |
| Framework/ResMgr | 100% | ✅ 已完成 | [查看文档](../../assets/scripts/Framework/ResMgr/README.md) |
| Framework/UI | 100% | ✅ 已完成 | [查看文档](../../assets/scripts/Framework/UI/README.md) |
| App/AppStatus | 100% | ✅ 已完成 | [查看文档](../../assets/scripts/App/AppStatus/README.md) |
| App/Login | 100% | ✅ 已完成 | [查看文档](../../assets/scripts/App/Login/README.md) |
| App/Game | 100% | ✅ 已完成 | [查看文档](../../assets/scripts/App/Game/README.md) |
| 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](../../assets/scripts/Framework/FSM/README.md)

#### 2.2 网络通信模块 (Net) ✅
- **职责**: 基于 TSRPC 的网络通信层,支持多平台
- **核心类**: NetManager, PlatformAdapter, NetConfig, NetEvent
- **详细文档**: [Framework/Net/README.md](../../assets/scripts/Framework/Net/README.md)

#### 2.3 资源管理模块 (ResMgr) ✅
- **职责**: 统一的资源加载管理器
- **核心类**: ResMgr, ResConfig
- **详细文档**: [Framework/ResMgr/README.md](../../assets/scripts/Framework/ResMgr/README.md)

#### 2.4 UI 系统 (UI) ✅
- **职责**: UI 管理系统,管理 UI 生命周期
- **核心类**: UIBase, UIMgr
- **详细文档**: [Framework/UI/README.md](../../assets/scripts/Framework/UI/README.md)

### App 模块(应用层)

#### 2.5 应用状态机 (AppStatus) ✅
- **职责**: 管理应用的整体状态流转
- **核心类**: AppStatusManager, AppStatusBoot, AppStatusLogin, AppStatusGame
- **状态流转**: Boot → Login → Game
- **详细文档**: [App/AppStatus/README.md](../../assets/scripts/App/AppStatus/README.md)

#### 2.6 登录模块 (Login) ✅
- **职责**: 用户登录功能,包括登录界面和业务逻辑
- **核心类**: UILogin
- **详细文档**: [App/Login/README.md](../../assets/scripts/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 核心使用示例

#### 网络通信

```typescript
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' });
```

#### 资源加载

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

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

#### UI 管理

```typescript
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 同步服务端协议

```bash
npm run sync-shared
```

### 5.2 使用协议

```typescript
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 游戏逻辑模块 (优先级: 高) ✅ 已完成
- [x] 创建 App/Game 目录
- [x] 实现角色控制器 (PlayerController)
- [x] 实现角色移动 (WASD 控制)
- [x] 实现其他玩家显示和同步 (RemotePlayer)
- [x] 实现世界管理器 (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 模块文档