# Game 模块

## 概述

Game 模块是游戏的核心业务模块,负责管理游戏世界、玩家控制、网络同步等功能。该模块基于玩家输入发送给服务器,服务器广播给所有玩家的在线游戏开发思路,确保帧间同步。

## 目录结构

```
App/Game/
├── World.ts              # 世界管理器,管理所有玩家
├── PlayerController.ts   # 本地玩家控制器,处理输入和移动
├── RemotePlayer.ts       # 远程玩家类,处理其他玩家的显示和同步
├── UIGame.ts            # 游戏主界面UI
└── README.md            # 本文档
```

## 核心类说明

### 1. World (世界管理器)

**职责:**
- 管理游戏世界中的所有玩家(本地玩家 + 远程玩家)
- 加载玩家模型预制体
- 监听网络消息(MsgPlayerJoin、MsgPlayerMove)
- 创建和销毁玩家对象

**主要方法:**
- `init(worldRoot, localPlayer)`: 初始化世界,传入世界根节点和本地玩家信息
- `destroy()`: 销毁世界,清理所有资源
- `getLocalPlayerController()`: 获取本地玩家控制器

**使用示例:**
```typescript
import { World } from './App/Game/World';
import { PlayerInfo } from './Shared/protocols/PtlLogin';

const worldRoot = this.node; // 世界根节点
const playerInfo: PlayerInfo = { ... }; // 登录返回的玩家信息

await World.getInstance().init(worldRoot, playerInfo);
```

### 2. PlayerController (本地玩家控制器)

**职责:**
- 监听键盘输入(WASD)
- 控制本地玩家移动
- 控制角色动画(待机、移动)
- 向服务器发送移动请求(PtlMove)

**主要特性:**
- **WASD 移动控制**: W(前)、S(后)、A(左)、D(右)
- **自动朝向**: 角色会自动面向移动方向
- **动画切换**: 移动时播放 move 动画,静止时播放 idle 动画
- **阈值同步**: 移动距离超过 0.5 单位时才向服务器发送移动请求,减少网络负担

**主要方法:**
- `init(playerInfo)`: 初始化玩家控制器
- `getPlayerInfo()`: 获取玩家信息

**内部实现:**
```typescript
// 键盘输入 → 计算移动方向 → 更新本地位置 → 检查阈值 → 发送网络请求
```

### 3. RemotePlayer (远程玩家)

**职责:**
- 显示其他玩家的角色模型
- 接收服务器广播的移动消息
- 平滑移动到目标位置(使用 Tween 补间)
- 控制远程玩家的动画

**主要特性:**
- **平滑移动**: 使用 Tween 让远程玩家平滑移动到目标位置
- **自动朝向**: 根据移动方向自动旋转角色
- **动画同步**: 移动时播放 move 动画,到达目标后播放 idle 动画

**主要方法:**
- `init(playerNode, playerId, playerName, position)`: 初始化远程玩家
- `updatePosition(position)`: 更新远程玩家位置(收到 MsgPlayerMove 时调用)
- `destroy()`: 销毁远程玩家

### 4. UIGame (游戏主界面)

**职责:**
- 游戏主界面 UI 组件
- 提供世界根节点(用于创建玩家)
- 继承自 Framework/UI/UIBase

**主要方法:**
- `onGetUrl()`: 返回 UI 预制体路径 `res://UI/UIGame`
- `getWorldRoot()`: 获取世界根节点

## 协议使用

### 1. 登录返回数据 (ResLogin)

登录成功后,服务器返回玩家信息,包含:
- `player`: 玩家详细信息(id、name、position 等)
- `isNewPlayer`: 是否新玩家

该数据在进入 Game 状态时传递给 World 和 PlayerController。

### 2. 移动请求 (PtlMove)

**请求 (ReqMove):**
```typescript
{
    x: number,  // 目标 X 坐标
    y: number   // 目标 Y 坐标(对应 3D 中的 Z 轴)
}
```

**响应 (ResMove):**
```typescript
{
    success: boolean,
    message?: string,
    position?: Position  // 服务器可能修正的位置
}
```

### 3. 玩家加入广播 (MsgPlayerJoin)

当有新玩家登录或加入游戏时,服务器广播给所有在线玩家:
```typescript
{
    playerId: string,
    playerName: string,
    position: Position,
    isNewPlayer: boolean,
    timestamp: number
}
```

### 4. 玩家移动广播 (MsgPlayerMove)

当有玩家移动时,服务器广播给所有在线玩家:
```typescript
{
    playerId: string,
    playerName: string,
    position: Position,
    timestamp: number
}
```

## 工作流程

### 初始化流程

```
登录成功 (ResLogin)
    ↓
进入 AppStatusGame 状态
    ↓
加载 UIGame 界面
    ↓
初始化 World
    ↓
加载玩家模型预制体 (res://Actor/M1/M1)
    ↓
注册网络监听 (MsgPlayerJoin, MsgPlayerMove)
    ↓
创建本地玩家 (PlayerController)
    ↓
游戏开始
```

### 本地玩家移动流程

```
按下 WASD 键
    ↓
PlayerController 计算移动方向
    ↓
更新本地节点位置
    ↓
播放 move 动画
    ↓
检查移动距离是否超过阈值 (0.5)
    ↓
发送 PtlMove 请求到服务器
    ↓
服务器返回确认
    ↓
(可选)使用服务器修正的位置
```

### 远程玩家同步流程

```
服务器广播 MsgPlayerMove
    ↓
World 接收消息
    ↓
查找对应的 RemotePlayer
    ↓
RemotePlayer.updatePosition()
    ↓
计算移动方向和距离
    ↓
启动 Tween 补间动画
    ↓
播放 move 动画
    ↓
平滑移动到目标位置
    ↓
到达后播放 idle 动画
```

## 角色模型和动画

### 模型路径
- 预制体路径: `res://Actor/M1/M1`
- 使用 ResMgr 加载

### RoleController 脚本

模型下挂载了 `RoleController` 脚本,可以控制角色动画:
- `PlayAnimation(action, loop)`: 播放指定动画
  - `action`: "idle"(待机) | "move"(移动) | "attack"(攻击) | "death"(死亡)
  - `loop`: 是否循环播放

**使用示例:**
```typescript
const roleController = playerNode.getComponentInChildren(RoleController);
roleController.PlayAnimation('move', true);  // 播放移动动画并循环
roleController.PlayAnimation('idle', true);  // 播放待机动画并循环
```

## 输入控制

### 键盘映射
- **W**: 向前移动(世界坐标 -Z 方向)
- **S**: 向后移动(世界坐标 +Z 方向)
- **A**: 向左移动(世界坐标 -X 方向)
- **D**: 向右移动(世界坐标 +X 方向)

### 移动特性
- **多方向合成**: 可以同时按多个方向键,移动方向会自动合成并归一化
- **移动速度**: 默认 5 单位/秒
- **自动朝向**: 角色会自动旋转面向移动方向

## 网络同步策略

### 本地玩家
- **客户端预测**: 立即更新本地位置,无需等待服务器确认
- **阈值同步**: 移动距离超过 0.5 单位时才发送网络请求,减少网络流量
- **服务器修正**: 如果服务器返回修正后的位置,使用服务器位置

### 远程玩家
- **延迟补偿**: 使用 Tween 补间动画平滑移动到目标位置
- **基于速度的时间**: 根据距离和移动速度计算补间时间,确保移动看起来自然

## 常见问题

### 1. 如何修改移动速度?

在 `PlayerController.ts` 中修改:
```typescript
private moveSpeed: number = 5;  // 修改为你想要的速度
```

### 2. 如何修改网络同步阈值?

在 `PlayerController.ts` 中修改:
```typescript
private moveSendThreshold: number = 0.5;  // 修改为你想要的阈值
```

### 3. 如何添加更多动画?

在 RoleController 中添加对应的动画剪辑,然后在 PlayerController 或 RemotePlayer 中调用:
```typescript
this.roleController.PlayAnimation('attack', false);  // 播放攻击动画,不循环
```

### 4. 如何处理玩家离线?

目前未实现玩家离线处理,可以添加 `MsgPlayerLeave` 消息监听:
```typescript
netManager.listenMsg('PlayerLeave', (msg) => {
    const remotePlayer = this.remotePlayers.get(msg.playerId);
    if (remotePlayer) {
        remotePlayer.destroy();
        this.remotePlayers.delete(msg.playerId);
    }
});
```

## 待实现功能

- [ ] 玩家名称显示
- [ ] 玩家血条显示
- [ ] 玩家离线处理
- [ ] 战斗系统
- [ ] 技能系统
- [ ] 物品拾取
- [ ] 聊天系统 UI
- [ ] 小地图

## 注意事项

1. **坐标系转换**: Cocos 3D 使用 (x, y, z),服务器协议使用 (x, y),需要注意:
   - 服务器的 y 对应 Cocos 的 z
   - Cocos 的 y 是高度,固定为 0

2. **网络消息监听**: 所有网络消息监听在 World 中注册,退出时需要取消监听

3. **资源释放**: 退出游戏时需要调用 `World.clear()` 清理所有资源

4. **单例模式**: World 使用单例模式,确保全局只有一个实例

5. **UI 预制体**: 需要在 Cocos Creator 中创建 `res://UI/UIGame` 预制体,并添加 `worldRoot` 节点

## 相关文档

- [Framework/FSM 模块文档](../../Framework/FSM/README.md)
- [Framework/Net 模块文档](../../Framework/Net/README.md)
- [Framework/ResMgr 模块文档](../../Framework/ResMgr/README.md)
- [Framework/UI 模块文档](../../Framework/UI/README.md)
- [App/AppStatus 模块文档](../AppStatus/README.md)