How Ball2D works
What runs on your server, what Ball2D provides, and how players reach your room.
A Ball2D room has one host. When you use the SDK, the host is your server: it runs the physics simulation, applies your room rules and decides what every player sees. Ball2D itself never runs your match.
ball2d.com
Admission, discovery and signaling
Your server
ball2d/node
Your server
createRoom() from ball2d/node starts a complete host inside your Node.js process. The package contains the compiled engine, the WebAssembly physics core, the network transport and the bundled stadiums, so a host needs no browser, no build step and no other Ball2D software.
The host is authoritative. Player input arrives at your server, the simulation advances there and the result is sent back to each player. Your code observes the room through events and changes it through room methods, which run in the order you call them.
The Ball2D service
ball2d.com provides three things around the match:
- Admission. Your server presents its API key when it opens a room. The service checks the key and your account's room limits before the room exists.
- Discovery. Public rooms appear in the room list on ball2d.com, and every room has an invitation link of the form
https://ball2d.com/r/<id>. - Signaling. When a player joins, the service introduces the player and your server to each other so they can connect directly.
Gameplay traffic
After signaling, each player connects to your server directly over WebRTC. Inputs, positions and chat travel on that connection, not through ball2d.com.
Ball2D does not relay gameplay. A player whose network cannot open a direct connection to your server cannot play in your room.
When a room ends
A room has exactly one host for its whole life. If your process stops, the host loses its connection to the service, or its API key is revoked or expires, the room closes. Hosting never moves to a player, and a room without its host is not kept alive. To keep a room available, run a new one: see Keep a room online.
Browser hosts
The same room API also exists in the browser as the ball2d entry, for pages served by a Ball2D deployment. It follows the browser's own admission policy and never uses an API key. See Browser entry.