多人游戏(WebRTC 点对点)
同一已部署域名上的所有访客会自动加入一个默认房间,并直接与每个其他访客建立原生 WebRTC 数据通道——游戏流量本身永远不会触及服务器。/api/rtc 上的微型中继仅处理连接握手(SDP/ICE)的路由,而对等方进行连接。您从工具包中使用的内容仅限客户端;中继是您的。
延迟为浏览器↔浏览器(通常 5–40 毫秒),且无每次刻度的服务器成本。
| 组件 | 路径 |
|---|---|
| 网格原语(从这里开始) | P2PRoom(来自 @/lib/multiplayer) |
| React 房间绑定(可选,您创建) | src/lib/multiplayer/use-p2p-room.ts |
| 信令中继(您创建) | src/lib/multiplayer/signaling.server.ts |
| HTTP 挂载(您创建) | src/routes/api/rtc.ts |
信任模型——在选择 P2P 前请阅读。 没有服务器权威:每个对等方运行自己的一套规则,并且可能撒谎(位置、分数等任何信息)。对等方还会在 ICE 过程中得知彼此的 IP 地址。P2P 适用于共同选择一起游戏的人之间的合作和休闲游戏——绝不适用于竞技排名、易作弊场景或匿名陌生人匹配。此模板不支持竞技或易作弊游戏:请在产品层面予以拒绝,而不是通过 P2P 提供。
实际限制:全网格是 O(N²) 连接——房间容量限制在约 8 个对等方。大约 10–20% 的对等方对方处于严格的 NAT 后面无法连接;工具包针对每个对等方将其显示为 connectionState: "failed"——请在 UI 中显示此状态而非让其挂起。
设置(一次性)
创建两个服务器文件——没有它们将无法工作:
src/lib/multiplayer/signaling.server.ts——基于数据库的信令中继(部署时使用 Neon,预览时使用 PGLite)。src/routes/api/rtc.ts——将其挂载到/api/rtc(GET 轮询,POST 信令/离开)。
两者均从 references/signaling-relay.md 复制,其中还包含了模式说明:中继在首次使用时自行创建两个表(CREATE TABLE IF NOT EXISTS),因此除非您有意要拥有该模式,否则不要在 migrations/ 中放置任何内容。
使用原语
P2PRoom 与框架无关,“房间”只是一个 rendezvous 键——大厅代码、一对一的通话 ID、共享文档 ID 等任意字符串(≤64 个字符)。任何架构都基于以下三个相同的调用:
import { P2PRoom } from "@/lib/multiplayer";
const p2p = new P2PRoom({
room: "doc-42",
selfId: myId,
name: "ani",
onPeersChanged: (peers) => render(peers),
onMessage: (from, data, channel) => apply(from, data, channel),
});
await p2p.join();
p2p.broadcast(state); // 不可靠的“状态”通道——游戏速率,陈旧数据丢弃
p2p.send(event, to); // 可靠通道——恰好一次事件(to 可选)
p2p.close();
对于“此应用上的所有人都一起玩”的常见 React 形式,请从 references/react-binding.md 复制 useP2PRoom 钩子(以及一个经过实际使用的组件:游戏速率广播循环约 20 发送/秒,可靠的一次性事件)。
模式:
broadcast()= 不可靠/无序,用于持续刷新的状态(位置、光标)。send()= 可靠/有序,用于必须恰好到达一次的事件。绝不要将游戏速率的状态流式传输到send()上;在广播之间进行插值以实现平滑运动。- 后期加入者一无所知:当
p2p.peers中出现新对等方时,现有对等方应send()当前共享状态。必须恰好有一个对等方响应:比较已经在房间中的对等方(您的selfId加上p2p.peers减去新加入者)的 ID,并且仅当您的selfId是最小时才响应——这样两个同时加入者既不会重复响应也不会得不到响应。 - 房间 ID:省略时表示“此应用上的所有人都一起玩”;传递
room: code用于私人大厅(生成短代码,放入 URL 中)。 - 对等方无故消失(标签页关闭、休眠):将
p2p.peers中缺失的对等方视为已离开,并丢弃其实体。 - 一个在首次渲染时捕获
room/name的 React 绑定(如references/react-binding.md中所示)需要重新挂载才能更改它们——请将组件键设为房间代码。
诊断
p2p.peers 中的每个条目都携带 connectionState、rttMs(数据通道 ping)和 candidateType(host/srflx = 直接)。要覆盖 STUN,请将 VITE_STUN_URLS(逗号分隔)添加到 .grok/app-env.json,然后重新启动开发服务器(Vite 在启动时读取环境变量;HMR 不会捕获更改)——在此沙箱中切勿编写 .env 文件。