Poki Networking Library (Netlib)

A peer-to-peer library for web games using WebRTC data channels for direct UDP connections between players. Think of it as the Steam Networking Library, but for the web, with an interface that aims to be as simple as WebSockets. Your game doesn't need to be on Poki to use it; Netlib is open source on GitHub and published to npm.

Features

True peer-to-peer (P2P) networking

• Direct client-to-client connections without a central game server.
• Lower latency for geographically close players.
• Reduced server costs and infrastructure complexity.
• No need to duplicate game logic between client and server.

Three main advantages:

1. No server costs: there is no server running the game.
2. No double implementation: you don't need to write your game logic twice, once for the client and once for the server.
3. Lower latency: when players are close by, latency is often much lower than when connecting through a server.

UDP performance

• Choice between reliable (TCP) and unreliable (UDP) channels.
• Optimized for real-time gaming with minimal latency.
• Perfect for fast-paced multiplayer games.
• Unlike WebSockets or HTTP (which use TCP), UDP doesn't pause new packets when one packet is slow or dropped.
• Includes reliable data channels for critical events like chat messages or NPC spawns.

Easy to use

• Simple WebSocket-like API.
• Built-in lobby system with filtering.
• Automatic connection management.
• Comprehensive TypeScript support.

Production ready

• Fallback to TURN servers when direct P2P fails.
• Built-in connection quality monitoring.
• Automatic reconnection handling.
• Secure by default.

Quick start

1. Install the package:

yarn add @poki/netlib
# or
npm install @poki/netlib

2. Create a network instance:

import { Network } from '@poki/netlib'
const network = new Network('<your-game-id>')

3. Create or join a lobby:

// Create a new lobby
network.on('ready', () => {
  network.create()
})

// Or join an existing one
network.on('ready', () => {
  network.join('ed84')
})

4. Start communicating:

// Send messages
network.broadcast('unreliable', { x: 100, y: 200 })

// Receive messages
network.on('message', (peer, channel, data) => {
  console.log(`Received from ${peer.id}:`, data)
})

For more detailed examples and API documentation, see the basic usage guide and the example usage.

Roadmap

• ✓ Basic P2P connectivity
• ✓ Lobby system
• ✓ Lobby discovery and filtering
• ☐ WebRTC data compression
• ☐ Connection statistics and debugging tools
• ☐ More extensive documentation
• ☐ API stability

Architecture

Network stack

Your Game
    ↓
Netlib API
    ↓
WebRTC DataChannels
    ↓
(STUN/TURN if needed)
    ↓
UDP Transport

Infrastructure components

Signaling server

• Handles initial peer discovery.
• Manages lobby creation and joining.
• Facilitates WebRTC connection establishment.

STUN/TURN servers

• STUN: helps peers discover their public IP (Google STUN servers by default).
• TURN: provides fallback relay when direct P2P fails (the Poki-hosted version uses Cloudflare TURN servers).

Self-hosting

Poki provides hosted STUN/TURN and signaling services for free, but you can also self-host these components:

1. Set up your own signaling server, using the provided Docker image:

   $ docker build -t netlib .
   $ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -p 8080:8080 -e ENV=local netlib

   Or by running the signaling server binary directly:

   $ go build -o signaling cmd/signaling/main.go
   $ ENV=local ./signaling

2. For persistent storage, remove ENV=local and set DATABASE_URL to your PostgreSQL database URL.
3. Configure your own STUN/TURN servers.

4. Initialize the network with custom endpoints:

   const network = new Network('<game-id>', {
     signalingServer: 'wss://your-server.com',
     stunServer: 'stun:your-stun.com:3478',
     turnServer: 'turn:your-turn.com:3478'
   })

Engine integrations

Defold integration by IndieSoft.