Module teams
Teams
Handles dynamic team assignment, player coloring, and UI rendering for team selection in a multiplayer match.
Tracks player membership in teams, allows hosts to force team starts, and synchronizes team state to clients.
Core responsibilities:
- Create and configure teams (names, colors, players)
- Manage player joins, leaves, and team switches
- Handle team-based color assignment
- Provide a UI for team selection and team joining
Execution context:
- Server-only logic (team state, assignment)
- Client-side UI (draw functions)
Functions
| teamsInit (teamCount) | Initialize the team system with a given number of teams (server). |
| teamsGetColor (teamId) | Get the configured color for a team. |
| teamsSetColors (colors) | Set custom colors for all teams (server). |
| teamsSetNames (names) | Set custom names for all teams (server). |
| teamsGetName (teamId) | Get the configured team name for a given team ID. |
| teamsSetTeams (teams) | Assign players to teams directly (server). |
| teamsGetPlayerTeamsList () | Returns a lookup table mapping each player to their team ID. |
| teamsGetTeamPlayers (teamId) | Get the list of players belonging to a specific team. |
| teamsGetPlayerColorsList () | Returns a lookup table mapping each player ID to their current team color. |
| teamsStart (skipCountdown) | Start the match or begin the team selection countdown (server). |
| teamsIsSetup () | Check if team setup is complete and the match has started. |
| teamsGetTeamId (playerId) | Get the team ID of a specific player. |
| teamsTick (dt) | Tick team logic (server). |
| teamsGetLocalTeam () | Get a list of players on the same team as the local player (client). |
| teamsDraw (dt) | Render the team selection screen UI (client). |
Functions
- teamsInit (teamCount)
-
Initialize the team system with a given number of teams (server).
Sets default team names and colors and clears any previous team state.
Parameters:
- teamCount number Number of teams to create.
- teamsGetColor (teamId)
-
Get the configured color for a team.
Returns the current team color. If the team does not exist, falls back to
_teamsGetDefaultColor(teamId).Parameters:
- teamId number Team ID of the team (1-based).
Returns:
-
table
RGB color table
{r, g, b}with components in [0, 1]. - teamsSetColors (colors)
-
Set custom colors for all teams (server).
Updates the
colorof each team. The provided list should have one entry per team.Parameters:
- colors
table
List of RGB color tables, one per team
(e.g.
{ {1,0,0}, {0,1,0}, ... }).
- colors
table
List of RGB color tables, one per team
(e.g.
- teamsSetNames (names)
-
Set custom names for all teams (server).
Updates the
namefor each team. The provided list should match the number of active teams.Parameters:
- names
table
List of team names as strings
(e.g.
{ "Red", "Blue", "Green" }).
- names
table
List of team names as strings
(e.g.
- teamsGetName (teamId)
-
Get the configured team name for a given team ID.
Retrieves the current team name. If the team does not exist, falls back to
_teamsGetDefaultTeamName(teamId).Parameters:
- teamId number Numeric ID of the team (1-based).
Returns:
-
string
Team name or default name if not configured.
- teamsSetTeams (teams)
-
Assign players to teams directly (server).
Replaces the current team player lists. Each element in teams is a list of player IDs.
Parameters:
- teams
table
List of player ID lists, one per team.
Example:
{ {1, 2}, {3, 4} }assigns players 1 and 2 to team 1, and players 3 and 4 to team 2.
- teams
table
List of player ID lists, one per team.
Example:
- teamsGetPlayerTeamsList ()
-
Returns a lookup table mapping each player to their team ID.
Iterates over all players and builds a map from player ID to their assigned team ID. Useful for broadcasting team membership.
Returns:
-
A table where keys are player IDs and values are team IDs
(e.g.,
{ [1] = 2, [2] = 1, ... }) - teamsGetTeamPlayers (teamId)
-
Get the list of players belonging to a specific team.
Parameters:
- teamId number Team ID (1-based).
Returns:
-
table
List of player IDs in the team (empty if team does not exist).
- teamsGetPlayerColorsList ()
-
Returns a lookup table mapping each player ID to their current team color.
This is convenient for construction UIs that uses team colors.
Returns:
-
table A table where keys are player IDs and values are RGB color tables
Usage:
- Returned table will have this format: { [1] = {0.2, 0.55, 0.8}, [2] = {0.8, 0.25, 0.2}, [3] = {0.3, 0.90, 0.1}, -- etc.. }
- teamsStart (skipCountdown)
-
Start the match or begin the team selection countdown (server).
If
skipCountdownistrue, teams are auto-assigned immediately and the team state assignment is concidered done. If countdown is not skipped, it is expected that the UI is rendered with teamsDraw to allow players to pick teams.Parameters:
- skipCountdown bool Whether to skip the team selection countdown.
- teamsIsSetup ()
-
Check if team setup is complete and the match has started.
Returns:
-
bool
trueif setup is complete. - teamsGetTeamId (playerId)
-
Get the team ID of a specific player.
Parameters:
- playerId number Player ID to look up.
Returns:
-
number
Team ID (1-based), or
0if the player is unassigned. - teamsTick (dt)
-
Tick team logic (server).
Should be called once per tick on the server. It: * Handles connecting/disconnecting players. * Assigns teams and updates player colors when the setup is done. * Posts an
teamsupdatedevent when team setup is complete.Parameters:
- dt number Time step in seconds.
Returns:
-
bool
trueif the pending game start was triggered this tick,falseotherwise. - teamsGetLocalTeam ()
-
Get a list of players on the same team as the local player (client).
Returns:
-
table
List of player IDs on the local player's team.
- teamsDraw (dt)
-
Render the team selection screen UI (client).
Draws a team selection UI where players can pick a team to join. Will early-out and skip any UI drawing if team setup is completed.
Parameters:
- dt number Time step in seconds.