Room · Ball2D Docs

A Room is your handle on one running room. It exposes read-only identity, synchronous reads, queued commands and event properties. In Node.js, createRoom() resolves with a NodeRoom, which adds closed.

Import fromball2d

Group	Methods
Players and teams	`getPlayerList` `getPlayer` `setPlayerTeam` `setPlayerAdmin` `setPlayerAvatar` `reorderPlayers` `setTeamsLock` `setTeamColors`
Moderation	`setPlayerMuted` `kickPlayer` `clearBan` `clearBans` `setPassword` `setRequireVerification`
Chat	`sendChat` `sendAnnouncement`
Matches	`startGame` `stopGame` `pauseGame` `setScoreLimit` `setTimeLimit` `setKickRateLimit` `getScores` `getState` `getBallPosition`
Stadiums	`setDefaultStadium` `setCustomStadium`
Physics	`CollisionFlags` `getDiscCount` `getDiscProperties` `setDiscProperties` `getPlayerDiscProperties` `setPlayerDiscProperties`
Recording	`startRecording` `stopRecording` `lastRecording`

Identity

roomId

property

room.roomId: string

readonly

The room's identifier: ten lowercase hexadecimal characters, such as 3f9a0c41be.

JavaScript

console.log(room.roomId); // "3f9a0c41be"

roomLink

property

room.roomLink: string

readonly

The invitation URL players open to join, https://ball2d.com/r/<roomId> for rooms on the default service. It is available as soon as createRoom() resolves.

JavaScript

console.log(`Join at ${room.roomLink}`);

roomName

property

room.roomName: string

readonly

The roomName you passed to createRoom(), exactly as given.

Lifecycle

signal

property

room.signal: AbortSignal

readonly

An AbortSignal that aborts when the room closes, for any reason: your close() call, a lost connection, a revoked or expired key. Pass it to timers, fetches and loops that should stop with the room.

JavaScript

const timer = setInterval(
  announceScore,
  60_000,
);
room.signal.addEventListener('abort', () =>
  clearInterval(timer),
);

// Or stop a fetch when the room ends:
await fetch(url, { signal: room.signal });

close()

method

room.close(): void

Closes the room. Calling it again does nothing. In order, it:

Rejects every queued command with Room is closed.
Aborts signal.
Finalizes an active recording and delivers it to onRecordingComplete with the reason Room closed.
Leaves the service, which tells players the host has left.

close() returns immediately. In Node.js, await closed for cleanup to finish. It does not wait for every player to receive the shutdown.

After closing, commands reject, events stop (except the final onRecordingComplete), getPlayerList() returns [] and the other reads return null or 0.

Graceful shutdown

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