@cavegiant/cave-world-r3f 1.0.0

package/doc/multiplayer-protocol.md

@@ -0,0 +1,757 @@
+# 多人游戏数据同步系统 - 前端接口文档
+
+## 概述
+
+本文档描述了多人游戏数据同步系统的WebSocket API接口，供前端开发者集成使用。系统支持实时多人游戏数据同步，包括位置、旋转、动画状态等。
+
+## 连接信息
+
+- **协议**: WebSocket (WSS)
+- **端点**: 由后端配置的WebSocket API Gateway端点
+- **认证**: 支持JWT认证和匿名访问
+
+## 消息格式
+
+所有消息都采用JSON格式，包含以下字段：
+
+```json
+{
+  "action": "动作名称",
+  "data": {
+    // 具体数据内容
+  }
+}
+```
+
+## 客户端到服务器消息
+
+### 1. 加入游戏
+
+**动作**: `JOIN_GAME`
+
+**描述**: 玩家加入指定应用的游戏
+
+**消息格式**:
+
+```json
+{
+  "action": "JOIN_GAME",
+  "data": {
+    "appId": "your-app-id"
+  }
+}
+```
+
+**参数说明**:
+
+- `appId` (string, 必需): 应用ID
+
+**响应**: 服务器会发送 `JOIN_SUCCESS` 消息
+
+**重复加入处理**:
+
+- 如果玩家已存在，系统会更新连接信息并返回 `isRejoin: true`
+- 如果玩家不存在，系统会创建新玩家并返回 `isRejoin: false`
+
+---
+
+### 2. 更新玩家状态
+
+**动作**: `UPDATE_STATE`
+
+**描述**: 更新玩家的位置、旋转、动画或Avatar状态
+
+**消息格式**:
+
+```json
+{
+  "action": "UPDATE_STATE",
+  "data": {
+    "position": [10.5, 0, -5.2],
+    "rotation": [0, 0.707, 0, 0.707],
+    "animation": "walking",
+    "avatarId": "warrior"
+  }
+}
+```
+
+**参数说明**:
+
+- `position` (array, 可选): 3D位置坐标 `[x, y, z]`
+- `rotation` (array, 可选): 四元数旋转 `[x, y, z, w]`
+- `animation` (string, 可选): 动画名称
+- `avatarId` (string, 可选): 人物ID
+
+**注意**: 可以只更新部分字段，例如只更新位置：
+
+```json
+{
+  "action": "UPDATE_STATE",
+  "data": {
+    "position": [10.5, 0, -5.2]
+  }
+}
+```
+
+或者只更新头像：
+
+```json
+{
+  "action": "UPDATE_STATE",
+  "data": {
+    "avatarId": "mage"
+  }
+}
+```
+
+**响应**: 服务器会向房间内其他玩家广播 `STATE_UPDATE` 消息
+
+---
+
+### 3. 同步房间状态
+
+**动作**: `SYNC_STATE`
+
+**描述**: 请求同步当前房间内所有玩家的状态
+
+**消息格式**:
+
+```json
+{
+  "action": "SYNC_STATE",
+  "data": {}
+}
+```
+
+**响应**: 服务器会发送 `STATE_SYNC` 消息
+
+---
+
+### 4. 心跳检测
+
+**动作**: `PING`
+
+**描述**: 发送心跳以保持连接活跃
+
+**消息格式**:
+
+```json
+{
+  "action": "PING",
+  "data": {}
+}
+```
+
+**响应**: 服务器会发送 `PONG` 消息
+
+### 5. 运维查询
+
+**动作**: `OPS_QUERY`
+
+**描述**: 运维人员查询系统数据
+
+**消息格式**:
+
+```json
+{
+  "action": "OPS_QUERY",
+  "data": {
+    "key": "mb:player:player-123"
+  }
+}
+```
+
+**参数说明**:
+
+- `key` (string, 必需): Redis原生键值
+
+**支持的key格式**:
+
+- `mb:player:{playerId}`: 查询玩家信息
+- `mb:room:{roomId}`: 查询房间信息
+- `mb:connection:{connectionId}`: 查询连接信息
+- `mb:app_rooms:{appId}`: 查询应用房间列表
+- `mb:room_players:{roomId}`: 查询房间玩家列表
+- `health`: 查询系统健康状态
+- 其他: 直接查询Redis键值
+
+**响应**: 服务器会发送 `OPS_RESULT` 或 `OPS_ERROR` 消息
+
+---
+
+## 服务器到客户端消息
+
+### 1. 加入成功
+
+**动作**: `JOIN_SUCCESS`
+
+**描述**: 玩家成功加入游戏房间
+
+**消息格式**:
+
+```json
+{
+  "action": "JOIN_SUCCESS",
+  "data": {
+    "roomId": "room_app_1234567890_1",
+    "playerId": "player-1",
+    "players": [
+      {
+        "id": "player-1",
+        "position": [0, 0, 0],
+        "rotation": [0, 0, 0, 1],
+        "animation": "idle",
+        "avatarId": "default",
+        "lastUpdate": 1234567890
+      }
+    ],
+    "isRejoin": false
+  }
+}
+```
+
+**参数说明**:
+
+- `roomId` (string): 分配的房间ID
+- `playerId` (string): 当前玩家的ID
+- `players` (array): 房间内所有玩家信息
+  - `id` (string): 玩家ID
+  - `position` (array): 位置坐标
+  - `rotation` (array): 旋转四元数
+  - `animation` (string): 当前动画
+  - `avatarId` (string): AvatarID
+  - `lastUpdate` (number): 最后更新时间戳
+- `isRejoin` (boolean): 是否为重新加入（true=重新加入，false=首次加入）
+
+**重要说明**:
+
+- `playerId` 字段用于标识当前玩家自己的ID
+- 客户端可以通过比较 `playerId` 和 `players` 数组中的 `id` 来区分自己和他人
+- 建议将其他玩家添加到游戏场景中，而自己的数据用于初始化或状态同步
+
+---
+
+### 2. 玩家加入
+
+**动作**: `PLAYER_JOINED`
+
+**描述**: 有新玩家加入当前房间
+
+**消息格式**:
+
+```json
+{
+  "action": "PLAYER_JOINED",
+  "data": {
+    "playerId": "player-2",
+    "position": [0, 0, 0],
+    "rotation": [0, 0, 0, 1],
+    "animation": "idle",
+    "avatarId": "default"
+  }
+}
+```
+
+---
+
+### 3. 玩家离开
+
+**动作**: `PLAYER_LEFT`
+
+**描述**: 有玩家离开当前房间
+
+**消息格式**:
+
+```json
+{
+  "action": "PLAYER_LEFT",
+  "data": {
+    "playerId": "player-2"
+  }
+}
+```
+
+---
+
+### 4. 状态更新
+
+**动作**: `STATE_UPDATE`
+
+**描述**: 房间内其他玩家的状态更新
+
+**消息格式**:
+
+```json
+{
+  "action": "STATE_UPDATE",
+  "data": {
+    "playerId": "player-1",
+    "position": [10.5, 0, -5.2],
+    "rotation": [0, 0.707, 0, 0.707],
+    "animation": "walking",
+    "avatarId": "warrior"
+  }
+}
+```
+
+**注意**: 服务器只会发送实际更新的字段
+
+---
+
+### 5. 状态同步
+
+**动作**: `STATE_SYNC`
+
+**描述**: 房间内所有玩家的完整状态信息
+
+**消息格式**:
+
+```json
+{
+  "action": "STATE_SYNC",
+  "data": {
+    "players": [
+      {
+        "id": "player-1",
+        "position": [10.5, 0, -5.2],
+        "rotation": [0, 0.707, 0, 0.707],
+        "animation": "walking",
+        "avatarId": "warrior",
+        "lastUpdate": 1234567890
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 6. 心跳响应
+
+**动作**: `PONG`
+
+**描述**: 服务器对心跳的响应
+
+**消息格式**:
+
+```json
+{
+  "action": "PONG",
+  "data": {
+    "timestamp": 1234567890
+  }
+}
+```
+
+### 6. 运维查询结果
+
+**动作**: `OPS_RESULT`
+
+**描述**: 运维查询成功响应
+
+**消息格式**:
+
+```json
+{
+  "action": "OPS_RESULT",
+  "data": {
+    "key": "mb:player:player-123",
+    "type": "cache",
+    "result": {
+      "id": "player-123",
+      "connectionId": "conn-456",
+      "appId": "app-789",
+      "roomId": "room-101",
+      "position": [0, 0, 0],
+      "rotation": [0, 0, 0, 1],
+      "animation": "idle",
+      "avatarId": "default",
+      "lastUpdate": 1234567890,
+      "isOnline": true,
+      "isAnonymous": false,
+      "createdAt": 1234567890
+    },
+    "timestamp": 1234567890
+  }
+}
+```
+
+**参数说明**:
+
+- `key` (string): 查询的键值
+- `type` (string): 结果类型
+- `result` (object): 查询结果数据
+- `timestamp` (number): 响应时间戳
+
+### 7. 运维查询错误
+
+**动作**: `OPS_ERROR`
+
+**描述**: 运维查询错误响应
+
+**消息格式**:
+
+```json
+{
+  "action": "OPS_ERROR",
+  "data": {
+    "key": "invalid_key",
+    "error": "Query key is required",
+    "code": "WS.0011",
+    "timestamp": 1234567890
+  }
+}
+```
+
+**参数说明**:
+
+- `key` (string): 查询的键值
+- `error` (string): 错误信息
+- `code` (string): 错误代码
+- `timestamp` (number): 响应时间戳
+
+---
+
+## 错误处理
+
+### 错误消息格式
+
+```json
+{
+  "action": "ERROR",
+  "data": {
+    "error_code": "WS.0001",
+    "error_msg": "错误描述"
+  }
+}
+```
+
+### 常见错误代码
+
+| 错误代码  | 描述             | 解决方案                             |
+| --------- | ---------------- | ------------------------------------ |
+| `WS.0001` | 不支持的事件类型 | 检查action字段是否正确               |
+| `WS.0002` | 连接未找到       | 重新建立连接                         |
+| `WS.0003` | 无效的JSON消息   | 检查消息格式                         |
+| `WS.0004` | 缺少消息动作     | 确保包含action字段                   |
+| `WS.0005` | 未知的消息动作   | 使用支持的动作名称                   |
+| `WS.0006` | 缺少应用ID       | 在JOIN_GAME中提供appId               |
+| `WS.0007` | 缺少状态字段     | 在UPDATE_STATE中提供至少一个状态字段 |
+| `WS.0008` | 位置数据格式错误 | 检查position数组格式                 |
+| `WS.0009` | 旋转数据格式错误 | 检查rotation四元数格式               |
+| `WS.0010` | 连接未找到       | 重新建立连接或检查连接状态           |
+| `PM.0010` | AvatarID格式错误 | 检查avatarId字符串格式               |
+
+---
+
+## 前端集成示例
+
+### JavaScript/TypeScript 示例
+
+```javascript
+class GameWebSocket {
+  constructor(wsUrl, appId) {
+    this.wsUrl = wsUrl
+    this.appId = appId
+    this.ws = null
+    this.players = new Map()
+  }
+
+  connect() {
+    this.ws = new WebSocket(this.wsUrl)
+
+    this.ws.onopen = () => {
+      console.log('WebSocket connected')
+      this.joinGame()
+    }
+
+    this.ws.onmessage = (event) => {
+      const message = JSON.parse(event.data)
+      this.handleMessage(message)
+    }
+
+    this.ws.onclose = () => {
+      console.log('WebSocket disconnected')
+      // 实现重连逻辑
+    }
+
+    this.ws.onerror = (error) => {
+      console.error('WebSocket error:', error)
+    }
+  }
+
+  joinGame() {
+    this.send({
+      action: 'JOIN_GAME',
+      data: { appId: this.appId }
+    })
+  }
+
+  updateState(position, rotation, animation, avatarId) {
+    const data = {}
+    if (position) data.position = position
+    if (rotation) data.rotation = rotation
+    if (animation) data.animation = animation
+    if (avatarId) data.avatarId = avatarId
+
+    this.send({
+      action: 'UPDATE_STATE',
+      data: data
+    })
+  }
+
+  // 运维查询方法
+  queryOps(key) {
+    this.send({
+      action: 'OPS_QUERY',
+      data: {
+        key: key
+      }
+    })
+  }
+
+  sendPing() {
+    this.send({
+      action: 'PING',
+      data: {}
+    })
+  }
+
+  send(message) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(message))
+    }
+  }
+
+  handleMessage(message) {
+    switch (message.action) {
+      case 'JOIN_SUCCESS':
+        this.handleJoinSuccess(message.data)
+        break
+      case 'PLAYER_JOINED':
+        this.handlePlayerJoined(message.data)
+        break
+      case 'PLAYER_LEFT':
+        this.handlePlayerLeft(message.data)
+        break
+      case 'STATE_UPDATE':
+        this.handleStateUpdate(message.data)
+        break
+      case 'STATE_SYNC':
+        this.handleStateSync(message.data)
+        break
+      case 'PONG':
+        this.handlePong(message.data)
+        break
+      case 'OPS_RESULT':
+        this.handleOpsResult(message.data)
+        break
+      case 'OPS_ERROR':
+        this.handleOpsError(message.data)
+        break
+      case 'ERROR':
+        this.handleError(message.data)
+        break
+    }
+  }
+
+  handleJoinSuccess(data) {
+    console.log('Joined room:', data.roomId)
+    console.log('My player ID:', data.playerId)
+
+    // 分离自己和他人数据
+    const otherPlayers = data.players.filter((player) => player.id !== data.playerId)
+    const myPlayer = data.players.find((player) => player.id === data.playerId)
+
+    // 添加其他玩家到游戏场景
+    otherPlayers.forEach((player) => {
+      this.players.set(player.id, player)
+    })
+
+    // 处理自己的玩家数据（如果需要）
+    if (myPlayer) {
+      console.log('My player data:', myPlayer)
+      // 可以在这里设置自己的初始状态或进行其他处理
+    }
+  }
+
+  handlePlayerJoined(data) {
+    console.log('Player joined:', data.playerId)
+    this.players.set(data.playerId, data)
+  }
+
+  handlePlayerLeft(data) {
+    console.log('Player left:', data.playerId)
+    this.players.delete(data.playerId)
+  }
+
+  handleStateUpdate(data) {
+    const player = this.players.get(data.playerId)
+    if (player) {
+      if (data.position) player.position = data.position
+      if (data.rotation) player.rotation = data.rotation
+      if (data.animation) player.animation = data.animation
+      if (data.avatarId) player.avatarId = data.avatarId
+      player.lastUpdate = Date.now()
+    }
+  }
+
+  handleStateSync(data) {
+    data.players.forEach((player) => {
+      this.players.set(player.id, player)
+    })
+  }
+
+  handlePong(data) {
+    console.log('Pong received:', data.timestamp)
+  }
+
+  handleError(data) {
+    console.error('Server error:', data.error_code, data.error_msg)
+  }
+}
+
+// 使用示例
+const gameWs = new GameWebSocket('wss://your-websocket-endpoint', 'your-app-id')
+gameWs.connect()
+
+// 定期发送心跳
+setInterval(() => {
+  gameWs.sendPing()
+}, 30000)
+
+// 更新玩家状态
+gameWs.updateState([10, 0, 5], [0, 0, 0, 1], 'walking', 'warrior')
+
+// 只更新头像
+gameWs.updateState(null, null, null, 'mage')
+
+// 运维查询示例
+gameWs.queryOps('mb:player:player-123')
+gameWs.queryOps('mb:room:room-456')
+gameWs.queryOps('mb:app_rooms:app-789')
+gameWs.queryOps('health')
+gameWs.queryOps('stats')
+```
+
+// 处理运维查询响应
+handleOpsResult(data) {
+console.log('Ops query result:', data);
+console.log('Key:', data.key);
+console.log('Type:', data.type);
+console.log('Result:', data.result);
+}
+
+handleOpsError(data) {
+console.error('Ops query error:', data);
+console.error('Key:', data.key);
+console.error('Error:', data.error);
+console.error('Code:', data.code);
+}
+
+```
+
+---
+
+## 最佳实践
+
+### 1. 连接管理
+- 实现自动重连机制
+- 处理网络中断和恢复
+- 设置合理的连接超时时间
+- 处理连接状态变化（连接、断开、重连）
+- 实现连接状态监控和错误恢复
+
+### 2. 状态同步
+- 使用节流机制避免过于频繁的状态更新
+- 实现状态插值和平滑过渡
+- 处理网络延迟和丢包情况
+
+### 3. 错误处理
+- 实现完整的错误处理机制
+- 提供用户友好的错误提示
+- 记录错误日志用于调试
+
+### 4. 性能优化
+- 只发送必要的状态更新
+- 使用批量更新减少网络请求
+- 实现客户端预测和回滚机制
+
+### 5. 数据清理和生命周期管理
+- 服务器会自动清理断开连接的数据
+- 支持只连接但不加入房间的场景
+- 实现优雅的连接断开处理
+- 避免数据泄漏和内存浪费
+
+---
+
+## 连接生命周期
+
+### 连接建立
+1. **WebSocket连接**: 客户端建立WebSocket连接
+2. **身份验证**: 系统验证JWT token（如果提供）或生成匿名ID
+3. **连接记录**: 系统记录连接信息，包括playerId和连接状态
+
+### 游戏加入
+1. **发送JOIN_GAME**: 客户端发送加入游戏消息
+2. **房间分配**: 系统分配或创建房间
+3. **玩家创建**: 系统创建玩家数据并关联到房间
+4. **状态同步**: 系统返回房间内所有玩家状态
+
+### 游戏进行
+1. **状态更新**: 客户端发送UPDATE_STATE消息
+2. **数据同步**: 服务器广播状态更新给其他玩家
+3. **心跳检测**: 定期发送PING/PONG保持连接活跃
+
+### 连接断开
+1. **断开检测**: 系统检测到连接断开
+2. **数据清理**:
+   - 如果玩家已加入房间：清理玩家数据、从房间移除、通知其他玩家
+   - 如果只连接未加入：只清理连接数据
+3. **资源释放**: 释放相关缓存和内存资源
+
+### 重连处理
+1. **连接恢复**: 客户端重新建立连接
+2. **身份识别**: 系统识别玩家身份（通过JWT或匿名ID）
+3. **状态恢复**: 如果玩家之前已加入房间，恢复游戏状态
+4. **无缝体验**: 提供平滑的重连体验
+
+---
+
+## 数据格式说明
+
+### 位置坐标
+- 格式: `[x, y, z]`
+- 类型: 数字数组
+- 范围: -1000 到 1000
+
+### 旋转四元数
+- 格式: `[x, y, z, w]`
+- 类型: 数字数组
+- 要求: 单位四元数（x² + y² + z² + w² = 1）
+
+### 动画名称
+- 格式: 字符串
+- 长度: 最大50个字符
+- 示例: "idle", "walking", "running", "jumping"
+
+### 头像ID
+- 格式: 字符串
+- 长度: 最大50个字符
+- 示例: "default", "warrior", "mage", "archer", "healer"
+- 说明: 由前端系统预定义的头像类型，用户可以选择
+
+---
+
+## 版本信息
+
+- **API版本**: 1.2.0
+- **最后更新**: 2024年12月
+- **兼容性**: 支持现代浏览器WebSocket API
+- **更新内容**:
+  - 添加头像ID同步支持
+  - 优化连接生命周期管理
+  - 改进数据清理机制
+  - 增强错误处理
+  - 支持只连接不加入房间的场景
+```