---
name: ineed-realtime
description: 为 Web 或 Godot 游戏选择实时联机方式、接入双人信令 SDK，并生成平台聊天交接说明；不适用于 AI 故事回合联机。
---
# 实时联机

先确认创作者选择随机匹配 random、公开联机大厅 lobby、非公开邀请 invite 的一种或多种。用户只要随机匹配时，不添加大厅和邀请入口。第一版仅双人，断线暂停后退出；其他人数/重连规则保持待办，不冒充已支持。

匿名可打开游戏，仅联网动作按需登录。先协商 `hello` 和 `multiplayer.*` 能力；没有能力时明确不可用并保留单人玩法。平台按作品开启服务；配置尚未回显或未通过线上预览时，不能声明已接入。

Web 适配器 `client.mjs` 负责平台信令；Godot 插件位于 `godot/`，通过 WebRTCMultiplayerPeer 复用游戏 RPC。Godot Web 不使用原生 ENet UDP。TURN 永久密钥只在平台；游戏只获取短时凭据。角色 RPC 等待 MultiplayerAPI 的连接完成事件，不能在底层 peer_connected 的过早阶段调用未知玩家编号。

匹配/入房成功不等于角色同步和对局开局成功。测试重复点击、取消、超时、刷新、账号切换、跨作品/版本隔离、双端动作、退出后停止；测试驱动不代替真实键盘/触屏验收。不同上传包默认隔离，build 不同拒绝连接。

交给平台聊天的已确认配置示例（替换实际选择和版本）：

```json
{"realtime":{"modes":["random"],"maxPlayers":2,"build":"my-game-v1","disconnect":"pause_then_exit"}}
```

同时带上引擎、人数、开局/结算、权威规则和是否需要平台排行/奖励。P2P 对局不是服务端反作弊或付款证明；支付、广告奖励等仍由平台服务端确认。完整信息收集、可复制说明与上传后的动作见 [本地到平台聊天](../../../guides/integration/handoff-workflow.md)。

最短接入步骤、Godot 示例与平台/创作者分工见 [SDK 使用说明](README.md)。

## 同一账号切换设备

随机匹配时，若账号已在其他页面或设备匹配/对战，平台宿主询问是否顶替。确认后结束旧联机，当前设备重新匹配；取消保留旧联机。旧对手收到断开，按游戏既有断线流程退出或重新匹配，不自动判负、发奖或接管旧对局。创作者只调用原匹配接口并处理 disconnected，无需实现顶号弹窗、登录互踢或信令协议。

弹窗等待中禁用重复匹配；关闭/取消不显示连接成功。保留失败原因，不能把取消、已有会话、浏览器不支持都改成同一个报错。旧平台若只返回 ALREADY_IN_ROOM，提示退出原页面后重试，不绕过校验。联机用户昵称只用于展示，身份以平台账号为准。

交接说明补一行：“同账号换设备采用平台确认顶替；旧对手按断线规则处理；已测等待中/对战中顶替、取消及重新匹配”。只把实际完成的测试写成已测；审核与正式版本的匹配池保持隔离。