@poki/netlib

The Poki Networking Library   

The Poki Networking Library is a peer-to-peer networking library for web games, leveraging WebRTC datachannels to enable direct UDP connections between players. Think of it as the Steam Networking Library for the web, designed to make WebRTC as simple to use as WebSockets for game development.

[!WARNING] This library is still under development and considered a beta. While it's being actively used in production by some games, the API can change. Make sure to get in touch if you want to go live with this so we can keep you up-to-date about changes.

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:
    • No server costs - there is no server running the game
    • No double implementation - you don't need to write your game logic twice (for the client and the server)
    • Lower latency - when players are living close by, the latency is often much lower than when connected via 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

• Install the package:

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

• Create a network instance:

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

• 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')
})

• 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:

• Basic Usage Guide
• 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

1. Signaling Server

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

2. STUN/TURN Servers

• STUN: Helps peers discover their public IP (by default Google STUN servers)
• TURN: Provides fallback relay when direct P2P fails (when using the Poki hosted version, Cloudflare TURN servers are used)

Self-Hosting

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

• 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
  

• For persistent storage remove ENV=local and set DATABASE_URL to your PostgreSQL database URL.

• Configure your own STUN/TURN servers.

• 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'
})

Contributing

We welcome contributions! Please see our Contributing Guide for details. This project adheres to the Poki Vulnerability Disclosure Policy.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Main Contributors

• Koen Bollen
• Erik Dubbelboer