whale-town/.kiro/specs/multi-client-sync-fix/requirements.md

需求文档

简介

本文档规定了修复 AI Town 游戏中多客户端同步问题的需求。目前，当多个 Web 客户端同时连接时，存在严重的同步问题：新角色的外观无法正确显示，新创建的角色看不到已存在的角色，角色之间无法相互交流。

术语表

• 客户端（Client）: 运行游戏的 Web 浏览器实例
• 角色（Character）: 游戏世界中由玩家控制的实体
• 服务器（Server）: 管理游戏状态的 WebSocket 服务器
• 世界状态（World State）: 游戏中所有角色及其属性的完整状态
• 角色外观（Character Appearance）: 视觉属性，包括身体颜色、头部颜色和精灵信息
• 角色状态消息（Character State Message）: 包含角色信息的网络消息，包括 ID、名称、位置、在线状态和外观数据
• 世界状态消息（World State Message）: 包含所有角色及其状态的完整列表的网络消息
• 广播（Broadcast）: 向除发送者外的所有已连接客户端发送消息

需求

需求 1

用户故事： 作为玩家，我希望在其他角色加入游戏时看到他们的正确外观，以便我可以在视觉上区分不同的玩家。

验收标准

1. WHEN 创建新角色时 THEN 服务器 SHALL 向所有已连接的客户端广播包含外观数据的完整角色状态
2. WHEN 客户端接收到角色状态消息时 THEN 客户端 SHALL 提取外观数据并应用到角色精灵上
3. WHEN 角色在世界中生成时 THEN 客户端 SHALL 使用外观数据中的正确身体颜色和头部颜色渲染角色
4. WHEN 角色状态消息中缺少外观数据时 THEN 客户端 SHALL 使用默认外观值
5. WHILE 角色在世界中可见时 THEN 客户端 SHALL 始终保持角色的外观属性一致

需求 2

用户故事： 作为加入游戏的新玩家，我希望看到世界中所有现有的角色，以便我可以与已经在线的其他玩家互动。

验收标准

1. WHEN 客户端成功认证时 THEN 服务器 SHALL 发送包含所有在线角色的世界状态消息
2. WHEN 客户端接收到世界状态消息时 THEN 客户端 SHALL 生成或更新消息中列出的所有角色
3. WHEN 从世界状态生成角色时 THEN 客户端 SHALL 包含完整的角色数据（包括外观）
4. WHEN 角色已在本地存在时 THEN 客户端 SHALL 更新现有角色而不是创建重复角色
5. WHILE 处理世界状态时 THEN 客户端 SHALL 从远程角色生成中排除玩家自己的角色

需求 3

用户故事： 作为玩家，我希望向其他玩家发送消息并接收他们的消息，以便我可以在游戏世界中进行交流和互动。

验收标准

1. WHEN 玩家发送对话消息时 THEN 服务器 SHALL 向所有已连接的客户端广播该消息
2. WHEN 客户端接收到对话消息时 THEN 客户端 SHALL 在适当的 UI 元素中显示该消息
3. WHEN 显示对话消息时 THEN 客户端 SHALL 显示发送者的角色名称
4. WHEN 消息发送给特定角色时 THEN 服务器 SHALL 仅将消息传递给该角色的客户端
5. WHILE 对话系统处于活动状态时 THEN 客户端 SHALL 为每个对话维护消息历史记录

需求 4

用户故事： 作为开发者，我希望服务器在所有状态消息中包含完整的角色数据，以便客户端拥有正确渲染角色所需的所有信息。

验收标准

1. WHEN 创建角色状态消息时 THEN 服务器 SHALL 包含 id、name、position、isOnline 和 appearance 字段
2. WHEN 广播角色状态时 THEN 服务器 SHALL 序列化完整的角色对象（包括嵌套的外观数据）
3. WHEN 角色外观发生变化时 THEN 服务器 SHALL 向所有客户端广播更新的外观
4. WHEN 从磁盘加载角色时 THEN 服务器 SHALL 保留所有外观数据
5. WHILE 维护角色状态时 THEN 服务器 SHALL 确保外观数据在保存和加载操作中的完整性

需求 5

用户故事： 作为玩家，我希望角色同步在多个客户端之间可靠工作，以便所有玩家的游戏状态保持一致。

验收标准

1. WHEN 角色移动时 THEN 服务器 SHALL 向所有其他客户端广播位置更新
2. WHEN 角色上线时 THEN 服务器 SHALL 向所有客户端广播在线状态
3. WHEN 角色下线时 THEN 服务器 SHALL 向所有客户端广播离线状态
4. WHEN 接收到角色状态更新时 THEN 客户端 SHALL 仅将更新应用于远程角色而不是玩家自己的角色
5. WHILE 多个客户端连接时 THEN 服务器 SHALL 在所有客户端之间维护一致的状态

需求 6

用户故事： 作为开发者，我希望所有新的同步功能与现有系统逻辑完美融合，以便系统保持稳定且不引入新的错误。

验收标准

1. WHEN 实现新的同步逻辑时 THEN 系统 SHALL 保持与现有网络管理器的兼容性
2. WHEN 修改角色状态广播时 THEN 系统 SHALL 保持与现有 MessageProtocol 的消息格式一致性
3. WHEN 更新世界管理器时 THEN 系统 SHALL 保持与现有角色生成和移除逻辑的兼容性
4. WHEN 处理角色外观数据时 THEN 系统 SHALL 保持与现有 CharacterData 和 CharacterController 的数据结构一致性
5. WHEN 添加新的消息处理逻辑时 THEN 系统 SHALL 不破坏现有的安全验证、速率限制和错误处理机制
6. WHEN 修改客户端同步逻辑时 THEN 系统 SHALL 保持与现有游戏状态管理器的状态转换逻辑一致性
7. WHILE 实现多客户端同步时 THEN 系统 SHALL 确保不与现有的单客户端功能（如玩家移动、对话系统）产生冲突