# This file is automatically generated. Please don't edit it manually. # To submit a bug report on the content, see # https://devforum.roblox.com/c/bug-reports/documentation-issues/72 name: Players type: class memory_category: Instances summary: | A service that contains presently connected `Class.Player` objects. description: | The `Class.Players` service contains `Class.Player` objects for presently connected clients to a Roblox server. It also contains information about a place's configuration. It can fetch information about players not connected to the server, such as character appearances, connections, and avatar thumbnail. code_samples: [] inherits: - Instance descendants: [] tags: - NotCreatable - Service deprecation_message: '' properties: - name: Players.BanningEnabled summary: | Enables or disables the three `Class.Players` methods (`Class.Players:BanAsync()|BanAsync()`, `Class.Players:UnbanAsync()|UnbanAsync()`, and `Class.Players:GetBanHistoryAsync()|GetBanHistoryAsync()`) that constitute the ban API. This property is not scriptable and can only be modified in Studio. description: | Enables or disables the three `Class.Players` methods (`Class.Players:BanAsync()|BanAsync()`, `Class.Players:UnbanAsync()|UnbanAsync()`, and `Class.Players:GetBanHistoryAsync()|GetBanHistoryAsync()`) that constitute the ban API. This property is not scriptable and can only be modified in Studio. code_samples: [] type: boolean tags: - NotScriptable deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Behavior serialization: can_load: true can_save: true capabilities: - Players - name: Players.BubbleChat summary: | Indicates whether or not bubble chat is enabled. It is set with the `Class.Players:SetChatStyle()` method. description: | This property indicates whether or not bubble chat is enabled. It is set with the `Class.Players:SetChatStyle()` method using the `Enum.ChatStyle` enum. When this chat mode is enabled, the experience displays chats in the chat user interface at the top-left corner of the screen. There are two other chat modes, `Class.Players.ClassicChat` and a chat mode where both classic and bubble chat are enabled. code_samples: [] type: boolean tags: - ReadOnly - NotReplicated deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Chat - Players - name: Players.CharacterAutoLoads summary: | Indicates whether `Class.Player.Character|characters` will respawn automatically. description: | This property indicates whether `Class.Player.Character|characters` will respawn automatically. The default value is true. If this property is disabled (false), player `Class.Player.Character|characters` will not spawn until the `Class.Player:LoadCharacterAsync()` function is called for each `Class.Player`, including when players join the experience. This can be useful in experiences where players have finite lives, such as competitive experiences in which players do not respawn until a round ends. code_samples: - player-respawn-timer type: boolean tags: - NotReplicated deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Behavior serialization: can_load: true can_save: true capabilities: - Players - name: Players.ClassicChat summary: | Indicates whether or not classic chat is enabled; set by the `Class.Players:SetChatStyle()` method. description: | Indicates whether or not classic chat is enabled. This property is set by the `Class.Players:SetChatStyle()` method using the `Enum.ChatStyle` enum. When this chat mode is enabled, the experience displays chats in a bubble above the sender's head. There are two other chat modes, `Class.Players.BubbleChat` and a chat mode where both classic and bubble chat are enabled. code_samples: [] type: boolean tags: - ReadOnly - NotReplicated deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Chat - Players - name: Players.LocalPlayer summary: | The `Class.Player` that the `Class.LocalScript` is running for. description: | This read-only property refers to the `Class.Player` whose client is running the experience. This property is only defined for `Class.LocalScript|LocalScripts` and `Class.ModuleScript|ModuleScripts` required by them, since they run on the client. For the server, on which `Class.Script` objects run their code, this property is `nil`. code_samples: [] type: Player tags: - ReadOnly - NotReplicated deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Players - name: Players.localPlayer summary: '' description: '' code_samples: [] type: Player tags: - Hidden - ReadOnly - NotReplicated - Deprecated deprecation_message: | This property is a deprecated variant of `Class.Players.LocalPlayer` which should be used instead. security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Players - name: Players.MaxPlayers summary: | The maximum number of players that can be in a server. description: | This property determines the maximum number of players that can be in a server. This property can only be set through a specific place's settings on the [Creator Dashboard](https://create.roblox.com/dashboard/creations) or through [Experience Settings](../../../studio/experience-settings.md). code_samples: [] type: int tags: - ReadOnly - NotReplicated deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Players - name: Players.NumPlayers summary: | Returns the number of people in the server at the current time. description: | This property indicates the number of people in the server at the current time. It is read only. Meaning it cannot be written to, only read. code_samples: [] type: int tags: - ReadOnly - NotReplicated - Deprecated deprecation_message: | This item is deprecated. Instead, of using this item, you should count the number of players returned by `Class.Players:GetPlayers()`. security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Players - name: Players.numPlayers summary: | Returns the number of people in the server at the current time. description: | This property indicates the number of people in the server at the current time. It is read only. Meaning it cannot be written to, only read. code_samples: [] type: int tags: - Hidden - ReadOnly - NotReplicated - Deprecated deprecation_message: | This property is a deprecated variant of `Class.Players.NumPlayers` which has also been deprecated. Neither property should be used in new work. Instead, you should count the number of players returned by `Class.Players:GetPlayers()`. security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Players - name: Players.PreferredPlayers summary: | The preferred number of players for a server. description: | This property indicates the number of players to which Roblox's matchmaker will fill servers. This number will be less than the maximum number of players (`Class.Players.MaxPlayers`) supported by the experience. code_samples: [] type: int tags: - ReadOnly - NotReplicated deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Players - name: Players.RespawnTime summary: | Controls the amount of time taken for a players character to respawn. description: | This property controls the time, in seconds, it takes for a player to respawn when `Class.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 experience but don't want to handle spawning players individually. Although this property can be set from within a `Class.Script`, you can more easily set it directly on the `Class.Players` object in Studio's [Explorer](../../../studio/explorer.md) window. code_samples: [] type: float tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: true can_save: true capabilities: - Players - name: Players.UseStrafingAnimations summary: '' description: '' code_samples: [] type: boolean tags: - NotScriptable deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Behavior serialization: can_load: true can_save: true capabilities: - Players methods: - name: Players:BanAsync summary: | Bans users from your experience, with options to specify duration, reason, whether the ban applies to the entire universe or just the current place, and more. This method is enabled and disabled by the `Class.Players.BanningEnabled` property, which you can toggle in Studio. description: | The `Class.Players:BanAsync()` method allows you to easily ban users who violate your experience's guidelines. You can specify the ban duration, enable the ban to propagate to suspected alternate accounts, and provide a message to the banned user in accordance with the [Usage Guidelines](../../../players/index.md#banning-users). You should also post your experience rules somewhere accessible to all users and provide a way for them to appeal. This method is enabled and disabled by the `Class.Players.BanningEnabled` property, which you can toggle in Studio. ##### Banning and Messaging Banned users will be immediately evicted and prevented from rejoining your experiences. They will be presented with an error modal displaying the time left on their ban and your `DisplayReason`. Roblox's backend systems will evict players across all servers from the place(s) that you specify. `DisplayReason` can have a maximum length of 400 characters and is subject to a text filter. For more information on acceptable modal text, see [ban messaging](../../../players/index.md#message-guidelines). ##### Places and Universe By default, bans extend to any place within that universe. To limit the ban to only the place from which this API is called, configure `ApplyToUniverse` to `false`. However, if a user is banned in the start place of the universe, it effectively results in the user being excluded from the entirety of the universe, irrespective of whether a universal ban is in place or not. ##### Alternative Accounts Users often play under multiple different accounts, known as alternate accounts or alt accounts, which are sometimes used to circumvent account bans. To help you keep banned users out, the default behavior of this API will propagate all bans from the source account you banned to any of their suspected alt accounts. You can turn off ban propagations to alt accounts by configuring `ExcludeAltAccounts` to `true`. ##### Ban Duration Not all transgressions are the same, so not all bans should be the same length. This API lets you configure the duration of the ban, in seconds, with the `Duration` field. To specify a permanent ban, set the field to `-1`. You may also want to dynamically configure the ban duration based on the user's ban history, which you can query for using `Class.Players:GetBanHistoryAsync()`. For example, you may want to consider the number of bans, the duration of previous bans, or build logic off of the notes you save under `PrivateReason` which can be up to 1000 characters and are not text filtered. `PrivateReason` notes are never shared with the client and can be considered safe from attackers. ##### Errors and Throttling This method invokes an HTTP call to backend services which are subject to throttling and may fail. If you're calling this API with more than one `Class.Player.UserId|UserId`, this method will attempt to make the HTTP call for each ID. It will then aggregate any error messages and join them as a comma separated list. For example, if this method is invoked for five users and requests for those with `Class.Player.UserId|UserIds` 2 and 4 fail, the following error message appears: `HTTP failure for UserId 2: Timedout, HTTP 504 (Service unavailable) failure for UserId 4: Service exception` The message will always include `failure for UserId {}` if it is an HTTP error. ##### Client-Side Requirement Because of the risks associated with banning users, this method may only be called on the backend experience server (client-side calls will result in an error). You may test this API in Studio, during [collaborative](../../../projects/collaboration.md) creation, or in a [team test](../../../studio/testing-modes.md#collaborative-testing), but the bans will not apply to production. This API uses the [User Restrictions Open Cloud API](/cloud/reference/UserRestriction). You will be able to utilize these APIs to manage your bans in third party applications. code_samples: - Players-Ban parameters: - name: config type: Dictionary default: summary: | - `UserIds` (required; array) — Array of `Class.Player.UserId|UserIds` of players to be banned. Max size is `50`. - `ApplyToUniverse` (optional; boolean) — Whether ban propagates to all places within the experience universe. Default is `true`. - `Duration` (required; integer) — Duration of the ban, in seconds. Permanent bans should have a value of `-1`. `0` and all other negative values are invalid. - `DisplayReason` (required; string) — The message that will be displayed to users when they attempt to and fail to join an experience. Maximum string length is `400`. - `PrivateReason` (required; string) — Internal messaging that will be returned when querying the user's ban history. Maximum string length is `1000`. - `ExcludeAltAccounts` (optional; boolean) — When `true`, Roblox does not attempt to ban alt accounts. Default is `false`. returns: - type: () summary: '' tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - Consequences - name: Players:Chat summary: | Makes the local player chat the given message. description: | This function makes the local player chat the given message. Since this item is protected, attempting to use it in a `Class.Script` or `Class.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 `Class.Chat` service's `Class.Chat:Chat()` function instead. code_samples: - Players-Chat1 parameters: - name: message type: string default: summary: | The message chatted. returns: - type: () summary: '' tags: [] deprecation_message: '' security: PluginSecurity thread_safety: Unsafe capabilities: - Players - name: Players:CreateHumanoidModelFromDescriptionAsync summary: | Returns a character `Class.Model` equipped with everything specified in the passed in `Class.HumanoidDescription`. description: | Returns a character `Class.Model` equipped with everything specified in the passed in `Class.HumanoidDescription`, and is R6 or R15 as specified by `rigType`. code_samples: - create-humanoid-model-from-description parameters: - name: description type: HumanoidDescription default: summary: | Specifies the appearance of the returned character. - name: rigType type: HumanoidRigType default: summary: | Specifies whether the returned character will be R6 or R15. - name: assetTypeVerification type: AssetTypeVerification default: Default summary: | The asset type verification mode. returns: - type: Model summary: | A `Class.Humanoid` character `Class.Model`. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Avatar - Players - name: Players:CreateHumanoidModelFromDescription summary: | Returns a character `Class.Model` equipped with everything specified in the passed in `Class.HumanoidDescription`. description: '' code_samples: [] parameters: - name: description type: HumanoidDescription default: summary: | Specifies the appearance of the returned character. - name: rigType type: HumanoidRigType default: summary: | Specifies whether the returned character will be R6 or R15. - name: assetTypeVerification type: AssetTypeVerification default: Default summary: | The asset type verification mode. returns: - type: Model summary: | A `Class.Humanoid` character `Class.Model`. tags: - Yields - Deprecated deprecation_message: | This method has been superseded by `Class.Players:CreateHumanoidModelFromDescription()|CreateHumanoidModelFromDescription()`. security: None thread_safety: Unsafe capabilities: - Avatar - Players - name: Players:CreateHumanoidModelFromUserIdAsync summary: | Returns a character Model set-up with everything equipped to match the avatar of the user specified by the passed in userId. description: | 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. code_samples: - create-humanoid-model-from-userid parameters: - name: userId type: int64 default: summary: | The userId for a Roblox user. (The UserId is the number in the profile of the user e.g www.roblox.com/users/1/profile). returns: - type: Model summary: | A Humanoid character Model. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - name: Players:CreateHumanoidModelFromUserId summary: | Returns a character Model set-up with everything equipped to match the avatar of the user specified by the passed in userId. description: '' code_samples: - create-humanoid-model-from-userid parameters: - name: userId type: int64 default: summary: | The userId for a Roblox user. (The UserId is the number in the profile of the user e.g www.roblox.com/users/1/profile). returns: - type: Model summary: | A Humanoid character Model. tags: - Yields - Deprecated deprecation_message: | This method has been superseded by `Class.Players:CreateHumanoidModelFromUserIdAsync()|CreateHumanoidModelFromUserIdAsync()`. security: None thread_safety: Unsafe capabilities: - Players - name: Players:GetBanHistoryAsync summary: | Retrieves the ban and unban history of any user within the experience's universe. This method is enabled and disabled by the `Class.Players.BanningEnabled` property, which you can toggle in Studio. description: | Retrieves the ban and unban history of any user within the experience's universe. This method returns a `Class.BanHistoryPages` instance that inherits from `Class.Pages`. This method is enabled and disabled by the `Class.Players.BanningEnabled` property, which you can toggle in Studio. This function call will only succeed on production servers and not on client devices or in Studio. This API uses the [User Restrictions Open Cloud API](/cloud/reference/UserRestriction). You will be able to utilize these APIs to manage your bans in third party applications. code_samples: [] parameters: - name: userId type: int64 default: summary: '' returns: - type: BanHistoryPages summary: | See `Class.BanHistoryPages` for return reference. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - Consequences - name: Players:GetCharacterAppearanceAsync summary: | Returns a `Class.Model` containing the assets which the player is wearing, excluding gear. description: | This function returns a `Class.Model` containing the assets which the player is wearing, excluding gear. If you prefer a Luau table of information about these assets instead of a model, use `Class.Players:GetCharacterAppearanceInfoAsync()`. This method behaves similar to `Class.InsertService:LoadAsset()`, and is like using `Class.InsertService:LoadAsset()|LoadAsset` on the asset information returned by `Class.Players:GetCharacterAppearanceInfoAsync()` except faster. code_samples: - how-to-get-a-character-s-appearance parameters: - name: userId type: int64 default: summary: | The `Class.Player.UserId` of the specified player. returns: - type: Model summary: '' tags: - Yields - Deprecated deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - name: Players:GetCharacterAppearanceInfoAsync summary: | Returns information about the character appearance of a given user. description: | This function returns information about a player's avatar on the Roblox website in the form of a dictionary. It is not to be confused with `Class.Players:GetCharacterAppearanceAsync()|GetCharacterAppearanceAsync`, which actually loads the assets described by this method. You can use `Class.InsertService:LoadAsset()` to load the assets that are used in the player's avatar. The structure of the returned dictionary is as follows:
Name Type Description
assets table (see below) Describes the equipped assets (hats, body parts, etc)
bodyColors table (see below) Describes the BrickColor values for each limb
bodyColor3s table (see below) Describes the Color3 instance for each limb which may not match perfectly with bodyColors
defaultPantsApplied bool Describes whether default pants are applied
defaultShirtApplied bool Describes whether default shirt is applied
emotes table (see below) Describes the equipped emote animations
playerAvatarType string Either "R15" or "R6"
scales table (see below) Describes various body scaling factors
##### Assets Sub-Table The `assets` table is an array of tables containing the following keys that describe the assets currently equipped by the player:
Name Type Description
id number The asset ID of the equipped asset
assetType table A table with name and id fields, each describing the kind of asset equipped ("Hat", "Face", etc.)
name string The name of the equipped asset
##### Scales Sub-Table The `scales` table has the following keys, each a number corresponding to one `Class.Humanoid` scaling property: `bodyType`, `head`, `height`, `proportion`, `depth`, `width`. ##### Body Colors Sub-Table The `bodyColors` table has the following keys, each a number corresponding to a `Datatype.BrickColor` ID number which can be used with `Datatype.BrickColor.new(id)`: `leftArmColorId`, `torsoColorId`, `rightArmColorId`, `headColorId`, `leftLegColorId`, `rightLegColorId`. code_samples: - example-return-dictionary parameters: - name: userId type: int64 default: summary: | The \*_userId_ of the specified player. returns: - type: Dictionary summary: | A dictionary containing information about the character appearance of a given user. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - name: Players:GetFriendsAsync summary: | Returns a `Class.FriendPages` object which contains information for all of the given player's connections. description: | The GetFriends `Class.Players` function returns a `Class.FriendPages` object which contains information for all of the given user's connections. The items within the `Class.FriendPages` object are tables with the following fields:
Name Type Description
Id int64 The connections's UserId
Username string The connections's username
DisplayName string The Class.Player.DisplayName|display name of the connections.
See the code samples for an easy way to iterate over all a player's connections. code_samples: - print-roblox-friends parameters: - name: userId type: int64 default: summary: | The user ID of the player being specified. returns: - type: FriendPages summary: '' tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - Social - name: Players:GetHumanoidDescriptionFromOutfitIdAsync summary: | Returns the HumanoidDescription for a specified outfit, which will be set with the parts/colors/Animations etc of the outfit. description: | 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. code_samples: - get-humanoiddescription-from-outfitid parameters: - name: outfitId type: int64 default: summary: | The ID of the outfit for which the HumanoidDescription is sought. returns: - type: HumanoidDescription summary: | HumanoidDescription initialized with the specification for the passed in outfitId. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Avatar - Players - name: Players:GetHumanoidDescriptionFromOutfitId summary: | Returns the HumanoidDescription for a specified outfit, which will be set with the parts/colors/Animations etc of the outfit. description: '' code_samples: - get-humanoiddescription-from-outfitid parameters: - name: outfitId type: int64 default: summary: | The ID of the outfit for which the HumanoidDescription is sought. returns: - type: HumanoidDescription summary: | HumanoidDescription initialized with the specification for the passed in outfitId. tags: - Yields - Deprecated deprecation_message: | This method has been superseded by `Class.Players:GetHumanoidDescriptionFromOutfitIdAsync()|GetHumanoidDescriptionFromOutfitIdAsync()`. security: None thread_safety: Unsafe capabilities: - Avatar - Players - name: Players:GetHumanoidDescriptionFromUserIdAsync summary: | Returns a HumanoidDescription which specifies everything equipped for the avatar of the user specified by the passed in userId. description: | 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. code_samples: - get-humanoiddescription-from-userid parameters: - name: userId type: int64 default: summary: | The userId for a Roblox user. (The UserId is the number in the profile of the user e.g www.roblox.com/users/1/profile). returns: - type: HumanoidDescription summary: | HumanoidDescription initialized with the passed in user's avatar specification. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Avatar - Players - name: Players:GetHumanoidDescriptionFromUserId summary: | Returns a HumanoidDescription which specifies everything equipped for the avatar of the user specified by the passed in userId. description: '' code_samples: - get-humanoiddescription-from-userid parameters: - name: userId type: int64 default: summary: | The userId for a Roblox user. (The UserId is the number in the profile of the user e.g www.roblox.com/users/1/profile). returns: - type: HumanoidDescription summary: | HumanoidDescription initialized with the passed in user's avatar specification. tags: - Yields - Deprecated deprecation_message: | This method has been superseded by `Class.Players.GetHumanoidDescriptionFromUserIdAsync|GetHumanoidDescriptionFromUserIdAsync()`. security: None thread_safety: Unsafe capabilities: - Avatar - Players - name: Players:GetNameFromUserIdAsync summary: | Sends a query to the Roblox website for the username of an account with a given `Class.Player.UserId|UserId`. description: | The GetNameFromUserIdAsync `Class.Players` function will send a query to the Roblox website asking what the username is of the account with the given `Class.Player.UserId|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 `Global.LuaGlobals.pcall()`. In addition, you can manually cache results to make future calls with the same UserId fast. See the code samples to learn more. code_samples: - Name-From-UserId - Name-From-UserId-Cache parameters: - name: userId type: int64 default: summary: | The `Class.Player.UserId` of the player being specified. returns: - type: string summary: | The name of a user with the specified `Class.Player.UserId`. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - name: Players:GetPlayerByUserId summary: | Returns the `Class.Player` with the given `Class.Player.UserId|UserId` if they are in-experience. description: | This function searches each `Class.Player` in `Class.Players` for one whose `Class.Player.UserId` matches the given `userId`. If such a player does not exist, it returns `nil`. This method is useful in finding the purchaser of a developer product using `Class.MarketplaceService.ProcessReceipt` which provides a table that includes the purchaser's `Class.Player.UserId|UserId` and not a reference to the `Class.Player` object itself. Most experiences will require a reference to the player in order to grant products. code_samples: - Players-GetPlayerByUserId1 parameters: - name: userId type: int64 default: summary: | The `Class.Player.UserId` of the player being specified. returns: - type: Player summary: '' tags: [] deprecation_message: '' security: None thread_safety: Safe capabilities: - Players - name: Players:GetPlayerFromCharacter summary: | Returns the `Class.Player` whose `Class.Player.Character` matches the given instance, or `nil` if one cannot be found. description: | This function returns the `Class.Player` associated with the given `Class.Player.Character`, or `nil` if one cannot be found. It is equivalent to the following function: ```lua local function getPlayerFromCharacter(character) for _, player in game:GetService("Players"):GetPlayers() do if player.Character == character then return player end end end ``` This method is often used when some event in player's character fires (such as their `Class.Humanoid` `Class.Humanoid.Died|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. code_samples: - Players-GetPlayerFromCharacter1 parameters: - name: character type: Model default: summary: | A character instance that you want to get the player from. returns: - type: Player summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - name: Players:GetPlayers summary: | Returns a table of all presently connected `Class.Player` objects. description: | This method returns a table of all presently connected `Class.Player` objects. It functions the same way `Class.Instance:GetChildren()` would except that it only returns `Class.Player` objects found under `Class.Players`. When used with a `for` loop, it is useful for iterating over all players in an experience. ```lua local Players = game:GetService("Players") for _, player in Players:GetPlayers() do print(player.Name) end ``` Scripts that connect to `Class.Players.PlayerAdded` are often trying to process every Player that connects to the experience. This method is useful for iterating over already-connected players that wouldn't fire `Class.Players.PlayerAdded|PlayerAdded`. Using this method ensures that no player is missed! ```lua local Players = game:GetService("Players") local function onPlayerAdded(player) print("Player: " .. player.Name) end for _, player in Players:GetPlayers() do onPlayerAdded(player) end Players.PlayerAdded:Connect(onPlayerAdded) ``` code_samples: - Give-Sparkles-to-Everyone parameters: [] returns: - type: Instances summary: | A table containing all the players in the server. tags: [] deprecation_message: '' security: None thread_safety: Safe capabilities: - Players - name: Players:getPlayers summary: '' description: '' code_samples: [] parameters: [] returns: - type: Instances summary: '' tags: - Deprecated deprecation_message: | This function is a deprecated variant of `Class.Players:GetPlayers()` which should be used instead. security: None thread_safety: Unsafe capabilities: - Players - name: Players:GetUserIdFromNameAsync summary: | Sends a query to the Roblox website for the `Class.Player.UserId|userId` of an account with a given username. description: | This function will send a query to the Roblox website asking what the `Class.Player.UserId` is of the account with the given `Class.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 `Global.LuaGlobals.pcall()`. In addition, you can manually cache results to quickly make future calls with the same username. See the code samples to learn more. code_samples: - UserId-From-Name - UserId-From-Name-Cache parameters: - name: userName type: string default: summary: | The username of the player being specified. returns: - type: int64 summary: | The `Class.Player.UserId` of a user whose name is specified. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - name: Players:GetUserThumbnailAsync summary: | Returns the content URL of a player thumbnail given the size and type, as well as a boolean describing if the image is ready to use. description: | This function returns the content URL of an image of a player's avatar given their `Class.Player.UserId|UserId`, the desired image size as a `Enum.ThumbnailSize` enum, and the desired type as a `Enum.ThumbnailType` enum. It also returns a boolean describing if the image is ready to use. Most often, this method is used with `Class.ImageLabel.Image` or `Class.Decal.Texture` to display user avatar pictures in an experience. code_samples: - display-player-thumbnail parameters: - name: userId type: int64 default: summary: | The `Class.Player.UserId` of the player being specified. - name: thumbnailType type: ThumbnailType default: summary: | A `Enum.ThumbnailType` describing the type of thumbnail. - name: thumbnailSize type: ThumbnailSize default: summary: | A `Enum.ThumbnailSize` specifying the size of the thumbnail. returns: - type: Tuple summary: | A tuple containing the content URL of a user thumbnail based on the specified parameters, and a bool describing if the image is ready to be used or not. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - name: Players:playerFromCharacter summary: '' description: '' code_samples: [] parameters: - name: character type: Model default: summary: '' returns: - type: Player summary: '' tags: - Deprecated deprecation_message: | This function is a deprecated variant of `Class.Players:GetPlayerFromCharacter()` which should be used in new work. security: None thread_safety: Unsafe capabilities: - Players - name: Players:players summary: | Returns a list of players in an experience. description: | This function was once used to return a list of players in an experience, but has since been deprecated in favor of `Class.Players:GetPlayers()` code_samples: [] parameters: [] returns: - type: Instances summary: '' tags: - Deprecated deprecation_message: | This item has been superseded by `Class.Players:GetPlayers()` which should be used in all new work. security: None thread_safety: Unsafe capabilities: - Players - name: Players:SetChatStyle summary: | Sets whether BubbleChat and ClassicChat are being used, and tells TeamChat and `Class.Chat` what to do. description: | This function sets whether BubbleChat and ClassicChat are being used, and tells TeamChat and Chat what to do using the `Enum.ChatStyle` enum. Since this item is protected, attempting to use it in a `Class.Script` or `Class.LocalScript` will cause an error. This function is used internally when the chat mode is set by the experience. code_samples: - setting-a-player-s-chat-style parameters: - name: style type: ChatStyle default: Classic summary: | The specified chat style being set. returns: - type: () summary: '' tags: [] deprecation_message: '' security: PluginSecurity thread_safety: Unsafe capabilities: - Players - name: Players:TeamChat summary: | Makes the local player chat the given message, which will only be viewable by users on the same team. description: | This function makes the `Class.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 `Class.Script` or `Class.LocalScript` will cause an error. This function is used internally when the `Class.Players.LocalPlayer` sends a message to their team. code_samples: - sending-team-chat parameters: - name: message type: string default: summary: | The message being chatted. returns: - type: () summary: '' tags: [] deprecation_message: '' security: PluginSecurity thread_safety: Unsafe capabilities: - Players - name: Players:UnbanAsync summary: | Unbans players banned from `Class.Players:BanAsync()` or the User Restrictions Open Cloud API. This method is enabled and disabled by the `Class.Players.BanningEnabled` property, which you can toggle in Studio. description: | Unbans players banned from `Class.Players:BanAsync()` or the [User Restrictions Open Cloud API](/cloud/reference/UserRestriction). This method is enabled and disabled by the `Class.Players.BanningEnabled` property, which you can toggle in Studio. Like `Class.Players:BanAsync()`, this method takes in a `config` dictionary that will let you bulk unban users. This configures the users that are unbanned and the scope from which they are unbanned from. Unbans will only take effect on bans with the same `ApplyToUniverse` scope. For example, an unban with `ApplyToUniverse` set to `true` will not invalidate a previous ban with `ApplyToUniverse` set to `false`. In other words, a universe level unban will not invalidate a place level ban. The opposite also holds true. This method invokes a HTTP call to backend services, which are throttled and may fail. If you are calling this API with multiple UserIds, this method will attempt to make this HTTP call for each UserId. It will then aggregate any error messages and join them as a comma separated list. For example, if this method is invoked for five `UserIds`: `{1, 2, 3, 4, 5}` and requests for users 2 and 4 fail then the following error message appears: `HTTP failure for UserId 2: Timedout, HTTP 504 (Service unavailable) failure for UserId 4: Service exception.` The message will always include `failure for UserId {}` if it is an HTTP error. It is undefined behavior if you pass in both valid and invalid UserIds, i.e. a `UserId` that is not a positive number, as some network requests may succeed before all input is validated. Because of the risks associated with banning users, this method may only be called on the backend server. Client side calls will result in an error. You may test this API in Studio, Team Create, and Team Test, but the bans will not apply to production. This function call will only attempt ban requests on production servers and not in Studio testing. However, all input validation steps will still work in Studio. This API uses the [User Restrictions Open Cloud API](/cloud/reference/UserRestriction). You will be able to utilize these APIs to manage your bans in third party applications. code_samples: - Players-Unban parameters: - name: config type: Dictionary default: summary: |
Name Type Description
UserIds array UserIDs to be force allowed into the experience(s).

Max size is 50.
ApplyToUniverse boolean Propagates the unban to all places within this universe.
returns: - type: () summary: '' tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Players - Consequences events: - name: Players.PlayerAdded summary: | Fires when a player enters the experience. description: | This event fires when a player enters the experience, such as loading the player's saved `Class.GlobalDataStore` data. This can be used alongside the `Class.Players.PlayerRemoving` event, which fires when a player is about to leave the experience. For instance, if you would like print a message every time a new player joins or leaves: ```lua local Players = game:GetService("Players") Players.PlayerAdded:Connect(function(player) print(player.Name .. " joined the experience!") end) Players.PlayerRemoving:Connect(function(player, reason) print(player.Name .. " left the experience! Reason: " .. tostring(exitReason)) end) ``` If you want to track when a player's character is added or removed from the experience, such as when a player respawns or dies, you can use the `Class.Player.CharacterAdded` and `Class.Player.CharacterRemoving` functions. Note that this event does not work as expected in a solo playtest mode because the player is created before scripts run that connect to `Class.Players.PlayerAdded|PlayerAdded`. To handle this case, as well as cases in which the script is added into the experience after a player enters, create an `onPlayerAdded()` function that you can call to handle a player's entrance. code_samples: - Players-PlayerAdded1 parameters: - name: player type: Player default: summary: | An instance of the player that joined the experience. tags: [] deprecation_message: '' security: None capabilities: - Players - name: Players.PlayerMembershipChanged summary: | Fires when the experience server recognizes that a player's membership has changed. description: | This event fires when the experience 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 experience 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 server will update their membership and trigger this event. To learn more about and incorporating Premium into your experience and monetizing with the engagement-based payouts system, see [Engagement-Based Payouts](../../../production/monetization/engagement-based-payouts.md). See also: - `Class.MarketplaceService:PromptPremiumPurchase()`, used to prompt a user to purchase Premium - `Class.MarketplaceService.PromptPremiumPurchaseFinished`, fires when the Premium purchase UI closes code_samples: - handling-premium-membership-changes parameters: - name: player type: Player default: summary: '' tags: [] deprecation_message: '' security: None capabilities: - Players - name: Players.PlayerRemoving summary: | Fires when a player is about to leave the experience. description: | This event fires right before a `Class.Player` leaves the experience, before `Class.Instance.ChildRemoved|ChildRemoved` fires on `Class.Players`, and behaves somewhat similarly to `Class.Instance.DescendantRemoving`. Since it fires before the actual removal of a `Class.Player`, this event is useful for storing player data using a `Class.GlobalDataStore`. This can be used alongside the `Class.Player.PlayerAdded` event, which fires when a player joins the experience. For instance, to print a message every time a new player joins or leaves: ```lua local Players = game:GetService("Players") Players.PlayerAdded:Connect(function(player) print(player.Name .. " joined the experience!") end) Players.PlayerRemoving:Connect(function(player, exitReason) print(player.Name .. " left the experience! - Reason: " .. tostring(exitReason)) end) ``` If you want to track when a player's character is added or removed from the experience, such as when a player respawns or dies, you can use the `Class.Player.CharacterAdded` and `Class.Player.CharacterRemoving` functions. code_samples: - Players-PlayerRemoving1 parameters: - name: player type: Player default: summary: | An instance of the player that is leaving. - name: reason type: PlayerExitReason default: summary: | Enum.PlayerExitReason in attempt to inform why. tags: [] deprecation_message: '' security: None capabilities: - Players - name: Players.UserSubscriptionStatusChanged summary: | Fires when the experience server recognizes that the user's status for a certain subscription has changed. description: | This event fires when the experience server recognizes that the user's status for a certain subscription has changed. Note that the server only attempts to check and update the status **after** the Subscription Purchase modal has been closed. To account for cases in which the user purchases the subscription **outside** of the experience while playing, you must still prompt them to purchase the subscription; the prompt shows a message telling the user they're already subscribed, and after they close the modal, the server updates their subscription status and triggers this event. Note that only server scripts receive this event. code_samples: [] parameters: - name: user type: Player default: summary: | User whose subscription status has changed. - name: subscriptionId type: string default: summary: | The ID of the subscription with a status change. tags: [] deprecation_message: '' security: None capabilities: - Players - Monetization callbacks: []