多人連線(WebRTC 點對點)
所有訪問同一部署網域的訪客會自動加入一個預設房間,並與每個其他訪客建立原生的 WebRTC 資料通道——遊戲流量完全不會觸及伺服器。一個微小的中繼服務位於 /api/rtc,僅處理連線握手(SDP/ICE)的路由,讓對等點之間直接連線。您從此工具包中使用的部分是客戶端專屬的;中繼服務歸您所有。
延遲是瀏覽器↔瀏覽器(通常 5–40 毫秒),且無任何每 tick 的伺服器成本。
| 元件 | 路徑 |
|---|---|
| 網狀原始物件(從這裡開始) | 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 不依賴任何框架,「房間」只是一個會合鍵——可以是大廳代碼、一對一通話 ID、共用文件 ID、任何字串(≤64 個字元)。任何架構都可以建立在以下三個相同的 API 呼叫之上:
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); // 不可靠的 "state" 通道——遊戲頻率的廣播,舊資料會被捨棄
p2p.send(event, to); // 可靠通道——確保一次傳送的事件(to 參數為選用)
p2p.close();
對於 React 中常見的「此應用程式中所有人都一起玩」的情境,請從 references/react-binding.md 複製 useP2PRoom hook(以及一個完整的組件範例:約 20 次/秒的遊戲頻率廣播循環,以及可靠的一次性事件)。
模式:
broadcast()= 不可靠/無序,用於持續更新的狀態(位置、游標)。send()= 可靠/有序,用於必須剛好送達一次的事件。切勿在send()上串流遊戲頻率的狀態;應透過在廣播之間插值來實現平滑移動。- 後加入者一無所知:當一個新對等點出現在
p2p.peers中時,應有一個既有對等點使用send()向其傳送當前的共享狀態。必須剛好有一個對等點回應:比較已在房間中的對等點 ID(您的selfId加上p2p.peers減去新加入者),並僅在您的selfId最小時才回應——這樣兩個同時加入者既不會重複回應也不會無人回應。 - 房間 ID:若要讓「此應用程式中所有人都一起玩」則省略;若要建立私人房間,則傳入
room: code(產生一個短代碼,放入 URL 中)。 - 對等點可能在未告別的情況下消失(分頁關閉、睡眠):將從
p2p.peers中消失的對等點視為已離開,並將其對應的實體刪除。 - 一個在首次渲染時捕獲
room/name的 React 綁定(例如references/react-binding.md中的那個)需要重新掛載才能變更它們——請將組件以房間代碼進行 key 綁定。
診斷
p2p.peers 中的每個條目都帶有 connectionState、rttMs(資料通道 ping)和 candidateType(host/srflx = 直接連線)。若要覆蓋 STUN 伺服器,請在 .grok/app-env.json 中加入 VITE_STUN_URLS(逗號分隔),然後重新啟動開發伺服器(Vite 在啟動時讀取環境變數;HMR 不會重新載入)——請勿在此沙盒中撰寫.env 檔案。