Tap制造踩坑实录：persistent_world 常驻服多玩家冷启动分裂，以及我们被 RestartGuard 逼出来的无奈解法

引擎：TapTap Maker（UrhoX WebGL）
模式：多人游戏 + 常驻服（persistent_world）+ 自定义大厅（lobby_runtime）
日期：2026-10-11

一、问题是什么

玩家冷启动 → 引擎 QUICK_QUERY_MIDDLE_ROOM → 找到中厅 → JOIN → 连服 → 开局

玩家A 冷启动 → QUICK_QUERY 失败（中厅还没建好）→ 建房 #111
玩家B 冷启动 → QUICK_QUERY 失败（中厅还没建好）→ 建房 #222
→ A 在 #111，B 在 #222，谁也看不到谁

二、我们怎么定位的

2.1 服务端选举：谁该退房？

• 每个孤房里的玩家，每 2 秒把自己的 uid 写到服务端的 serverCloud 键里（lone_claim）
• 服务端每 1 秒聚合所有孤房的声明，找出 uid 最小的那个（它是"锚点房"，应该留守）
• 其他所有 uid 更大的玩家，通过 lobby_state 广播收到一个 E=1（eject）标记
• 收到 E=1 的客户端执行退房，试图回流到锚点房

2.2 问题出在：退房之后呢？

ReturnToLobby 是主动离开语义。引擎设计上就不会自动重连、不会自动查房，只恢复大厅 UI 等玩家手动操作。

冷启动会自动查房，是因为它走的是 persistent_world 的连接流程；ReturnToLobby 走的是"主动返回"，两条路径的引擎契约本就不同。

三、我们试过的所有方法（全部失败）

方法 1：服务端下发锚点 roomId，客户端回流后 JoinRoom

方法 2：RequestRestartGame（薄壳加载时立即发）

方法 3：PersistentApp 壳延迟 5s 再发

方法 4：薄壳里延迟 10s 再发

方法 5：游戏脚本相位连发 ReturnToLobby + RequestRestartGame

lua
SendEvent("ReturnToLobby", VariantMap())       -- 先退房
SendEvent("RequestRestartGame", VariantMap())  -- 紧接着重启

方法 6：给个"开始游戏"按钮，让玩家手动点了再进中厅

客户端连接流程（Lobby 自动处理，游戏脚本无需关心）：
Lobby 加载 → 发现 persistent_world 已启用 → 查询可加入的房间 → 找到就加入/没找到就建房 → 连服

• 冷启动时引擎自动查房连服，薄壳代码里 grep 不到任何 QUICK_QUERY 相关字符串——全是引擎内部行为
• ReturnToLobby 回大厅后引擎不自动查房（设计如此），但薄壳里也没有"手动触发查房"的 API
• client:StartMatch 是普通房间匹配，在 persistent_world 模式下走的不是中厅查房（实测 GetRoomList 永远返回空，中厅不在普通房间列表里）

四、被堵死之后的无奈解法

最终方案：强制弹窗，红色按钮退出游戏

• 红色标题："大厅环境异常"
• 白色提示："请退出游戏后重新进入"
• 一个红色按钮："退出游戏" → 点击调 engine:Exit()

判据

lua
-- onLobbyState 收到 (R, S, G, E, A) 时
if R == 1 and E == 1 then
    -- 自己在孤房，且被服务端标记为 eject 方（大 uid）
    -- 弹强制退出弹窗
    ShowSplitAlert()
end

• E=1（大 uid，被 eject）→ 弹窗
• E=2（小 uid，锚点留守）→ 正常待着，不弹窗

五、踩坑总结（给后来者）

1. TapTap Maker 的 persistent_world 模式假设"中厅只有一个、且由服务端管理"。如果出现客户端同时冷启动各自建房的分裂，客户端层几乎没有干净的解法。
2. RequestRestartGame 不是你想发就能发的——RestartGuard 在 C++ 内部，文档零命中，我们试了所有相位全被拦。只有 i18n 那种"对局中切语言"的场景能成功。
3. ReturnToLobby 是主动离开语义，引擎不自动重连不自动查房——别指望退房后引擎帮你重新匹配。
4. GetRoomList 返回的是普通房间，不含 persistent_world 中厅。别想着客户端自己找中厅。
5. 中厅连接是 Lobby 自动跑的，Lua 拦不住也触发不了——没有"手动触发查房"的 API，给不了玩家一个"点了才进中厅"的按钮。
6. 最后能用的，就是让玩家手动退出重进。丑，但可靠。。。。。。

六、还没解决的问题

• RestartGuard 到底在什么条件下放行？冷却窗口多长？文档里完全没有，只能靠真机逐相位试。
• 如果线上真的同时来了 100 个玩家，小 uid 那个建房后，其他 99 个人都要弹"请退出重进"——体验很糟，但这是目前客户端能做的极限。
• 真正的解法应该在服务端：冷启动建房时加全局锁，或者由服务端主动创建中厅而不是让客户端建。但我们管不到服务端。