Skip to content
Ball2DDocs

Host rooms

Room lifecycle

Configure a room, open it, watch it run and close it cleanly.

A room lives from a successful createRoom() until it closes. It never outlives its host and never changes hands.

Settings

Pass settings to createRoom(). Unknown keys fail at startup, so typos never go unnoticed.

apiKeystringrequired

Your API key. Node.js only.

roomNamestringdefault Headless Room

Shown in the room list. 1–64 characters.

publicbooleandefault false

List the room on ball2d.com. Unlisted rooms are reachable only through their link.

maxPlayersnumberdefault 12

Players admitted, including the host player. Clamped to 2–30.

noPlayerbooleandefault false

Run the room without a host player. When false, your process is player 0, an admin.

playerNamestringdefault Host

The host player's name, 1–24 characters.

passwordstring

Required to join. Up to 64 characters.

stadiumstring

Stadium source text to start with. To use a bundled stadium, call setDefaultStadium() after the room opens.

geoRoomGeo

The location shown in the room list. Advertising only.

Startup

createRoom() validates your settings and key, asks the service to admit the room, loads the engine and connects to signaling. It resolves only when the service confirms your process as the host, and rejects if any step fails within 15 seconds. On failure, everything it started is cleaned up and no room is left behind.

JavaScript
const room = await createRoom(config, {
  signal: AbortSignal.timeout(10_000),
});

The optional signal cancels startup only. Once the room is open, stop it with close().

While it runs

  • Commands such as setPlayerTeam() return promises and run in the order you call them. SDK conventions covers ordering, copies and the 256-command queue.
  • Events such as onPlayerJoin report what happens. Failures in your handlers go to onError, not to your process.
  • room.signal aborts when the room ends, whatever the reason. Tie timers and requests to it.

What closes a room

CauseonError reports
You call close()Nothing
The host's connection to the service is lost, or silent for three minutesHost connection ended
The API key is revokedAPI key revoked
The API key expiresRoom authorization expired

Players see that the host left. Nothing is transferred; to keep a room available, open a new one. See Keep a room online.

Shut down cleanly

Close the room when your process is asked to stop, then wait for cleanup:

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

Closing releases the room's place in your room limits right away. A process that exits without closing holds its place until the service notices the host is gone.