멀티플레이어 (WebRTC 피어 투 피어)
동일한 배포 도메인의 모든 방문자는 하나의 기본 방에 참여하여 각 방문자와 네이티브 WebRTC 데이터 채널을 직접 엽니다. 게임 트래픽 자체는 서버를 전혀 거치지 않습니다. /api/rtc에 있는 작은 릴레이는 피어가 연결되는 동안 연결 핸드셰이크(SDP/ICE)의 라우팅만 처리합니다. 키트에서 사용하는 것은 클라이언트 전용이며, 릴레이는 사용자 소유입니다.
지연 시간은 브라우저↔브라우저 간이며(보통 5–40ms), 서버 비용이 전혀 들지 않습니다.
| 구성 요소 | 경로 |
|---|---|
| 메시 프리미티브 (여기서 시작) | @/lib/multiplayer의 P2PRoom |
| 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— DB 기반 시그널링 릴레이 (Neon 배포, PGLite 프리뷰).src/routes/api/rtc.ts—/api/rtc에 마운트합니다(GET 폴링, POST 시그널/떠나기).
둘 다 references/signaling-relay.md에서 복사하세요, 스키마 노트도 포함되어 있습니다: 릴레이는 첫 사용 시 자체 두 테이블을 생성합니다(CREATE TABLE IF NOT EXISTS). 따라서 migrations/에 아무것도 넣지 마세요. 단, 의도적으로 스키마를 소유하려는 경우는 예외입니다.
프리미티브 사용하기
P2PRoom은 프레임워크에 독립적이며, "방"은 단순히 랑데부 키입니다 — 로비 코드, 1:1 통화 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); // 신뢰할 수 없는 "state" 채널 — 게임 속도, 오래된 것은 드롭
p2p.send(event, to); // 신뢰할 수 있는 채널 — 정확히 한 번 이벤트 (to는 선택 사항)
p2p.close();
"이 앱의 모든 사람이 함께 플레이"하는 일반적인 React 형태의 경우, useP2PRoom 훅(및 작업된 컴포넌트: 초당 약 20회 전송의 게임 속도 브로드캐스트 루프, 신뢰할 수 있는 단발 이벤트)을 references/react-binding.md에서 복사하세요.
패턴:
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(데이터 채널 핑) 및 candidateType(host/srflx = 직접)이 포함됩니다. STUN을 재정의하려면 .grok/app-env.json에 VITE_STUN_URLS(쉼표로 구분)를 추가하고 개발 서버를 다시 시작하세요(Vite는 시작 시 env를 읽습니다. HMR이 이를 감지하지 못함) — 이 샌드박스에서 .env를 작성하지 마세요.