Players and teams
Read the roster, move players between teams and style the teams.
Teams are numbers: 0 is spectators, 1 is red and 2 is blue. Players are identified by stable IDs; see HostPlayer. The host player, when the room has one, is player 0.
Reading players
getPlayerList()
room.getPlayerList(): HostPlayer[]Includes the host player when the room has one. Returns [] after the room closes.
Returns
HostPlayer[]Copies of every player, in roster order.
const fielded = room
.getPlayerList()
.filter((p) => p.team !== 0);
console.log(
`${fielded.length} players on the pitch`,
);getPlayer()
room.getPlayer(id: number): HostPlayer | nullParameters
numberrequiredReturns
HostPlayer | nullA copy of the player, or null if no player has that ID.
const player = room.getPlayer(id);
if (player?.admin) await room.startGame();Teams
setPlayerTeam()
room.setPlayerTeam(id: number, team: 0 | 1 | 2): Promise<void>Moves a player, including during a match and while teams are locked. A player who changes team moves to the end of the roster. Unknown IDs and moves to the current team do nothing. Fires onPlayerTeamChange with byPlayer set to null.
Parameters
numberrequired0 | 1 | 2required0 spectators, 1 red or 2 blue.Returns
Promise<void>
room.onPlayerJoin = (player) => {
const red = room
.getPlayerList()
.filter((p) => p.team === 1).length;
const blue = room
.getPlayerList()
.filter((p) => p.team === 2).length;
void room.setPlayerTeam(
player.id,
red <= blue ? 1 : 2,
);
};setTeamsLock()
room.setTeamsLock(locked: boolean): Promise<void>The lock only affects players picking a team for themselves. You and room admins can still move anyone. Fires onTeamsLockChange when the value changes.
Parameters
booleanrequiredtrue stops players from choosing their own team.Returns
Promise<void>
await room.setTeamsLock(true);setTeamColors()
room.setTeamColors(team: number, angle: number, textColor: number, colors: number[]): Promise<void>Sets a team's kit. Invalid colors reject with Invalid team colors; a team other than 1 or 2 rejects with Invalid team.
Parameters
numberrequired1 red or 2 blue.numberrequirednumberrequired0x000000 to 0xffffff.number[]requiredReturns
Promise<void>
// Red: vertical white and red stripes,
// black numbers.
await room.setTeamColors(
1,
90,
0x000000,
[0xffffff, 0xd9574a],
);
// Blue: plain navy with white numbers.
await room.setTeamColors(
2,
0,
0xffffff,
[0x1f3a8a],
);Roles and order
setPlayerAdmin()
room.setPlayerAdmin(id: number, admin: boolean): Promise<void>From the game's interface, admins can start, pause and stop matches, move players, change the stadium and room settings, and mute, kick or ban other players. They cannot act on the room owner. Only your code can grant admin: players cannot promote each other, so onPlayerAdminChange always reports byPlayer as null.
Parameters
numberrequiredbooleanrequiredtrue to grant admin rights, false to remove them.Returns
Promise<void>
const owners = new Set(['captain', 'referee']);
room.onPlayerJoin = (player) => {
if (owners.has(player.name))
void room.setPlayerAdmin(player.id, true);
};setPlayerAvatar()
room.setPlayerAvatar(id: number, avatar: string | null): Promise<void>Overrides the text drawn on a player's disc. Control and formatting characters are rejected.
Parameters
numberrequiredstring | nullrequiredGK or an emoji, or null to restore the player’s own avatar.Returns
Promise<void>
await room.setPlayerAvatar(keeper.id, 'GK');reorderPlayers()
room.reorderPlayers(playerIdList: number[], moveToTop: boolean): Promise<void>Changes the roster order, which is also the order of player discs in the physics API.
Parameters
number[]requiredbooleanrequiredtrue puts the listed players first, in this order; false puts them last.Returns
Promise<void>
// Bring the captains to the top of the list.
await room.reorderPlayers(
[captainRed.id, captainBlue.id],
true,
);