The Network module provides peer-to-peer connectivity using WebRTC, enabling multiplayer games and distributed applications without dedicated server infrastructure.
WebRTC (Web Real-Time Communication) is a browser-native technology that enables direct peer-to-peer connections. Clayground uses WebRTC Data Channels for reliable and ordered message delivery between nodes.
On Desktop and Mobile, WebRTC is implemented via libdatachannel. In browsers (WASM), the native WebRTC APIs are used directly.
All communication flows directly between peers after initial connection setup. This approach is ideal for:
Connecting two peers involves three phases:
Enable verbose mode and watch the diagnosticMessage signal to see which candidate types are discovered and how long each phase takes.
By default, two Google STUN servers are used. For connections across restrictive NATs (symmetric NAT, carrier-grade NAT), configure TURN servers via the iceServers property:
Network { iceServers: [ "stun:stun.l.google.com:19302", { urls: "turn:relay.example.com:3478", username: "user", credential: "pass" } ] }
Warning: P2P networking is not suitable for large-scale applications. Each node must maintain connections to other nodes, and message relay overhead grows with the number of participants.
For games requiring more than 8 players or MMO-style architectures, consider dedicated server solutions instead.
Signaling is only needed for initial peer discovery - once connected, all data flows directly between peers.
| Problem | Likely Cause | Solution |
|---|---|---|
| Connection hangs in "Connecting" (ice phase) | Both peers behind restrictive NATs (symmetric/carrier-grade) | Add a TURN server to iceServers |
| Works one direction but not the other | Asymmetric NAT types between peers | Add a TURN server; check diagnosticMessage for candidate types |
| Only "host" candidates, no "srflx" | STUN server unreachable or blocked | Check firewall, try different STUN servers |
| "Network full" error | maxNodes limit reached | Increase maxNodes or wait for a slot |
| Connection times out | Signaling server unreachable or NAT blocks all paths | Enable verbose mode, check diagnosticMessage for which phase fails |
Configurable HTTP client with automatic API method generation | |
Unified P2P networking for games, apps, and distributed systems |