62 min read

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

Player

Inherits from: Instance → Object

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:

• You can get a table of current Player objects using Players:GetPlayers(); again, use this instead of Instance:GetChildren().
• To detect the addition of Player objects, it is recommended to use the Players.PlayerAdded event (instead of Instance.ChildAdded on the Players service).
• Similarly, you can detect the removal of Player objects using Players.PlayerRemoving, which fires just before the Player is removed (instead of Instance.ChildRemoved which fires after). This is important if you are saving information about the player that might be removed or cleaned up on removal.

Inherits from: Instance

Memory category: Instances

Properties

Inherited from Instance

Inherited from Object

Player.AccountAge

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.

Player.AgeChecked

This read-only property holds an AgeCheckStatus value indicating whether the player has completed age verification. The default value is AgeCheckStatus.Unchecked. It transitions to AgeCheckStatus.Checked when the player passes age verification through the Player:PromptAgeCheck() flow.

This property is set by the server and cannot be changed by scripts.

Player.AutoJumpEnabled

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.

Code samples: View on Creator Hub (Auto-Jump-Toggle).

Player.CameraMaxZoomDistance

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.

Player.CameraMinZoomDistance

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.

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

Code samples: View on Creator Hub (playing-in-first-person).

Player.CanLoadCharacterAppearance

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 LoadCharacterAsync() to load the new appearance.

Player.Character

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 LoadCharacterAsync().

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:

Code samples: View on Creator Hub (Player-Character).

Player.CharacterAppearance

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

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 LoadCharacterAsync() to load the new appearance.

Player.CharacterAppearanceId

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.

Player.DataComplexity

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

This property was once used by an ancient data persistence method to indicate the total amount of data currently being stored in the player's cache on the current place.

Notes

• Booleans and numbers cost 1 data complexity unit.
• Strings cost their length divided by 100 in data complexity units.
• Instances cost their DataCost in data complexity units.
• Saving the default value (0 for numbers, false for booleans, "" for strings and nil for Instances) removes the key from the DataComplexity count.
• If, when using the SaveBoolean, SaveString, SaveNumber or SaveInstance functions, the DataComplexity for the player goes over the limit (currently 45000 units, defined by DataComplexityLimit), the function throws an error, the value is not saved, and any previous value of the key that was being saved to is deleted.

Player.DataReady

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

This property was once used by an ancient data persistence method to indicate when the player's data is available to load. Becomes true when data is available.

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

Player.DevComputerCameraMode

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.

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

Player.DevEnableMouseLock

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.

Player.DevTouchCameraMode

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.

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

Player.DisplayName

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 LoadCharacterAsync() 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.

Player.FollowUserId

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.

Code samples: View on Creator Hub (Followed-Alert).

Player.FrustumStreaming

This property controls the engine's instance streaming behavior for the camera view of the given player. Enabled means the player will always stream their camera view. Automatic means the engine will decide to stream the camera view based on the player's capability (based on the bandwidth, device memory, etc.) and gameplay suitability. Disabled means the player will never stream their camera view. Default currently behaves the same as Disabled.

Player.GameplayPaused

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

• Workspace.StreamingEnabled which controls whether content streaming is enabled
• Workspace.StreamingIntegrityMode and StreamingIntegrityMode for more details on when gameplay is paused.

Player.HasRobloxSubscription

This read-only property is true when the player has an active Roblox subscription (the flagship Roblox membership), and false otherwise. It is set by the server and cannot be changed by scripts.

Use this property instead of Player.MembershipType to check for the Roblox subscription.

Code samples: View on Creator Hub (check-roblox-subscription).

Player.HasVerifiedBadge

This property indicates if the player has a Verified badge.

Player.HealthDisplayDistance

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.

Player.InputLatency

Latency used by the Server Authority netcode system. This property is not accessible through scripts.

Player.LocaleId

This property shows the locale ID that the local player has set for their Roblox account. It holds a string with the two letter code, for example en-us.

See also LocalizationService.RobloxLocaleId, the locale ID used for localizing internal content. This can be a different value when the player's account locale isn't supported for internal content localization.

Player.MembershipType

Deprecated. This property is deprecated. Use Player.HasRobloxSubscription to check whether a player has an active Roblox subscription.

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.

Code samples: View on Creator Hub (check-membership-status).

Player.NameDisplayDistance

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.

Player.Neutral

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.

Player.PartyId

A read-only string identifying the party the player currently belongs to within the experience. If the player is not in a party, this value is an empty string.

This property is essential for integrating with the Roblox Party feature. Use it in combination with SocialService:GetPlayersByPartyId() and SocialService:GetPartyAsync() to access information about a player's party and its members.

To test this service in your experience, use the Party Simulator in Roblox Studio or publish the experience and play it in the Roblox application.

Code samples: View on Creator Hub (Player-PartyId).

Player.ReplicationFocus

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.

Player.RespawnLocation

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

• Descendant of Workspace.

• The SpawnLocation.TeamColor property is set to the player's TeamColor or the SpawnLocation.Neutral property is set to true.

Alternatives

• A Player will spawn from SpawnLocations belonging to their team. In some cases it may be simpler to change the player's Team instead.
• Implement your own custom spawn logic using PVInstance:PivotTo() to manually move the Character.

Code samples: View on Creator Hub (change-spawn-on-touch).

Player.StepIdOffset

Offset between client and server used by the Server Authority system. This property is not accessible through scripts.

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

Player.TeamColor

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.

Player.ThirdPartyTextChatRestrictionStatus

This read-only property holds the ChatRestrictionStatus that a third-party platform (for example, a console platform's parental or communication settings) reports for the player's text chat. The default value is ChatRestrictionStatus.Unknown.

This property cannot be set from scripts.

Player.User

A read-only User value that represents this player's domain-scoped identity within the current experience. The User encapsulates the player's domain user ID alongside the domain type and domain ID, providing an unambiguous identifier that carries its context.

Use this property as the standard way to identify users in new code. Engine APIs that accept user ID parameters also accept User values directly.

Code samples: View on Creator Hub (Player-User).

Player.UserId

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.

Code samples: View on Creator Hub (Player-UserId1, GlobalDataStore-GetAsync1).

Player.userId

Deprecated. This property is a deprecated variant of Player.UserId which should be used instead.

Methods

Inherited from Instance

Inherited from Object

Player:AddReplicationFocus

This method adds an additional replication focus for the player in order to trigger streaming around the location of the specified part. In this manner, streaming can occur around multiple locations, not just the location of Player.ReplicationFocus. This has no effect in experiences that are not streaming enabled.

Additional foci will use the same values of Workspace.StreamingMinRadius and Workspace.StreamingTargetRadius as are used by the primary focus.

This method should only be called on the server. It has no effect when called from a LocalScript.

Parameters

Returns

Player:ClearCachedAvatarAppearance

This method clears the cached avatar appearance for the player. The next time LoadCharacterAsync() is called with the player's default platform appearance, a fresh version will be fetched from the backend instead of using the cached version.

Avatar appearance is cached after the first load to improve respawn latency and reduce backend load; most players do not change their avatar mid-session. Call this method when you want to reflect a change the player has made to their avatar outside of the experience, for example to implement a custom refresh button that mirrors the behavior of the default in-experience menu.

Returns

Player:ClearCharacterAppearance

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.

Returns

Code samples: View on Creator Hub (Player-ClearCharacterAppearance1).

Player:DistanceFromCharacter

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:

Parameters

Returns

Code samples: View on Creator Hub (Player-DistanceFromCharacter1, Player-DistanceFromCharacter).

Player:GetCameraState

Returns a dictionary containing information about the player's current camera state. This method requires Server Authority to be enabled in the game. The dictionary contains the following fields:

On the client, this method can only be called on the Players.LocalPlayer. On the server, it can be called on any Player object to retrieve their replicated camera state. Typical server-side uses include aim and look-direction logic in server-authoritative gameplay, and camera-aware content streaming.

The CFrame field is replicated as part of the player's input stream, meaning it is synchronized with other inputs such as movement and actions. The FieldOfView and ViewportSize fields use standard client-to-server property replication which is not synchronized with input and may update at a different cadence.

Returns

Code samples: View on Creator Hub (Player-GetCameraState).

Player:GetFriendsOnline

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

This method returns an array describing the LocalPlayer's currently online friends, up to a maximum of maxFriends entries. It can only be called on the Players.LocalPlayer; calling it on any other Player raises an error. No more than 200 friends are ever returned, and requesting more logs a warning.

This method has been superseded by GetFriendsOnlineAsync(), which shares the same behavior and return format. See that method for the full description of the returned dictionary array.

Parameters

Returns

Code samples: View on Creator Hub (how-to-get-a-list-of-online-friends).

Player:GetFriendsOnlineAsync

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

Parameters

Returns

Code samples: View on Creator Hub (how-to-get-a-list-of-online-friends).

Player:GetFriendsWhoPlayedAsync

Returns an array of user IDs of any friends who have previously played this game. For example, if a player has had two friends play the game, the method might return {1111111111, 2222222222}. If no friends have played this game, the method returns an empty array ({}).

This is particularly useful for friend leaderboards: by narrowing DataStore lookups to only friends who have actually played the experience, you avoid fetching scores for the entire friends list and reduce the risk of hitting DataStore rate limits.

Returns

Player:GetJoinData

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

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.

Returns

Code samples: View on Creator Hub (Player-GetJoinData-Tracking-Traffic-Sources, Player-GetJoinData-Referral-Url-Generator, Player-GetJoinData-Table-as-Launch-Data, Player-GetJoinData-Decoding-Json-Launch-Data, server-teleportdata-example).

Player:GetMouse

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.

Returns

Player:GetNetworkPing

Returns the round-trip, 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.

Returns

Player:GetRankInGroup

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

Only public roles are considered.

Parameters

Returns

Code samples: View on Creator Hub (Player-GetRankInGroup1).

Player:GetRankInGroupAsync

Deprecated. This method returns only the rank value of the member's highest public role. Use GroupService:GetRolesInGroupAsync() instead, which returns all public roles.

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. Only public roles are considered.

This call may not yield the most up-to-date information. If a player leaves a group while they are in the experience, GetRankInGroupAsync() 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 GetRankInGroupAsync() 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.

When a player joins a group in-experience due to a call to GroupService:PromptJoinAsync(), any cached value for that player will be cleared on the client where the prompt was shown.

Parameters

Returns

Code samples: View on Creator Hub (Player-GetRankInGroup1).

Player:GetRoleInGroup

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

Only public roles are considered.

Parameters

Returns

Code samples: View on Creator Hub (Player-GetRoleInGroup1).

Player:GetRoleInGroupAsync

Deprecated. This method returns only the member's highest public role. Use GroupService:GetRolesInGroupAsync() instead, which returns all public roles.

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

This call may not yield the most up-to-date information. If a player leaves a group while they are in the experience, GetRoleInGroupAsync() 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 GetRoleInGroupAsync() 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.

When a player joins a group in-experience due to a call to GroupService:PromptJoinAsync(), any cached value for that player will be cleared on the client where the prompt was shown.

Parameters

Returns

Code samples: View on Creator Hub (Player-GetRoleInGroup1).

Player:HasAppearanceLoaded

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.

Returns

Code samples: View on Creator Hub (check-if-a-player-s-appearance-has-loaded).

Player:IsBestFriendsWith

Deprecated. This function is obsolete because the "best friends" feature was removed. Use Player:IsFriendsWithAsync() instead.

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

Parameters

Returns

Player:IsFriendsWith

Deprecated. This method has been superseded by the Player:IsFriendsWithAsync() method which should be used for new work.

This method sends a request to Roblox asking whether the player is a friend of the user with the given UserId. Results are cached, so multiple calls on the same player with the same userId may not reflect the most up-to-date friendship status.

This method has been superseded by IsFriendsWithAsync(), which shares the same behavior and should be used for new work.

Parameters

Returns

Code samples: View on Creator Hub (Player-IsFriendsWith1).

Player:isFriendsWith

Deprecated. This method has been superseded by the Player:IsFriendsWithAsync() method which should be used for new work.

Parameters

Returns

Player:IsFriendsWithAsync

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.

Parameters

Returns

Player:IsInGroup

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

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

This method has been superseded by IsInGroupAsync(), which shares the same behavior (including its per-peer result caching) and should be used for new work.

Parameters

Returns

Player:IsInGroupAsync

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

This call may not yield the most up-to-date information. If a player leaves a group while they are in the experience, IsInGroupAsync() 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 IsInGroupAsync() 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.

When a player joins a group in-experience due to a call to GroupService:PromptJoinAsync(), any cached value for that player will be cleared on the client where the prompt was shown.

Parameters

Returns

Player:IsVerified

Returns a boolean value indicating whether the player meets the specified VerifiedLevel. When level is omitted, this method defaults to VerifiedLevel.Low. Note that this is a distinct check from the verified badge.

Verification uses concrete, real-world signals, including, but not limited to, 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.

Parameters

Returns

Code samples: View on Creator Hub (Player-IsVerified).

Player:Kick

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.

Parameters

Returns

Player:LoadBoolean

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

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.

Parameters

Returns

Player:loadBoolean

Deprecated. This deprecated function is a variant of Player:LoadBoolean() which has also been deprecated. Neither function should be used in new work.

Parameters

Returns

Player:LoadCharacter

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

This method creates a new Character for the player, removing the old one, and also clears the player's Backpack and PlayerGui. It can only be called on the server.

This method has been superseded by LoadCharacterAsync(), which shares the same character-loading behavior and should be used for new work.

Returns

Code samples: View on Creator Hub (Player-LoadCharacter1).

Player:LoadCharacterAppearance

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

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:LoadCharacterAsync(), except it does not reload the entire character instance, StarterGear, or PlayerGui.

Note:

• Accessory, Shirt, ShirtGraphic, CharacterMesh, BodyColors, and Accoutrement are parented to the player's character.
• Decal, FileMesh, SpecialMesh, BlockMesh, CylinderMesh, and Texture are parented to the character's head.
• Tool is parented to the player's StarterGear.
• All other classes are ignored.

Parameters

Returns

Code samples: View on Creator Hub (Player-LoadCharacterAppearance1).

Player:LoadCharacterAsync

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.

When reloading a Player with their default platform appearance applied, a cached version of their appearance will be loaded. The cached version is cleared whenever the player's appearance is updated using AvatarEditorService or when the player manually resets via the in-experience menu. To programmatically clear this cache, call ClearCachedAvatarAppearance() before calling LoadCharacterAsync().

After calling LoadCharacterAsync() 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 LoadCharacterAsync() method on any Player fires events in the following order:

1. Player.Character sets, automatically removing old character.
2. Player.CharacterAdded fires.
3. Object.Changed fires on the Player with a value of Character.
4. The character appearance initializes.
5. Player.CharacterAppearanceLoaded fires.
6. The character's Parent sets to the DataModel.
7. The character rig builds and scales.
8. The character moves to the spawn location.

Returns

Code samples: View on Creator Hub (Player-LoadCharacter1).

Player:LoadCharacterWithHumanoidDescription

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

This method spawns a player character with everything equipped in the passed-in HumanoidDescription, such as body parts, colors, body scaling, accessories, clothing, and animations. A nil description raises an error, and a description that contains duplicate costume assets or duplicate body parts logs a warning before the character loads.

This method has been superseded by LoadCharacterWithHumanoidDescriptionAsync(), which shares the same behavior and should be used for new work.

Parameters

Returns

Code samples: View on Creator Hub (spawn-characters-with-humanoiddescription).

Player:LoadCharacterWithHumanoidDescriptionAsync

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.

Parameters

Returns

Code samples: View on Creator Hub (spawn-characters-with-humanoiddescription).

Player:LoadInstance

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

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.

Parameters

Returns

Code samples: View on Creator Hub (Player-LoadInstance1).

Player:loadInstance

Deprecated. This deprecated function is a variant of Player:LoadInstance() which has also been deprecated. Neither function should be used in new work.

Parameters

Returns

Player:LoadNumber

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

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.

Parameters

Returns

Code samples: View on Creator Hub (Player-LoadNumber1).

Player:loadNumber

Deprecated. This deprecated function is a variant of Player:LoadNumber() which has also been deprecated. Neither function should be used in new work.

Parameters

Returns

Player:LoadString

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

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.

Parameters

Returns

Code samples: View on Creator Hub (Player-LoadString1).

Player:loadString

Deprecated. This function is a deprecated variant of Player:LoadString() which has also been deprecated. Neither function should be used in new work.

Parameters

Returns

Player:Move

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

Parameters

Returns

Code samples: View on Creator Hub (Player-Move1).

Player:PromptAgeCheck

This method requests that the player be shown the age verification prompt. When called from a LocalScript, it must target the Players.LocalPlayer; when called from a server Script, it can target any Player. Repeated calls for the same player within a short cooldown window are silently ignored.

On success, the PromptAgeCheckRequested event fires on the target player's client. When the player passes verification, their Player.AgeChecked property transitions to AgeCheckStatus.Checked.

Returns

Player:RemoveReplicationFocus

This method removes a replication focus previously added by AddReplicationFocus(). Has no effect in experiences that are not streaming enabled.

This method should only be called on the server. It has no effect when called from a LocalScript.

Parameters

Returns

Player:RequestStreamAroundAsync

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.

Parameters

Returns

Player:SaveBoolean

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

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

Parameters

Returns

Code samples: View on Creator Hub (Player-SaveBoolean1).

Player:saveBoolean

Deprecated. This function is a deprecated variant of Player:SaveBoolean() which has also been deprecated. Neither function should be used in new work.

Parameters

Returns

Player:SaveInstance

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

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

Parameters

Returns

Code samples: View on Creator Hub (Player-SaveInstance1).

Player:saveInstance

Deprecated. This function is a deprecated variant of Player:SaveInstance() which has also been deprecated. Neither function should be used in new work.

Parameters

Returns

Player:SaveNumber

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

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

Parameters

Returns

Code samples: View on Creator Hub (Player-SaveNumber1).

Player:saveNumber

Deprecated. This function is a deprecated variant of Player:SaveNumber() which has also been deprecated. Neither function should be used in new work.

Parameters

Returns

Player:SaveString

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

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

Parameters

Returns

Code samples: View on Creator Hub (Player-SaveString1).

Player:saveString

Deprecated. This function is a deprecated variant of Player:SaveString() which has also been deprecated. Neither function should be used in new work.

Parameters

Returns

Player:SetAccountAge

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

Parameters

Returns

Player:SetSuperSafeChat

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

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.

Parameters

Returns

Player:WaitForDataReady

Deprecated. This item is deprecated, as it may have been used for a now obsolete data persistence method. Please save and load player data using DataStoreService for new work.

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

Returns

Player:waitForDataReady

Deprecated. This function is a deprecated variant of Player:WaitForDataReady() which has also been deprecated. Neither function should be used in new work.

Returns

Events

Inherited from Instance

Inherited from Object

Player.CharacterAdded

This event fires when a player's character spawns or respawns. It fires soon after setting Character to a non-nil value or calling LoadCharacterAsync(), 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 on the server when this event fires, but clothing items like Hats, Shirts, and Pants might take a few seconds to be added to the character. The parts will also take time to replicate to clients. 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.

Parameters

Code samples: View on Creator Hub (spawns-and-despawns, accessory-remover).

Player.CharacterAppearanceLoaded

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.

Parameters

Code samples: View on Creator Hub (remove-accessories-after-loading).

Player.CharacterRemoving

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.

Parameters

Code samples: View on Creator Hub (spawns-and-despawns).

Player.Chatted

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.

Parameters

Player.Idled

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.

Once the player becomes active again, Idled stops firing and the elapsed idle time resets. There is no separate event for the transition back to activity. If the player goes idle again later, Idled waits the same ~2 minutes before firing again.

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.

Parameters

Player.OnTeleport

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

Parameters

Code samples: View on Creator Hub (Player-OnTeleport1).