开发进度文档

2025-12-14 22:37:49 +08:00
parent 4f5b2d02ea
commit 7bd2c74e3d
5 changed files with 2356 additions and 0 deletions
--- a/client/.creator/asset-template/typescript/Custom
+++ b/client/.creator/asset-template/typescript/Custom
@@ -0,0 +1,2 @@
+[InternetShortcut]
+URL=https://docs.cocos.com/creator/manual/en/scripting/setup.html#custom-script-template
--- a/client/.github/instructions/AppStatus-Guide.md
+++ b/client/.github/instructions/AppStatus-Guide.md
@@ -0,0 +1,351 @@
+# AppStatus 应用状态机使用指南
+
+## 📚 概述
+
+AppStatus 是基于 FSM 状态机实现的应用级状态管理系统,负责管理整个游戏的状态流转。
+
+**简化后的流程**: Boot(连接) → Login(登录) → Game(游戏世界)
+
+## 🏗️ 项目结构
+
+```
+assets/scripts/
+├── Boot/
+│   └── Boot.ts                    # 启动组件(挂载到场景)
+├── App/
+│   └── AppStatus/
+│       ├── AppStatusBoot.ts       # 启动状态(连接服务器)
+│       ├── AppStatusLogin.ts      # 登录状态(调用Login API)
+│       ├── AppStatusGame.ts       # 游戏状态(监听广播)
+│       └── AppStatusManager.ts    # 状态管理器
+├── Framework/
+│   ├── FSM/                       # 状态机框架
+│   └── Net/                       # 网络通信框架
+└── Shared/
+    └── protocols/                 # TSRPC协议定义
+```
+
+## 🚀 快速开始
+
+### 1. 在场景中使用
+
+1. 打开 Cocos Creator
+2. 打开主场景 `assets/scenes/main.scene`
+3. 创建一个空节点,命名为 "Boot"
+4. 将 `assets/scripts/Boot/Boot.ts` 拖拽到 Boot 节点上
+5. 运行游戏
+
+### 2. 状态流转
+
+应用启动后会自动按以下顺序流转:
+
+```
+Boot(启动) → Login(登录) → Game(游戏世界)
+     ↑           ↓              ↓
+     └───────────────────────────┘
+          (退出/死亡返回登录)
+
+## 📋 各状态详解
+
+### Boot 启动状态
+
+**触发时机**: 应用启动时
+**主要工作**:
+- 初始化网络管理器
+- 连接服务器
+
+**完成后**: 自动切换到 Login 状态
+
+### Login 登录状态
+
+**触发时机**: Boot 状态完成后
+**主要工作**:
+- 显示登录界面
+- 等待用户输入玩家ID
+- 调用 Login API 登录
+
+**如何触发登录**:
+```typescript
+// 在登录UI中调用
+const loginState = AppStatusManager.getInstance()
+    .getCurrentState() as AppStatusLogin;
+await loginState.login("player123", "玩家昵称");
+```
+
+**协议**: 
+- API: `Login`
+- 请求: `{ playerId: string, playerName?: string }`
+- 响应: `{ success: boolean, player: PlayerInfo, isNewPlayer: boolean }`
+
+**完成后**: 登录成功后直接进入 Game 状态
+
+### Game 游戏状态
+
+**触发时机**: 登录成功后
+**主要工作**:
+- 接收登录返回的玩家信息(PlayerInfo)
+- 加载游戏场景
+- 创建玩家角色
+- 监听服务器广播消息
+- 运行游戏主循环
+
+**监听的服务器广播**:
+```typescript
+// PlayerJoin - 其他玩家加入
+NetManager.getInstance().listenMsg("PlayerJoin", (msg) => {
+    console.log(`${msg.playerName} 加入了游戏`);
+    // 在场景中创建其他玩家
+});
+
+// PlayerMove - 其他玩家移动
+NetManager.getInstance().listenMsg("PlayerMove", (msg) => {
+    console.log(`${msg.playerName} 移动到 (${msg.position.x}, ${msg.position.y})`);
+    // 更新其他玩家位置
+});
+
+// Chat - 聊天消息
+NetManager.getInstance().listenMsg("Chat", (msg) => {
+    console.log(`${msg.playerName}: ${msg.content}`);
+    // 显示聊天内容
+});
+```
+
+**可用操作**:
+```typescript
+const gameState = AppStatusManager.getInstance()
+    .getCurrentState() as AppStatusGame;
+
+// 移动(调用Move API)
+await NetManager.getInstance().callApi("Move", { x: 10, y: 5 });
+
+// 发送聊天(调用Send API)
+await NetManager.getInstance().callApi("Send", { content: "Hello!" });
+
+// 暂停/恢复游戏
+gameState.pauseGame();
+gameState.resumeGame();
+
+// 玩家死亡
+gameState.onPlayerDeath();
+
+// 退出游戏(返回登录)
+gameState.quitGame();
+```
+
+## 🎮 AppStatusManager API
+
+### 获取管理器实例
+
+```typescript
+import { AppStatusManager } from './App/AppStatus/AppStatusManager';
+
+const appManager = AppStatusManager.getInstance();
+```
+
+### 主要方法
+
+#### start()
+启动应用,从 Boot 状态开始
+
+```typescript
+appManager.start();
+```
+
+#### changeState(stateName, params?)
+手动切换状态
+
+```typescript
+// 切换到登录状态
+appManager.changeState("Login");
+
+// 切换到大厅状态并传递用户信息
+appManager.changeState("Lobby", { 
+    userInfo: { userId: "123", username: "玩家" }
+});
+
+// 切换到游戏状态
+appManager.changeState("Game", { 
+    roomId: "room123",
+    userInfo: currentUser 
+});
+```
+
+#### getCurrentStateName()
+获取当前状态名称
+
+```typescript
+const stateName = appManager.getCurrentStateName();
+console.log(`当前状态: ${stateName}`); // 输出: "Login"
+```
+
+#### getCurrentState()
+获取当前状态实例
+
+```typescript
+const currentState = appManager.getCurrentState();
+if (currentState) {
+    console.log(`当前状态: ${currentState.name}`);
+}
+```
+
+#### update(dt)
+更新状态机(在游戏主循环中调用)
+
+```typescript
+// Boot.ts 中已自动处理
+update(deltaTime: number) {
+    this._appStatusManager.update(deltaTime);
+}
+```
+
+## 🔧 扩展新状态
+
+如果需要添加新的应用状态:
+
+### 1. 创建状态类
+
+```typescript
+import { BaseState } from "../../Framework/FSM/BaseState";
+
+export class AppStatusNewState extends BaseState {
+    constructor(fsm: any) {
+        super(fsm, "NewState");
+    }
+    
+    onEnter(params?: any): void {
+        super.onEnter(params);
+        // 进入状态的逻辑
+    }
+    
+    onExit(): void {
+        super.onExit();
+        // 退出状态的逻辑
+    }
+}
+```
+
+### 2. 在 AppStatusManager 中注册
+
+```typescript
+// AppStatusManager.ts
+import { AppStatusNewState } from "./AppStatusNewState";
+
+private initStates(): void {
+    // ... 其他状态
+    this._fsm.addState(new AppStatusNewState(this._fsm));
+}
+```
+
+### 3. 从其他状态切换
+
+```typescript
+this._fsm.changeState("NewState", { /* 参数 */ });
+```
+
+## 💡 最佳实践
+
+### 1. 状态间传递数据
+
+使用 `changeState` 的第二个参数传递数据:
+
+```typescript
+// 传递数据
+this._fsm.changeState("Lobby", { 
+    userInfo: { userId: "123", username: "玩家" }
+});
+
+// 接收数据
+onEnter(params?: any): void {
+    if (params && params.userInfo) {
+        this._userInfo = params.userInfo;
+    }
+}
+```
+
+### 2. 保持状态独立
+
+每个状态应该是独立的,不要在状态间共享可变数据,而是通过参数传递。
+
+### 3. 异步操作处理
+
+在状态的 `onEnter` 中处理异步操作:
+
+```typescript
+async onEnter(params?: any): Promise<void> {
+    super.onEnter(params);
+    
+    try {
+        await this.loadSomething();
+        this._fsm.changeState("NextState");
+    } catch (error) {
+        console.error("加载失败:", error);
+        // 处理错误
+    }
+}
+```
+
+### 4. 状态清理
+
+始终在 `onExit` 中清理资源:
+
+```typescript
+onExit(): void {
+    super.onExit();
+    // 清理UI
+    // 取消网络监听
+    // 释放资源
+}
+```
+
+## 🐛 调试技巧
+
+### 1. 查看状态流转日志
+
+所有状态切换都会在控制台输出日志:
+
+```
+[FSM] 进入状态: Boot
+[AppStatusBoot] 开始初始化应用...
+[FSM] 退出状态: Boot
+[FSM] 进入状态: Loading
+```
+
+### 2. 查看当前状态
+
+```typescript
+console.log("当前状态:", AppStatusManager.getInstance().getCurrentStateName());
+```
+
+### 3. 直接切换到指定状态(测试用)
+
+```typescript
+// 跳过登录直接进入大厅
+AppStatusManager.getInstance().changeState("Lobby", { 
+    userInfo: { userId: "test", username: "测试用户" }
+});
+```
+
+## 📝 TODO 清单
+
+当前 AppStatus 模块已完成基础框架,但以下功能需要后续实现:
+
+- [ ] 集成 UI 管理器
+- [ ] 实现实际的服务器连接
+- [ ] 实现资源预加载
+- [ ] 实现房间系统
+- [ ] 实现匹配系统
+- [ ] 实现游戏场景加载
+- [ ] 添加状态转换动画
+- [ ] 添加错误处理和重试机制
+
+## 🎯 下一步
+
+1. 实现 UI 系统
+2. 创建登录界面
+3. 连接服务器
+4. 实现房间和匹配功能
+5. 开发游戏主逻辑
+
+---
+
+更新时间: 2025-12-14
--- a/client/.github/instructions/development-plan.md
+++ b/client/.github/instructions/development-plan.md
--- a/client/.github/instructions/net-module-summary.md
+++ b/client/.github/instructions/net-module-summary.md
@@ -0,0 +1,155 @@
+# 网络模块开发完成总结
+
+## ✅ 已完成内容
+
+### 📁 目录结构
+```
+assets/scripts/Framework/Net/
+├── NetConfig.ts          # 网络配置接口
+├── NetEvent.ts           # 网络事件定义
+├── PlatformAdapter.ts    # 平台适配器
+├── NetManager.ts         # 网络管理器(核心)
+├── index.ts              # 模块导出
+├── NetExample.ts         # 使用示例
+└── README.md             # 快速入门文档
+
+项目根目录:
+├── sync-shared.js        # 协议同步脚本
+├── SYNC-SHARED.md        # 同步说明文档
+└── package.json          # 添加依赖和脚本
+```
+
+### 🎯 核心功能
+
+#### 1. NetManager - 网络管理器
+- ✅ 单例模式设计
+- ✅ 自动平台检测和适配
+- ✅ 连接管理(连接/断开)
+- ✅ 自动重连机制
+- ✅ API 调用支持
+- ✅ 消息监听和发送
+- ✅ 事件系统
+- ✅ 完善的错误处理
+
+#### 2. PlatformAdapter - 平台适配
+- ✅ 自动检测当前平台
+- ✅ 浏览器平台使用 `tsrpc-browser`
+- ✅ 小程序平台使用 `tsrpc-miniapp`
+- ✅ 统一的客户端接口
+
+#### 3. 协议同步机制
+- ✅ Node.js 同步脚本
+- ✅ 自动复制服务端 shared 目录
+- ✅ npm 脚本命令支持
+- ✅ 详细的使用文档
+
+### 📦 依赖包安装
+- ✅ `tsrpc-browser: ^3.4.15`
+- ✅ `tsrpc-miniapp: ^3.4.15`
+- ✅ `fs-extra: ^11.2.0` (devDependencies)
+
+## 🎓 使用指南
+
+### 快速开始
+
+1. **安装依赖**
+   ```bash
+   npm install
+   ```
+
+2. **同步协议** (需要服务端存在)
+   ```bash
+   npm run sync-shared
+   ```
+
+3. **使用网络管理器**
+   ```typescript
+   import { NetManager, NetConfig } from './Framework/Net';
+   
+   const netManager = NetManager.getInstance();
+   netManager.init({ serverUrl: 'http://localhost:3000' });
+   await netManager.connect();
+   ```
+
+### 文档资源
+- 📖 [快速入门](assets/scripts/Framework/Net/README.md)
+- 📖 [协议同步说明](SYNC-SHARED.md)
+- 📖 [开发规划](.github/instructions/development-plan.md)
+- 💡 [使用示例](assets/scripts/Framework/Net/NetExample.ts)
+
+## 🔄 下一步工作
+
+### 待完成任务
+
+1. **服务端对接**
+   - ⬜ 确保服务端 shared 目录存在
+   - ⬜ 运行 `npm run sync-shared` 同步协议
+   - ⬜ 在 PlatformAdapter 中导入实际协议定义
+
+2. **状态机模块** (阶段一剩余)
+   - ⬜ 创建 Framework/FSM 目录
+   - ⬜ 实现 IState.ts
+   - ⬜ 实现 BaseState.ts
+   - ⬜ 实现 FSM.ts
+
+3. **应用状态机** (阶段二)
+   - ⬜ 创建 App/AppStatus 目录
+   - ⬜ 实现各个应用状态
+   - ⬜ 集成网络模块到应用状态
+
+## 🎉 成果展示
+
+### 代码质量
+- ✅ TypeScript 严格类型检查
+- ✅ 完整的 JSDoc 注释
+- ✅ 单一职责原则
+- ✅ 依赖注入和控制反转
+- ✅ 事件驱动架构
+
+### 可维护性
+- ✅ 模块化设计
+- ✅ 清晰的接口定义
+- ✅ 详细的文档说明
+- ✅ 完整的使用示例
+- ✅ 友好的错误提示
+
+### 跨平台支持
+- ✅ 浏览器 Web 平台
+- ✅ 微信小游戏
+- ✅ 字节跳动小游戏
+- ✅ QQ 小游戏
+- ✅ 自动平台检测
+
+## 📊 代码统计
+
+| 文件 | 行数 | 功能 |
+|------|------|------|
+| NetManager.ts | ~300 | 网络管理核心逻辑 |
+| PlatformAdapter.ts | ~130 | 平台适配逻辑 |
+| NetConfig.ts | ~30 | 配置定义 |
+| NetEvent.ts | ~25 | 事件定义 |
+| NetExample.ts | ~80 | 使用示例 |
+| sync-shared.js | ~100 | 同步脚本 |
+| **总计** | **~665** | **6 个核心文件** |
+
+## 💡 技术亮点
+
+1. **自动平台适配**: 无需手动判断平台,自动加载对应的 TSRPC 客户端
+2. **智能重连**: 支持自动重连,可配置重连次数和间隔
+3. **事件驱动**: 基于事件系统,解耦网络状态和业务逻辑
+4. **类型安全**: 完整的 TypeScript 类型定义,编译时检查
+5. **开发友好**: 详细的日志输出,快速定位问题
+
+## 🎯 项目进度
+
+- ✅ 阶段一 - 网络模块: **100% 完成**
+- ⬜ 阶段一 - 状态机模块: **0% 完成**
+- ⬜ 阶段二 - 应用状态: **0% 完成**
+- ⬜ 阶段三 - UI 系统: **0% 完成**
+- ⬜ 阶段四 - 游戏逻辑: **0% 完成**
+
+---
+
+**开发时间**: 2025-12-14  
+**模块版本**: 1.0.0  
+**状态**: ✅ 已完成并可用
--- a/client/.github/instructions/workspace.instructions.md
+++ b/client/.github/instructions/workspace.instructions.md
@@ -0,0 +1,4 @@
+---
+applyTo: '**'
+---
+这是cocos3.x的3d项目，请使用中文回答。