星火 2.0 开发文档

主题

随进随出模式与开放局 ​

系统文档：docs/systems/DropInOpenGameSystem.md。

开放局加入 API：docs/systems/OpenGameJoinSystem.md。

先判断用户在处理哪一层 ​

  • 大厅自动把玩家加入已有游戏局：检查随进随出模式、模式 key、房间最大人数和“大厅进入时创建全新的游戏局”。
  • 好友或队员主动进入某个具体游戏局：使用 OpenGameRef 和 LobbyService.LeaveAndJoinOpenGame。
  • 切局前保存 CloudData 或停止旧局继续写用户状态：联用 user-session-handoff。
  • 在不同游戏局之间分发邀请：联用 ServerChannel，并由项目自行实现权限、好友或队伍协议。

硬规则 ​

  • 把地图真人玩家槽位视为游戏局硬上限。
  • 把后台房间最大人数视为大厅自动匹配容量，不要写成开放局绝对人数上限。
  • 后台有有效正数房间最大人数时必须使用该值；只有缺少有效值时才由 Host 以地图真人玩家槽位兜底。
  • 同一游戏中规则不兼容的大厅模式必须使用不同、稳定且非空的模式 key。
  • 相同模式 key 会共享大厅自动匹配池；不同 key 隔离。模式显示名不能替代模式 key。
  • 服务端用 Game.LobbyModeKey 读取创作者中心传入的大厅模式 key；它是平台入口元数据，不是数编的 Game.GameModeLink。前者可能为空，后者用于选择项目内 GameDataGameMode 数据；两者不能互相替代。
  • 平台不会替项目判断新客户端/服务器逻辑与旧开放局是否兼容；不要假设客户端版本、AppBundle 版本或服务器版本会自动隔离匹配池。发布版本时由项目方判断：兼容则保留原 key，不兼容则使用新的稳定 key；不要因每次例行发布而机械修改 key。
  • 更换模式 key 只影响大厅自动匹配，不会迁移或关闭旧开放局；OpenGameRef 定向加入会绕过模式 key 分池。如果项目不允许跨版本定向加入，必须在自己的引用分发或邀请逻辑中做版本检查。
  • 如果兼容性测试难以充分实施，优先建议新版本使用新的模式 key，可在 key 中带上协议或内容版本标识；暂时无法匹配旧开放局通常比匹配后运行错误更安全。兼容性确认后再评估是否恢复共用原 key。
  • “大厅进入时创建全新的游戏局”为“否”时先找未达到自动匹配容量的旧局；为“是”时每次都新建开放局。
  • 随进随出模式不会为了凑齐“匹配开局人数”而等待，通常将该值设为 1。
  • LeaveAndJoinOpenGame 按 MapName + JoinKey 定向加入，不使用后台自动匹配容量筛选，但仍受地图真人玩家槽位限制。
  • LeaveAndJoinOpenGame 返回 true 只表示切局请求已被接受并排队，不表示最终加入成功。
  • LobbyService.QuitCurrentGame()、服务端 Player.Disconnect() 和 Player.Kick(...) 都是明确离开路径；框架会在离开流程中清理开放局占位和地图真人玩家槽位。
  • 普通网络断线会保留重连名额，当前通常约 30 秒后才释放；未完成连接的预约通常约 5 分钟后过期释放。不要把暂时离线立即当作空槽位。
  • LeaveAndJoinOpenGame 会由框架清理源局并在目标局实际加入成功后占用目标槽位；项目不要根据 API 返回值手工增减房间人数。
  • OpenGameRef 是短期引用；目标局结束、JoinKey 失效或槽位耗尽都可能导致加入失败。
  • 框架不负责把 OpenGameRef 分发给其他玩家，也不自动提供好友、队伍、邀请和权限系统。

配置工作流 ​

  1. 确认地图真人玩家槽位能够覆盖游戏局可能达到的实际人数。
  2. 在创作者中心的 运营配置 → 游戏基础配置 → 游戏大厅配置 中选择“随进随出”。
  3. 为每个玩法模式填写独立、稳定的模式 key。
  4. 发布新版本时先判断其与旧开放局的协议、逻辑、数据和资源是否兼容：兼容则沿用 key，不兼容则为新版本使用新的 key 隔离大厅自动匹配池。
  5. 把房间最大人数设置为希望大厅自动放入同一局的人数。
  6. 随进随出模式的匹配开局人数通常设为 1。
  7. 选择大厅进入时先找旧局还是总是新建局。
  8. 如果还需要好友或队伍定向加入，再设计 OpenGameRef 的项目内分发链路，并自行处理跨版本兼容性。
  9. 如果玩家从旧局切走时涉及云数据，接入 UserSessionHandoff 停止旧局后续写入。

区分大厅模式与数编游戏模式 ​

当项目需要按创作者中心的后台入口执行不同规则时，在服务端读取 Game.LobbyModeKey：

csharp
#if SERVER
if (Game.LobbyModeKey == "co-op")
{
    // 使用后台 co-op 大厅入口对应的规则。
}
#endif

Game.GameModeLink 仍用于读取项目数编的 GameDataGameMode 配置。调试局或未通过大厅入口创建的游戏局可能没有 LobbyModeKey，应按空字符串处理。

常用设计 ​

多个自动匹配模式 ​

例如同一地图有双人和三人模式：

  • 地图至少提供 3 个真人玩家槽位。
  • 双人模式使用独立模式 key，房间最大人数设为 2。
  • 三人模式使用另一个模式 key，房间最大人数设为 3。
  • 不要让两个模式只靠不同显示名区分。

平时单人，组队进入同一开放局 ​

例如地图有 100 个真人玩家槽位：

  1. 后台随进随出模式的房间最大人数设为 1。
  2. 匹配开局人数设为 1。
  3. 需要明确一人一世界时，将“大厅进入时创建全新的游戏局”设为“是”。
  4. 队长调用 TryGetCurrentOpenGameRef 并通过项目逻辑分享引用。
  5. 队员调用 LeaveAndJoinOpenGame 定向加入队长局。

此时后台的 1 只限制大厅自动匹配；定向加入可让队长局超过 1 人，直至 100 个地图真人玩家槽位耗尽。

排查顺序 ​

第二个大厅玩家没有进入旧局 ​

  • 确认模式类型为“随进随出”。
  • 确认两次进入使用同一游戏、运行环境和模式 key。
  • 确认“大厅进入时创建全新的游戏局”为“否”。
  • 确认旧局当前人数低于后台房间最大人数。
  • 确认旧局仍在运行并持续同步人数。

新客户端是否会进入旧版本开放局 ​

  • 不要假设平台会按客户端、AppBundle 或服务器版本自动隔离开放局；先由项目判断新旧逻辑、协议、数据和资源是否兼容。
  • 兼容时可以保留原模式 key，让大厅继续使用同一个匹配池。
  • 不兼容时应为新版本改用新的稳定模式 key；这只影响后续大厅自动匹配，旧 key 下的运行中开放局不会自动迁移或关闭。
  • 如果难以完成充分兼容性测试，采用带版本标识的新 key 作为保守默认策略；不要为了维持匹配率而让未经验证的新版本进入旧池。
  • 如果玩家通过 OpenGameRef 定向加入，模式 key 不会再次参与筛选；需要由项目自己的邀请/队伍逻辑阻止不兼容的跨版本加入。

已找到目标开放局但最终没有进入 ​

  • 区分“大厅自动找到房间”和“客户端完成加载进入”两个阶段。
  • 检查目标局是否结束、JoinKey 是否有效、地图是否还有真人玩家槽位。
  • 检查客户端项目代码和发布产物是否成功启动；不要把脚本初始化失败误判为匹配失败。
  • 如果从另一个游戏局切换，检查 UserSessionHandoff 清理是否异常或超时。

玩家离开后房间人数或槽位没有立即下降 ​

  • 确认使用的是 QuitCurrentGame、Player.Disconnect、Player.Kick 或放弃重连等明确离开路径。
  • 如果只是网络断线、客户端崩溃或进程被杀，先等待当前重连窗口；开放局通常会保留约 30 秒。
  • 如果玩家尚未完成连接，检查是否仍在约 5 分钟的进入预约保护期内。
  • 在线踢人会先发送踢出通知，随后才断开并清理；不要把通知发出时刻当成槽位已经释放。
  • 查询结果存在短暂异步传播延迟；项目不要自行修改房间人数，必要时结合服务端玩家事件和最终加入结果判断。

相关文档 ​

  • 后台配置和人数模型：docs/systems/DropInOpenGameSystem.md
  • OpenGameRef 与加入代码：docs/systems/OpenGameJoinSystem.md
  • 切局前旧局清理：docs/systems/UserSessionHandoffSystem.md
  • 跨游戏局邀请消息：docs/systems/ServerChannelSystem.md
  • 重连、主动退出和重新加入的区别：docs/systems/PlayerSessionStateSemantics.md