Multiplayer (WebRTC Peer-to-Peer)
Alle Besucher derselben bereitgestellten Domain treten einem Standard-Raum bei und öffnen einen natives WebRTC-Datenkanal direkt zu jedem anderen Besucher – der Spielverkehr selbst berührt niemals einen Server. Ein winziger Relay unter /api/rtc kümmert sich nur um das Routing des Verbindungs-Handshakes (SDP/ICE), während die Peers eine Verbindung herstellen. Was Sie aus dem Kit verwenden, ist clientseitig; der Relay gehört Ihnen.
Die Latenz ist Browser↔Browser (oft 5–40 ms) mit null Serverkosten pro Tick.
| Stück | Pfad |
|---|---|
| Mesh-Primitiv (hier beginnen) | P2PRoom von @/lib/multiplayer |
| React-Raum-Bindung (optional, von Ihnen erstellt) | src/lib/multiplayer/use-p2p-room.ts |
| Signalisierungs-Relay (von Ihnen erstellt) | src/lib/multiplayer/signaling.server.ts |
| HTTP-Mount (von Ihnen erstellt) | src/routes/api/rtc.ts |
Vertrauensmodell – vor der Wahl von P2P lesen. Es gibt keine Server-Autorität: Jeder Peer führt seine eigene Kopie der Regeln aus und kann lügen (Position, Punktzahl, alles). Peers erfahren auch gegenseitig ihre IP-Adressen während ICE. P2P ist für Kooperation und lockeres Spielen unter Leuten, die sich zum gemeinsamen Spielen entscheiden – niemals für wettbewerbsorientierte Ranglisten, cheat-empfindliche oder anonyme Fremdenvermittlung. Wettbewerbsorientiertes oder cheat-empfindliches Spielen wird in dieser Vorlage nicht unterstützt: Lehnen Sie es produktseitig ab, anstatt es auf P2P auszuliefern.
Praktische Grenzen: Ein Full Mesh ist O(N²)-Verbindungen – begrenzen Sie Räume auf ~8 Peers. Etwa 10–20 % der Peer-Paare sitzen hinter strikten NATs und können keine Verbindung herstellen; das Kit zeigt dies pro Peer als connectionState: "failed" an – zeigen Sie es in der UI an, anstatt es hängen zu lassen.
Einrichtung (einmalig)
Erstellen Sie die beiden Serverdateien – ohne sie funktioniert nichts:
src/lib/multiplayer/signaling.server.ts– der datenbankgestützte Signalisierungs-Relay (Neon deployed, PGLite in der Vorschau).src/routes/api/rtc.ts– mountet es unter/api/rtc(GET Poll, POST signal/leave).
Kopieren Sie beide aus references/signaling-relay.md, das auch den Schema-Hinweis enthält: Der Relay erstellt seine eigenen beiden Tabellen bei der ersten Verwendung (CREATE TABLE IF NOT EXISTS), also geht nichts in migrations/, es sei denn, Sie möchten das Schema bewusst selbst verwalten.
Das Primitiv verwenden
P2PRoom ist frameworkfrei, und ein „Raum" ist nur ein Rendezvous-Schlüssel – ein Lobby-Code, eine 1:1-Anruf-ID, eine gemeinsame Dokumenten-ID, eine beliebige Zeichenfolge (≤64 Zeichen). Jede Architektur sitzt auf denselben drei Aufrufen:
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); // unzuverlässiger "state"-Kanal – Spielrate, veraltete Pakete werden verworfen
p2p.send(event, to); // zuverlässiger Kanal – Exactly-Once-Ereignisse (to optional)
p2p.close();
Für die übliche Form „Alle in dieser App spielen zusammen" in React kopieren Sie den useP2PRoom-Hook (plus eine ausgearbeitete Komponente: Spielraten-Broadcast-Schleife mit ~20 Sendungen/s, zuverlässige One-Shot-Ereignisse) aus references/react-binding.md.
Muster:
broadcast()= unzuverlässig/ungeordnet, für kontinuierlich aktualisierten Zustand (Positionen, Cursor).send()= zuverlässig/geordnet, für Ereignisse, die genau einmal eintreffen müssen. Streamen Sie niemals spielraten Zustand übersend(); interpolieren Sie zwischen Broadcasts für flüssige Bewegung.- Späte Beitritte wissen nichts: Wenn ein neuer Peer in
p2p.peerserscheint, sollte ein vorhandener Peer ihm den aktuellen gemeinsamen Zustand persend()senden. Genau ein Peer muss antworten: Vergleichen Sie IDs unter den Peers, die BEREITS im Raum waren (IhreselfIdplusp2p.peersminus den Neuankömmling) und antworten Sie nur, wenn IhreselfIddie kleinste ist – so antworten zwei gleichzeitige Beitritte weder doppelt noch bleiben sie unbeantwortet. - Raum-IDs: Lassen Sie sie weg für „Alle in dieser App spielen zusammen"; übergeben Sie
room: codefür private Lobbys (generieren Sie einen kurzen Code, setzen Sie ihn in die URL). - Peers verschwinden ohne Verabschiedung (Tab-Schließen, Schlafmodus): Behandeln Sie einen Peer, der in
p2p.peersfehlt, als verschwunden und entfernen Sie seine Entitäten. - Eine React-Bindung, die
room/namebeim ersten Rendern erfasst (wie die inreferences/react-binding.md), benötigt ein erneutes Mounten, um sie zu ändern – keyen Sie die Komponente auf den Raum-Code.
Diagnose
Jeder Eintrag in p2p.peers enthält connectionState, rttMs (Datenkanal-Ping) und candidateType (host/srflx = direkt). Um STUN zu überschreiben, fügen Sie VITE_STUN_URLS (kommasepariert) zu .grok/app-env.json hinzu und starten Sie den Entwicklungsserver neu (Vite liest env beim Start; HMR erkennt es nicht) – schreiben Sie niemals eine .env in dieser Sandbox.