@web-engine-dev/netcode-server

Server-side room framework for hosting multiplayer game sessions. Manages room lifecycle, player connections, and synchronized state with schema-based delta serialization for bandwidth-efficient updates.

Layer 7 · Gameplay

Features

• Room Management: Create, join, leave, dispose with automatic cleanup
• Schema-Based Delta Sync: State patches sent as delta operations for bandwidth efficiency
• WebSocket Transport: Automatic reconnection and session resumption
• Configurable Tick Rate: Fixed-timestep accumulator (default 60 Hz simulation, 20 Hz patch rate)
• Heartbeat Monitoring: Disconnect unresponsive clients with configurable timeout
• Reconnection Windows: Session resumption after transient disconnects
• Horizontal Scaling: Room distribution across server instances
• Typed Message Handlers: Type-safe message routing with registered handlers
• Room-to-Room Messaging: Cross-game communication between rooms
• Matchmaking Integration: Room discovery via matchmaking system

Installation

npm install @web-engine-dev/netcode-server
# or
pnpm add @web-engine-dev/netcode-server

Quick Start

import { GameServer, GameRoom } from '@web-engine-dev/netcode-server';

// Define a custom room type
class BattleRoom extends GameRoom {
  onCreate(options: RoomOptions) {
    this.setState({ players: [], scores: {} });
    this.setTickRate(60);
    this.setPatchRate(20);
  }

  onJoin(client: ClientSession) {
    this.state.players.push({ id: client.id, x: 0, y: 0 });
  }

  onLeave(client: ClientSession) {
    this.state.players = this.state.players.filter((p) => p.id !== client.id);
  }

  onTick(dt: number) {
    // Fixed-timestep game simulation
    this.simulatePhysics(dt);
    this.checkWinCondition();
  }

  onMessage(client: ClientSession, type: string, data: unknown) {
    if (type === 'move') {
      this.handleMovement(client, data);
    }
  }

  onDispose() {
    // Cleanup resources
  }
}

// Start the server
const server = new GameServer({ port: 3000 });
server.define('battle', BattleRoom, { maxPlayers: 8 });
server.listen();

Room Lifecycle

1. Define Room Type — Register class with options
2. onCreate — Initialize state, set tick rate
3. onJoin / onLeave — Handle player connections
4. onTick — Fixed-timestep simulation loop
5. onDispose — Cleanup and shutdown

Two-Layer Architecture

Layer	Components	Responsibility
Framework	GameServer, GameRoom, RoomManager, ClientSession, StateSynchronizer	HTTP + WebSocket host, room lifecycle, delta compression
Game	Extends GameRoom	Custom game logic, state management, win conditions

State Synchronization

• State patches sent at configurable patch rate (default 20 Hz) independent of simulation tick rate (default 60 Hz)
• Fixed-timestep accumulator prevents "spiral of death" with 250ms cap
• Schema-based serialization for efficient binary diffs

Dependencies

• @web-engine-dev/netcode — Transport, QoS levels, serialization
• @web-engine-dev/serialization — Schema-driven binary serialization