Skip to main content

Players

A player is a human or AI who controls the game. See Players for a broader overview of how players work and what they can do.

Audience​

Audience:All -> symbol
Audience:Players -> symbol
Audience:Spectators -> symbol
Audience:None -> symbol

These values can be used to control who can see particular elements of the game. It is used by the audience of functions such as Content or ImageSprite. See Audience to learn more about audience parameters.

  • Audience:All means the element can be seen by everyone.
  • Audience:Players means the element can be seen by players.
  • Audience:Spectators means the element can be seen by spectators.
  • Audience:None means the element can be seen by no one.

AfterEliminated​

await owner.AfterEliminated

Waits until the specified owner player has been eliminated. If the player has already been eliminated, returns immediately without waiting.

AfterGameLocked​

await AfterGameLocked

Waits until the game is locked. If the game is already locked, returns immediately. See LockGame.

BeforePlayerLeave​

await owner.BeforePlayerLeave -> owner

await BeforePlayerLeave can be used to wait until a player leaves the game. If owner is provided, then it only waits for that particular player to leave, otherwise it returns when any player leaves the game. If the owner player has already left the game, this function returns immediately without waiting.

CountPlayers​

CountPlayers(against?, isEliminated?=, isHuman?, [owner?]) -> number

Counts the number of players that match the given criteria.

  • isEliminated (Boolean): If set, the player's Eliminated status must match this.

  • isHuman (Bool): If set, the player's IsHuman status must match this.

  • against (Flags): Filters players based on their alliance status with owner. For a player to match, the alliance status between the owner parameter and the player must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.

  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

DespawnBot​

owner.DespawnBot

DespawnBot makes the bot player specified by owner leave the game. The player must have been created with SpawnBot. Does nothing if the player is null, undefined, not a bot or has already left the game.

Eliminate​

owner.Eliminate

Eliminates the owner player from the game. If the player is already eliminated, this function does nothing.

Eliminating players who are no longer actively playing helps improve the experience for the remaining players as the network is optimized to focus on only the players who are actively playing the game. See Players to learn more.

This is the equivalent to setting Eliminated = true directly.

Eliminated​

owner.Eliminated -> boolean

Returns whether the owner player has been eliminated. If owner is null, undefined or not a player entity, returns undefined.

owner.Eliminated = boolean

Sets whether the owner player is eliminated. If the player is already in the specified state, this function does nothing.

Eliminating players who are no longer actively playing helps improve the experience for the remaining players as the network is optimized to focus on only the players who are actively playing the game. See Players to learn more.

await owner.Eliminated -> boolean

Waits until the Eliminated property changes, then returns its new value.

EliminatedTick​

owner.EliminatedTick -> tick

Returns the tick when the owner player was eliminated from the game. Returns null if owner has not been eliminated. If any parameter is nullish, returns undefined.

ExternalConfig​

owner.ExternalConfig -> value

Returns the external configuration data for the given owner player. If the game is running inside an iframe, this will contain the data passed to the iframe via the externalConfig field. If no config is available, returns undefined.

GameLocked​

GameLocked -> boolean

Returns whether the game is locked or not. See LockGame.

await GameLocked -> boolean

Waits until the GameLocked property changes, then returns the new value.

IsHuman​

owner.IsHuman -> boolean

IsHuman returns true if the owner player is a human player, false if it is a bot. If owner is null, undefined or not a player entity, returns undefined.

IsPresent​

owner.IsPresent -> boolean

IsPresent returns whether the owner player is still currently present in the game. When a player leaves or disconnects in the middle of the game (i.e. after LockGame has been called), they remain in the game but their status changes to not present. If any parameter is nullish, returns undefined.

await owner.IsPresent -> boolean

await IsPresent waits until the specified owner player's presence status changes. Waits forever if owner is null, undefined or not a player entity.

LockGame​

LockGame

Locks the game, preventing new human players from joining. When a player leaves after the game is locked, their player entity will not be despawned, instead their IsPresent property will be changed to false.

PlayerEliminated​

await PlayerEliminated -> owner

Waits until the next elimination of a player. Returns the player that was eliminated.

PlayerJoined​

await PlayerJoined -> owner

await PlayerJoined waits until the next player joins the game. It returns the new player.

PlayerName​

owner.PlayerName -> string

Returns the name of the owner player. Returns undefined if owner is nullish or not a player entity.

await owner.PlayerName -> string

Waits until the owner player's name changes, then returns the new name. Waits forever if owner is nullish or not a player entity.

PlayerNameDisplay​

PlayerNameDisplay([owner], playerName?=, color?, verified?, premium?, bot?, [ui])

Creates a element that displays the name of the player in their team color.

  • owner (player Entity): The player whose name will be displayed.
  • playerName (String): Optional. Can be used to override the name of the player that is displayed. Defaults to owner.PlayerName.
  • color (Color): Optional. Can be used to override the color of the name that is displayed. Defaults to the team color of the owner player.
  • verified (Boolean): Optional. Can be used to override whether a verified checkmark is displayed next to the name. Defaults to owner.PlayerName == owner.Username.
  • premium (Number): Optional. Can be used to override the premium level displayed next to the name. Defaults to owner.PremiumUserTier.
  • bot (Boolean): Optional. Can be used to override whether a bot icon is displayed next to the name. Defaults to !owner.IsHuman.
  • ui (UI): The slot in the user interface where the element will be inserted.

PlayerNameEditor​

PlayerNameEditor(width?=, [ui])

Creates a text input element that allows the current player to edit their name. The player's name is used to identify them in the game, both to themselves and other players. The player's name can be accessed programmatically using the PlayerName function.

QueryAnyPlayer​

QueryAnyPlayer(against?, isEliminated?=, isHuman?, [owner?]) -> player

Finds a player that matches the given criteria.

  • isEliminated (Boolean): If set, the player's Eliminated status must match this.

  • isHuman (Bool): If set, the player's IsHuman status must match this.

  • against (Flags): Filters players based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the player must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.

  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

If no player matches, returns undefined.

QueryPlayers​

QueryPlayers(against?, isEliminated?=, isHuman?, [owner?]) -> playerArray

Finds all players that match the given criteria.

  • isEliminated (Boolean): If set, the player's Eliminated status must match this.

  • isHuman (Bool): If set, the player's IsHuman status must match this.

  • against (Flags): Filters players based on their alliance status with owner. For a player to match, the alliance status between the owner parameter and the player must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.

  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Returns an array of matching players.

SpawnBot​

SpawnBot(name?) |use this = use owner| { } -> player

SpawnBot creates a new bot player and returns a new player entity representing the new bot.

The IsHuman property of bots is always false. Bots cannot store any persistent data between games - any changes to their accumulators or preferences are lost at the end of the game.

Parameters:

  • name: Defines the PlayerName of the new bot. Defaults to Bot if not specified.

Subblock: The subblock can be used to represent the main behavior of the bot. It is optional. The subblock runs concurrently with the rest of the game, and will automatically be terminated if/when the bot player entity despawns.

SpawnEachPlayer​

SpawnEachPlayer |use this = use owner| { }

Defines the main behavior for players in the game.

Only one SpawnEachPlayer can be active at a time. Calling SpawnEachPlayer a second time will replace the first call, terminating the behaviors that were spawned by the first call.

Subblock: Use the subblock to define the main behavior for each player in the game. The subblock will be executed for all players currently in the game, and any new players that join in the future. It runs concurrently with the rest of the game, and will be automatically terminated if/when the player entity despawns.