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

Return

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)