Team

Show Deprecated

The Team class represents a faction in a Roblox place. The only valid parent for a Team is in the Teams service. Teams offer a range of features that are useful to developers that can be divided into two rough groups:

  • Features that work 'out of the box'
  • Features developers can program into their game.

Built-in Team Behavior

The following functionality of Teams exists by default and does not require the developer to program any custom behavior.

Optional Extended Team Behaviors

Many developers chose to add the following features to teams in their own code.

  • Implement checks in weapon code to prevent friendly fire.
  • Implement checks in doors or other features that allow only certain teams to use them
  • Periodically reassign teams to maintain team balance

Code Samples

Simple Team Rebalance

1local Teams = game:GetService("Teams")
2
3-- create two teams
4local redTeam = Instance.new("Team")
5redTeam.TeamColor = BrickColor.new("Bright red")
6redTeam.AutoAssignable = true
7redTeam.Name = "Red Team"
8redTeam.Parent = Teams
9
10local blueTeam = Instance.new("Team")
11blueTeam.TeamColor = BrickColor.new("Bright blue")
12blueTeam.AutoAssignable = true
13blueTeam.Name = "Blue Team"
14blueTeam.Parent = Teams
15
16-- start counting the number of players on each team
17local numberRed, numberBlue = 0, 0
18
19local function playerAdded(team)
20 -- increase the team's count by 1
21 if team == redTeam then
22 numberRed = numberRed + 1
23 elseif team == blueTeam then
24 numberBlue = numberBlue + 1
25 end
26end
27
28local function playerRemoved(team)
29 -- decrease the team's count by 1
30 if team == redTeam then
31 numberRed = numberRed - 1
32 elseif team == blueTeam then
33 numberBlue = numberBlue - 1
34 end
35
36 -- check if the teams are unbalanced
37 local bigTeam, smallTeam = nil, nil
38 if (numberRed - numberBlue) > 2 then
39 bigTeam = redTeam
40 smallTeam = blueTeam
41 elseif (numberBlue - numberRed) > 2 then
42 bigTeam = blueTeam
43 smallTeam = redTeam
44 end
45
46 if bigTeam then
47 -- pick a random player
48 local playerList = bigTeam:GetPlayers()
49 local player = playerList[math.random(1, #playerList)]
50
51 -- check the player exists
52 if player then
53 -- change the player's team
54 player.TeamColor = smallTeam.TeamColor
55 -- respawn the player
56 player:LoadCharacter()
57 end
58 end
59end
60
61-- listen for players being added / removed
62blueTeam.PlayerAdded:Connect(function(_player)
63 playerAdded(blueTeam)
64end)
65
66blueTeam.PlayerRemoved:Connect(function(_player)
67 playerRemoved(blueTeam)
68end)
69
70redTeam.PlayerAdded:Connect(function(_player)
71 playerAdded(redTeam)
72end)
73
74redTeam.PlayerRemoved:Connect(function(_player)
75 playerRemoved(redTeam)
76end)
Team Kill Check

1local Players = game:GetService("Players")
2
3function checkTeamKill(playerAttack, playerVictim)
4 if playerAttack.Team ~= playerVictim.Team or playerAttack.Neutral or playerVictim.Neutral then
5 return false
6 end
7 return true
8end
9
10local players = Players:GetPlayers()
11
12checkTeamKill(players[1], players[2])
Team Only Door

1local Players = game:GetService("Players")
2
3local door = Instance.new("Part")
4door.Anchored = true
5door.Size = Vector3.new(7, 10, 1)
6door.Position = Vector3.new(0, 5, 0)
7door.Parent = workspace
8
9local debounce = false
10
11door.Touched:Connect(function(hit)
12 if not debounce then
13 debounce = true
14 if hit then
15 local player = Players:GetPlayerFromCharacter(hit.Parent)
16 if player and player.TeamColor == BrickColor.new("Bright red") then
17 door.Transparency = 0.5
18 door.CanCollide = false
19 task.wait(3)
20 door.Transparency = 0
21 door.CanCollide = true
22 end
23 end
24 task.wait(0.5)
25 debounce = false
26 end
27end)

Summary

Properties

This property determines whether Players will be automatically placed onto the Team when joining. If multiple teams have this property set to true, Roblox will attempt to even the teams out when Players are added.

This property sets the color of the Team. Determines the Player.TeamColor property of players who are a member of the team. Also determines the color displayed on the player list and above player's heads.

Events


Fires whenever a Player is assigned to the Team. A player is considered assigned if their Player.Team property is equal to the Team and Player.Neutral is false.


Fires whenever a Player is removed from a Team. This can be due to the Player leaving the game, Player.Neutral being set to true or the Player joining a different team.

Methods


Returns a list of Players who are assigned to the Team. A Player is considered assigned if their Player.Team property is equal to the Team and Player.Neutral is false.

Properties

AutoAssignable

This property determines whether Players will be automatically placed onto the Team when joining. If multiple teams have this property set to true, Roblox will attempt to even the teams out when Players are added.

When a Player joins a game they will be assigned to the Team with Team.AutoAssignable set to true that has the fewest players. If no such team is available, Player.Neutral will be set to true.

Note while using this property will help even out teams when players are added, it will not do anything when players are removed. For this reason developers may wish to implement their own team balancing system.

ChildOrder

TeamColor

This property sets the color of the Team. Determines the Player.TeamColor property of players who are a member of the team.

A lot of Roblox's default team functionality is based on the team color, rather than the name or object. For example, SpawnLocations can be assigned to a team via SpawnLocation.TeamColor. For this reason it is recommended that developers ensure each Team has a unique TeamColor.

Any player which is a part of a team will have their name color changed to the team's TeamColor property. They will also be put underneath the team heading on the player list.

Events

PlayerAdded

Fires whenever a Player is assigned to the Team. A player is considered assigned if their Player.Team property is equal to the Team and Player.Neutral is false.

This event is team specific and will only fire when a Player joints the specific Team. Any function connected to this event will be passed the Player object of the player who joined the team. For example:


1Team.PlayerAdded:Connect(function(player)
2 print(player.Name.." has joined the team")
3end)
4

Parameters

player: Player

The Player that was added.


Code Samples

Simple Team Rebalance

1local Teams = game:GetService("Teams")
2
3-- create two teams
4local redTeam = Instance.new("Team")
5redTeam.TeamColor = BrickColor.new("Bright red")
6redTeam.AutoAssignable = true
7redTeam.Name = "Red Team"
8redTeam.Parent = Teams
9
10local blueTeam = Instance.new("Team")
11blueTeam.TeamColor = BrickColor.new("Bright blue")
12blueTeam.AutoAssignable = true
13blueTeam.Name = "Blue Team"
14blueTeam.Parent = Teams
15
16-- start counting the number of players on each team
17local numberRed, numberBlue = 0, 0
18
19local function playerAdded(team)
20 -- increase the team's count by 1
21 if team == redTeam then
22 numberRed = numberRed + 1
23 elseif team == blueTeam then
24 numberBlue = numberBlue + 1
25 end
26end
27
28local function playerRemoved(team)
29 -- decrease the team's count by 1
30 if team == redTeam then
31 numberRed = numberRed - 1
32 elseif team == blueTeam then
33 numberBlue = numberBlue - 1
34 end
35
36 -- check if the teams are unbalanced
37 local bigTeam, smallTeam = nil, nil
38 if (numberRed - numberBlue) > 2 then
39 bigTeam = redTeam
40 smallTeam = blueTeam
41 elseif (numberBlue - numberRed) > 2 then
42 bigTeam = blueTeam
43 smallTeam = redTeam
44 end
45
46 if bigTeam then
47 -- pick a random player
48 local playerList = bigTeam:GetPlayers()
49 local player = playerList[math.random(1, #playerList)]
50
51 -- check the player exists
52 if player then
53 -- change the player's team
54 player.TeamColor = smallTeam.TeamColor
55 -- respawn the player
56 player:LoadCharacter()
57 end
58 end
59end
60
61-- listen for players being added / removed
62blueTeam.PlayerAdded:Connect(function(_player)
63 playerAdded(blueTeam)
64end)
65
66blueTeam.PlayerRemoved:Connect(function(_player)
67 playerRemoved(blueTeam)
68end)
69
70redTeam.PlayerAdded:Connect(function(_player)
71 playerAdded(redTeam)
72end)
73
74redTeam.PlayerRemoved:Connect(function(_player)
75 playerRemoved(redTeam)
76end)

PlayerRemoved

Fires whenever a Player is removed from a Team. This can be due to the Player leaving the game, Player.Neutral being set to true or the Player joining a different team.

This event is team specific and will only fire when a Player leaves the specific Team. Any function connected to this event will be passed the Player object of the player who left the team. For example:


1Team.PlayerRemoved:Connect(function(player)
2 print(player.Name.." has left the team")
3end)
4

Parameters

player: Player

The Player removed.


Code Samples

Simple Team Rebalance

1local Teams = game:GetService("Teams")
2
3-- create two teams
4local redTeam = Instance.new("Team")
5redTeam.TeamColor = BrickColor.new("Bright red")
6redTeam.AutoAssignable = true
7redTeam.Name = "Red Team"
8redTeam.Parent = Teams
9
10local blueTeam = Instance.new("Team")
11blueTeam.TeamColor = BrickColor.new("Bright blue")
12blueTeam.AutoAssignable = true
13blueTeam.Name = "Blue Team"
14blueTeam.Parent = Teams
15
16-- start counting the number of players on each team
17local numberRed, numberBlue = 0, 0
18
19local function playerAdded(team)
20 -- increase the team's count by 1
21 if team == redTeam then
22 numberRed = numberRed + 1
23 elseif team == blueTeam then
24 numberBlue = numberBlue + 1
25 end
26end
27
28local function playerRemoved(team)
29 -- decrease the team's count by 1
30 if team == redTeam then
31 numberRed = numberRed - 1
32 elseif team == blueTeam then
33 numberBlue = numberBlue - 1
34 end
35
36 -- check if the teams are unbalanced
37 local bigTeam, smallTeam = nil, nil
38 if (numberRed - numberBlue) > 2 then
39 bigTeam = redTeam
40 smallTeam = blueTeam
41 elseif (numberBlue - numberRed) > 2 then
42 bigTeam = blueTeam
43 smallTeam = redTeam
44 end
45
46 if bigTeam then
47 -- pick a random player
48 local playerList = bigTeam:GetPlayers()
49 local player = playerList[math.random(1, #playerList)]
50
51 -- check the player exists
52 if player then
53 -- change the player's team
54 player.TeamColor = smallTeam.TeamColor
55 -- respawn the player
56 player:LoadCharacter()
57 end
58 end
59end
60
61-- listen for players being added / removed
62blueTeam.PlayerAdded:Connect(function(_player)
63 playerAdded(blueTeam)
64end)
65
66blueTeam.PlayerRemoved:Connect(function(_player)
67 playerRemoved(blueTeam)
68end)
69
70redTeam.PlayerAdded:Connect(function(_player)
71 playerAdded(redTeam)
72end)
73
74redTeam.PlayerRemoved:Connect(function(_player)
75 playerRemoved(redTeam)
76end)

Methods

GetPlayers

Returns a list of Players who are assigned to the Team. A Player is considered assigned if their Player.Team property is equal to the Team and Player.Neutral is false.

This function has a number of potential uses, including counting the number of players on a Team or giving every Player on a Team a Tool.


Returns

An array of Players in the Team.

Code Samples

Teams GetTeams

1local Teams = game:GetService("Teams")
2
3local teams = Teams:GetTeams()
4
5for _, team in pairs(teams) do
6 local players = team:GetPlayers()
7 print("Team", team.Name, "has", #players, "players")
8end