Players

Supported Class Services NotCreatable Service

A service that contains presently connected Player objects.

Note: Player lifecycle, character appearance, friends, and name lookup are present; some platform-only APIs are restricted.

49 Nova members · 27 modern Roblox members not implemented yet

Description

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.

Inheritance

Object → Instance → Players

Nova inheritance: Instance → Players

Properties

BubbleChat Supported Property Indicates whether or not bubble chat is enabled. It is set with the Players.SetChatStyle() method.

BubbleChat: bool

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.

Roblox documentation

CharacterAutoLoads Supported Property Indicates whether characters will respawn automatically.

CharacterAutoLoads: bool

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.

Roblox documentation

ClassicChat Supported Property Indicates whether or not classic chat is enabled; set by the Players.SetChatStyle() method.

ClassicChat: bool

Indicates whether or not classic chat is enabled; set by the Players.SetChatStyle() method.

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.

Roblox documentation

LocalPlayer Supported Property The Player that the LocalScript is running for.

LocalPlayer: Object

The Player that the LocalScript is running for.

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.

Roblox reference signature

LocalPlayer: Player

Roblox documentation

localPlayer Supported Property Deprecated

localPlayer: Object

No description available.

Roblox reference signature

localPlayer: Player

Nova behaviour: Nova keeps this legacy member for compatibility. Roblox's modern deprecation wording may describe later Roblox behaviour; verify it against Nova before relying on the copied text.

Roblox documentation

MaxPlayers Supported Property The maximum number of players that can be in a server.

MaxPlayers: int

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.

Roblox documentation

MaxPlayersInternal Supported Property

MaxPlayersInternal: int

No description available.

Security: LocalUserSecurity

Roblox documentation

NumPlayers Supported Property Deprecated Returns the number of people in the server at the current time.

NumPlayers: int

Returns the number of people in the server at the current time.

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.

Roblox documentation

numPlayers Supported Property Deprecated Returns the number of people in the server at the current time.

numPlayers: int

Returns the number of people in the server at the current time.

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.

Nova behaviour: Nova keeps this legacy member for compatibility. Roblox's modern deprecation wording may describe later Roblox behaviour; verify it against Nova before relying on the copied text.

Roblox documentation

PreferredPlayers Supported Property The preferred number of players for a server.

PreferredPlayers: int

The preferred number of players for a server.

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.

Roblox documentation

PreferredPlayersInternal Supported Property

PreferredPlayersInternal: int

No description available.

Security: LocalUserSecurity

Roblox documentation

Methods

AddLeaderboardKey Supported Function

Players:AddLeaderboardKey(string key)

No description available.

Security: LocalUserSecurity

Roblox documentation

BlockUser Supported Function

Players:BlockUser(int blockerUserId, int blockeeUserId): string

No description available.

Security: RobloxScriptSecurity

Roblox documentation

Chat Supported Function Makes the local player chat the given message.

Players:Chat(string message)

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.

Roblox reference signature

Players:Chat(message: string): null

Security: PluginSecurity

Roblox documentation

CreateLocalPlayer Supported Function

Players:CreateLocalPlayer(int userId, bool isTeleport = false): Instance

No description available.

Roblox reference signature

Players:CreateLocalPlayer(): Player

Security: PluginSecurity

Roblox documentation

GetCharacterAppearanceAsync Supported Function Deprecated Returns a Model containing the assets which the player is wearing, excluding gear.

Players:GetCharacterAppearanceAsync(int userId): Instance

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.

Roblox reference signature

Players:GetCharacterAppearanceAsync(userId: User): Model

Roblox documentation

GetFriendsAsync Supported Function Returns a FriendPages object which contains information for all of the given player's friends.

Players:GetFriendsAsync(int userId): Instance

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

Name	Type	Description
Id	int64	The friend's UserId
Username	string	The friend's username
DisplayName	string	The Class.Player.DisplayName|display name of the friend.

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

Roblox reference signature

Players:GetFriendsAsync(userId: User): FriendPages

Roblox documentation

GetNameFromUserIdAsync Supported Function Sends a query to the Roblox website for the username of an account with a given UserId.

Players:GetNameFromUserIdAsync(int userId): string

Sends a query to the Roblox website for the username of an account with a given UserId.

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

Roblox reference signature

Players:GetNameFromUserIdAsync(userId: User): string

Roblox documentation

GetPlayerByID Supported Function Deprecated

Players:GetPlayerByID(int userID): Instance

No description available.

Nova behaviour: Nova keeps this legacy member for compatibility. Roblox's modern deprecation wording may describe later Roblox behaviour; verify it against Nova before relying on the copied text.

Security: LocalUserSecurity

Roblox documentation

GetPlayerById Supported Function

Players:GetPlayerById(int userId): Instance

No description available.

Security: LocalUserSecurity

Roblox documentation

GetPlayerByUserId Supported Function Returns the Player with the given UserId if they are in-experience.

Players:GetPlayerByUserId(int userId): Instance

Returns the Player with the given UserId if they are in-experience.

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.

Roblox reference signature

Players:GetPlayerByUserId(userId: User): Player

Roblox documentation

GetPlayerFromCharacter Supported Function Returns the Player whose Player.Character matches the given instance, or nil if one cannot be found.

Players:GetPlayerFromCharacter(Instance character): Instance

Returns the Player whose Player.Character matches the given instance, or nil if one cannot be found.

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.

Roblox reference signature

Players:GetPlayerFromCharacter(character: Model): Player

Roblox documentation

getPlayerFromCharacter Supported Function Deprecated

Players:getPlayerFromCharacter(Instance character): Instance

No description available.

Nova behaviour: Nova keeps this legacy member for compatibility. Roblox's modern deprecation wording may describe later Roblox behaviour; verify it against Nova before relying on the copied text.

Roblox documentation

GetPlayers Supported Function Returns a table of all presently connected Player objects.

Players:GetPlayers(): Objects

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)

Roblox reference signature

Players:GetPlayers(): Instances

Roblox documentation

getPlayers Supported Function Deprecated

Players:getPlayers(): Objects

No description available.

Roblox reference signature

Players:getPlayers(): Instances

Nova behaviour: Nova keeps this legacy member for compatibility. Roblox's modern deprecation wording may describe later Roblox behaviour; verify it against Nova before relying on the copied text.

Roblox documentation

GetUseCoreScriptHealthBar Supported Function

Players:GetUseCoreScriptHealthBar(): bool

No description available.

Security: RobloxScriptSecurity

Roblox documentation

GetUserIdFromNameAsync Supported Function Sends a query to the Roblox website for the userId of an account with a given username.

Players:GetUserIdFromNameAsync(string userName): int

Sends a query to the Roblox website for the userId of an account with a given username.

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

Roblox reference signature

Players:GetUserIdFromNameAsync(userName: string): int64

Roblox documentation

playerFromCharacter Supported Function Deprecated

Players:playerFromCharacter(Instance character): Instance

No description available.

Roblox reference signature

Players:playerFromCharacter(character: Model): Player

Nova behaviour: Nova keeps this legacy member for compatibility. Roblox's modern deprecation wording may describe later Roblox behaviour; verify it against Nova before relying on the copied text.

Roblox documentation

players Supported Function Deprecated Nova: legacy alias Legacy alias of Players:GetPlayers().

Players:players(): Objects

Legacy alias of Players:GetPlayers().

Returns a list of players. In Nova this is a deprecated alias that calls the same implementation as GetPlayers().

Roblox reference signature

Players:players(): Instances

Nova behaviour: Still works; prefer GetPlayers() in new code.

Roblox documentation

ReportAbuse Supported Function

Players:ReportAbuse(Instance player, string reason, string optionalMessage)

No description available.

Roblox reference signature

Players:ReportAbuse(player: Player, reason: string, optionalMessage: string): null

Security: LocalUserSecurity

Roblox documentation

SetAbuseReportUrl Supported Function

Players:SetAbuseReportUrl(string url)

No description available.

Security: RobloxSecurity

Roblox documentation

SetBuildUserPermissionsUrl Supported Function

Players:SetBuildUserPermissionsUrl(string url)

No description available.

Security: RobloxSecurity

Roblox documentation

SetChatFilterUrl Supported Function

Players:SetChatFilterUrl(string url)

No description available.

Security: RobloxSecurity

Roblox documentation

SetChatStyle Supported Function Sets whether BubbleChat and ClassicChat are being used, and tells TeamChat and Chat what to do.

Players:SetChatStyle(ChatStyle style = Classic)

Sets whether BubbleChat and ClassicChat are being used, and tells TeamChat and Chat what to do.

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.

Roblox reference signature

Players:SetChatStyle(style: ChatStyle = Classic): null

Security: PluginSecurity

Roblox documentation

SetLoadDataUrl Supported Function

Players:SetLoadDataUrl(string url)

No description available.

Security: LocalUserSecurity

Roblox documentation

SetSaveDataUrl Supported Function

Players:SetSaveDataUrl(string url)

No description available.

Security: LocalUserSecurity

Roblox documentation

SetSaveLeaderboardDataUrl Supported Function

Players:SetSaveLeaderboardDataUrl(string url)

No description available.

Security: LocalUserSecurity

Roblox documentation

SetSysStatsUrl Supported Function

Players:SetSysStatsUrl(string url)

No description available.

Security: LocalUserSecurity

Roblox documentation

SetSysStatsUrlId Supported Function

Players:SetSysStatsUrlId(string urlId)

No description available.

Security: LocalUserSecurity

Roblox documentation

TeamChat Supported Function Makes the local player chat the given message, which will only be viewable by users on the same team.

Players:TeamChat(string message)

Makes the local player chat the given message, which will only be viewable by users on the same team.

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.

Roblox reference signature

Players:TeamChat(message: string): null

Security: PluginSecurity

Roblox documentation

UnblockUser Supported Function

Players:UnblockUser(int exblockerUserId, int exblockeeUserId): string

No description available.

Security: RobloxScriptSecurity

Roblox documentation

WhisperChat Supported Function

Players:WhisperChat(string message, Instance player)

No description available.

Roblox reference signature

Players:WhisperChat(message: string, player: Instance): null

Security: LocalUserSecurity

Roblox documentation

Events

FriendRequestEvent Supported Event

FriendRequestEvent(Instance player, Instance player, FriendRequestEvent friendRequestEvent)

No description available.

Roblox reference signature

FriendRequestEvent(player: Player, player: Player, friendRequestEvent: FriendRequestEvent)

Security: RobloxScriptSecurity

Roblox documentation

GameAnnounce Supported Event

GameAnnounce(string message)

No description available.

Security: RobloxScriptSecurity

Roblox documentation

PlayerAdded Supported Event Fires when a player enters the experience.

PlayerAdded(Instance player)

Fires when a player enters the experience.

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.

Roblox reference signature

PlayerAdded(player: Player)

Roblox documentation

PlayerAddedEarly Supported Event

PlayerAddedEarly(Instance player)

No description available.

Security: LocalUserSecurity

Roblox documentation

PlayerChatted Supported Event

PlayerChatted(PlayerChatType chatType, Instance player, string message, Instance targetPlayer)

No description available.

Roblox reference signature

PlayerChatted(chatType: PlayerChatType, player: Player, message: string, targetPlayer: Player)

Security: LocalUserSecurity

Roblox documentation

PlayerRemoving Supported Event Fires when a player is about to leave the experience.

PlayerRemoving(Instance player)

Fires when a player is about to leave the experience.

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.

Roblox reference signature

PlayerRemoving(player: Player, reason: PlayerExitReason)

Roblox documentation

PlayerRemovingLate Supported Event

PlayerRemovingLate(Instance player)

No description available.

Security: LocalUserSecurity

Roblox documentation

Inherited members

Inherited from Instance: 8 properties, 36 methods, 7 events. They are documented on the base class page.

27 modern Roblox member(s) are not implemented yet — expand to inspect

Members declared by Roblox's Players class (or by a missing base class) that Nova does not expose. Use this list to scope a migration; the compatibility guide has the recommended workaround.

Properties

Member	Signature	Status	Notes	Flags
RespawnTime	RespawnTime: float	Not yet	Controls the amount of time taken for a players character to respawn.	—

Methods

Member	Signature	Status	Notes	Flags
BanAsync	Players:BanAsync(config: Dictionary): null	Not yet	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 metho…	Yields
CreateHumanoidModelFromDescription	Players:CreateHumanoidModelFromDescription(description: HumanoidDescription, rigType: HumanoidRigType, assetTypeVerification: AssetTypeVerification = Default): Model	Not yet	Returns a character Model equipped with everything specified in the passed in HumanoidDescription.	Yields, PreferredDescriptorName, ThreadSafety, PreferredDes…
CreateHumanoidModelFromDescriptionAsync	Players:CreateHumanoidModelFromDescriptionAsync(description: HumanoidDescription, rigType: HumanoidRigType, assetTypeVerification: AssetTypeVerification = Default): Model	Not yet	Returns a character Model equipped with everything specified in the passed in HumanoidDescription. If `HumanoidDescription.UseAvata…	Yields
CreateHumanoidModelFromUserId	Players:CreateHumanoidModelFromUserId(userId: User): Model	Not yet	Returns a character Model set-up with everything equipped to match the avatar of the user specified by the passed in userId.	Yields, PreferredDescriptorName, ThreadSafety, PreferredDes…
CreateHumanoidModelFromUserIdAsync	Players:CreateHumanoidModelFromUserIdAsync(userId: User): Model	Not yet	Returns a character Model set-up with everything equipped to match the avatar of the user specified by the passed in userId.	Yields
CreateThumbnailPlayer	Players:CreateThumbnailPlayer(): Player	Not yet	—	RobloxScriptSecurity
GetBanHistoryAsync	Players:GetBanHistoryAsync(userId: User): BanHistoryPages	Not yet	Retrieves the ban and unban history of any user within the experience's universe. This method is enabled and disabled by the [Players.BanningEnabled](Players.md#banninge…	Yields
GetCharacterAppearanceInfoAsync	Players:GetCharacterAppearanceInfoAsync(userId: User): Dictionary	Not yet	Returns information about the character appearance of a given user.	Yields
GetHumanoidDescriptionFromOutfitId	Players:GetHumanoidDescriptionFromOutfitId(outfitId: int64): HumanoidDescription	Not yet	Returns the HumanoidDescription for a specified outfit, which will be set with the parts/colors/Animations etc of the outfit.	Yields, PreferredDescriptorName, ThreadSafety, PreferredDes…
GetHumanoidDescriptionFromOutfitIdAsync	Players:GetHumanoidDescriptionFromOutfitIdAsync(outfitId: int64): HumanoidDescription	Not yet	Returns the HumanoidDescription for a specified outfit, which will be set with the parts/colors/Animations etc of the outfit.	Yields
GetHumanoidDescriptionFromUserId	Players:GetHumanoidDescriptionFromUserId(userId: User): HumanoidDescription	Not yet	Returns a HumanoidDescription which specifies everything equipped for the avatar of the user specified by the passed in userId.	Yields, PreferredDescriptorName, ThreadSafety, PreferredDes…
GetHumanoidDescriptionFromUserIdAsync	Players:GetHumanoidDescriptionFromUserIdAsync(userId: User): HumanoidDescription	Not yet	Returns a HumanoidDescription which specifies everything equipped for the avatar of the user specified by the passed in userId.	Yields
GetProfileConfigurationFromUserIdAsync	Players:GetProfileConfigurationFromUserIdAsync(userId: User): Dictionary	Not yet	Returns the profile configuration of a user as a dictionary.	Yields
GetUserThumbnailAsync	Players:GetUserThumbnailAsync(userId: User, thumbnailType: ThumbnailType, thumbnailSize: ThumbnailSize): Tuple	Not yet	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.	Yields
ReportAbuseV3	Players:ReportAbuseV3(player: Player, jsonTags: string): null	Not yet	—	RobloxScriptSecurity
ReportAvatarAbuse	Players:ReportAvatarAbuse(targetUserId: int64, tags: Dictionary): null	Not yet	—	RobloxScriptSecurity
ReportChatAbuse	Players:ReportChatAbuse(eligibleChatLines: Array, targetChatLines: Array, tags: Dictionary): null	Not yet	—	RobloxScriptSecurity
ResetLocalPlayer	Players:ResetLocalPlayer(): null	Not yet	—	LocalUserSecurity
SetLocalPlayerInfo	Players:SetLocalPlayerInfo(userId: int64, userName: string, displayName: string, membershipType: MembershipType, isUnder13: bool, hasRobloxSubscription: bool = false, ageCheckedStatus: AgeCheckStatus = Unchecked): null	Not yet	—	RobloxScriptSecurity
UnbanAsync	Players:UnbanAsync(config: Dictionary): null	Not yet	Unbans players banned from Players.BanAsync() or the User Restrictions Open Cloud API. This method is enabled and disabled by the [Players.Banning…	Yields

Events

Member	Signature	Status	Notes	Flags
PlayerConnecting	PlayerConnecting(player: Player)	Not yet	—	LocalUserSecurity
PlayerDisconnecting	PlayerDisconnecting(player: Player)	Not yet	—	LocalUserSecurity
PlayerMembershipChanged	PlayerMembershipChanged(player: Player)	Not yet	Fires when the experience server recognizes that a player's membership has changed.	—
PlayerRejoining	PlayerRejoining(player: Player)	Not yet	—	LocalUserSecurity
PromptAgeCheckRequested	PromptAgeCheckRequested(player: Player)	Not yet	—	RobloxScriptSecurity
UserSubscriptionStatusChanged	UserSubscriptionStatusChanged(user: Player, subscriptionId: string)	Not yet	Fires when the experience server recognizes that the user's status for a certain subscription has changed.	—

Roblox reference: Players

Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.