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

CameraMaxZoomDistance

number

This property defines the maximum zoom-out distance of the camera. Increasing this value allows the camera to zoom out farther, while decreasing it limits the maximum zoom-out range. If the current camera zoom distance exceeds the updated CameraMaxZoomDistance, the camera’s zoom distance will be automatically clamped to the specified maximum value.

Code Samples

local Players = game:GetService("Players") 
local Player = Players.LocalPlayer

player.CameraMaxZoomDistance = 50  

CameraMinZoomDistance

number

This property defines the minimum zoom-in distance of the camera. Decreasing this value allows the camera to move closer to the character, while increasing it prevents the camera from zooming in beyond a certain point. If the current camera zoom distance is smaller than the updated CameraMinZoomDistance, the camera’s zoom distance will be automatically clamped to the specified minimum value.

Code Samples

local Players = game:GetService("Players") 
local Player = Players.LocalPlayer

player.CameraMaxZoomDistance = 10  

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)

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)

Team

Team

Currently not supported.

Code Samples

TeamColor

BrickColor

Currently not supported.

Code Samples

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)

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)

GetNetworkPing

This method returns the player’s current network ping (latency) in seconds. The ping value represents the communication delay between the client and the server — a lower value indicates a faster and more stable connection.

Parameters

Return

number	The player's current network ping (in seconds).

Code Samples

local Players = game.Players

Players.PlayerAdded:Connect(function(player)
    print(player.Name.." : "..player:GetNetworkPing())
end)

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)