Player
Player : Instance
Overview
The Player object represents each user connected to the server.
When a new user connects, they are registered as a Player object in the Players service and automatically removed from the list when disconnected.
Although the Name property of this object displays the user's nickname, it is safer to use UserId instead of the nickname for data storage because nicknames can be changed while UserId remains fixed.
To detect users connecting to the server, use the Players.PlayerAdded event. To detect disconnections, use the Players.PlayerRemoving event. This allows you to safely perform data saving or cleanup before a player leaves.
The list of all currently connected users can be retrieved using the Players:GetPlayers() method.
Properties
Character
Model
Returns the model object that constitutes the player's avatar, including the humanoid, body parts, scripts, and various elements needed for avatar movement.
The Character is automatically created if Players.CharacterAutoLoads is true, but if false, it must be manually created by calling LoadCharacter().
The initial value of this property is nil, and when the player's character is created, the model is assigned to this property.
It is recommended to use the CharacterAdded event for detecting the creation of a character and use the CharacterRemoving event for detecting just before a character removal.
Code Samples
local Players = game:GetService("Players")
local function OnAddPlayer(player)
repeat wait(0.1) until player.Character
local character = player.Character
end
Players.PlayerAdded:Connect(OnAddPlayer)
UserId
string
Returns a read-only unique ID that identifies the user's account.
Unlike the nickname, UserId never changes, so it is used for identifying accounts when storing or retrieving player data via DataStore.
Code Samples
local Players = game:GetService("Players")
local function OnAddPlayer(player)
print(player.UserId)
end
Players.PlayerAdded:Connect(OnAddPlayer)
Team
Team
Currently not supported.
Code Samples
TeamColor
BrickColor
Currently not supported.
Code Samples
RespawnLocation
SpawnLocation
Sets the SpawnLocation object where the player's character will respawn.
The specified object must belong to the Workspace.
Code Samples
local Workspace = game:GetService("Workspace")
local Players = game:GetService("Players")
local Part = script.Parent
local Checkpoint = Workspace:WaitForChild("Checkpoint")
local function SetCheckpoint(otherPart)
local partParent = otherPart.Parent
local humanoid = partParent:FindFirstChild("Humanoid")
if humanoid then
local character = humanoid.Parent
local player = Players:GetPlayerFromCharacter(character)
player.RespawnLocation = Checkpoint
end
end
Part.Touched:Connect(SetCheckpoint)
Methods
GetMouse
Returns the client's Mouse object.
The returned object can be used to detect and process mouse inputs such as left or right clicks.
However, in mobile environments, it is generally recommended to use UserInputService.
Parameters
Mouse
The mouse object.
Code Samples
local Players = game:GetService("Players")
local Player = Players.LocalPlayer
local Mouse = Player:GetMouse()
local function OnButton1Down()
print("Button1Down", Mouse.Target)
if Mouse.Target.Name == "SpawnLocation" then
print("Hit SpawnLocation!")
end
end
Mouse.Button1Down:Connect(OnButton1Down)
LoadCharacter
Removes the player's current character and creates a new one.
This is mainly used when the character needs to be recreated without killing the player.
Parameters
Return
void
Code Samples
player:LoadCharacter()
RemoveCharacter
Removes the player's current character.
When the character is removed with RemoveCharacter(), the Character property is set to nil, and it can only be recreated by calling the LoadCharacter() method.
Parameters
Return
void
Code Samples
player:RemoveCharacter()
Events
CharacterAdded
This event is executed when the player's character is created or recreated.
At this point, the character's humanoid and basic body parts (head, torso, limbs) already exist, but clothing and accessories (hats, shirts, pants, etc.) can be added a few seconds later.
To track a player's connection or disconnection, the Players.PlayerAdded and Players.PlayerRemoving events need to be used.
Parameters
Model
Character
The created character.
Code Samples
local Players = game:GetService("Players")
local function OnEnterPlayer(player)
local function OnCharacterAdded(character)
print("[OnAddCharacter]", character)
end
player.CharacterAdded:Connect(OnCharacterAdded)
end
Players.PlayerAdded:Connect(OnEnterPlayer)
CharacterRemoving
This event is executed just before the player's character is deleted.
This is mainly used to perform necessary actions before the character object is removed.
To track a player's connection or disconnection, the Players.PlayerAdded and Players.PlayerRemoving events need to be used.
Parameters
Model
Character
The removed character.
Code Samples
local Players = game:GetService("Players")
local function OnEnterPlayer(player)
local function OnCharacterRemoving(character)
print("[OnCharacterRemoving]", character)
end
player.CharacterRemoving:Connect(OnCharacterRemoving)
end
Players.PlayerAdded:Connect(OnEnterPlayer)
Last updated