튜토리얼 · 플레이어 데이터

Roblox Studio에서 리더보드 만드는 법

Roblox 게임 오른쪽 위의 플레이어 목록은 leaderstats라는 폴더 하나로 제어됩니다. 이 가이드에서는 처음부터 만듭니다. 서버 스크립트, 점수를 안전하게 주는 방법, 세션 사이에 저장하기, 그리고 글로벌 톱 10까지 다룹니다.

업데이트: 2026년 11월 20일읽는 데 5분작성:

요약

ServerScriptService에 Script를 만들어 Players.PlayerAdded를 듣고, 이름이 정확히 leaderstats(모두 소문자)인 Folder를 만들어 플레이어의 자식으로 넣으세요. 이 폴더 안의 IntValue, NumberValue, StringValue는 각각 플레이어 목록의 열이 됩니다.

  • 통계는 서버에서만 만들고 바꾸세요. LocalScript에서 바꾼 값은 그 플레이어만 보고, 다른 사람은 아무도 보지 못합니다.
  • leaderstats는 저장되지 않습니다. 다음 세션까지 남아야 하는 값은 data store로 불러오고 저장하세요.
  • 모든 플레이어를 대상으로 한 순위가 필요하면 점수를 ordered data store에 기록하고, 월드 안의 보드나 플레이어 목록의 Global 모드로 보여 주세요.
이 페이지의 내용
  1. leaderstats 작동 방식
  2. 1. leaderstats 만들기
  3. 2. 점수 주기
  4. 3. 저장
  5. 4. 글로벌 톱 10
  6. Common errors
  7. RoCode로
  8. 자주 묻는 질문
  9. 출처와 더 읽을거리

leaderstats의 작동 방식

예시 화면실행 중인 게임 안의 완성된 leaderstats 스크립트와 코인 패드.

Roblox는 모든 게임에서 플레이어 목록을 보여 줍니다. 플레이어에게 이름이 leaderstats인 자식 Folder가 있으면, 목록은 그 안의 값 오브젝트마다 열을 하나씩 추가하고 각 플레이어 줄에 그 플레이어의 값을 보여 줍니다. 열 제목은 값 오브젝트의 Name입니다.

leaderstats에 넣을 수 있는 값 오브젝트
오브젝트저장하는 것어울리는 용도
IntValue정수코인, 킬, 승리, 레벨
NumberValue소수최고 랩 타임, 거리
StringValue텍스트랭크나 팀 칭호

작동하지 않는 리더보드는 거의 다 두 가지 규칙 때문입니다. 폴더 이름은 정확히 leaderstats여야 합니다. Leaderstats나 leaderStats는 무시됩니다. 그리고 폴더는 서버 Script가 만들어야 합니다. 서버에서 일어난 변경만 모든 플레이어에게 복제되기 때문입니다. 코드가 어디서 실행되는지 확실하지 않다면 먼저 Script vs LocalScript vs ModuleScript(영어)를 읽어 보세요.

1단계: leaderstats 스크립트 만들기

  1. Explorer에서 ServerScriptService에 마우스를 올리고 + 버튼을 눌러 Script를 넣으세요.
  2. 나중에 찾기 쉽도록 이름을 Leaderstats로 바꾸세요.
  3. 내용을 아래 코드로 바꾸고 Play를 누르세요. 플레이어 목록에 내 이름이 Coins와 Wins 0으로 나타납니다.
Script 위치: ServerScriptService 이름: Leaderstats
local Players = game:GetService("Players")

local function setupLeaderstats(player: Player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats" -- 이름은 정확히 이대로, 모두 소문자여야 함

	local coins = Instance.new("IntValue")
	coins.Name = "Coins"
	coins.Value = 0
	coins.Parent = leaderstats

	local wins = Instance.new("IntValue")
	wins.Name = "Wins"
	wins.Value = 0
	wins.Parent = leaderstats

	leaderstats.Parent = player -- 값을 다 넣은 뒤 부모를 마지막에 설정
end

Players.PlayerAdded:Connect(setupLeaderstats)

-- Studio에서는 이 스크립트가 실행되기 전에 들어올 수 있으므로 이미 있는 플레이어도 설정
for _, player in Players:GetPlayers() do
	setupLeaderstats(player)
end

마지막 반복문은 Studio에서 테스트할 때 중요합니다. 첫 플레이어가 PlayerAdded가 연결되기 전에 들어오는 경우가 있는데, 반복문이 없으면 통계 없이 남게 됩니다.

2단계: 점수를 안전하게 주기

통계를 바꾸려면 서버 스크립트에서 Value를 설정하세요. 이 코인 패드는 플레이어가 닿으면 코인 10개를 줍니다. 캐릭터가 파트 위에 서 있는 동안 Touched는 1초에 여러 번 발생하므로, 스크립트는 플레이어마다 짧은 쿨다운을 둡니다.

Script 위치: Workspace의 파트 이름: CoinPad
local Players = game:GetService("Players")

local part = script.Parent :: BasePart
local REWARD = 10
local COOLDOWN_SECONDS = 1

local lastReward: { [Player]: number } = {}

part.Touched:Connect(function(hit: BasePart)
	local character = hit:FindFirstAncestorOfClass("Model")
	local player = character and Players:GetPlayerFromCharacter(character)
	if not player then
		return
	end

	local now = os.clock()
	local last = lastReward[player]
	if last and now - last < COOLDOWN_SECONDS then
		return -- Touched는 한 걸음에도 여러 번 발생함; 한 번 닿았는데 열 번 지급되는 것을 막음
	end
	lastReward[player] = now

	local leaderstats = player:FindFirstChild("leaderstats")
	local coins = leaderstats and leaderstats:FindFirstChild("Coins")
	if coins and coins:IsA("IntValue") then
		coins.Value += REWARD
	end
end)

Players.PlayerRemoving:Connect(function(player: Player)
	lastReward[player] = nil
end)

FindFirstAncestorOfClass("Model")는 닿은 파트가 액세서리 안에 있어도 캐릭터를 찾아내지만, 단순한 hit.Parent 확인은 이를 놓칩니다.

플레이어가 자기 화면에서 하는 행동, 예를 들어 버튼 누르기에 점수를 준다면, LocalScript가 RemoteEvent로 서버에 요청하고 지급 여부는 서버가 정해야 합니다. 클라이언트가 금액을 보내게 해서는 절대 안 됩니다. RemoteEvent 가이드에서 검증을 포함한 이 패턴을 보여 줍니다.

완성된 예시 네 가지: 첫 게임 가이드는 코스에서 닿는 코인마다 Coin 1개를 주고 코인 3개를 모은 뒤 결승 패드에서 Win을 줍니다. 클리커 시뮬레이터 가이드는 서버의 클릭 제한과 함께 버튼을 누를 때마다 Coins를 줍니다. 칼 가이드는 플레이어가 죽기 전 마지막으로 때린 사람의 Kills에 1을 더합니다. 총 가이드는 총알이 대상의 Health를 0으로 만들었을 때 킬을 세는 방법을 보여 줍니다.

3단계: 세션 사이에 통계 저장하기

leaderstats는 서버가 살아 있는 동안만 존재합니다. 코인과 승리를 남기려면 플레이어가 들어올 때 data store에서 불러오고 나갈 때 저장하세요. 이 버전은 1단계 스크립트를 대체합니다. 데이터를 불러오지 못한 플레이어는 절대 저장하지 않습니다. 복사해 온 저장 스크립트 대부분에서 진행 상황을 날려 버리는 것이 바로 이 실수입니다.

Script 위치: ServerScriptService 이름: Leaderstats
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")

-- 아래 각 pcall 안에서 호출되므로, 아직 퍼블리시하지 않은 플레이스
-- (data store 접근 없음)에서도 리더보드는 나옴
local function statsStore(): DataStore
	return DataStoreService:GetDataStore("PlayerStats_v1")
end

-- 저장된 통계를 불러온 플레이어. 여기에 없는 플레이어는 절대 저장하지 않으므로
-- 불러오기에 실패해도 실제 진행 상황이 0으로 덮어써지지 않음.
local loaded: { [Player]: boolean } = {}

local function keyFor(player: Player): string
	return "player_" .. player.UserId
end

local function onPlayerAdded(player: Player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"

	local coins = Instance.new("IntValue")
	coins.Name = "Coins"
	coins.Parent = leaderstats

	local wins = Instance.new("IntValue")
	wins.Name = "Wins"
	wins.Parent = leaderstats

	local ok, data = pcall(function()
		return statsStore():GetAsync(keyFor(player))
	end)
	if ok then
		if type(data) == "table" then
			coins.Value = tonumber(data.Coins) or 0
			wins.Value = tonumber(data.Wins) or 0
		end
		loaded[player] = true
	else
		warn(`Could not load stats for {player.Name}: {data}`)
	end

	leaderstats.Parent = player
end

local function save(player: Player)
	if not loaded[player] then
		return
	end
	local leaderstats = player:FindFirstChild("leaderstats")
	local coins = leaderstats and leaderstats:FindFirstChild("Coins")
	local wins = leaderstats and leaderstats:FindFirstChild("Wins")
	if not (coins and coins:IsA("IntValue") and wins and wins:IsA("IntValue")) then
		return
	end
	local ok, err = pcall(function()
		statsStore():SetAsync(keyFor(player), { Coins = coins.Value, Wins = wins.Value })
	end)
	if not ok then
		warn(`Could not save stats for {player.Name}: {err}`)
	end
end

Players.PlayerAdded:Connect(onPlayerAdded)
for _, player in Players:GetPlayers() do
	task.spawn(onPlayerAdded, player)
end

Players.PlayerRemoving:Connect(function(player: Player)
	save(player)
	loaded[player] = nil
end)

-- 서버가 꺼질 때 닫히기 전에 모두 저장
game:BindToClose(function()
	local pending = 0
	for _, player in Players:GetPlayers() do
		pending += 1
		task.spawn(function()
			save(player)
			pending -= 1
		end)
	end
	while pending > 0 do
		task.wait()
	end
end)

작은 게임이라면 이것으로 충분합니다. 재시도, UpdateAsync, 요청 한도, 두 서버가 같은 플레이어를 쓰는 상황을 막는 방법은 DataStore 튜토리얼에서 이어서 읽어 보세요.

4단계: 글로벌 톱 10

leaderstats는 같은 서버에 있는 플레이어끼리만 비교합니다. 글로벌 순위에는 ordered data store가 필요합니다. 키마다 숫자 하나를 저장하고 값으로 정렬된 키를 돌려줄 수 있는 data store입니다. 서버에서 각 플레이어의 점수를 여기에 기록한 다음, 상위 항목을 다시 읽어 오세요.

보여 주는 방법은 두 가지입니다. Roblox 플레이어 목록에는 Creator Hub에 등록한 ordered data store를 읽는 Friends와 Global 모드가 있습니다(이 글을 쓰는 시점에는 베타 기능이며, 게임당 활성 리더보드는 하나입니다). 아니면 월드 안의 보드에 순위를 직접 그릴 수도 있습니다. 이 방법은 어떤 게임에서든 작동하고 원하는 대로 꾸밀 수 있습니다. 아래 스크립트는 두 번째 방법을 쓰며, 점수를 플레이어의 user ID를 키로 해서 기록합니다. 이는 Creator Hub 리더보드가 기대하는 것과 같은 형식입니다.

  1. Workspace에 고정된 Part를 추가하고 이름을 WinsBoard로 한 뒤, 간판 크기(예: 12 x 8 x 1 스터드)로 만들고 앞면이 스폰을 향하게 하세요.
  2. ServerScriptService에 이름이 GlobalWinsBoard인 Script를 넣고 아래 코드를 붙여 넣으세요.
  3. Play를 누르세요. 보드는 첫 새로 고침 뒤에 채워지고 매분 업데이트됩니다.
Script 위치: ServerScriptService 이름: GlobalWinsBoard
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")

local winsBoard = DataStoreService:GetOrderedDataStore("GlobalWins_v1")

local TOP_N = 10
local REFRESH_SECONDS = 60

-- 보드: Workspace에 있는 이름이 WinsBoard인 고정 Part. 스크립트가 SurfaceGui와
-- 줄을 직접 추가하므로 Part만 만들면 됨.
local boardPart = workspace:WaitForChild("WinsBoard") :: BasePart

local gui = Instance.new("SurfaceGui")
gui.Face = Enum.NormalId.Front
gui.SizingMode = Enum.SurfaceGuiSizingMode.PixelsPerStud
gui.PixelsPerStud = 50
gui.Parent = boardPart

local list = Instance.new("Frame")
list.Size = UDim2.fromScale(1, 1)
list.BackgroundColor3 = Color3.fromRGB(18, 11, 31)
list.Parent = gui

local layout = Instance.new("UIListLayout")
layout.SortOrder = Enum.SortOrder.LayoutOrder
layout.Parent = list

local nameCache: { [number]: string } = {}

local function nameFor(userId: number): string
	local cached = nameCache[userId]
	if cached then
		return cached
	end
	local ok, name = pcall(function()
		return Players:GetNameFromUserIdAsync(userId)
	end)
	local result = if ok then name else "Unknown player"
	nameCache[userId] = result
	return result
end

local function recordWins(player: Player)
	local leaderstats = player:FindFirstChild("leaderstats")
	local wins = leaderstats and leaderstats:FindFirstChild("Wins")
	if wins and wins:IsA("IntValue") then
		local ok, err = pcall(function()
			winsBoard:SetAsync(tostring(player.UserId), wins.Value)
		end)
		if not ok then
			warn(`Could not record wins for {player.Name}: {err}`)
		end
	end
end

local function refresh()
	local ok, pages = pcall(function()
		return winsBoard:GetSortedAsync(false, TOP_N)
	end)
	if not ok then
		warn(`Could not read the wins board: {pages}`)
		return
	end

	for _, child in list:GetChildren() do
		if child:IsA("TextLabel") then
			child:Destroy()
		end
	end

	for rank, entry in pages:GetCurrentPage() do
		local label = Instance.new("TextLabel")
		label.Size = UDim2.new(1, 0, 1 / TOP_N, 0)
		label.BackgroundTransparency = 1
		label.TextColor3 = Color3.new(1, 1, 1)
		label.TextScaled = true
		label.Text = `{rank}. {nameFor(tonumber(entry.key) or 0)}   {entry.value}`
		label.LayoutOrder = rank
		label.Parent = list
	end
end

while true do
	for _, player in Players:GetPlayers() do
		recordWins(player)
	end
	refresh()
	task.wait(REFRESH_SECONDS)
end

GetSortedAsync(false, 10)는 가장 큰 값 10개를 먼저 돌려줍니다. Ordered data store는 정수만 저장하므로 점수는 정수로 저장하세요. 스크립트는 1분에 한 번 각 플레이어를 기록하고 1분에 한 번 톱 10을 읽는데, 이는 서버당 기본 한도(2026년 9월 30일 기준 문서에 따르면 ordered data store 쓰기는 분당 30 + 플레이어당 5, 정렬된 읽기는 5 + 플레이어당 2) 안에서 넉넉한 수준입니다.

자주 발생하는 오류와 해결 방법

아래 문제들이 "리더보드가 작동하지 않아요"라는 불만 대부분을 차지합니다. 먼저 Output 창을 확인하세요(Studio의 Window 메뉴나 Script 탭에서 열 수 있습니다). 스크립트가 오류로 멈췄다면 거기에 줄 번호가 나옵니다.

리더보드가 아예 나오지 않습니다

폴더 이름이 소문자 leaderstats인지, 그 부모가 (캐릭터가 아니라) Player인지, 코드가 LocalScript가 아니라 ServerScriptService의 Script인지 확인하세요.

다른 플레이어에게 내 통계 변경이 안 보입니다

값을 클라이언트에서 바꿨습니다. 변경을 서버 Script로 옮기고, 버튼이나 키가 변경을 일으킨다면 RemoteEvent를 보내서 서버가 값을 바꾸게 하세요.

attempt to index nil with 'Coins'

폴더가 생기기 전에 코드가 player.leaderstats.Coins를 읽으려 했거나, 이름이 다르게 쓰였습니다. 서버에서는 FindFirstChild를 쓰고 결과를 확인하세요. LocalScript에서는 player:WaitForChild("leaderstats")를 쓰세요. 스크립트 오류 가이드에서 이 오류를 자세히 다룹니다.

한 번 닿았는데 코인이 10, 20, 50씩 늘어납니다

파트가 겹쳐 있는 동안 Touched가 계속해서 발생합니다. 2단계처럼 플레이어마다 쿨다운을 두거나, 주운 아이템을 삭제하세요.

다시 들어올 때마다 통계가 초기화됩니다

Roblox는 leaderstats를 저장하지 않습니다. 3단계 스크립트를 추가하세요. Studio에서 저장을 테스트하려면 플레이스를 퍼블리시하고 Experience Settings에서 Studio Access to API Services를 켜세요.

RoCode로 만들기

직접 만들고 싶지 않다면 RoCode가 지금 열려 있는 플레이스 안에 전부 만들어 줄 수 있습니다. Roblox Studio 플러그인을 통해 작동하는 AI 에이전트라서, 붙여 넣을 코드를 건네주는 대신 Explorer에 스크립트와 파트를 직접 만듭니다.

입력하는 내용

세션 사이에 저장되는 Coins와 Wins 리더보드를 추가하고, 스폰 옆 파트에 승리 기준 톱 10 보드를 만들어 줘.

RoCode가 하는 일
  • 먼저 플레이스에서 기존 leaderstats나 DataStore 코드를 찾아서, 리더보드를 하나 더 추가하는 대신 있는 것을 보완할 수 있습니다
  • ServerScriptService에 서버 스크립트를, Workspace에 보드용 파트를 만듭니다
  • 끝내기 전에 작성한 스크립트의 컴파일을 Studio 안에서 확인합니다
  • 변경을 묶음으로 보내고, 각 묶음은 Studio 기록에 실행 취소 지점으로 표시됩니다

결과를 확인하고 게임 안에서 통계와 저장을 테스트하는 것은 여전히 직접 해야 합니다. 플러그인 3.9 이상에서는 RoCode가 짧은 플레이테스트를 실행하고 오류를 읽을 수 있고, 플러그인 3.9.11 이상에서는 테스트 캐릭터를 조종하며 Coins와 Wins 같은 값을 확인할 수 있지만, 스스로 테스트하기로 고른 것만 확인합니다. Leaderstats는 보통 게임의 여러 시스템 중 첫 번째입니다. 같은 방식으로 요청 하나에 시스템 하나씩 나머지 게임을 만드세요. RoCode가 Studio에 연결되는 방식.

자주 묻는 질문

Roblox에서 leaderstats란 무엇인가요?

Player 안에 있는, 이름이 정확히 leaderstats(모두 소문자)인 Folder입니다. Roblox는 그 안의 IntValue, NumberValue, StringValue를 각각 플레이어 목록의 열로 보여 줍니다. 1단계처럼 서버 Script에서 만드세요.

Roblox에서 글로벌 리더보드는 어떻게 만드나요?

서버에서 각 플레이어의 점수를 ordered data store에 기록한 다음, 상위 항목을 다시 읽어 월드 안의 보드에 보여 주세요. 4단계에 톱 10 전체 스크립트가 있습니다.

Roblox가 leaderstats를 자동으로 저장하나요?

아니요. leaderstats는 플레이어가 서버에 있는 동안만 존재합니다. 3단계처럼 플레이어가 나갈 때 data store로 값을 저장하고, 들어올 때 불러오세요.

리더보드에서 값을 숨길 수 있나요?

네. leaderstats 폴더 안의 값만 표시됩니다. 공개하지 않을 데이터는 플레이어 아래 다른 폴더나 서버 스크립트의 테이블에 보관하세요.

플레이어 목록 전체를 숨기려면 어떻게 하나요?

LocalScript에서 StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)를 호출하세요. 다시 보이게 하려면 true를 넘기세요.

코인에 NumberValue를 써도 되나요?

써도 되지만, 정수로 된 화폐에는 IntValue가 더 맞습니다. 나중에 이 값으로 순위를 만들고 싶다면 ordered data store는 정수만 받습니다.

출처와 더 읽을거리

코드 검증 방법: 이 페이지의 모든 스크립트는 Roblox API 정의를 적용한 Luau의 엄격한 타입 검사기(luau-lsp, 2026년 11월 20일)를 통과합니다. 타입 검사는 잘못 쓴 API 이름과 잘못된 타입을 찾아내지만 게임 로직의 오류는 찾지 못하므로, 게시하기 전에 Studio에서 직접 테스트하세요.

내 게임에서 RoCode를 사용해 보세요.

매일 무료 크레딧, 카드 등록 없이 시작합니다. 플러그인을 설치하고, 원하는 기능을 설명한 뒤, Studio에 만들어진 결과를 확인하세요.