Player

Player : Instance

Overview

Player는 서버에 접속한 각 사용자를 나타내는 객체입니다.

새로운 사용자가 접속하면 Players 서비스에 Player 객체로 등록되며, 접속이 종료되면 목록에서 자동으로 제외됩니다.

이 객체의 Name 속성에는 사용자의 닉네임이 표시되지만, 데이터 저장 시에는 닉네임 대신 UserId를 사용하는 것이 안전합니다. 닉네임은 사용자가 변경할 수 있지만 UserId는 고정되어 변경되지 않기 때문입니다.

서버에 접속한 사용자를 감지하려면 Players.PlayerAdded 이벤트를, 접속 종료를 감지하려면 Players.PlayerRemoving 이벤트를 사용합니다. 이를 통해 플레이어가 퇴장하기 직전에 데이터 저장이나 정리 작업을 안전하게 수행할 수 있습니다.

현재 서버의 모든 접속자 목록은 Players:GetPlayers() 메서드를 사용하여 가져올 수 있습니다.

Properties

CameraMaxZoomDistance

number

카메라의 최대 줌 아웃(Zoom Out) 거리를 설정하는 변수입니다.

값을 크게 설정할수록 카메라가 더 멀리까지 줌 아웃할 수 있으며, 작게 설정하면 최대 줌 아웃 거리가 짧아집니다.

만약 현재 카메라의 줌 거리가 변경된 CameraMaxZoomDistance 값보다 크다면, 카메라 줌 거리는 강제로 CameraMaxZoomDistance 값으로 조정됩니다.

Code Samples

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

player.CameraMaxZoomDistance = 50

CameraMinZoomDistance

number

카메라의 최소 줌 인(Zoom In) 거리를 설정하는 변수입니다.

값을 작게 설정할수록 카메라가 캐릭터에 더 가까이 접근할 수 있고, 크게 설정하면 카메라가 일정 거리 이하로 줌인되지 않습니다.

만약 현재 카메라의 줌 거리가 변경된 CameraMinZoomDistance 값보다 작다면, 카메라 줌 거리는 강제로 CameraMinZoomDistance 값으로 조정됩니다.

Code Samples

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

player.CameraMaxZoomDistance = 10

Character

Model

플레이어의 아바타를 구성하는 모델 객체를 반환합니다. 해당 모델에는 Humanoid, 신체 파트, 스크립트, 그리고 아바타 동작에 필요한 다양한 요소가 포함됩니다.

Character는 Players.CharacterAutoLoads 값이 true이면 자동으로 생성되지만, false일 경우 LoadCharacter()를 호출해 수동으로 생성해야 합니다.

속성의 초기값은 nil이며, 플레이어 캐릭터가 생성되면 이 속성에 해당 모델이 할당됩니다.

캐릭터 생성 시점을 감지하려면 CharacterAdded 이벤트를, 캐릭터 제거 직전 시점을 감지하려면 CharacterRemoving 이벤트를 활용하는 것이 좋습니다.

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)

LocaleId

string

플레이어 계정에 설정된 로케일 ID를 나타내는 읽기 전용 속성입니다.

값은 en-us 형식의 언어 코드 문자열이며, 예를 들어 ko-kr, pt-br, hi-in, en 등이 반환됩니다.

클라이언트에서 노출되는 로케일 값은 디바이스 또는 스튜디오 설정값을 그대로 반환하며, 지원되지 않는 언어에 대해 en, pt-br, hi 등의 prefix 기반 fallback 매칭은 적용되지 않습니다. 즉, fallback 처리 이전의 원본 로케일 값이 그대로 제공됩니다.

플레이어별로 번역을 적용하려면 이 값을 LocalizationService의 GetTranslatorForLocaleAsync 메서드에 전달하거나, GetTranslatorForPlayerAsync 메서드를 사용하세요.

Code Samples

local Players = game:GetService("Players")
local LocalizationService = game:GetService("LocalizationService")

local function OnPlayerAdded(player)
    print(player.Name, "LocaleId : ", player.LocaleId)

    local translator = LocalizationService:GetTranslatorForLocaleAsync(player.LocaleId)
    print(translator:Translate(game, "Welcome!"))
end
Players.PlayerAdded:Connect(function(OnPlayerAdded)

RespawnLocation

SpawnLocation

플레이어 캐릭터가 리스폰할 SpawnLocation 객체를 설정합니다.

지정한 객체는 반드시 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)

TeamColor

BrickColor

이 속성은 플레이어가 어떤 팀에 속할지를 TeamColor 값을 기준으로 결정합니다.

SpawnLocation 중 Neutral이 false이고 TeamColor가 플레이어의 TeamColor와 일치하는 지점이 있을 경우, 캐릭터는 스폰 시 해당 위치에서 생성됩니다.

Code Samples

player.TeamColor = BrickColor.new("Really red")

UserId

string

사용자의 계정을 식별하는 읽기 전용의 고유 ID를 반환합니다.

UserId는 닉네임과 달리 절대 변경되지 않으므로, DataStore를 통해 플레이어 데이터를 저장하거나 불러올 때, 계정 식별을 위한 용도로 사용됩니다.

Code Samples

local Players = game:GetService("Players")

local function OnAddPlayer(player)
    print(player.UserId)
end
Players.PlayerAdded:Connect(OnAddPlayer)

Methods

GetMouse

클라이언트의 Mouse 객체를 반환합니다.

반환된 객체를 이용하여 좌/우 클릭 등 마우스 입력을 감지하고 처리할 수 있습니다.

다만, 모바일 환경에서는 UserInputService를 사용하는 것이 일반적으로 권장됩니다.

Parameters

Return

Mouse	마우스 객체입니다.

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

플레이어의 현재 네트워크 핑(Network Ping, 지연 시간)을 반환합니다. 핑 값은 서버와 클라이언트 간의 통신 지연 시간을 초 단위로 나타내며, 값이 낮을수록 네트워크 반응 속도가 빠름을 의미합니다.

Parameters

Return

number	해당 플레이어의 현재 네트워크 ping (초 단위)

Code Samples

local Players = game.Players

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

LoadCharacter

플레이어의 기존 캐릭터를 제거한 뒤 새 캐릭터를 생성합니다.

플레이어를 사망 처리하지 않고 캐릭터만 재생성해야 할 때 주로 사용됩니다.

Parameters

Return

void

Code Samples

player:LoadCharacter()

RemoveCharacter

플레이어의 기존 캐릭터를 제거합니다.

RemoveCharacter()로 캐릭터가 제거되면 Character 속성은 nil로 설정되며, LoadCharacter() 메서드를 호출해야만 다시 생성할 수 있습니다.

Parameters

Return

void

Code Samples

player:RemoveCharacter()

Events

CharacterAdded

플레이어 캐릭터가 생성되거나 재생성될 때 실행되는 이벤트입니다.

이 시점에는 캐릭터의 Humanoid와 기본 신체 부위(머리, 몸통, 팔다리)는 이미 존재하지만, 의상과 액세서리(모자, 셔츠, 바지 등)는 몇 초 뒤에 추가될 수 있습니다.

플레이어의 접속이나 퇴장을 추적하려면 Players.PlayerAdded와 Players.PlayerRemoving 이벤트를 사용해야 합니다.

Parameters

Model 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

플레이어 캐릭터가 삭제되기 직전에 실행되는 이벤트입니다.

캐릭터 객체가 사라지기 전에 필요한 작업을 수행할 때 주로 사용됩니다.

플레이어의 접속이나 퇴장을 추적하려면 Players.PlayerAdded와 Players.PlayerRemoving 이벤트를 사용해야 합니다.

Parameters

Model 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)