game/.trae/documents/Nakama 服务端集成规划.md

Nakama 服务端集成规划 (修订版：4人自动匹配)

根据您的补充需求（4人自动匹配、无需手动管理房间），我调整了规划如下。我们将继续基于“动物扫雷大作战”项目进行开发。

1. 核心流程：自动匹配 (Auto-Matchmaking)

我们将完全屏蔽“房间”概念，采用类似《王者荣耀》或《英雄联盟》的匹配机制：

1. 点击“开始游戏”: 客户端调用 Nakama Matchmaker API，参数设定为 min_count=4, max_count=4。
2. 服务端排队: Nakama 自动将请求的玩家放入匹配池。
3. 匹配成功: 当凑齐 4 人后，服务端自动创建一个权威比赛 (Authoritative Match)。
4. 自动入场: 客户端收到匹配成功通知 (Match Found)，携带 Token 自动加入比赛，进入游戏画面。

2. 系统架构与实施

第一阶段：基础设施 (不变)

• 动作: 配置 Docker (Nakama + CockroachDB)。
• 动作: 前端安装 nakama-js。

第二阶段：服务端逻辑 (TypeScript)

• Match Handler (比赛控制器):
  • 硬性限制: 仅当凑齐 4 人时游戏逻辑才正式开始（或等待超时添加 AI，目前先按纯真人规划）。
  • 回合制逻辑: 维护 4 人行动顺序（如：P1 -> P2 -> P3 -> P4 -> P1...）。
  • 状态同步: 广播 100 个格子的状态、4 名玩家的血量/道具/Buff。

第三阶段：前端改造 (针对 4 人匹配)

• UI 调整:
  • 主界面增加“开始匹配 (4人)”大按钮。
  • 增加“匹配中...”的等待状态提示。
  • 游戏内固定显示 4 个玩家的头像槽位（如 App.tsx 中已有的布局，需确保能动态映射 P1-P4）。
• 逻辑对接:
  • Socket 监听: 监听 onmatchmakermatched 事件 -> 自动执行 joinMatch。
  • 游戏开始: 收到服务端 OP_GAME_START 信号后，解锁棋盘交互。

3. 下一步执行计划

1. 环境搭建: 启动 Nakama 服务端。
2. 前端集成: 实现“点击匹配 -> 等待 -> 自动进入游戏”的完整链路。
3. 逻辑迁移: 将现有的 Mock 数据替换为服务端数据。

请确认是否开始执行环境搭建？