Reference API Roblox

Engine API

Website

Related

Reference API Roblox

Player

An object that represents a presently connected client to the experience.

Member index 155

HistoryMember
554AccountAge: int
554AutoJumpEnabled: bool
554CameraMaxZoomDistance: float
554CameraMinZoomDistance: float
554CameraMode: CameraMode
554CanLoadCharacterAppearance: bool
554Character: Model
554CharacterAppearance: string
554CharacterAppearanceId: int64
554DevCameraOcclusionMode: DevCameraOcclusionMode
554DevComputerCameraMode: DevComputerCameraMovementMode
554DevComputerMovementMode: DevComputerMovementMode
578DevEnableMouseLock: bool
554DevTouchCameraMode: DevTouchCameraMovementMode
554DevTouchMovementMode: DevTouchMovementMode
554DisplayName: string
554FollowUserId: int64
554GameplayPaused: bool
554HasVerifiedBadge: bool
554HealthDisplayDistance: float
554MembershipType: MembershipType
554NameDisplayDistance: float
554Neutral: bool
554ReplicationFocus: Instance
554RespawnLocation: SpawnLocation
663StepIdOffset: int
554Team: Team
554TeamColor: BrickColor
663ThirdPartyTextChatRestrictionStatus: ChatRestrictionStatus
554UserId: int64
554userId: int64
660AddReplicationFocus(part: BasePart): null
662AddReplicationFocusPosition(center: Vector3, radius: int): null
573AddToBlockList(userIds: Array): null
573ClearCharacterAppearance(): null
462DistanceFromCharacter(point: Vector3): float
664GetData(): PlayerData
483GetFriendStatus(player: Player): FriendStatus
462GetFriendsOnline(maxFriends: int = 200): Array
462GetGameSessionID(): string
624GetJoinData(): Dictionary
483GetMouse(): Mouse
562GetNetworkPing(): float
462GetRankInGroup(groupId: int64): int
462GetRoleInGroup(groupId: int64): string
462GetUnder13(): bool
462HasAppearanceLoaded(): bool
462IsBestFriendsWith(userId: int64): bool
462IsFriendsWith(userId: int64): bool
462IsInGroup(groupId: int64): bool
573IsVerified(): bool
573Kick(message: string = ): null
462LoadBoolean(key: string): bool
573LoadCharacter(): null
573LoadCharacterAppearance(assetInstance: Instance): null
573LoadCharacterBlocking(): null
672LoadCharacterWithAvatarRules(avatarRules: AvatarRules): null
573LoadCharacterWithHumanoidDescription(humanoidDescription: HumanoidDescription): null
573LoadData(): null
462LoadInstance(key: string): Instance
462LoadNumber(key: string): double
462LoadString(key: string): string
573Move(walkDirection: Vector3, relativeToCamera: bool = false): null
666OverrideStreamingRadii(minRadius: int, targetRadius: int): null
675PinStreamingForInstance(instance: Instance, depth: int): null
573RemoveCharacter(): null
660RemoveReplicationFocus(part: BasePart): null
662RemoveReplicationFocusPosition(center: Vector3, radius: int): null
573RequestFriendship(player: Player): null
573RequestStreamAroundAsync(position: Vector3, timeOut: double = 0): null
573RevokeFriendship(player: Player): null
573SaveBoolean(key: string, value: bool): null
573SaveData(): null
573SaveInstance(key: string, value: Instance): null
573SaveNumber(key: string, value: double): null
573SaveString(key: string, value: string): null
573SetAccountAge(accountAge: int): null
593SetBlockListInitialized(): null
573SetCharacterAppearanceJson(jsonBlob: string): null
611SetChatTranslationSettingsLocaleId(locale: string): null
573SetExperienceSettingsLocaleId(locale: string): null
573SetMembershipType(membershipType: MembershipType): null
573SetModerationAccessKey(moderationAccessKey: string): null
573SetSuperSafeChat(value: bool): null
573SetUnder13(value: bool): null
675UnpinStreamingForInstance(instance: Instance, depth: int): null
573UpdatePlayerBlocked(userId: int64, blocked: bool): null
462WaitForDataReady(): bool
553isFriendsWith(userId: int64): bool
553loadBoolean(key: string): bool
553loadInstance(key: string): Instance
553loadNumber(key: string): double
553loadString(key: string): string
573saveBoolean(key: string, value: bool): null
573saveInstance(key: string, value: Instance): null
573saveNumber(key: string, value: double): null
573saveString(key: string, value: string): null
553waitForDataReady(): bool
483CharacterAdded(character: Model)
483CharacterAppearanceLoaded(character: Model)
483CharacterRemoving(character: Model)
483Chatted(message: string, recipient: Player)
678CloudEditSelectionChanged(newSelection: Array)
483FriendStatusChanged(player: Player, friendStatus: FriendStatus)
462Idled(time: double)
462OnTeleport(teleportState: TeleportState, placeId: int64, spawnName: string)
462SimulationRadiusChanged(radius: float)
675StreamingPinComplete(instance: Instance)
inherited from Instance
553Archivable: bool
670Capabilities: SecurityCapabilities
553Name: string
553Parent: Instance
670Sandboxed: bool
680UniqueId: UniqueId
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
648GetChildren(): Instances
462GetDebugId(scopeLength: int = 4): string
486GetDescendants(): Array
486GetFullName(): string
641GetStyled(name: string): Variant
657GetStyledPropertyChangedSignal(property: string): RBXScriptSignal
576GetTags(): Array
576HasTag(tag: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
664IsPropertyModified(property: string): bool
573Remove(): null
576RemoveTag(tag: string): null
664ResetPropertyToDefault(property: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
648children(): Instances
553clone(): Instance
573destroy(): null
553findFirstChild(name: string, recursive: bool = false): Instance
648getChildren(): Instances
553isDescendantOf(ancestor: Instance): bool
573remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
657StyledPropertiesChanged()
553childAdded(child: Instance)
inherited from Object
647ClassName: string
647className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
650isA(className: string): bool
647Changed(property: string)

Removed member index 19

HistoryMember
180ClanTag: string
273HasBuildTools: bool
273PersonalServerRank: int
335PlayerJoinData: PlayerJoinData
310BlockUser(player: Instance): string
273GetWebPersonalServerRank(): string
52HasBuildPermission(role: BuildPermission): bool
535IsUserAvailableForExperiment(): bool
338JumpCharacter(): void
338MoveCharacter(walkDirection: Vector2, maxWalkDelta: float): void
258SaveLeaderboardData(): void
180SetClanTag(newClanTag: string): void
273SetWebPersonalServerRank(rank: int): bool
310UnblockUser(player: Instance): string
90HoverOnPlayerChanged(playerHoveredOn: Instance)
90MouseDownOnPlayer(playerMouseDownOn: Instance)

Description

A Player object is a client that is currently connected. These objects are added to the Players service when a new player connects, then removed when they eventually disconnect from the server.

The Instance.Name property reflects the player's username. When saving information about a player, you should use their UserId since it is possible that a player can change their username.

There are several similar methods in the Players service for working with Player objects. Use these over their respective Instance methods:

History 594

Members 155

AccountAge

TypeDefault
int

This property describes how long ago a player's account was registered in days. It is set using the SetAccountAge() method, which cannot be accessed by scripts.

This property is not replicated. Its interface does not cross the network boundary.
This property is read-only. Its value can be read, but it cannot be modified.

History 5

Tags: [ReadOnly, NotReplicated]

AddReplicationFocus

Parameters (1)
partBasePart
Returns (1)
null

History 1

AddReplicationFocusPosition

Parameters (2)
centerVector3
radiusint
Returns (1)
null

History 1

AddToBlockList

Parameters (1)
userIdsArray
Returns (1)
null

History 3

AutoJumpEnabled

TypeDefault
bool

This property determines whether the Character of a Player using a mobile device will automatically jump when they hit an obstacle. This can make levels more navigable while on a mobile device.

When the player joins the experience, the StarterPlayer.AutoJumpEnabled value determines the initial state of this property. Then, this property determines the value of the Humanoid.AutoJumpEnabled property of the Character on spawn. In other words, it is possible to set the auto-jump behavior on a per-character, per-player, and per-experience basis using these three properties.

History 5

CameraMaxZoomDistance

TypeDefault
float

This property sets the maximum distance the player's camera is allowed to zoom out, in studs.

The default value of this property is set by StarterPlayer.CameraMaxZoomDistance. If this value is set to a lower value than CameraMinZoomDistance, it will be increased to CameraMinZoomDistance.

History 5

CameraMinZoomDistance

TypeDefault
float

This property sets the minimum distance the player's camera is allowed to zoom in, in studs.

The default value of this property is set by StarterPlayer.CameraMinZoomDistance. If this value is set to a higher value than CameraMaxZoomDistance, it will be decreased to CameraMaxZoomDistance.

History 5

CameraMode

TypeDefault
CameraMode

This property sets the player's camera mode, defaulting to third person.

Third Person

In the default third person mode (CameraMode.Classic), the character can be seen in the camera. While in this mode, the default behavior is:

  • Players can right-click and drag (mouse), tap and drag (mobile), use the secondary thumbstick (gamepad), or press the left/right arrows (keyboard) to rotate the camera around their character.
  • When a player moves their character, it faces in the corresponding movement direction.
  • Players can zoom in and out freely, even to first person on full zoom in.

First Person

In first person mode (CameraMode.LockFirstPerson), the player's camera is zoomed all the way in. Unless there is a visible GUI present with the GuiButton.Modal property set to true, moving the mouse, tap-dragging on mobile, or using the secondary thumbstick on a gamepad will rotate the camera around the character.

History 5

CanLoadCharacterAppearance

TypeDefault
bool

This property determines whether the character's appearance will be loaded when the player spawns. The default value of this property is set by StarterPlayer.LoadPlayerAppearance.

  • If true, the character will load the appearance of the player corresponding to the player's CharacterAppearanceId.

  • If false, the player will spawn with a default appearance.

Attempting to set the property after the character has spawned will not change the character; you must call LoadCharacter() to load the new appearance.

History 5

Character

TypeDefault
Model

This property contains a reference to a Model containing a Humanoid, body parts, scripts, and other objects required for simulating the player's avatar in-experience. The model is parented to the Workspace but it may be moved. It is automatically loaded when Players.CharacterAutoLoads is true and it can be manually loaded otherwise using LoadCharacter().

Initially this property is nil and it is set when the player's character first spawns. Use the CharacterAdded event to detect when a player's character properly loads, and the CharacterRemoving event to detect when the character is about to despawn. Avoid using Object:GetPropertyChangedSignal() on this property.

Note that LocalScripts that are cloned from StarterGui or StarterPack into a player's PlayerGui or Backpack respectively are often run before the old character model is replaced, so Player.Character may refer to the old model whose Parent property is nil. Therefore, in a LocalScript under StarterGui or StarterPack, it is advisable to make sure the parent of Character is not nil before using it, for example:

1
2
3
4
5
6
7
local Players = game:GetService("Players")
local player = Players.LocalPlayer

local character = player.Character
if not character or character.Parent == nil then
	character = player.CharacterAdded:Wait()
end

History 6

CharacterAdded

Parameters (1)
characterModel

This event fires when a player's character spawns or respawns. It fires soon after setting Character to a non-nil value or calling LoadCharacter(), which is before the character is parented to the Workspace.

This can be used alongside the CharacterRemoving event which fires right before a player's character is about to be removed, typically after death. As such, both of these events can potentially fire many times as players die then respawn in a place.

Note that the Humanoid and its default body parts (head, torso, and limbs) will exist when this event fires, but clothing items like Hats, Shirts, and Pants may take a few seconds to be added to the character. Connect Instance.ChildAdded on the added character to detect these, or wait for the CharacterAppearanceLoaded event to be sure the character has everything equipped.

If you instead need to track when a player joins/leaves the experience, use the events Players.PlayerAdded and Players.PlayerRemoving.

History 3

CharacterAppearance

TypeDefault
string

This property indicates the URL of the asset containing the character's appearance, clothing, and gear. It is automatically set by Roblox to load your avatar's appearance when you join an experience.

Attempting to set the property after the character has spawned will not change the character, you must call LoadCharacter() to load the new appearance.

This property is deprecated. It exists only for backward compatibility, and should not be used for new work. CharacterAppearanceId should be used instead.
This property is not browsable. It is not visible in Studio's object browser.

History 6

Tags: [NotBrowsable, Deprecated]

CharacterAppearanceId

TypeDefault
int64

This property determines the user ID of the account whose character appearance is used for a player's Character. By default, this property is the UserId, which uses the player's avatar as they have created it on Roblox.

Changing this property to the user ID of another account will cause the player to spawn with that account's appearance.

You can also toggle whether or not a player's character appearance is loaded in experience by changing the StarterPlayer.LoadCharacterAppearance property.

History 6

CharacterAppearanceLoaded

Parameters (1)
characterModel

This event fires when the full appearance of a Character has been inserted. It only fires on the server.

A Character generally has a range of objects modifying its appearance, including Accoutrements, Shirts, Pants and CharacterMeshes. This event will fire when all such objects have been inserted into the character.

For custom character implementations, such as using a character model named StarterCharacter inside StarterPlayer, use CharacterAdded and handle your own accessories.

One use for this event is to ensure all accessories have loaded before destroying them. See below for an example of this.

History 3

CharacterRemoving

Parameters (1)
characterModel

This event fires right before a player's Character is removed, such as when the player is respawning. This can be used alongside the CharacterAdded event which fires when a player's character spawns or respawns.

If you instead need to track when a player joins/leaves the experience, use the events Players.PlayerAdded and Players.PlayerRemoving.

History 3

Chatted

Parameters (2)
messagestring
recipientPlayer

This event fires when a Player types a message and presses Enter in Roblox's provided chat bar. This is done using some Luau bindings by the default chat script. You can prevent players from chatting by using StarterGui:SetCoreGuiEnabled() and setting CoreGuiType.Chat to false.

History 3

ClearCharacterAppearance

Parameters (0)
No parameters.
Returns (1)
null

This method removes all Accessory, Shirt, Pants, CharacterMesh, and BodyColors from the given player's Character. In addition, it also removes the T-Shirt Decal on the player's torso. The character's body part colors and face will remain unchanged. This method does nothing if the player does not have a Character.

History 3

CloudEditSelectionChanged

Parameters (1)
newSelectionArray

History 3

DevCameraOcclusionMode

TypeDefault
DevCameraOcclusionMode

Defines how the default camera scripts handle objects between the camera and the camera subject. Set by StarterPlayer.DevCameraOcclusionMode and can't be changed for individual players.

The default value is Zoom. See DevCameraOcclusionMode for a list of available modes.

History 7

DevComputerCameraMode

TypeDefault
DevComputerCameraMovementMode

This property determines the manner in which a player moves their camera when using a device with a mouse and keyboard. This property cannot be set using a LocalScript (it must be set on the server using a Script).

The default value of this property is determined by StarterPlayer.DevComputerCameraMovementMode.

This property doesn't affect players using a TouchEnabled device. See DevTouchCameraMode instead.

History 7

DevComputerMovementMode

TypeDefault
DevComputerMovementMode

This property determines the manner in which a player moves their character when using a device with a mouse and keyboard. This property cannot be set using a LocalScript (it must be set on the server using a Script).

The default value of this property is determined by StarterPlayer.DevComputerMovementMode.

This property doesn't affect players using a TouchEnabled device. See DevTouchMovementMode instead.

History 7

DevEnableMouseLock

TypeDefault
bool

This property determines if a player is able to toggle mouse lock by pressing Shift. A player can disable the mouse lock switch in the experience's settings during play. By default, this property is set to the value of StarterPlayer.EnableMouseLockOption. This can be set server-side during runtime by using a Script. It can not be set client-side.

When mouse lock is enabled, the player's cursor is locked to the center of the screen. Moving the mouse will orbit the camera around the player's Character, and the character will face the same direction as the Camera. It also offsets the camera view just over the right shoulder of the player's character.

History 9

DevTouchCameraMode

TypeDefault
DevTouchCameraMovementMode

This property determines the manner in which a player moves their camera when using a TouchEnabled device. This property cannot be set using a LocalScript (it must be set on the server using a Script).

The default value of this property is determined by StarterPlayer.DevTouchCameraMovementMode.

This property doesn't affect players who aren't using a TouchEnabled device. See DevComputerCameraMode instead.

History 7

DevTouchMovementMode

TypeDefault
DevTouchMovementMode

This property determines the manner in which a player moves their character when using a TouchEnabled device. This property cannot be set using a LocalScript (it must be set on the server using a Script).

The default value of this property is determined by StarterPlayer.DevTouchMovementMode.

This property doesn't affect players who aren't using a TouchEnabled device. See DevComputerMovementMode instead.

History 7

DisplayName

TypeDefault
string

This property contains the display name of the authenticated user associated with the Player object. Unlike UserId, display names are non-unique names a player displays to others.

Usage Notes

  • Since display names are non-unique, it's possible for two players in a single instance to have identical names. If you need a globally unique identifier for a player, use UserId instead.

  • Characters generated with LoadCharacter() or by the Roblox engine will have their Humanoid.DisplayName property assigned to the Player.DisplayName property.

  • Display names may have unicode characters in the string. See UTF-8 for more information on how to work with strings with unicode characters.

History 6

DistanceFromCharacter

Parameters (1)
pointVector3
Returns (1)
float

This method returns the distance between the character's head and the given Vector3 point, or 0 if the player has no Character.

This is useful when determining the distance between a player and another object or location in experience.

If you would like to determine the distance between two non-player instances or positions, you can use the following:

1
local distance = (position1 - position2).Magnitude

History 2

FollowUserId

TypeDefault
int64

This property contains the UserId of the user that a player followed into the experience, or 0 if the player did not follow anyone in. This property is useful for alerting players who have been followed by another player into the experience.

You can get the name of the player followed using this user ID and the Players:GetNameFromUserIdAsync() method.

This property is not replicated. Its interface does not cross the network boundary.
This property is read-only. Its value can be read, but it cannot be modified.

History 6

Tags: [ReadOnly, NotReplicated]

FriendStatusChanged

Parameters (2)
playerPlayer
friendStatusFriendStatus

History 3

GameplayPaused

TypeDefault
bool

This property indicates if the player is currently in a pause state in a place with StreamingEnabled activated. It is set on the client but replicated to the server.

See Also

History 8

GetData

Parameters (0)
No parameters.
Returns (1)
PlayerData

History 1

GetFriendStatus

Parameters (1)
playerPlayer
Returns (1)
FriendStatus

History 3

GetFriendsOnline

Parameters (1)Default
maxFriendsint200
Returns (1)
Array

This function returns a dictionary array of online friends, using a 30 second cache. In the returned array, some fields are only present for certain location types; for example, PlaceId won't be present when LocationType is 0 (mobile website).

NameTypeDescription
VisitorIdnumberThe UserId of the friend.
UserNamestringThe username of the friend.
DisplayNamestringThe DisplayName of the friend.
LastOnlinestringWhen the friend was last online.
IsOnlinebooleanIf the friend is currently online.
LastLocationstringThe name of the friend's current location.
PlaceIdnumberThe place ID of the friend's last location.
GameIdstringThe DataModel.JobId of the friend's last location.
LocationTypenumberThe location type of the friend's last location.
This function yields. It will block the calling thread until completion.

History 4

Tags: [Yields]

GetGameSessionID

Parameters (0)
No parameters.
Returns (1)
string

History 2

GetJoinData

Parameters (0)
No parameters.
Returns (1)
Dictionary

Returns a dictionary containing information describing how the player joins the experience. The dictionary contains any of the following fields:

KeyValue TypeDescription
SourceGameIdnumberThe DataModel.GameId of the experience the Player teleported from. Only present if the player teleports to the current experience and if a server calls the teleport function.
SourcePlaceIdnumberThe DataModel.PlaceId of the place the Player teleported from. Only present if the player teleports to the current place and a server calls the teleport function.
ReferredByPlayerIdnumberThe UserId of the player who invited the current player to the experience. Use this data to identify the referrer and trigger reward logic.
MembersarrayAn array containing the UserId numbers of the users teleported alongside the player. Only present if the player teleported as part of a group.
TeleportDatavariantReflects the teleportData specified in the original teleport. Useful for sharing information between servers the player teleports to. Only present if teleportData was specified and a server calls the teleport function.
LaunchDatastringA plain or JSON encoded string that contains launch data specified in a deep link URL or ExperienceInviteOptions.LaunchData.
GameJoinContextdictionaryA dictionary that includes relevant information based on the context of the join. It contains the following keys:

If a server initiates the player's teleport, the dictionary that this method returns includes the player's teleport data. The GetJoinData() method can only be used to fetch teleport data on the server. To fetch the data on the client, use TeleportService:GetLocalPlayerTeleportData().

Unlike TeleportService:GetLocalPlayerTeleportData(), GetJoinData() only provides teleport data that meets the following security criteria:

  • It's guaranteed to have been sent by a Roblox server in the past 48 hours.
  • It's guaranteed to have been sent with this Player.
  • The SourcePlaceId and SourceGameId are guaranteed to be the place and universe the data was sent from. This means you can verify the teleport data came from an approved place.

As this data is transmitted by the client, it can still potentially be abused by an exploiter. Sensitive data such as player currency should be transmitted via a secure solution like Memory Stores.

This function has a custom internal state. It may behave in a non-standard way.

History 3

Tags: [CustomLuaState]

GetMouse

Parameters (0)
No parameters.
Returns (1)
Mouse

This method returns the Mouse being used by the client. The player's mouse instance can be used to track user mouse input including left and right mouse button clicks and movement and location.

Note that UserInputService provides additional methods, properties, and events to track user input, especially for devices that do not use a mouse.

History 3

GetNetworkPing

Parameters (0)
No parameters.
Returns (1)
float

Returns the isolated network latency of the player in seconds. "Ping" is a measurement of the time taken for data to be sent from the client to the server, then back again. It doesn't involve data deserialization or processing.

For client-side LocalScripts, this function can only be called on the Players.LocalPlayer. This function is useful in identifying and debugging issues that occur in high network latency scenarios. It's also useful for masking latency, such as adjusting the speed of throwing animations for projectiles.

History 3

GetRankInGroup

Parameters (1)
groupIdint64
Returns (1)
int

This method returns the player's rank in the group as an integer between 0 and 255, where 0 is a non-member and 255 is the group's owner.

Using this in a Script, as opposed to a LocalScript, will not get you the most up-to-date information. If a player leaves a group while they are in the experience, GetRankInGroup() will still think they're in that group until they leave. However, this does not happen when used with a LocalScript because the method caches results, so multiple calls of GetRankInGroup() on the same player with the same group ID will yield the same result as when the method was first called with the given group ID. The caching behavior is on a per-peer basis: a server does not share the same cache as a client.

This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields]

GetRoleInGroup

Parameters (1)
groupIdint64
Returns (1)
string

This method returns the player's role in the group as a string, or Guest if the player isn't part of the group.

Using this in a Script, as opposed to a LocalScript, will not get you the most up-to-date information. If a player leaves a group while they are in the experience, GetRoleInGroup() will still think they're in that group until they leave. However, this does not happen when used with a LocalScript because the method caches results, so multiple calls of GetRoleInGroup() on the same player with the same group ID will yield the same result as when the method was first called with the given group ID. The caching behavior is on a per-peer basis: a server does not share the same cache as a client.

This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields]

GetUnder13

Parameters (0)
No parameters.
Returns (1)
bool

History 2

HasAppearanceLoaded

Parameters (0)
No parameters.
Returns (1)
bool

This method returns whether or not the appearance of the player's Character has loaded. Appearance includes items such as the player's Shirt, Pants, and Accessories.

This is useful when determining whether a player's appearance has loaded after they first join the experience, which can be tracked using the Players.PlayerAdded event.

History 2

HasVerifiedBadge

TypeDefault
bool

This property indicates if the player has a Verified badge.

History 1

HealthDisplayDistance

TypeDefault
float

This property sets the distance in studs at which this player will see other Humanoid health bars. If set to 0, the health bars will not be displayed. This property is set to StarterPlayer.HealthDisplayDistance by default.

If a humanoid's health bar is visible, you can set the display type using Humanoid.DisplayDistanceType.

History 5

Idled

Parameters (1)
timedouble

This event fires approximately two minutes after the engine classifies the player as idle. Time is the number of seconds that have elapsed since that point. The event continues to fire every 30 seconds for as long as the player remains idle.

This event only fires in client scripts, not server scripts; use a RemoteEvent to notify the server of idle players.

Roblox automatically disconnects players that have been idle for at least 20 minutes, so this event is useful for warning players that they will be disconnected soon, disconnecting players prior to those 20 minutes, or other away from keyboard (AFK) features.

To track how often automatic disconnects occur, try correlating this event with occurrences of Players.PlayerRemoving.

History 2

IsBestFriendsWith

Parameters (1)
userIdint64
Returns (1)
bool

This function was once used to return whether a player is best friends with the specified user, but the best friend feature has since been removed.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
This function yields. It will block the calling thread until completion.

History 4

Tags: [Yields, Deprecated]

IsFriendsWith

Parameters (1)
userIdint64
Returns (1)
bool

This method sends a request to Roblox asking whether a player is a friend of another user, given the UserId of that user. This method caches results so multiple calls on the same player with the same userId may not yield the most up-to-date result.

This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields]

IsInGroup

Parameters (1)
groupIdint64
Returns (1)
bool

This method sends a request to Roblox asking whether a player is a member of a group, given the ID of that group.

Using this in a Script, as opposed to a LocalScript, will not get you the most up-to-date information. If a player leaves a group while they are in the experience, IsInGroup() will still think they're in that group until they leave. However, this does not happen when used with a LocalScript because the method caches results, so multiple calls of IsInGroup() on the same player with the same group ID will yield the same result as when the method was first called with the given group ID. The caching behavior is on a per-peer basis: a server does not share the same cache as a client.

This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields]

IsVerified

Parameters (0)
No parameters.
Returns (1)
bool

Returns a boolean value indicating that player's verification status. When true, the player is verified. Verification includes, but isn't limited to, non-VOIP phone number or government ID verification.

When implementing IsVerified, exercise caution to ensure that the implementation does not inadvertently block all unverified users.

Note that the method can only be called on the backend server. Calling it client-side results in an error. Additionally, this method will always return false in Studio.

History 1

Kick

Parameters (1)Default
messagestring
Returns (1)
null

This method allows an experience to gracefully disconnect a client and optionally provide a message to the disconnected user. This is useful for moderating abusive users. You should only allow specific users whom you trust to trigger this method on other users.

Calling this method on a Player with no arguments disconnects the user from the server and provides a default notice message. Calling this method on a Player along with a string as the first argument replaces the default message with the provided string.

When using this method from a LocalScript, only the local user's client can be kicked.

History 4

LoadBoolean

Parameters (1)
keystring
Returns (1)
bool

This function returns a boolean value that was previously saved to the player with Player:SaveBoolean() with the same key. Returns false if the key doesn't exist, not nil.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 3

Tags: [Deprecated]

LoadCharacter

Parameters (0)
No parameters.
Returns (1)
null

This method creates a new character for the player, removing the old one. It also clears the player's Backpack and PlayerGui. This is useful in cases where you want to reload the character without killing the player, such as when you want to load a new character appearance after changing the player's CharacterAppearance.

After calling LoadCharacter() for an individual player, it is not recommended to call it again for the same player until after that player's CharacterAppearanceLoaded event has fired.

Character Loading Event Order

Calling the LoadCharacter() method on any Player fires events in the following order:

  1. The character appearance initializes.
  2. The character rig builds and scales.
  3. The character moves to the spawn location.
  4. Player.Character sets.
  5. Object.Changed fires on the Player with a value of Character.
  6. The character's Parent sets to the DataModel.
  7. Player.CharacterAdded fires.
  8. Player.CharacterAppearanceLoaded fires.
This function yields. It will block the calling thread until completion.

History 6

Tags: [Yields]

LoadCharacterAppearance

Parameters (1)
assetInstanceInstance
Returns (1)
null

The LoadCharacterAppearance Player function places the given instance either in the player's Player.Character, head, or StarterGear based on the instance's class.

This is useful when giving a player's character an asset from the Roblox catalog, such as a hat or piece of gear.

It is similar to Player:LoadCharacter(), except it does not reload the entire character instance, StarterGear, or PlayerGui.

Note:

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 4

Tags: [Deprecated]

LoadCharacterBlocking

Parameters (0)
No parameters.
Returns (1)
null
This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields]

LoadCharacterWithAvatarRules

Parameters (1)
avatarRulesAvatarRules
Returns (1)
null
This function yields. It will block the calling thread until completion.

History 1

Tags: [Yields]

LoadCharacterWithHumanoidDescription

Parameters (1)
humanoidDescriptionHumanoidDescription
Returns (1)
null

This method spawns a player character with everything equipped in the passed in HumanoidDescription.

After calling this method for an individual player, it is not recommended to call it again for the same player until after that player's CharacterAppearanceLoaded event has fired.

See also HumanoidDescription System, an article which explains the humanoid description system in greater detail and provides several scripting examples.

This function yields. It will block the calling thread until completion.

History 4

Tags: [Yields]

LoadData

Parameters (0)
No parameters.
Returns (1)
null
This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 4

Tags: [Deprecated]

LoadInstance

Parameters (1)
keystring
Returns (1)
Instance

This function returns an instance that was previously saved to the player with Player:SaveInstance() with the same key. Returns nil if the key doesn't exist.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 3

Tags: [Deprecated]

LoadNumber

Parameters (1)
keystring
Returns (1)
double

This function was once used by an ancient data persistence method to return a number value that was previously saved to the player with Player:SaveNumber() with the same key. Returns 0 if the key doesn't exist, not nil.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 4

Tags: [Deprecated]

LoadString

Parameters (1)
keystring
Returns (1)
string

This function returns a string value that was previously saved to the player with Player:SaveString() with the same key. Returns an empty string ("") if the key doesn't exist, not nil.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 3

Tags: [Deprecated]

MembershipType

TypeDefault
MembershipType

This property can only be read from to determine membership (it cannot be set to another membership type). It holds a MembershipType enum of the account's membership type.

This property is not replicated. Its interface does not cross the network boundary.
This property is read-only. Its value can be read, but it cannot be modified.

History 5

Tags: [ReadOnly, NotReplicated]

Move

Parameters (2)Default
walkDirectionVector3
relativeToCameraboolfalse
Returns (1)
null

This method causes the player's character to walk in the given direction until stopped, or interrupted by the player (by using their controls).

This is useful when scripting NPC Humanoids that move around a map but are not controlled by an actual player's input.

Note that the function's second argument indicates whether the provided Vector3 should move the player relative to world coordinates (false) or the player's Camera (true).

History 3

NameDisplayDistance

TypeDefault
float

This property sets the distance in studs at which this player will see other Humanoid names. If the property is set to 0, names are hidden. This property is set to StarterPlayer.NameDisplayDistance by default.

If a humanoid's name is visible, you can set the display type using Humanoid.DisplayDistanceType.

History 5

Neutral

TypeDefault
bool

This property determines whether the player is on a specific team.

  • When true, the player is not on a specific team. This also means that the Team property will be nil and the TeamColor will be white.

  • When false, the player is on a specific team. The Team property will correspond to the Team that the player is on, as will the TeamColor.

History 5

OnTeleport

Parameters (3)
teleportStateTeleportState
placeIdint64
spawnNamestring

This event fires when the TeleportState of a player changes. This event is useful for detecting whether a teleportation was successful.

History 3

OverrideStreamingRadii

Parameters (2)
minRadiusint
targetRadiusint
Returns (1)
null

History 1

PinStreamingForInstance

Parameters (2)
instanceInstance
depthint
Returns (1)
null

History 1

RemoveCharacter

Parameters (0)
No parameters.
Returns (1)
null

History 3

RemoveReplicationFocus

Parameters (1)
partBasePart
Returns (1)
null

History 1

RemoveReplicationFocusPosition

Parameters (2)
centerVector3
radiusint
Returns (1)
null

History 1

ReplicationFocus

TypeDefault
Instance

This property sets the part to focus replication around a player. Different Roblox systems that communicate over the network (such as physics, streaming, etc.) replicate at different rates depending on how close objects are to the replication focus.

When this property is nil, it reverts to its default behavior which is to treat the local player's character's PrimaryPart as the replication focus.

This property should only be set on the server with a Script, not a LocalScript. Note that this property does not change or update network ownership of parts.

History 6

RequestFriendship

Parameters (1)
playerPlayer
Returns (1)
null

History 4

RequestStreamAroundAsync

Parameters (2)Default
positionVector3
timeOutdouble0
Returns (1)
null

For experiences where instance streaming is enabled, requests that the server stream to the player regions (parts and terrain) around the specified X, Y, Z location in the 3D world. It is useful if the experience knows that the player's CFrame will be set to the specified location in the near future. Without providing the location with this call, the player may not have streamed in content for the destination, resulting in a streaming pause or other undesirable behavior.

The effect of this call will be temporary and there are no guarantees of what will be streamed in around the specified location. Client memory limits and network conditions may impact what will be available on the client.

Usage Precaution

Requesting streaming around an area is not a guarantee that the content will be present when the request completes, as streaming is affected by the client's network bandwidth, memory limitations, and other factors.

This function yields. It will block the calling thread until completion.

History 5

Tags: [Yields]

RespawnLocation

TypeDefault
SpawnLocation

If set, the player will respawn at the given SpawnLocation which must meet the following criteria:

Alternatives

History 6

RevokeFriendship

Parameters (1)
playerPlayer
Returns (1)
null

History 4

SaveBoolean

Parameters (2)
keystring
valuebool
Returns (1)
null

This function is used to save a boolean value that can be loaded again at a later time using Player:LoadBoolean().

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 4

Tags: [Deprecated]

SaveData

Parameters (0)
No parameters.
Returns (1)
null
This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 4

Tags: [Deprecated]

SaveInstance

Parameters (2)
keystring
valueInstance
Returns (1)
null

This function was once used by an ancient data persistence method to save an instance which can be loaded again at a later time using Player:LoadInstance()..

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 4

Tags: [Deprecated]

SaveNumber

Parameters (2)
keystring
valuedouble
Returns (1)
null

This function was once used by an ancient data persistence method to save a number value that can be loaded again at a later time using Player:LoadNumber().

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 5

Tags: [Deprecated]

SaveString

Parameters (2)
keystring
valuestring
Returns (1)
null

This function was once used by an ancient data persistence method to save a string value that can be loaded again at a later time using Player:LoadString().

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 4

Tags: [Deprecated]

SetAccountAge

Parameters (1)
accountAgeint
Returns (1)
null

This method sets the AccountAge of the player in days, meaning the age of the account itself relative to when it was first created.

History 4

SetBlockListInitialized

Parameters (0)
No parameters.
Returns (1)
null

History 1

SetCharacterAppearanceJson

Parameters (1)
jsonBlobstring
Returns (1)
null

History 2

SetChatTranslationSettingsLocaleId

Parameters (1)
localestring
Returns (1)
null

History 1

SetExperienceSettingsLocaleId

Parameters (1)
localestring
Returns (1)
null

History 2

SetMembershipType

Parameters (1)
membershipTypeMembershipType
Returns (1)
null

History 3

SetModerationAccessKey

Parameters (1)
moderationAccessKeystring
Returns (1)
null

History 2

SetSuperSafeChat

Parameters (1)
valuebool
Returns (1)
null

This method sets whether or not the player sees chat filtered by TextService:FilterStringAsync() rather than normal chats.

1
2
3
4
local Players = game:GetService("Players")

local player = Players.LocalPlayer
player:SetSuperSafeChat(true)

Regardless of whether a player has filtered chat enabled, all chat should be filtered by TextService when broadcast to other players or on the player's own screen. TextService:FilterStringAsync() returns a TextFilterResult object that can be filtered differently according to the message's intended use.

History 4

SetUnder13

Parameters (1)
valuebool
Returns (1)
null
This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 4

Tags: [Deprecated]

SimulationRadiusChanged

Parameters (1)
radiusfloat

History 2

StepIdOffset

TypeDefault
int

History 1

StreamingPinComplete

Parameters (1)
instanceInstance

History 1

Team

TypeDefault
Team

This property is a reference to a Team object within the Teams service. If the player isn't on a team or has an invalid TeamColor, this property is nil. When this property is set, the player has joined the Team and the Team.PlayerAdded event fires on the associated team. Similarly, Team.PlayerRemoved fires when the property is unset from a certain Team.

This property is not replicated. Its interface does not cross the network boundary.

History 6

Tags: [NotReplicated]

TeamColor

TypeDefault
BrickColor

This property determines which Team a player is associated with according to that team's Team.TeamColor. If no Team object has the associated BrickColor, the player will not be associated with a team.

It's often a better idea to set Player.Team to the respective Team instead of using this property. Setting this property often leads to repetition of the same BrickColor value for a certain team across many scripts.

History 5

ThirdPartyTextChatRestrictionStatus

TypeDefault
ChatRestrictionStatus
This property is not replicated. Its interface does not cross the network boundary.
This property is read-only. Its value can be read, but it cannot be modified.

History 1

Tags: [ReadOnly, NotReplicated]

UnpinStreamingForInstance

Parameters (2)
instanceInstance
depthint
Returns (1)
null

History 1

UpdatePlayerBlocked

Parameters (2)
userIdint64
blockedbool
Returns (1)
null

History 3

UserId

TypeDefault
int64

This property contains a read-only integer that uniquely and consistently identifies the user's account on Roblox. Unlike the player's DisplayName which may change, this value will never change for the same account.

This property is essential when saving/loading player data using GlobalDataStores.

History 6

WaitForDataReady

Parameters (0)
No parameters.
Returns (1)
bool

This function is used to pause the script until the player's data is available to manipulate, or until a certain amount of time has elapsed without fetching the player's data

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields, Deprecated]

isFriendsWith

Parameters (1)
userIdint64
Returns (1)
bool
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. IsFriendsWith should be used instead.
This function yields. It will block the calling thread until completion.

History 4

Tags: [Yields, Deprecated]

loadBoolean

Parameters (1)
keystring
Returns (1)
bool
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. LoadBoolean should be used instead.

History 3

Tags: [Deprecated]

loadInstance

Parameters (1)
keystring
Returns (1)
Instance
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. LoadInstance should be used instead.

History 3

Tags: [Deprecated]

loadNumber

Parameters (1)
keystring
Returns (1)
double
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. LoadNumber should be used instead.

History 4

Tags: [Deprecated]

loadString

Parameters (1)
keystring
Returns (1)
string
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. LoadString should be used instead.

History 3

Tags: [Deprecated]

saveBoolean

Parameters (2)
keystring
valuebool
Returns (1)
null
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. SaveBoolean should be used instead.

History 4

Tags: [Deprecated]

saveInstance

Parameters (2)
keystring
valueInstance
Returns (1)
null
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. SaveInstance should be used instead.

History 4

Tags: [Deprecated]

saveNumber

Parameters (2)
keystring
valuedouble
Returns (1)
null
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. SaveNumber should be used instead.

History 4

Tags: [Deprecated]

saveString

Parameters (2)
keystring
valuestring
Returns (1)
null
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. SaveString should be used instead.

History 4

Tags: [Deprecated]

userId

TypeDefault
int64
This property is deprecated. It exists only for backward compatibility, and should not be used for new work. UserId should be used instead.

History 8

Tags: [Deprecated]

waitForDataReady

Parameters (0)
No parameters.
Returns (1)
bool
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. WaitForDataReady should be used instead.
This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields, Deprecated]

Removed members 19

BlockUser

Parameters (1)
playerInstance
Returns (1)
string
This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields, Deprecated]

ClanTag

TypeDefault
string

History 2

GetWebPersonalServerRank

Parameters (0)
No parameters.
Returns (1)
string
This function yields. It will block the calling thread until completion.

History 7

Tags: [backend, Yields]

HasBuildPermission

Parameters (1)
roleBuildPermission
Returns (1)
bool

History 2

HasBuildTools

TypeDefault
bool

History 4

HoverOnPlayerChanged

Parameters (1)
playerHoveredOnInstance

History 2

IsUserAvailableForExperiment

Parameters (0)
No parameters.
Returns (1)
bool
This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 3

Tags: [Deprecated]

JumpCharacter

Parameters (0)
No parameters.
Returns (1)
void

History 2

MouseDownOnPlayer

Parameters (1)
playerMouseDownOnInstance

History 2

MoveCharacter

Parameters (2)
walkDirectionVector2
maxWalkDeltafloat
Returns (1)
void

History 2

PersonalServerRank

TypeDefault
int

History 4

PlayerJoinData

TypeDefault
PlayerJoinData
This property is read-only. Its value can be read, but it cannot be modified.

History 2

Tags: [ReadOnly]

SaveLeaderboardData

Parameters (0)
No parameters.
Returns (1)
void
This function is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 5

Tags: [Deprecated]

SetClanTag

Parameters (1)
newClanTagstring
Returns (1)
void

History 3

SetWebPersonalServerRank

Parameters (1)
rankint
Returns (1)
bool
This function yields. It will block the calling thread until completion.

History 5

Tags: [Yields]

UnblockUser

Parameters (1)
playerInstance
Returns (1)
string
This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields, Deprecated]

Settings