Players

The BubbleChat Players property indicates whether or not bubble chat is enabled. It is set with the Players:SetChatStyle() method using the ChatStyle enum.

When this chat mode is enabled, the game displays chats in the chat user interface at the top-left corner of the screen.

There are two other chat modes, Players.ClassicChat and a chat mode where both classic and bubble chat are enabled.

The CharacterAutoLoads Players property indicates whether Characters will respawn automatically. The default value is true.

If this property is disabled (false), players Characters will not spawn until the Player:LoadCharacter() function is called for each Player - including when players join the game.

This can be useful in games where players have finite lives, such as competitive games in which players do not respawn until a game round ends.

Indicates whether or not classic chat is enabled. This property is set by the Players:SetChatStyle() method using the ChatStyle enum.

When this chat mode is enabled, the game displays chats in a bubble above the sender's head.

There are two other chat modes, Players.BubbleChat and a chat mode where both classic and bubble chat are enabled.

LocalPlayer is a read-only property which refers to the Player whose client is running the game.

This property is only defined for LocalScripts (and ModuleScripts required by them), as they run on the client. For the server (on which Script objects run their code), this property is nil.

This property is useful in LocalScripts which display information about the player viewing a GUI. Using For example, if there were IntValue parented to a Player named "Coins" which represented how much money that player has, you could use the following to display this value for them:

1-- This code is appropriate for a LocalScript in StarterGui,
2-- for example: game.StarterGui.ScreenGui.TextLabel.LocalScript
3
4local player = game:GetService("Players").LocalPlayer
5-- Wait for a value we're expecting for the server to have created
6local vCoins = player:WaitForChild("Coins")
7
8local textLabel = script.Parent
9local function update()
10    textLabel.Text = "Coins: " .. vCoins.Value
11end
12
13-- Update once, then every time the value changes
14update()
15vCoins.Changed:Connect(update)
16

Loading GUIs

When creating loading GUIs using ReplicatedFirst, sometimes a LocalScript can run before the LocalPlayer is available. In this case, you should yield until it becomes available by using Instance:GetPropertyChangedSignal()

1local Players = game:GetService("Players")
2-- Below: access Players.LocalPlayer; if it is nil, we'll wait for it using GetPropertyChangedSignal.
3local player = Players.LocalPlayer or Players:GetPropertyChangedSignal("LocalPlayer"):wait()
4

Doing this isn't for a LocalScript within StarterGui, StarterPlayerScripts or StarterCharacterScripts: these scripts can only run after a Player object is already available, and LocalPlayer will have been set by then.

The MaxPlayers Players property determines the maximum amount of players that can be in this server.

While this property cannot be set through Scripts or LocalScripts in-game, it can be set from the place settings' Access tab on the site.

You can change this value depending on the number of player's you would like to limit in a single server. The number of players in a server affects the feel of your game and it's performance.

The MaxPlayersInternal Players property is the internal variant of Players.MaxPlayers and determines the maximum amount of players that can be in this server.

While this property cannot be set through Scripts or LocalScripts in-game, it can be set from the place settings' Access tab on the site.

You can change this value depending on the number of player's you would like to limit in a single server. The number of players in a server affects the feel of your game and it's performance.

The PreferredPlayers property determines the number of players to which Roblox's matchmaker will fill servers. This number should be less than the maximum number of players supported by the game in order to leave some spaces for additional players (such as friends or those following another player) to join.

This property can be set from the place settings' Access tab on the site. It cannot be set through Scripts or LocalScripts in-game.

When a player press the Play button to join a game server, Roblox attempts to match that player to a server such that the player count will try not to exceed PreferredPlayers. If a friend (or friends) of the player are in a server that is not full, Roblox prioritizes that server instead.

Example

There are 8 players in a server where the Player.MaximumPlayers is 10 and the PreferredPlayers is 8. A player presses the play button:

• If the player has at least one friend in the server, Roblox selects the already-existing server so the player can play with their friend.
• If the player has no friends in the server, a new server is started since the existing server has met the number of PreferredPlayers (the player could still join the server by manually selecting it or following another user).

The PreferredPlayersInternal Players property is the internal variant of Players.PreferredPlayersInternal, which controls the preferred amount of players for this server.

When someone press the Play-button, Roblox will try to fill all servers up to the amount of given players. If there is a server that has friends on you in it, Roblox will send you to that server instead. (Unless the server is completely full)

This system allows developers to have servers more friends-friendly. Normally, when PreferredPlayers ~= MaxPlayers, a server would never fill up, unless a player follows another player, or a player pressing the Play button has one or more friends in that server.

While this property cannot be set through Scripts or LocalScripts in-game, it can be set from the place settings' Access tab on the site.

##Example Given a server with 8 players where the Player.MaximumPlayers is 10 and the PreferredPlayers is 8, 2 things can happen whenever a player press the Play-button:

• The player has friends in the server, which makes Roblox send them to that server
• The player has no friends in it, and will start a new server, as the server is already "filled" up to PreferredPlayers amount.

The RespawnTime property controls the time, in seconds, it takes for a player to respawn when Players.CharacterAutoLoads is true. It defaults to 5.0 seconds.

This is useful when you want to change how long it takes to respawn based on the type of your game but don't want to handle spawning players individually. Social games may want to decrease the respawn time whereas action games may want to increase it.

Although this can be set from within a Script, you will likely set the property from within Studio via the Players service property window.

1local Players = game:GetService("Players")
2Players.RespawnTime = 10.0
3

See also:

• Player.SpawnLocation, if set, the player will respawn at the given SpawnLocation

The PlayerAdded event fires when a player enters the game. This is used to fire an event when a player joins a game, such as loading the player's saved GlobalDataStore data.

This can be used alongside the Players.PlayerRemoving event, which fires when a player is about to leave the game. For instance, if you would like print a message every time a new player joins or leaves the game:

1local Players = game:GetService("Players")
2
3Players.PlayerAdded:Connect(function(player)
4	print(player.Name .. " joined the game!")
5end)
6
7Players.PlayerRemoving:Connect(function(player)
8	print(player.Name .. " left the game!")
9end)
10

If you want to track when a player's character is added or removed from the game, such as when a player respawns or dies, you can use the Player.CharacterAdded and Player.CharacterRemoving functions.

• Up until recently, this event didn't work on the client (in Localscripts), but this has been changed

• This event does not work as expected in solo mode, because the player is created before scripts that connect to PlayerAdded run. To handle this case, as well as cases in which the script is added into the game after a player enters, create an OnPlayerAdded function that you can call to handle a player's entrance.

The PlayerChatted Players event fires when a player chats.

The value of the PlayerChatType determines the type of chat sent. There are three types of chat: | Type | Description | |---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | All | A global message that everyone can receive. | | Team | A team message only players in the same team can receive. | | Whisper | A whispered message only the person it's whispered to can receive. If the chat type is a Whisper Chat, the targetPlayer is the player being whispered to. |

Note that this event is not intended for wide use and will not work in Scripts or LocalScripts.

The PlayerConnecting Players event fires when a player is connecting to the game. It indicates the Player instance connecting.

This event is not intended for wide use and will not work in Scripts or LocalScripts. Instead, you can use the Player.PlayersAdded and Players.PlayerRemoving events.

Similarly, if you want to track when a player's character is added or removed from the game, such as when a player respawns or dies, you can use the Player.CharacterAdded and Player.CharacterRemoving functions.

The PlayerDisconnecting Players event fires when a player is disconnecting from the game. It indicates the Player instance disconnecting.

This event is not intended for wide use and will not work in Scripts or LocalScripts. Instead, you can use the Player.PlayersAdded and Players.PlayerRemoving events.

Similarly, if you want to track when a player's character is added or removed from the game, such as when a player respawns or dies, you can use the Player.CharacterAdded and Player.CharacterRemoving functions.

This event fires when the game server recognizes that a player's membership has changed. Note, however, that the server will only attempt to check and update the membership after the Premium modal has been closed. Thus, to account for cases where the user purchases Premium outside of the game while playing, you must still prompt them to purchase Premium; this will then show a message telling them they're already upgraded and, once they close the modal, the game server will update their membership and trigger this event.

To learn more about and incorporating Premium into your game, and monetizing your game with the Premium Payouts system, see Premium Payouts.

See also:

• MarketplaceService:PromptPremiumPurchase(), used to prompt a user to purchase Premium
• MarketplaceService.PromptPremiumPurchaseFinished, fires when the Premium purchase UI closes

The PlayerRejoining Players event fires when a player rejoins a game session after having disconnected prior. It indicates the Player instance rejoining.

This event is not intended for wide use and will not work in Scripts or LocalScripts. Instead, you can use the Player.PlayersAdded and Players.PlayerRemoving events.

Similarly, if you want to track when a player's character is added or removed from the game, such as when a player respawns or dies, you can use the Player.CharacterAdded and Player.CharacterRemoving functions.

The PlayerRemoving event fires right before a Player leaves the game. This event fires before ChildRemoved does on Players, and behaves somewhat similarly to Instance.DescendantRemoving. Since it fires before the actual removal of a Player, this event is useful for storing player data using a GlobalDataStore.

This can be used alongside the Player.PlayerAdded event, which fires when a player joins the game. For instance, to print a message every time a new player joins or leaves the game:

1local Players = game:GetService("Players")
2
3Players.PlayerAdded:Connect(function(player)
4  print(player.Name .. " joined the game!")
5end)
6
7Players.PlayerRemoving:Connect(function(player)
8  print(player.Name .. " left the game!")
9end)
10

If you want to track when a player's character is added or removed from the game, such as when a player respawns or dies, you can use the Player.CharacterAdded and Player.CharacterRemoving functions.

This function makes the local player chat the given message. Since this item is protected, attempting to use it in a Script or LocalScript will cause an error.

Instead, when creating a custom chat system, or a system that needs access to the chat, you can use the Chat service's Chat:Chat() function instead.

The LocalPlayer will be set automatically when a client connects to the game, so uses for this method are extremely limited. This function is protected, attempting to use it in a Script or LocalScript will cause an error.

Although you cannot create the LocalPlayer, you can reference the LocalPlayer created by a game using the following code in a LocalScript:

1	local player = game.Players.LocalPlayer
2

This function searches each player in Players for one whose Player.UserId matches the given UserId. If such a player does not exist, it simply returns nil. It is equivalent to the following function:

1local Players = game:GetService("Players")
2local function getPlayerByUserId(userId)
3	for _, player in pairs(Players:GetPlayers()) do
4		if player.UserId == userId then
5			return player
6		end
7	end
8end
9

This method is useful in finding the purchaser of a developer product using MarketplaceService.ProcessReceipt, which provides a table that includes the purchaser's UserId and not a reference to the Player object itself. Most games will require a reference to the player in order to grant products.

This function returns the Player associated with the given Player.Character, or nil if one cannot be found. It is equivalent to the following function:

1local function getPlayerFromCharacter(character)
2	for _, player in pairs(game:GetService("Players"):GetPlayers()) do
3		if player.Character == character then
4			return player
5		end
6	end
7end
8

This method is often used when some event in player's character fires (such as their Humanoid dying). Such an event might not directly reference the Player object, but this method provides easy access. The inverse of this function can be described as getting the Character of a Player. To do this, simply access the Character property.

This method returns a table of all presently connected Player. It functions the same way Instance:GetChildren() would except that it only returns Player objects. It functions similarly to Instance:GetChildren() when called on Players. When used in conjunction with a for-loop, it is useful for iterating over all players in a game.

1Players = game:GetService("Players")
2for i, player in pairs(Players:GetPlayers()) do
3    print(player.Name)
4end
5

Scripts that connect to Players.PlayerAdded are often trying to process every Player that connects to the game. This method is useful for iterating over already-connected players that wouldn't fire PlayerAdded. Using this method ensures that no player is missed!

1local Players = game:GetService("Players")
2
3local function onPlayerAdded(player)
4	print("Player: " .. player.Name)
5end
6
7for _, player in pairs(Players:GetPlayers()) do
8	onPlayerAdded(player)
9end
10Players.PlayerAdded:Connect(onPlayerAdded)
11

This function attempts to report the given player for the given reason. Since this item is protected, attempting to use it in a Script or LocalScript will cause an error.

The game uses this function internally when a player interact's with the game's default report system. Players should use this system to report players for offensive or inappropriate behavior.

This function sets whether BubbleChat and ClassicChat are being used, and tells TeamChat and Chat what to do using the ChatStyle enum. Since this item is protected, attempting to use it in a Script or LocalScript will cause an error.

This function is used internally when the chat mode is set by the game.

This function makes the Players.LocalPlayer chat the given message, which will only be viewable by users on the same team. Since this item is protected, attempting to use it in a Script or LocalScript will cause an error.

This function is used internally when the Players.LocalPlayer sends a message to their team.

This function delivers the given message to a recipient without anyone else seeing. Since this item is protected, attempting to use it in a Script or LocalScript causes an error.

This function is used internally when the Players.LocalPlayer sends whispers to another player.

Returns a character Model equipped with everything specified in the passed in HumanoidDescription, and is R6 or R15 as specified by the rigType.

Returns a character Model set-up with everything equipped to match the avatar of the user specified by the passed in userId. This includes whether that character is currently R6 or R15.

This function returns information about a player's avatar (ignoring gear) on the Roblox website in the form of a dictionary. It is not to be confused with GetCharacterAppearanceAsync, which actually loads the assets described by this method. You can use InsertService:LoadAsset() to load the assets that are used in the player's avatar. The structure of the returned dictionary is as follows:

Assets sub-table

The assets table is an array of tables containing the following keys that describe the assets currently equipped by the player:

Scales sub-table

The scales table has the following keys, each a number corresponding to one Humanoid scaling property: bodyType, head, height, proportion, depth, width.``

Body Colors sub-table

The body colors table has the following keys, each a number corresponding to a BrickColor ID number which can be used with BrickColor.new(): leftArmColorId, torsoColorId, rightArmColorId, headColorId, leftLegColorId, rightLegColorId.

The GetFriends Players function returns a FriendPages object which contains information for all of the given Player's friends. The items within the FriendPages object are tables with the following fields:

See the code samples for an easy way to iterate over all a player's friends.

Returns the HumanoidDescription for a specified outfitId, which will be set with the parts/colors/Animations etc of the outfit. An outfit can be one created by a user, or it can be the outfit for a bundle created by Roblox.

Returns a HumanoidDescription which specifies everything equipped for the avatar of the user specified by the passed in userId. Also includes scales and body colors.

The GetNameFromUserIdAsync Players function will send a query to the Roblox website asking what the username is of the account with the given UserId.

This method errors if no account exists with the given UserId. If you aren't certain such an account exists, it's recommended to wrap calls to this function with pcall. In addition, you can manually cache results to make future calls with the same UserId fast. See the code samples to learn more.

This function will send a query to the Roblox website asking what the Player.UserId is of the account with the given Player name.

This method errors if no account exists with the given username. If you aren't certain such an account exists, it's recommended to wrap calls to this function with pcall. In addition, you can manually cache results to quickly make future calls with the same username. See the code samples to learn more.

This function fetches a content URL of an image of a player's avatar given their UserId, the image size (as an enum) and type (also an enum: avatar, bust, headshot). It also returns a bool describing if the image is ready to be used.

Most often, this method is used with ImageLabel.Image to display player pictures next to their username in-game. It is also appropriate for Decal.Texture as well.

Available Sizes

ThumbnailSize: Size48x48, Size60x60, Size100x100, Size150x150, Size180x180, Size353x353, Size420x420.

Types of User Thumbnails

Enum.ThumbnailType	Description	Example (60px)
AvatarBust	Upper chest and head
AvatarThumbnail	Entire avatar
HeadShot	Just the head and face