Want a special badge and 30 bux? Make some PolyWorld! Content and post it in the Creations forum!
Dark mode is incomplete! Please report any issues to the Discord.

Player

LocalScripts Scripts Not creatable

Players represent people currently in the place.
A Player is not an Instance. Their avatar in the world is a Character.

Get Players from `Players:GetPlayers`, events such as PlayerAdded, or Touched.

Overview

Properties

Methods

Events

API

Properties

Id

Id readonly : int
Network id of the player for this session.

id

id deprecated : int
Identical to Id.
No longer recommended for use.

Name

Name readonly : string
Display name of the player.

name

name deprecated : string
Identical to Name.
No longer recommended for use.

username

username deprecated : string
Identical to Name.
No longer recommended for use.

Character

Character readonly : Character?
The player's current Character Instance, or nil if they have none.

Camera

Camera readonly : Camera?
The local player's camera. Position is the eye in world space. Rotation is Vector3 yaw/pitch/roll in degrees (X = yaw, Y = pitch, Z = roll), same as `CameraModule.Rotation`.
Writing Position or Rotation takes over the camera (same as setting `CameraModule.Override` to true).
Nil on the server and for any player that is not the local client.

local cam = Players:GetLocalPlayer().Camera
if cam then
    print(cam.Position.x, cam.Position.y, cam.Position.z)
    cam.Position = Vector3.new(0, 20, 40)
    cam.Rotation = Vector3.new(0, -20, 0)
end

Health

Health deprecated : number
Forwards to `Character.Health`.
Prefer the Character property.
No longer recommended for use.

health

health deprecated : number
Identical to Health.
No longer recommended for use.

Position

Position deprecated : Vector3
Forwards to `Character.Position`.
Prefer the Character property.
No longer recommended for use.

position

position deprecated : Vector3
Identical to Position.
No longer recommended for use.

x

x deprecated : number
X component of Position.
Writing teleports the player.
No longer recommended for use.

y

y deprecated : number
Y component of Position.
Writing teleports the player.
No longer recommended for use.

z

z deprecated : number
Z component of Position.
Writing teleports the player.
No longer recommended for use.

Yaw

Yaw deprecated : number
Forwards to `Character.Yaw`.
Prefer the Character property.
No longer recommended for use.

yaw

yaw deprecated : number
Identical to Yaw.
No longer recommended for use.

Animation

Animation deprecated : int
Forwards to `Character.Animation`.
Prefer the Character property.
No longer recommended for use.

animation

animation deprecated : int
Identical to Animation.
No longer recommended for use.

Transparency

Transparency deprecated : number
Forwards to `Character.Transparency`.
Prefer the Character property.
No longer recommended for use.

transparency

transparency deprecated : number
Identical to Transparency.
No longer recommended for use.

CustomNameColor

CustomNameColor : Color?
Override color for chat, player list, and nametag.
Set to nil to restore the default color.

customNameColor

customNameColor deprecated : Color?
Identical to CustomNameColor.
No longer recommended for use.

Team

Team readonly : string?
Current team name from TeamsModule, or nil.
Prefer TeamsModule:GetTeam(player) when assigning.

TeamColor

TeamColor readonly : Color?
Color of the player's current team, or nil.

EquippedHead

EquippedHead readonly : int
Catalog id of the equipped head.

equippedHead

equippedHead deprecated : int
Identical to EquippedHead.
No longer recommended for use.

EquippedShirt

EquippedShirt readonly : int
Catalog id of the equipped shirt.

equippedShirt

equippedShirt deprecated : int
Identical to EquippedShirt.
No longer recommended for use.

EquippedPants

EquippedPants readonly : int
Catalog id of the equipped pants.

equippedPants

equippedPants deprecated : int
Identical to EquippedPants.
No longer recommended for use.

Dead

Dead readonly : bool
Whether the player is currently dead.
Primarily useful in LocalScripts.

dead

dead deprecated : bool
Identical to Dead.
No longer recommended for use.

LastAttacker

LastAttacker readonly : Player?
The player who last damaged this player, or nil if nobody has.
Clears when there is no recorded attacker.

local attacker = player.LastAttacker
if attacker then
    print(attacker.Name, "hit", player.Name)
end

lastAttacker

lastAttacker deprecated : Player?
Identical to LastAttacker.
No longer recommended for use.

Methods

SetPosition

SetPosition(x: number, y: number, z: number) : void deprecated
Teleports the player's Character.
Prefer `Character:SetPosition`.
No longer recommended for use.

SetSpawn

SetSpawn(x: number, y: number, z: number) : void
Sets a custom respawn point.
The next death or respawn uses this position until cleared.

ClearSpawn

ClearSpawn() : void
Clears a custom spawn from SetSpawn.
Respawn uses map Respawn points again.

Damage

Damage(amount: number) : void deprecated
Subtracts health from the player's Character.
Prefer `Character:Damage`.
No longer recommended for use.

TakeDamage

TakeDamage(amount: number) : void deprecated
Identical to Damage.
No longer recommended for use.

Kill

Kill() : void deprecated
Sets the Character's health to 0.
Prefer `Character:Kill`.
No longer recommended for use.

PlayMusic

PlayMusic(url: string, volume: number?) : void
Plays looping BGM for this player only.
volume is 0 to 1 (default 0.5).

StopMusic

StopMusic() : void
Stops BGM started with PlayMusic for this player.

Message

Message(text: string) : void
Sends a system chat message to this player only.

Notify

Notify(text: string, seconds: number?) : void
Shows a center toast for this player.
Default duration is about 3 seconds.

Hud

Hud(text: string, seconds: number?) : void
Shows a top HUD label for this player.
Pass 0 to keep it until ClearUI or a replacement.

ClearUI

ClearUI() : void
Clears this player's toast and HUD.

GiveTool

GiveTool(name: string) : bool
Adds a Tool to this player's backpack and syncs the toolbar.
name is a preset or custom tool name (for example "Sword").
Returns true if the player already had it or it was added.
Fails if the backpack is full (9 tools).

player:GiveTool("Sword")

RemoveTool

RemoveTool(name: string) : bool
Removes a Tool from this player's backpack and syncs the toolbar.
Returns true if it was removed.

InGroup

InGroup(groupId: int) : bool
Returns true if this player is a member of that group.

if player:InGroup(12) then
    print(player.Name, "is in the group")
end

InGroupRank

InGroupRank(groupId: int, rankName: string) : bool
Returns true if this player is in that group at the given rank.
rankName matches the rank name or tag, case-insensitive.

if player:InGroupRank(12, "Admin") then
    print("admin")
end

GetHealth

GetHealth() : number deprecated
Returns Character health.
Prefer reading player.Character.Health.
No longer recommended for use.

GetPosition

GetPosition() : Vector3 deprecated
Returns Character position.
Prefer reading player.Character.Position.
No longer recommended for use.

Events

CharacterAdded

CharacterAdded : Event (character: Character)
Triggers when this player's Character is created or respawned.

Players.PlayerAdded:Connect(function(player)
    player.CharacterAdded:Connect(function(character)
        character.Health = 100
    end)
end)

Defining function CharacterAdded(player) in a Script body is still supported.
Prefer Connect on the Player instead.
No longer recommended for use.

CharacterRemoving

CharacterRemoving : Event (character: Character)
Triggers when this player's Character is about to be removed.