boardgame.io — State Management and Networking for Turn-Based Games

Introduction

boardgame.io is an open-source framework for building turn-based games in JavaScript and TypeScript. It separates game logic from rendering and networking, letting developers define game rules as pure functions while the framework handles state synchronization, multiplayer lobbies, and optional AI opponents automatically.

What boardgame.io Does

• Manages game state transitions through a declarative move system
• Synchronizes state between players over WebSockets or peer-to-peer
• Provides a lobby system for creating, joining, and listing game rooms
• Includes an AI framework with Monte Carlo Tree Search for bot opponents
• Offers a debug panel for inspecting and time-traveling through game state

Architecture Overview

Games are defined as plain objects specifying setup, moves, end conditions, and turn order. The framework wraps this definition in a state machine that validates and applies moves on the server. Clients receive state updates and render the game using any UI framework (React, Vue, plain DOM). The server component runs on Node.js and stores game state in memory or a persistent database.

Self-Hosting & Configuration

• Install via npm and import the Client and Server modules
• Define your game object with setup, moves, endIf, and turn properties
• Start the server with Server({ games: [MyGame] }) on any Node.js host
• Connect the client to the server by passing the server URL to Client()
• Use the built-in lobby API for room management or build a custom one

Key Features

• Pure function game logic that is easy to test and reason about
• Automatic state synchronization with conflict resolution
• Built-in MCTS AI that can play any game defined in the framework
• Secret state support for hidden information games like card games
• Framework-agnostic rendering works with React, Vue, Svelte, or vanilla JS

Comparison with Similar Tools

• Colyseus — general real-time multiplayer; boardgame.io is specialized for turn-based games with built-in AI
• Nakama — full game backend with accounts and matchmaking; boardgame.io focuses purely on game state and rules
• Phaser — rendering engine; boardgame.io handles state and networking, not graphics
• Socket.IO — raw WebSocket library; boardgame.io provides game-specific abstractions on top

FAQ

Q: Can boardgame.io be used for real-time games? A: It is optimized for turn-based games. Real-time games with physics or continuous movement are better served by frameworks like Colyseus.

Q: What UI libraries work with boardgame.io? A: Any. The framework is UI-agnostic. React has first-class support, but Vue, Svelte, and plain JavaScript work equally well.

Q: Does boardgame.io handle player authentication? A: It provides basic player credential support. For full authentication, integrate with an external auth provider.

Q: Can I add AI opponents to my game? A: Yes. The framework includes a Monte Carlo Tree Search bot that can play any game you define, with configurable difficulty.

Sources

• https://github.com/boardgameio/boardgame.io
• https://boardgame.io/documentation