Run in production

Runtime

Run hosts on Node.js 24 or newer. The native transport is verified on Node.js 24 on macOS (Apple silicon). Other operating systems have not been verified yet: test your platform, including real players joining from other networks, before you depend on it. Bun runs the same package as a compatibility target.

The package is self-contained. It includes the engine, the WebAssembly physics core and the bundled stadiums, and needs no browser, no postinstall step and no build.

Secrets

Provide the API key through your platform's secret store or an environment variable. Don't bake it into images, commit it, or log it. Use one key per deployment so you can revoke one without stopping the others, and create the replacement before a key expires.

One room per key

A key runs one room at a time, and an account two. Run at most one host process per key; a second process with the same key is refused while the first room is open. See Admission and limits.

Networking

Players connect directly to your host over WebRTC. Your server needs outbound HTTPS and WebSocket access to the Ball2D service, and must be able to establish WebRTC connections with players. Ball2D doesn't relay gameplay, so networks that block direct connections can prevent players from joining. Test from the networks your players use.

Shutdown

Handle SIGTERM, the signal process managers and container platforms send, and SIGINT for local runs. Close the room and wait for cleanup:

for (const signal of ['SIGINT', 'SIGTERM']) {
  process.once(signal, async () => {
    room.close();
    await room.closed;
    process.exit(0);
  });
}

Give the process a few seconds between SIGTERM and a forced kill; cleanup is usually immediate.

Keep the room available

A room ends if the host loses its service connection or its key changes. A production host should notice and open a new room: see Keep a room online, and Run under a process manager to restart the process itself.

Monitor

• Log every onError message with the room ID.
• Watch the event loop. Blocking your process for more than half a second pauses the match and reports Host scheduler stalled; match paused. Keep onGameTick handlers short and move heavy work, such as uploading recordings, off the tick.
• Record the room link when it opens, so you can find a room from your logs.

Upgrade

A host and its players must run the same engine. When ball2d.com updates its engine, install the matching SDK release and redeploy; the changelog says when this is needed.