37 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Players

Inherits from: Instance → Object

The Players service contains 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, friends, and avatar thumbnail.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service

Properties

Inherited from Instance

Inherited from Object

Players.BanningEnabled

Enables or disables the three Players methods (BanAsync(), UnbanAsync(), and GetBanHistoryAsync()) that constitute the ban API. This property cannot be set through developer-facing Luau and must be set in Studio through the Players properties window.

Players.BubbleChat

This 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 experience 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.

Players.CharacterAutoLoads

This property indicates whether characters will respawn automatically. The default value is true.

If this property is disabled (false), player characters will not spawn until the Player:LoadCharacterAsync() function is called for each 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: View on Creator Hub (player-respawn-timer).

Players.ClassicChat

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 experience 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.

Players.LocalPlayer

This read-only property refers to the Player whose client is running the experience.

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

Players.localPlayer

Deprecated. This property is a deprecated variant of Players.LocalPlayer which should be used instead.

Players.MaxPlayers

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.

Players.NumPlayers

Deprecated. This item is deprecated. Instead, of using this item, you should count the number of players returned by Players:GetPlayers().

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.

Players.numPlayers

Deprecated. This property is a deprecated variant of 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 Players:GetPlayers().

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.

Players.PreferredPlayers

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 (Players.MaxPlayers) supported by the experience.

Players.RespawnTime

This 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 experience but don't want to handle spawning players individually.

Although this property can be set from within a Script, you can more easily set it directly on the Players object in Studio's Explorer window.

Players.UseStrafingAnimations

When enabled, R15 character Humanoids play directional locomotion animations, strafing sideways and backpedaling while keeping their current facing direction instead of rotating to face whichever direction they move. When disabled, characters turn to face their direction of movement. Defaults to false.

This property cannot be set through developer-facing Luau and must be set in Studio through the Players properties window.

Methods

Inherited from Instance

Inherited from Object

Players:BanAsync

The 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, enable the ban to temporarily block the banned user's device from rejoining the experience, and provide a message to the banned user in accordance with the Usage Guidelines. 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 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.

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, 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 alternate accounts. You can turn off ban propagations to alternate accounts by configuring ExcludeAltAccounts to true.

Device Blocks

To help address disruptive users who circumvent alternate account detection, set ApplyDeviceBlock to true. This blocks the banned user's device from rejoining the experience for 24 hours after the ban is applied.

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 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 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 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 creation, or in a team test, but the bans will not apply to production.

This API uses the User Restrictions Open Cloud API. You will be able to utilize these APIs to manage your bans in third party applications.

Parameters

Returns

Code samples: View on Creator Hub (Players-Ban).

Players:Chat

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.

Parameters

Returns

Code samples: View on Creator Hub (Players-Chat1).

Players:CreateHumanoidModelFromDescription

Deprecated. This method has been superseded by CreateHumanoidModelFromDescriptionAsync().

Returns a character Model equipped with everything specified in the passed in HumanoidDescription, and is R6 or R15 as specified by rigType. This method has been superseded by CreateHumanoidModelFromDescriptionAsync(), which should be used in new work.

Parameters

Returns

Players:CreateHumanoidModelFromDescriptionAsync

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

Parameters

Returns

Code samples: View on Creator Hub (create-humanoid-model-from-description).

Players:CreateHumanoidModelFromUserId

Deprecated. This method has been superseded by CreateHumanoidModelFromUserIdAsync().

Returns a character Model set up with everything equipped to match the avatar of the user specified by the passed in userId, including whether that character is currently R6 or R15. This method has been superseded by CreateHumanoidModelFromUserIdAsync(), which should be used in new work.

Parameters

Returns

Code samples: View on Creator Hub (create-humanoid-model-from-userid).

Players:CreateHumanoidModelFromUserIdAsync

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.

Parameters

Returns

Code samples: View on Creator Hub (create-humanoid-model-from-userid).

Players:GetBanHistoryAsync

Retrieves the ban and unban history of any user within the experience's universe. This method returns a BanHistoryPages instance that inherits from Pages. This method is enabled and disabled by the 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. You will be able to utilize these APIs to manage your bans in third party applications.

Parameters

Returns

Players:GetCharacterAppearanceAsync

Deprecated. This method is deprecated. Do not use it for new work.

This function returns a 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 Players:GetCharacterAppearanceInfoAsync().

This method behaves similar to InsertService:LoadAsset(), and is like using LoadAsset on the asset information returned by Players:GetCharacterAppearanceInfoAsync() except faster.

Parameters

Returns

Code samples: View on Creator Hub (how-to-get-a-character-s-appearance).

Players:GetCharacterAppearanceInfoAsync

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 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 bodyColors table has the following keys, each a number corresponding to a BrickColor ID number which can be used with BrickColor.new(id): leftArmColorId, torsoColorId, rightArmColorId, headColorId, leftLegColorId, rightLegColorId.

Parameters

Returns

Code samples: View on Creator Hub (example-return-dictionary).

Players:GetFriendsAsync

The GetFriends Players function returns a FriendPages object which contains information for all of the given user'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.

Parameters

Returns

Code samples: View on Creator Hub (print-roblox-friends).

Players:GetHumanoidDescriptionFromOutfitId

Deprecated. This method has been superseded by GetHumanoidDescriptionFromOutfitIdAsync().

Returns the HumanoidDescription for the specified outfitId, set with the parts, colors, animations, and other properties of the outfit. An outfit can be one created by a user, or the outfit for a bundle created by Roblox. This method has been superseded by GetHumanoidDescriptionFromOutfitIdAsync(), which should be used in new work.

Parameters

Returns

Code samples: View on Creator Hub (get-humanoiddescription-from-outfitid).

Players:GetHumanoidDescriptionFromOutfitIdAsync

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.

Parameters

Returns

Code samples: View on Creator Hub (get-humanoiddescription-from-outfitid).

Players:GetHumanoidDescriptionFromUserId

Deprecated. This method has been superseded by GetHumanoidDescriptionFromUserIdAsync().

Returns a HumanoidDescription which specifies everything equipped for the avatar of the user specified by the passed in userId, including scales and body colors. This method has been superseded by GetHumanoidDescriptionFromUserIdAsync(), which should be used in new work.

Parameters

Returns

Code samples: View on Creator Hub (get-humanoiddescription-from-userid).

Players:GetHumanoidDescriptionFromUserIdAsync

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.

Parameters

Returns

Code samples: View on Creator Hub (get-humanoiddescription-from-userid).

Players:GetNameFromUserIdAsync

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 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.

Parameters

Returns

Code samples: View on Creator Hub (Name-From-UserId, Name-From-UserId-Cache).

Players:GetPlayerByUserId

This function searches each Player in Players for one whose 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 MarketplaceService.ProcessReceipt which provides a table that includes the purchaser's UserId and not a reference to the Player object itself. Most experiences will require a reference to the player in order to grant products.

Parameters

Returns

Code samples: View on Creator Hub (Players-GetPlayerByUserId1).

Players:GetPlayerFromCharacter

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:

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 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.

Parameters

Returns

Code samples: View on Creator Hub (Players-GetPlayerFromCharacter1).

Players:GetPlayers

This method returns a table of all presently connected Player objects. It functions the same way Instance:GetChildren() would except that it only returns Player objects found under Players. When used with a for loop, it is useful for iterating over all players in an experience.

local Players = game:GetService("Players")

for _, player in Players:GetPlayers() do
	print(player.Name)
end

Scripts that connect to 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 PlayerAdded. Using this method ensures that no player is missed!

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)

Returns

Code samples: View on Creator Hub (Give-Sparkles-to-Everyone).

Players:getPlayers

Deprecated. This function is a deprecated variant of Players:GetPlayers() which should be used instead.

Returns

Players:GetProfileConfigurationFromUserIdAsync

Returns the profile configuration of the user specified by the given Player.UserId as a dictionary. The dictionary can include a BackgroundAssetId field for the user's profile background asset ID and a FrameAssetId field for the user's profile frame image asset ID.

Can only be called from the server and is throttled to a limited number of requests per minute.

Parameters

Returns

Players:GetUserIdFromNameAsync

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 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.

Parameters

Returns

Code samples: View on Creator Hub (UserId-From-Name, UserId-From-Name-Cache).

Players:GetUserThumbnailAsync

This function returns the content URL of an image of a player's avatar given their UserId, the desired image size as a ThumbnailSize enum, and the desired type as a ThumbnailType enum. It also returns a boolean describing if the image is ready to use.

Most often, this method is used with ImageLabel.Image or Decal.Texture to display user avatar pictures in an experience.

Parameters

Returns

Code samples: View on Creator Hub (display-player-thumbnail).

Players:playerFromCharacter

Deprecated. This function is a deprecated variant of Players:GetPlayerFromCharacter() which should be used in new work.

Parameters

Returns

Players:players

Deprecated. This item has been superseded by Players:GetPlayers() which should be used in all new work.

This function was once used to return a list of players in an experience, but has since been deprecated in favor of Players:GetPlayers()

Returns

Players:SetChatStyle

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 experience.

Parameters

Returns

Code samples: View on Creator Hub (setting-a-player-s-chat-style).

Players:TeamChat

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.

Parameters

Returns

Code samples: View on Creator Hub (sending-team-chat).

Players:UnbanAsync

Unbans players banned from Players:BanAsync() or the User Restrictions Open Cloud API. This method is enabled and disabled by the Players.BanningEnabled property, which you can toggle in Studio.

Like 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.

For the case where a user's device may be blocked by a ban where ApplyDeviceBlock was set to true, an unban applied by this method will override the device block for the unbanned player. Please note that unbanning a user through any other method, such as the Open Cloud API or the Creator Hub, will not lift the device block.

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. You will be able to utilize these APIs to manage your bans in third party applications.

Parameters

Returns

Code samples: View on Creator Hub (Players-Unban).

Events

Inherited from Instance

Inherited from Object

Players.PlayerAdded

This event fires when a player enters the experience, 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 experience. For instance, if you would like print a message every time a new player joins or leaves:

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 Player.CharacterAdded and 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 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.

Parameters

Code samples: View on Creator Hub (Players-PlayerAdded1).

Players.PlayerMembershipChanged

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.

See also:

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

Parameters

Code samples: View on Creator Hub (handling-premium-membership-changes).

Players.PlayerRemoving

This event fires right before a Player leaves the experience, before ChildRemoved fires 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 experience. For instance, to print a message every time a new player joins or leaves:

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 Player.CharacterAdded and Player.CharacterRemoving functions.

Parameters

Code samples: View on Creator Hub (Players-PlayerRemoving1).

Players.UserSubscriptionStatusChanged

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.

Parameters