Players

Players : Instance

Overview

Players 서비스는 현재 서버에 연결된 클라이언트를 Player 객체 형태로 관리하며, Player와 관련된 다양한 기능을 함께 제공합니다.

Properties

CharacterAutoLoads

bool

캐릭터의 자동 리스폰 여부를 설정합니다.

기본값은 true이며, false로 설정하면 플레이어가 게임에 들어오더라도 Player:LoadCharacter()를 호출하기 전까지 캐릭터가 생성되지 않습니다.

이 옵션은 목숨 제한이 있는 게임이나, 라운드 종료 전까지 부활을 허용하지 않는 경쟁형 게임 모드에서 특히 유용합니다.

Code Samples

local Players = game:GetService("Players")

Players.CharacterAutoLoads = false

UseStrafingAnimations

bool

캐릭터 이동 시 재생되는 애니메이션의 방향 처리 방식을 지정하는 속성입니다.

false로 설정하면 이동 방향과 관계없이 단일 이동 애니메이션만 재생되며, true로 설정하면 상·하·좌·우와 대각선을 포함한 8방향 이동 애니메이션이 실제 이동 방향에 맞춰 재생됩니다.

이를 통해 게걸음(Strafing), 후진, 대각선 이동 등 TPS 게임에서 필요한 다양한 방향 전환을 보다 자연스럽게 표현할 수 있습니다.

이 속성은 런타임에서 변경할 수 없으며, 스튜디오 편집 단계에서 미리 설정해야 합니다.

Code Samples

LocalPlayer

Player

현재 클라이언트에서 게임을 실행 중인 플레이어 객체를 참조하는 읽기 전용 속성입니다.

LocalScript와 같은 클라이언트 환경에서만 값을 가져올 수 있으며, 서버 환경에서 실행되는 Script에서는 항상 nil을 반환합니다.

Code Samples

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

RespawnTime

number

CharacterAutoLoads 속성이 true일 경우, 플레이어의 리스폰 대기 시간을 초 단위로 지정하는 속성입니다.

기본값은 5초입니다.

Code Samples

local Players = game:GetService("Players")

Players.RespawnTime = 2

Methods

GetPlayerFromCharacter

지정한 Character에 해당하는 Player 객체를 반환하며, 연결된 플레이어가 없을 경우 nil을 반환합니다.

Touched, CharacterAdded와 같이 Player 객체를 직접 반환하지 않는 이벤트에서 캐릭터를 통해 Player를 조회할 때 사용됩니다.

반대로 Player 객체에서 캐릭터를 가져오려면 Player.Character 속성을 사용하면 됩니다.

Parameters

Model InCharacter	Player로 변환할 대상 캐릭터입니다.

Return

Player	반환된 Player입니다.

Code Samples

local Players = game:GetService("Players")

local Part = script.Parent

local function OnTouched(otherPart)
    local partParent = otherPart.Parent
    local humanoid = partParent:FindFirstChild("Humanoid")
	
    if humanoid then
        local character = humanoid.Parent
        local player = Players:GetPlayerFromCharacter(character)
    end
end
Part.Touched:Connect(OnTouched)

GetPlayerByUserId

지정한 UserId에 해당하는 Player 객체를 반환하며, 해당 플레이어가 없을 경우 nil을 반환합니다.

Parameters

string UserId	Player로 변환할 대상 Player의 UserId입니다.

Return

Player	반환된 Player입니다.

Code Samples

local Players = game:GetService(Players)

local playerId = Players.LocalPlayer.UserId
print(Players:GetPlayerByUserId(playerId))

GetPlayers

현재 서버에 연결된 모든 Player 객체를 테이블 형태로 반환합니다.

for 반복문과 함께 사용하면 게임 내 모든 플레이어를 손쉽게 순회할 수 있습니다.

Parameters

Return

Array	플레이어 목록입니다.

Code Samples

local Players = game:GetService("Players")

local PlayerList = Players:GetPlayers() 
for i = 1, #PlayerList do
    print(PlayerList[i])
end

Events

PlayerAdded

플레이어가 게임에 접속하는 순간 실행되는 이벤트입니다.

주로 플레이어가 들어올 때 저장된 GlobalDataStore 데이터를 불러오거나 초기 설정을 적용하는 데 사용됩니다.

Parameters

Player player	접속한 플레이어입니다.

Code Samples

local Players = game:GetService("Players")

local function OnPlayerAdded(player)
    print("[OnPlayerAdded]", player)
end
Players.PlayerAdded:Connect(OnPlayerAdded)

PlayerRemoving

플레이어가 게임을 떠나기 직전에 실행되는 이벤트입니다.

플레이어가 완전히 제거되기 전에 호출되므로, GlobalDataStore를 통해 플레이어 데이터를 저장할 때 적합합니다.

Parameters

Player player	퇴장한 플레이어입니다.

Code Samples

local Players = game:GetService("Players")

local function OnPlayerRemoving(player)
    print("[OnPlayerRemoving]", player)
end
Players.PlayerRemoving:Connect(OnPlayerRemoving)