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

The BubbleChat 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 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:LoadCharacter() 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 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.

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.

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

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

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.

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

1
2
3
4
5
6
7
8

local Players = game:GetService("Players")
local function getPlayerByUserId(userId)
	for _, player in Players:GetPlayers() do
		if player.UserId == userId then
			return player
		end
	end
end

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:

1
2
3
4
5
6
7

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.

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

1
2
3
4
5

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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)