Skip to content
Ball2DDocs

Get started

Introduction

Host Ball2D football rooms on your own server and run them with code.

Ball2D is a football game that runs in the browser. The Ball2D SDK lets you host rooms from your own server: your code runs the match, sets the rules and reacts to every kick, goal and chat message, while players join from ball2d.com like any other room.

To host a room, you'll need:

  1. A Ball2D account with an API key
  2. Node.js 24 or newer on the machine that runs the room

Your server runs the simulation. Ball2D admits the room with your API key, lists it for players and introduces each player to your server; the match itself flows directly between your server and the players. How Ball2D works explains each part.

Quickstart

Open a public room from Node.js in a few minutes.

Node.js quickstart

Install the SDK and host your first room.

Create an API key

Authorize a server to open rooms for your account.

SDK reference

Every function, room method, event and type.

Explore

Build the room you want to run.

Players and teams

Assign teams, admins and colors as players arrive.

Matches

Start, pause and stop matches with score and time limits.

Stadiums

Use the bundled stadiums or load your own.

Recordings and replays

Record matches and decode them on your server.

Moderation

Mute, kick and ban players, and filter chat.

Admission and limits

How many rooms a key may run, and how to back off.

Current release

These docs describe ball2d 0.3.1, which speaks room protocol 5. A host and the players in its room must run the same engine, so a room hosted with an SDK release older than the live game cannot be joined from ball2d.com. Check the changelog before you upgrade or deploy.