Players and teams · Ball2D Docs

Every player has a stable numeric ID for as long as they stay. Use IDs in your logic; names are free text chosen by players and may repeat.

Who is in the room

getPlayerList() returns a copy of every player; getPlayer(id) returns one. Both are synchronous and reflect every command that has finished.

JavaScript

const players = room.getPlayerList();
const spectators = players.filter((p) => p.team === 0);

Keep your own per-player state in a Map keyed by ID, and clean it up in onPlayerLeave:

JavaScript

const stats = new Map();
room.onPlayerJoin = (player) =>
  stats.set(player.id, { goals: 0 });
room.onPlayerLeave = (player) => stats.delete(player.id);

Teams

Teams are 0 spectators, 1 red and 2 blue. setPlayerTeam() moves anyone at any time, including mid-match. setTeamsLock(true) stops players from switching themselves.

Balance teams automatically is a complete example that fills the smaller team and rebalances when players leave.

Kits

setTeamColors() sets a team's stripes, their angle and the number color:

JavaScript

await room.setTeamColors(
  1,
  60,
  0xffffff,
  [0xb91c1c, 0x7f1d1d, 0xb91c1c],
);

Admins can manage the room from the game: start and stop matches, move players, change the stadium and settings, and mute, kick or ban. Only your code can make someone an admin, with setPlayerAdmin(). When your room has a host player, it is an admin from the start.

Player names are not identities. Don't grant admin because a name matches; anyone can type any name. Use a secret the player sends in chat, as in Chat commands.

Avatars and order

setPlayerAvatar() draws up to two characters on a player's disc, such as GK. reorderPlayers() changes the roster order.