Player

Show Deprecated

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:

Summary

Properties

Methods

Events

Properties

AccountAge

Read Only
Not Replicated
Read Parallel

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.

AutoJumpEnabled

Read Parallel

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

This code sample is meant for a TextButton. It allows the player to toggle the auto-jumping behavior while on a mobile device.

Auto-Jump Toggle

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local button = script.Parent
local function update()
-- Update button text
if player.AutoJumpEnabled then
button.Text = "Auto-Jump is ON"
else
button.Text = "Auto-Jump is OFF"
end
-- Reflect the property in the player's character, if they have one
if player.Character then
local human = player.Character:FindFirstChild("Humanoid")
if human then
human.AutoJumpEnabled = player.AutoJumpEnabled
end
end
end
local function onActivated()
-- Toggle auto-jump
player.AutoJumpEnabled = not player.AutoJumpEnabled
-- Update everything else
update()
end
button.Activated:Connect(onActivated)
update()

CameraMaxZoomDistance

Read Parallel

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.

CameraMinZoomDistance

Read Parallel

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.

CameraMode

Read Parallel

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

Third Person

In the default third person mode (Enum.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 (Enum.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

This example demonstrates how to change the character's CameraMode to first person using the LockFirstPerson value of the Enum.CameraMode enum.

Playing in First Person

local Players = game:GetService("Players")
local player = Players.LocalPlayer
player.CameraMode = Enum.CameraMode.LockFirstPerson

CanLoadCharacterAppearance

Read Parallel

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.

Character

Read Parallel

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:


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

CharacterAppearanceId

Read Parallel

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.

DevCameraOcclusionMode

Read Parallel

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 Enum.DevCameraOcclusionMode for a list of available modes.

Read Parallel

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.

DevComputerMovementMode

Read Parallel

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.

DevEnableMouseLock

Read Parallel

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.

Read Parallel

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.

DevTouchMovementMode

Read Parallel

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.

DisplayName

Read Parallel

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.

FollowUserId

Read Only
Not Replicated
Read Parallel

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

This code sample alerts players if a new player follows the local player into the game. Place this in a LocalScript in StarterPlayerScripts.

Followed Alert

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local screenGui = Instance.new("ScreenGui")
screenGui.Parent = player:WaitForChild("PlayerGui")
local function onPlayerAdded(newPlayer)
if newPlayer.FollowUserId == player.UserId then
local textLabel = Instance.new("TextLabel")
textLabel.Parent = screenGui
textLabel.Text = "You were followed to this game by " .. newPlayer.Name .. "!"
task.delay(3, function()
if textLabel then
textLabel:Destroy()
end
end)
end
end
Players.PlayerAdded:Connect(onPlayerAdded)

GameplayPaused

Not Accessible Security
Read Parallel

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

HasVerifiedBadge

Read Parallel

This property indicates if the player has a Verified badge.

HealthDisplayDistance

Read Parallel

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.

LocaleId

Hidden
Read Only
Not Replicated
Read Parallel

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 will be a different value when Roblox does not yet internally support the local player's set locale.

MembershipType

Read Only
Not Replicated
Read Parallel

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

Code Samples

The following example checks whether a player has Premium membership.

Check Player Membership Status

local Players = game:GetService("Players")
local player = Players.LocalPlayer
if player.MembershipType == Enum.MembershipType.Premium then
-- Take some action specifically for Premium members
end

NameDisplayDistance

Read Parallel

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.

Neutral

Read Parallel

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.

PartyId

Hidden
Not Replicated
Roblox Security
Read Parallel

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.

Note that this service does not work during playtesting in Roblox Studio; to test aspects of your experience using it, you must publish the experience and play it in the Roblox application.

Code Samples

This example checks the Player.PartyId of a Player when they join the experience. If the player is in a party, it outputs the Player.PartyId; otherwise, it outputs that the player is not in a party.

Player.PartyId

local Players = game:GetService("Players")
Players.PlayerAdded:Connect(function(player)
local partyId = player.PartyId
if partyId ~= "" then
print("Player is in a party with ID: " .. partyId)
else
warn("Player is not in a party")
end
end)

ReplicationFocus

Read Parallel

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.

RespawnLocation

Read Parallel

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

Alternatives

Code Samples

This code sample will set the player to always respawn from the last SpawnLocation they touched. New players will respawn from the SpawnLocation named 'FirstSpawn' until they touch a different SpawnLocation.

This is an alternative to using the AllowTeamChangeOnTouch property to switch SpawnLocations and does not require Teams.

Change Spawn on Touch

local Players = game:GetService("Players")
local function addSpawn(spawnLocation)
-- listen for the spawn being touched
spawnLocation.Touched:Connect(function(hit)
local character = hit:FindFirstAncestorOfClass("Model")
if character then
local player = Players:GetPlayerFromCharacter(character)
if player and player.RespawnLocation ~= spawnLocation then
local humanoid = character:FindFirstChildOfClass("Humanoid")
-- make sure the character isn't dead
if humanoid and humanoid:GetState() ~= Enum.HumanoidStateType.Dead then
print("spawn set")
player.RespawnLocation = spawnLocation
end
end
end
end)
end
local firstSpawn
-- look through the workspace for spawns
for _, descendant in pairs(workspace:GetDescendants()) do
if descendant:IsA("SpawnLocation") then
if descendant.Name == "FirstSpawn" then
firstSpawn = descendant
end
addSpawn(descendant)
end
end
local function playerAdded(player)
player.RespawnLocation = firstSpawn
end
-- listen for new players
Players.PlayerAdded:Connect(playerAdded)
-- go through existing players
for _, player in pairs(Players:GetPlayers()) do
playerAdded(player)
end

StepIdOffset

Roblox Security
Read Parallel

Team

Not Replicated
Read Parallel

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.

TeamColor

Read Parallel

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.

ThirdPartyTextChatRestrictionStatus

Read Only
Not Replicated
Roblox Script Security
Read Parallel

UserId

Read Parallel

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

The below example would print the UserId of every user who entered a game.

Player.UserId

local Players = game:GetService("Players")
local function onPlayerAdded(player)
print(player.UserId)
end
Players.PlayerAdded:Connect(onPlayerAdded)

This code sample retrieves a player's saved gold from a data store and puts the returned value onto the leaderboard. Note that this sample does not save players' gold — it only loads it.

Data Store to Leaderboard

local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local goldDataStore = DataStoreService:GetDataStore("Gold")
local STARTING_GOLD = 100
local function onPlayerAdded(player)
local playerKey = "Player_" .. player.UserId
local leaderstats = Instance.new("IntValue")
leaderstats.Name = "leaderstats"
local gold = Instance.new("IntValue")
gold.Name = "Gold"
gold.Parent = leaderstats
local success, result = pcall(function()
return goldDataStore:GetAsync(playerKey) or STARTING_GOLD
end)
if success then
gold.Value = result
else
-- Failed to retrieve data
warn(result)
end
leaderstats.Parent = player
end
Players.PlayerAdded:Connect(onPlayerAdded)

Methods

AddReplicationFocus

()

Parameters

part: BasePart
Default Value: ""

Returns

()

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

How to Clear a Character's Appearance

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
local function onChildRemoved(child)
print(child.ClassName, "removed from character")
end
character.ChildRemoved:Connect(onChildRemoved)
player:ClearCharacterAppearance()
--> BodyColors removed from character
--> ShirtGraphic removed from character
--> Shirt removed from character
--> Pants removed from character
--> CharacterMesh removed from character
--> Hat removed from character
--> Shirt removed from character

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:


local distance = (position1 - position2).Magnitude

Parameters

point: Vector3

The location from which player's distance to is being measured.

Default Value: ""

Returns

The distance in studs between the player and the location.

Code Samples

This example demonstrates how to measure the distance between a player's Player.Character and another location.

This code will print the distance of each player's character from the origin (0, 0, 0):

Measuring the Distance Between a Player and a Position

local Players = game:GetService("Players")
for _, player in pairs(Players:GetPlayers()) do
print(player:DistanceFromCharacter(Vector3.new(0, 0, 0)))
end

GetJoinData

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


Returns

A dictionary containing PlaceId and UserId values (see table in description).

Code Samples

The following example tracks sources of traffic for analytics. By creating URLs with unique launch data for each social platform, you can determine the most popular traffic sources. The sample checks the source against a list of possible samples and discards any invalid sources because users can modify the launch data.

Tracking Traffic Sources

local DataStoreService = game:GetService("DataStoreService")
local Players = game:GetService("Players")
local analyticsStore = DataStoreService:GetDataStore("Analytics")
local ALLOWED_SOURCES = {
"twitter",
"youtube",
"discord",
}
local function onPlayerAdded(player)
local source = player:GetJoinData().LaunchData
-- check if the provided source is valid
if source and table.find(ALLOWED_SOURCES, source) then
-- update the data store to track the source popularity
local success, result = pcall(analyticsStore.IncrementAsync, analyticsStore, source)
if success then
print(player.Name, "joined from", source, "- total:", result)
else
warn("Failed to record join source: " .. result)
end
end
end
Players.PlayerAdded:Connect(onPlayerAdded)

The following example generates a URL with the user's ID used as launch data. It then displays the URL in a read-only text box that makes it easy for the user to copy and share the link with their friends. When a user joins the game using a referral link, you can use the launch data to reward the referrer.

Referral URL Generator

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local DIRECT_JOIN_URL = "https://www.roblox.com/games/start?placeId=%d&launchData=%s"
local textBox = script.Parent
local function generateReferralURL(player)
return DIRECT_JOIN_URL:format(game.PlaceId, player.UserId)
end
local function highlightAll()
if -- avoid recursive property updates
textBox:IsFocused() and not (textBox.SelectionStart == 1 and textBox.CursorPosition == #textBox.Text + 1)
then
textBox.SelectionStart = 1
textBox.CursorPosition = #textBox.Text + 1
end
end
textBox.Focused:Connect(highlightAll)
textBox:GetPropertyChangedSignal("SelectionStart"):Connect(highlightAll)
textBox:GetPropertyChangedSignal("CursorPosition"):Connect(highlightAll)
textBox.TextEditable = false
textBox.ClearTextOnFocus = false
textBox.Text = generateReferralURL(player)

The following example is a function that converts a table into a string you can use as launch data. The provided data is JSON encoded, checked for valid character length, and escaped with percent signs.

Using a Table as Launch Data

local HttpService = game:GetService("HttpService")
local DATA_CHARACTER_LIMIT = 200
local function encodeTableAsLaunchData(data)
-- convert the table to a string
local jsonEncodedData = HttpService:JSONEncode(data)
if #jsonEncodedData <= DATA_CHARACTER_LIMIT then
-- escape potentially invalid characters, such as spaces
local urlEncodedData = HttpService:UrlEncode(jsonEncodedData)
return true, urlEncodedData
else
-- report character limit error
return false, ("Encoded table exceeds %d character limit"):format(DATA_CHARACTER_LIMIT)
end
end
local sampleData = {
joinMessage = "Hello!",
urlCreationDate = os.time(),
magicNumbers = {
534,
1337,
746733573,
},
}
local success, encodedData = encodeTableAsLaunchData(sampleData)
if success then
print(encodedData)
else
warn("failed to encode launch data: " .. encodedData)
end

The following example attempts to decode launch data, using pcall to prevent an error in case the data is corrupt.

Decoding JSON Launch Data

local HttpService = game:GetService("HttpService")
local Players = game:GetService("Players")
local function onPlayerAdded(player)
local launchData = player:GetJoinData().LaunchData
if launchData then
-- attempt to decode the data
local success, result = pcall(HttpService.JSONDecode, HttpService, launchData)
if success then
print(player.Name, "joined with data:", result)
else
-- this is probably due to the user messing with the URL
warn("Failed to parse launch data:" .. result)
end
end
end
Players.PlayerAdded:Connect(onPlayerAdded)

The following code sample is an example of how teleport data can be retrieved on the server using Player:GetJoinData(). This code, when ran in a Script in ServerScriptService, will listen for new Player|Players joining the game. When they join it will retrieve their teleport data (verifying it came from a valid place) to find their current level.

Server TeleportData Example

local Players = game:GetService("Players")
local approvedPlaceIds = { 1 } -- insert approved PlaceIds here
local function isPlaceIdApproved(placeId)
for _, id in pairs(approvedPlaceIds) do
if id == placeId then
return true
end
end
return false
end
local function onPlayerAdded(player)
local joinData = player:GetJoinData()
-- verify this data was sent by an approved place
if isPlaceIdApproved(joinData.SourcePlaceId) then
local teleportData = joinData.TeleportData
if teleportData then
local currentLevel = teleportData.currentLevel
print(player.Name .. " is on level " .. currentLevel)
end
end
end
Players.PlayerAdded:Connect(onPlayerAdded)

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

GetNetworkPing

Write Parallel

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.


Returns

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

A boolean indicating whether or not the appearance of the player's character has loaded.

Code Samples

This example prints the result of Player:HasAppearanceLoaded() after a player joins the game until the player's appearance has loaded.

Check if a Player's Appearance Has Loaded

local Players = game:GetService("Players")
local function onPlayerAdded(player)
local loaded = player:HasAppearanceLoaded()
print(loaded)
while not loaded do
loaded = player:HasAppearanceLoaded()
print(loaded)
task.wait()
end
end
Players.PlayerAdded:Connect(onPlayerAdded)

IsVerified

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.


Returns

A boolean indicating whether the player is verified.

Code Samples

The following example prints "true" if the player is verified.

Using IsVerified

local Players = game:GetService("Players")
local function onPlayerAdded(player)
print(player:IsVerified())
end
for _, player in pairs(Players:GetPlayers()) do
onPlayerAdded(player)
end
Players.PlayerAdded:Connect(onPlayerAdded)

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

message: string

The message to show the user upon kicking.

Default Value: ""

Returns

()

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

walkDirection: Vector3

The Vector3 direction that the player should move.

Default Value: ""
relativeToCamera: boolean

A boolean indicating whether the player should move relative to the player's camera.

Default Value: false

Returns

()

Code Samples

Demonstrates moving a player relative to their camera's position using Player:Move().

The script first waits for the player's Character and Humanoid to load, as both are required before calling Player:Move(). Otherwise a warning will display in the Output.

Moving the Player relative to their Camera

local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
-- Wait for the player's character and humanoid, which must exist before calling :Move()
local character = localPlayer.Character or localPlayer.CharacterAdded:Wait()
character:WaitForChild("Humanoid")
-- The player will move until they are 50 studs away from the camera's position at the time of running
localPlayer:Move(Vector3.new(0, 0, -50), true)

RemoveReplicationFocus

()

Parameters

part: BasePart
Default Value: ""

Returns

()

SetAccountAge

()
Plugin Security

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

accountAge: number

The age of the account in days.

Default Value: ""

Returns

()

SetSuperSafeChat

()
Plugin Security

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

value: boolean

A boolean indicating whether or not the player sees filtered chat.

Default Value: ""

Returns

()

GetFriendsOnline

Yields

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.

Parameters

maxFriends: number

The maximum number of online friends to return.

Default Value: 200

Returns

A dictionary of online friends (see the table above).

Code Samples

This example demonstrates how to get a dictionary of a player's online friends. It returns the maximum number of friends specified by the argument, or 200 if an argument is not provided.

Get a List of Online Friends

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local success, result = pcall(player.GetFriendsOnline, player, 10)
if success then
for _, friend in pairs(result) do
print(friend.UserName)
end
else
warn("Failed to get online players: " .. result)
end

GetRankInGroup

Yields

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.

Parameters

groupId: number

The groupId of the specified group.

Default Value: ""

Returns

The player's rank in the group.

Code Samples

The code below will check if a player that has entered the game has a rank equal to 255, in a group with an ID of 2. If they are, it will print "Player is the owner of the group, 'LOL'!", otherwise "Player is NOT the owner of the group, 'LOL'!" will be printed to the output.

How to Check a Player's Rank in a Group

local Players = game:GetService("Players")
local function onPlayerAdded(player)
if player:GetRankInGroup(2) == 255 then
print("Player is the owner of the group, 'LOL'!")
else
print("Player is NOT the owner of the group, 'LOL'!")
end
end
Players.PlayerAdded:Connect(onPlayerAdded)

GetRoleInGroup

Yields

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.

Parameters

groupId: number

The group ID of the specified group.

Default Value: ""

Returns

The player's role in the specified group, or Guest if the player is not a member.

Code Samples

The code below will print the name of the rank that the player is currently a part of, in a specific group. In this instance we're checking what rank the player is within a group which has a group ID of 2.

How to Check a Player's Role in a Group

local Players = game:GetService("Players")
local function onPlayerAdded(player)
print("Player is ranked as '", player:GetRoleInGroup(2), "' in group, 'LOL'!")
end
Players.PlayerAdded:Connect(onPlayerAdded)

IsFriendsWith

Yields

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

userId: number

The Player.UserId of the specified player.

Default Value: ""

Returns

A boolean indicating whether a player is a friend of the specified user.

Code Samples

The below example would print whether or not a recently added player is friends with Gordonrox24.

How to Check if a Player is a Friend

local Players = game:GetService("Players")
local function onPlayerAdded(player)
if player:IsFriendsWith(146569) then
print(player.Name .. " is friends with gordonrox24!")
end
end
Players.PlayerAdded:Connect(onPlayerAdded)

IsInGroup

Yields

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.

Parameters

groupId: number

The group ID of the specified group.

Default Value: ""

Returns

A boolean indicating whether the player is in the specified group.

LoadCharacter

()
Yields

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. Object.Changed fires on the Player with a value of Character.
  5. The character's Parent sets to the DataModel.

Returns

()

Code Samples

This script turns off auto-loading and simulates character respawning.

Turn Off Auto-Loading and Simulate Character Respawn

local Players = game:GetService("Players")
local RESPAWN_DELAY = 5
Players.CharacterAutoLoads = false
local function onPlayerAdded(player)
local function onCharacterAdded(character)
local humanoid = character:WaitForChild("Humanoid")
local function onDied()
task.wait(RESPAWN_DELAY)
player:LoadCharacter()
end
humanoid.Died:Connect(onDied)
end
player.CharacterAdded:Connect(onCharacterAdded)
player:LoadCharacter()
end
Players.PlayerAdded:Connect(onPlayerAdded)

LoadCharacterWithHumanoidDescription

()
Yields

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

humanoidDescription: HumanoidDescription

A HumanoidDescription containing traits like body parts/colors, body scaling, accessories, clothing, and animations that will be equipped to the loaded character.

Default Value: ""

Returns

()

Code Samples

To create a HumanoidDescription and then spawn a character with that description applied, add a Script (not a LocalScript) to the workspace and add this code to it.

Spawn Characters With HumanoidDescription

local Players = game:GetService("Players")
Players.CharacterAutoLoads = false
local function onPlayerAdded(player)
local humanoidDescription = Instance.new("HumanoidDescription")
humanoidDescription.HatAccessory = "2551510151,2535600138"
humanoidDescription.BodyTypeScale = 0.1
humanoidDescription.ClimbAnimation = 619521311
humanoidDescription.Face = 86487700
humanoidDescription.GraphicTShirt = 1711661
humanoidDescription.HeadColor = Color3.new(0, 1, 0)
player:LoadCharacterWithHumanoidDescription(humanoidDescription)
end
Players.PlayerAdded:Connect(onPlayerAdded)

RequestStreamAroundAsync

()
Yields

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.

Parameters

position: Vector3

World location where streaming is requested.

Default Value: ""
timeOut: number

Optional timeout for the request, the maximum duration that the engine attempts to stream regions around the position parameter before abandoning the request. If you don't specify a value, the timeout is effectively infinite. However, if the client is low on memory, the engine abandons all streaming requests, even those that are still within the timeout duration.

Default Value: 0

Returns

()

Events

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

Parameters

character: Model

An instance of the character that spawned/respawned.


Code Samples

This code sample demonstrates the usage of Players.PlayerAdded, Player.CharacterAdded and Player.CharacterRemoving in order to detect the spawning and despawning of players' characters. You can use this as a boilerplate script to make changes to players' characters as they spawn, such as changing Humanoid.WalkSpeed.

Detecting Player Spawns and Despawns

local Players = game:GetService("Players")
local function onCharacterAdded(character)
print(character.Name .. " has spawned")
end
local function onCharacterRemoving(character)
print(character.Name .. " is despawning")
end
local function onPlayerAdded(player)
player.CharacterAdded:Connect(onCharacterAdded)
player.CharacterRemoving:Connect(onCharacterRemoving)
end
Players.PlayerAdded:Connect(onPlayerAdded)

This code sample automatically removes Accessory objects like hats from the Player's character when they respawn. Warning: this includes hair, so this script may cause acute baldness.

When the Character() is added, we wait for RunService.Stepped to fire once (using the wait function of events). This is so the accessory removal logic runs one frame after the character spawns. A warning can appear if you delete accessories too quickly after the player spawns, so waiting one frame will avoid that.

Accessory Remover

local Players = game:GetService("Players")
local RunService = game:GetService("RunService")
local function destroyAccessory(object)
if object:IsA("Hat") or object:IsA("Accessory") then
object:Destroy()
end
end
local function onCharacterAdded(character)
-- Wait a brief moment before removing accessories to avoid the
-- "Something unexpectedly set ___ parent to NULL" warning
RunService.Stepped:Wait()
-- Check for any existing accessories in the player's character
for _, child in pairs(character:GetChildren()) do
destroyAccessory(child)
end
-- Hats may be added to the character a moment after
-- CharacterAdded fires, so we listen for those using ChildAdded
character.ChildAdded:Connect(destroyAccessory)
end
local function onPlayerAdded(player)
player.CharacterAdded:Connect(onCharacterAdded)
end
Players.PlayerAdded:Connect(onPlayerAdded)

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

This code sample will wait for accessories to fully load, print out how many there are, and then destroy them all.

Remove Accessories After Loading

local Players = game:GetService("Players")
local function onPlayerAddedAsync(player)
local connection = player.CharacterAppearanceLoaded:Connect(function(character)
-- All accessories have loaded at this point
local humanoid = character:FindFirstChildOfClass("Humanoid")
local numAccessories = #humanoid:GetAccessories()
print(("Destroying %d accessories for %s"):format(numAccessories, player.Name))
humanoid:RemoveAccessories()
end)
-- Make sure we disconnect our connection to the player after they leave
-- to allow the player to get garbage collected
player.AncestryChanged:Wait()
connection:Disconnect()
end
for _, player in Players:GetPlayers() do
task.spawn(onPlayerAddedAsync, player)
end
Players.PlayerAdded:Connect(onPlayerAddedAsync)

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

character: Model

An instance of the character that is being removed.


Code Samples

This code sample demonstrates the usage of Players.PlayerAdded, Player.CharacterAdded and Player.CharacterRemoving in order to detect the spawning and despawning of players' characters. You can use this as a boilerplate script to make changes to players' characters as they spawn, such as changing Humanoid.WalkSpeed.

Detecting Player Spawns and Despawns

local Players = game:GetService("Players")
local function onCharacterAdded(character)
print(character.Name .. " has spawned")
end
local function onCharacterRemoving(character)
print(character.Name .. " is despawning")
end
local function onPlayerAdded(player)
player.CharacterAdded:Connect(onCharacterAdded)
player.CharacterRemoving:Connect(onCharacterRemoving)
end
Players.PlayerAdded:Connect(onPlayerAdded)

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 Enum.CoreGuiType.Chat to false.

Parameters

message: string

The content of the message the player typed in chat.

recipient: Player

Deprecated. For whisper messages, this was the Player who was the intended target of the chat message.


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.

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

time: number

The time in seconds the player has been idle.


OnTeleport

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

Parameters

teleportState: Enum.TeleportState

The new Enum.TeleportState of the Player.

placeId: number

The ID of the place the Player is being teleported to.

spawnName: string

The name of the spawn to teleport to, if TeleportService:TeleportToSpawnByName() has been used.


Code Samples

This example prints which stage of a teleport a player is at, as well as printing if the teleport was a failure.

Player.OnTeleport

local Players = game:GetService("Players")
Players.PlayerAdded:Connect(function(player)
local playerOnTeleport = player
player.OnTeleport:Connect(function(teleportState, _placeId, _spawnName)
if teleportState == Enum.TeleportState.Started then
print("Teleport started (" .. playerOnTeleport.Name .. ")")
elseif teleportState == Enum.TeleportState.WaitingForServer then
print("Teleport waiting for server (" .. playerOnTeleport.Name .. ")")
elseif teleportState == Enum.TeleportState.InProgress then
print("Teleport in progress (" .. playerOnTeleport.Name .. ")")
elseif teleportState == Enum.TeleportState.Failed then
print("Teleport failed! (" .. playerOnTeleport.Name .. ")")
end
end)
end)