요약
서버 Script에서 DataStoreService를 쓰세요. 플레이어가 들어오면 GetAsync로 데이터를 불러오고, 플레이하는 동안 테이블에 들고 있다가, 타이머에 맞춰, 나갈 때(PlayerRemoving), 그리고 서버가 꺼질 때(game:BindToClose) UpdateAsync로 저장합니다. 모든 호출을 pcall로 감싸고, 실패한 호출은 몇 번 다시 시도하세요.
- Studio에서 테스트하려면 플레이스를 게시하고 별도의 테스트 게임에서 File > Experience Settings > Security > Enable Studio Access to API Services를 켜세요. Studio는 라이브 서버와 같은 데이터를 씁니다.
- 플레이어의 데이터를 불러오지 못했다면 그 플레이어는 절대 저장하지 마세요. 기본값을 저장하면 실제 진행 상황을 덮어씁니다.
- 플레이어마다 테이블 하나를
User_12345같은 키 하나에 저장하고, 변경할 때마다가 아니라 타이머에 맞춰 저장하세요. - 아이템 교환이나 유료 아이템이 있다면 세션 잠금을 추가해서 두 서버가 같은 플레이어를 저장할 수 없게 하세요.
이 페이지의 내용
시작하기 전에: 테스트 복사본에서 Studio 접근 켜기
Studio에서 실행한 게임은 허용하기 전까지 데이터 스토어에 접근할 수 없습니다. 이 허용에는 Roblox 문서가 경고하는 함정이 있습니다. 그러면 Studio가 라이브 게임과 같은 데이터 스토어를 읽고 쓰기 때문에, Studio에서 코인을 0으로 만드는 테스트는 라이브 게임에서도 코인을 0으로 만들고, 테스트 코드의 버그가 실제 플레이어의 키를 망가뜨릴 수 있습니다.
- 테스트 복사본을 만드세요. 플레이스를 파일로 저장하고 복사본을 연 다음 File > Publish to Roblox As를 고르고 Create new game을 누르세요. 라이브 게임 안의 플레이스로 추가하지 마세요. 한 게임의 모든 플레이스는 같은 데이터 스토어를 공유합니다.
- 테스트 복사본에서 File > Experience Settings를 열고 Security로 가세요.
- Enable Studio Access to API Services를 켜고 Save를 누르세요.
데이터 스토어 호출은 서버 Script에서만 작동합니다. 시도하는 LocalScript는 오류를 받으므로 클라이언트는 저장된 데이터를 쓸 수 없습니다. 버튼으로 데이터를 바꿔야 할 때는 클라이언트가 RemoteEvent로 서버에 요청하고, 결정은 서버가 합니다(RemoteEvent 가이드 참고).
데이터 스토어가 플레이어 데이터를 보관하는 방식
데이터 스토어(data store)는 Roblox 서버에 있는 이름이 붙은 키와 값의 모음이며, 게임의 모든 서버와 모든 플레이스가 공유합니다. DataStoreService:GetDataStore("PlayerData")는 그런 스토어 하나를 돌려줍니다.
Roblox의 권장 사항은 플레이어 데이터용 스토어 하나, 플레이어당 키 하나, 키마다 테이블 하나라는 규칙으로 요약됩니다. 키는 플레이어의 UserId로 만드세요. 예를 들어 User_12345처럼요. 플레이어가 바꿀 수 있는 이름으로는 절대 만들지 마세요. 고정된 User_{UserId} 패턴을 쓰면, 설정해 두었을 경우 Roblox의 잊힐 권리 자동 처리가 플레이어의 데이터를 찾을 수도 있습니다.
| 타입 | 저장됨? | 참고 |
|---|---|---|
| 숫자, 문자열, 불리언, 버퍼 | 예 | 문자열은 올바른 UTF-8이어야 합니다. inf나 nan은 저장하지 마세요. |
| 테이블 | 예 | 안에 있는 것도 모두 저장할 수 있다면 됩니다. 숫자 키가 1부터 시작하지 않는 테이블(그래서 길이가 0인 테이블)은 그 키들이 문자열로 바뀐 채 돌아옵니다. |
Instance, Vector3, CFrame, Color3 | 아니요 | 저장하면 오류가 나거나 nil이 기록됩니다. 아이템 이름을 저장하거나 위치를 숫자 세 개로 저장하세요. |
모든 요청은 실패할 수 있고, 시간이 걸리고, 분당 예산을 쓰는 웹 호출입니다. 그래서 믿을 만한 저장 시스템은 플레이어가 들어올 때 데이터를 한 번 읽고, 플레이하는 동안 서버 테이블에 들고 있다가, 가끔씩 다시 기록합니다.
GetAsync, SetAsync, UpdateAsync 중 무엇을 쓸까
| 메서드 | 하는 일 | 용도 |
|---|---|---|
GetAsync(key) | 값을 읽습니다. 결과는 이 서버에서 4초 동안 캐시됩니다. | 플레이어 데이터 불러오기 |
SetAsync(key, value) | 값을 읽지 않고 덮어씁니다. 쓰기 한 번. | 새 키, 또는 이전 값과 상관없는 값 |
UpdateAsync(key, callback) | 최신 값을 읽어 여러분의 함수에 넘기고, 함수가 돌려준 것을 기록합니다. 읽기 한 번과 쓰기 한 번. | 플레이어 데이터 저장, 그리고 여러 서버가 쓸 수 있는 모든 키 |
IncrementAsync(key, delta) | 저장된 정수에 정수를 더합니다. | 카운터 |
RemoveAsync(key) | 키를 지우고 이전 값을 돌려줍니다. 예전 버전은 여전히 목록을 보고 읽을 수 있습니다. | 플레이어 데이터 삭제 |
SetAsync는 보지 않고 씁니다. 두 서버가 거의 동시에 같은 키를 저장하면, 내용이 무엇이든 마지막 쓰기가 이깁니다. UpdateAsync는 먼저 현재 값을 읽고, 그사이 다른 서버가 쓰면 Roblox가 새 값으로 여러분의 함수를 다시 실행합니다. Roblox는 쓰기가 현재 값에 따라 달라지거나 여러 서버가 키를 쓸 수 있을 때 항상 이것을 권하는데, 플레이어 데이터가 바로 그런 경우입니다. 함수에는 세 가지 규칙이 있습니다.
- 실행을 양보(yield)하면 안 됩니다. 안에서
task.wait()나 다른 데이터 스토어 호출을 하지 마세요. - 두 번 이상 실행될 수 있으므로 새 값을 계산하기만 해야 하고, 아이템을 주거나 이벤트를 발생시키면 절대 안 됩니다.
nil을 돌려주면 쓰기가 취소됩니다. 모듈은 이것으로 게임의 더 새로운 버전이 저장한 데이터를 덮어쓰지 않습니다.
1단계: PlayerData 모듈 만들기
이 ModuleScript는 데이터 스토어와 통신하는 유일한 코드입니다. 플레이어가 들어오면 데이터를 불러오고, 메모리에 들고 있고, 180초마다, 나갈 때, 서버가 꺼질 때 저장하며, 데이터를 불러오지 못한 플레이어는 저장하지 않습니다.
- Explorer에서 ServerScriptService에 마우스를 올리고 +를 눌러 ModuleScript를 넣으세요. 이름을
PlayerData로 바꾸고 내용을 아래 코드로 바꾸세요. - ModuleScript는 어떤 스크립트가 불러올(require) 때만 실행됩니다. ServerScriptService에 이름이
Main인 Script를 넣고 다음 줄을 넣으세요:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). 다른 서버 스크립트도 같은 방식으로 불러옵니다. DEFAULTS와Data타입을 게임에 맞게 바꾸되, 모든 필드는 숫자, 문자열, 불리언 또는 테이블로 두세요.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData: 플레이어가 들어오면 데이터를 불러와 메모리에 들고 있고,
-- 타이머에 맞춰, 나갈 때, 서버가 꺼질 때 저장합니다.
-- 다른 서버 스크립트는 PlayerData.Get(player)로 데이터를 읽고 바꿉니다.
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")
local STORE_NAME = "PlayerData"
local SCHEMA_VERSION = 2 -- 데이터 형태가 바뀌면 올리고 migrate()에 단계를 추가하세요
local AUTOSAVE_SECONDS = 180
-- Studio에서는 실패한 호출이 바로 포기하므로, 스토어 접근 없이 하는 테스트가 빠릅니다
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- 실패할 때마다 두 배: 1, 2, 4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- 완전히 새로운 플레이어가 시작하는 값
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- 불러오기가 실패하면 false: 기본 데이터가 실제 진행 상황을 대신하면 안 됩니다
}
-- 아래의 모든 pcall 안에서 호출되므로, 아직 게시하지 않은 플레이스도
-- (스토어 접근 없이) 기본 데이터로 플레이어를 불러옵니다
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- 아직 진행 중인 저장, 키별
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- 플레이어의 데이터가 준비되면 그 플레이어와 함께 발생합니다. 테이블은 PlayerData.Get(player)로 가져오세요:
-- BindableEvent로 보낸 테이블은 복사본으로 도착하므로, 그것을 바꿔도 아무것도 바뀌지 않습니다.
PlayerData.Loaded = loadedEvent.Event
local function deepCopy(value: any): any
if type(value) ~= "table" then
return value
end
local copy = {}
for key, item in value do
copy[key] = deepCopy(item)
end
return copy
end
local function defaultData(): Data
local data = deepCopy(DEFAULTS) -- 새 복사본이므로 플레이어들이 Inventory 테이블 하나를 공유하는 일이 없습니다
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- 저장된 데이터를 현재 스키마로 맞춥니다. 안전하게 쓸 수 없으면 nil을 돌려줍니다.
local function migrate(saved: any): Data?
if type(saved) ~= "table" then
return nil
end
local version = tonumber(saved.SchemaVersion) or 1
if version > SCHEMA_VERSION then
return nil -- 게임의 더 새로운 버전이 저장함: 여기서 불러오지도 덮어쓰지도 않음
end
-- 스키마 변경마다 단계 하나씩, 오래된 것부터 새로운 것 순으로
if version < 2 then
-- 예: 버전 1에서는 화폐 이름이 Gold였습니다. Coins가 없을 때만 복사해서,
-- Coins는 이미 있지만 SchemaVersion이 없는 예전 데이터가 값을 유지하게 합니다.
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- 플레이어가 마지막으로 저장한 뒤에 생긴 필드를 추가하고, 타입이 틀린 값을 바꿉니다
for field, default in DEFAULTS do
if type(saved[field]) ~= type(default) then
saved[field] = deepCopy(default)
end
end
saved.SchemaVersion = SCHEMA_VERSION
return saved
end
-- 데이터 스토어 호출을 pcall로 실행합니다. 실패하면 기다렸다가 다시 시도하며, 매번 기다리는 시간을
-- 두 배로 늘리고 약간의 무작위성을 더해서 서버들이 한꺼번에 재시도하지 않게 합니다.
local function withRetries(label: string, call: () -> any): (boolean, any)
for attempt = 1, MAX_ATTEMPTS do
local ok, result = pcall(call)
if ok then
return true, result
end
warn(`{label} failed (attempt {attempt} of {MAX_ATTEMPTS}): {result}`)
if attempt < MAX_ATTEMPTS then
local waitTime = FIRST_RETRY_SECONDS * 2 ^ (attempt - 1)
task.wait(waitTime + math.random() * waitTime / 2)
end
end
return false, nil
end
local function save(session: Session): boolean
if not session.canSave then
return false
end
local key = session.key
pendingSaves[key] = (pendingSaves[key] or 0) + 1
local newerSchema = false
local ok = withRetries(`Save {key}`, function()
return store():UpdateAsync(key, function(current: any)
if type(current) == "table" and (tonumber(current.SchemaVersion) or 1) > SCHEMA_VERSION then
newerSchema = true
return nil -- nil을 돌려주면 쓰기가 취소됩니다
end
-- 현재 테이블 전체를 플레이어의 UserId 표시와 함께 씁니다
return session.data, { session.userId }
end)
end)
local left = (pendingSaves[key] or 1) - 1
if left > 0 then
pendingSaves[key] = left
else
pendingSaves[key] = nil
end
if newerSchema then
session.canSave = false
warn(`{key} was saved by a newer version of the game, so this server stopped saving it`)
end
return ok and not newerSchema
end
local function startAutosave(player: Player, session: Session)
task.spawn(function()
-- 간격 안의 무작위 시점에 시작해서 서버들이 한꺼번에 저장하지 않게 합니다
task.wait(math.random() * AUTOSAVE_SECONDS)
while sessions[player] == session do
save(session)
task.wait(AUTOSAVE_SECONDS)
end
end)
end
local function load(player: Player)
local key = "User_" .. player.UserId
-- 플레이어가 방금 이 서버에서 나갔다가 돌아왔다면, 먼저 마지막 저장이 끝나기를 기다립니다
while pendingSaves[key] do
task.wait()
end
local ok, saved = withRetries(`Load {key}`, function()
return store():GetAsync(key)
end)
if player.Parent ~= Players then
return -- 불러오는 중에 나감: 바뀐 것이 없으니 저장할 것도 없음
end
local data: Data? = nil
if ok then
data = if saved == nil then defaultData() else migrate(saved)
end
local session: Session = {
key = key,
userId = player.UserId,
data = data or defaultData(),
canSave = data ~= nil,
}
if not session.canSave then
warn(`Could not load {key}. {player.Name} is playing on default data that will not be saved.`)
end
sessions[player] = session
player:SetAttribute("DataLoaded", session.canSave) -- GUI가 이것을 읽고 플레이어에게 경고할 수 있습니다
startAutosave(player, session)
loadedEvent:Fire(player)
end
local function endSession(player: Player)
local session = sessions[player]
if not session then
return
end
sessions[player] = nil -- 자동 저장 반복을 멈추고, 두 번째 호출은 아무것도 하지 않게 합니다
save(session)
end
-- 플레이어의 실시간 데이터 테이블, 또는 아직 불러오지 않았다면 nil. 서버 스크립트에서만 바꾸세요.
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- 플레이어의 데이터를 불러왔고 저장될 것이라면 true. 무언가를 팔기 전에 확인하세요.
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- 타이머를 기다리지 않고 지금 저장합니다. 구매처럼 중요한 순간에 쓰세요.
-- 실행을 양보하며, 저장이 성공하면 true를 돌려줍니다.
function PlayerData.SaveNow(player: Player): boolean
local session = sessions[player]
return session ~= nil and save(session)
end
Players.PlayerAdded:Connect(load)
Players.PlayerRemoving:Connect(endSession)
for _, player in Players:GetPlayers() do
task.spawn(load, player) -- 이 모듈이 처음 불리기 전에 들어온 플레이어
end
game:BindToClose(function()
-- 서버는 이 함수들에 30초를 주므로 모두를 동시에 저장합니다
for player in sessions do
task.spawn(endSession, player)
end
-- 그다음 PlayerRemoving에서 시작된 것을 포함해 아직 진행 중인 저장을 모두 기다립니다
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
게임을 출시한 뒤에는 STORE_NAME과 키 패턴 User_를 바꾸지 마세요. 둘 중 하나라도 바꾸면 모듈이 빈 키를 보게 되고, 모든 플레이어가 기본값에서 다시 시작합니다.
모듈이 데이터를 지키는 방법
기본값과 스키마 버전
새 플레이어는 DEFAULTS의 새 복사본을 받습니다. 반드시 복사본이어야 합니다. 모든 플레이어가 Inventory 테이블 하나를 공유한다면 한 사람에게 추가한 아이템이 모두에게 나타납니다.
저장된 모든 테이블에는 SchemaVersion이 들어 있습니다. 필드를 추가하는 데는 새 버전이 필요 없습니다. migrate가 빠진 필드를 기본값으로 채우기 때문입니다. 이름을 바꾸거나 구조를 바꿀 때는 필요합니다. SCHEMA_VERSION을 올리고, Gold를 Coins로 바꾸는 예시처럼 단계를 추가하세요(새 게임이라면 이 예시를 지우고 1부터 시작하세요). 서버보다 버전이 높은 데이터는 아직 배포 중인 더 새로운 릴리스에서 온 것이므로 예전 서버는 건드리지 않습니다.
불러오기에 실패한 데이터는 절대 저장되지 않음
이 규칙은 전부 지워지는 일을 막습니다. 불러오기 시도가 모두 실패하면 플레이어는 기본 데이터로 플레이하지만 canSave가 false이므로, 이 값들은 실제 진행 상황을 절대 덮어쓰지 않습니다. 모듈은 DataLoaded 속성도 false로 설정하고, 3단계는 이것으로 플레이어에게 알립니다. Roblox의 참조 예제도 실패한 불러오기를 같은 방식으로 처리하며, 킥 대신 이 방식을 제안합니다. 킥을 선호한다면 모듈이 경고를 출력하는 곳에서 메시지와 함께 player:Kick()을 호출하세요.
점점 길어지는 간격의 재시도
withRetries는 모든 호출을 pcall로 감쌉니다. 실패하면 1초, 그다음 2초, 그다음 4초를 기다리고, 매번 그 시간의 절반까지 무작위로 더하며, 네 번 시도한 뒤 멈춥니다(Studio에서는 한 번 뒤에 멈춰서, 스토어 접근이 없는 플레이스가 바로 시작됩니다). 무작위성은 장애 뒤 많은 서버의 재시도를 분산시키고, 제한은 기다리는 시간을 약 10초 이내로, 서버가 종료할 때 받는 30초 안으로 유지합니다. 모든 저장이 UpdateAsync로 실시간 테이블 전체를 쓰므로, 늦게 끝난 재시도가 예전 데이터를 되돌려 놓을 수 없습니다.
모듈이 저장하는 시점
| 시점 | 이유 |
|---|---|
| 플레이어가 서버에 있는 동안 180초마다 | 서버가 다운될 때의 손실을 줄입니다. 첫 저장은 간격 안의 무작위 시점에 이루어져서 서버들이 한꺼번에 저장하지 않습니다. Roblox의 참조 예제도 180초를 씁니다. |
플레이어가 나갈 때(PlayerRemoving) | 일반적인 마지막 저장입니다. 세션을 먼저 지우므로 자동 저장이 멈춥니다. |
서버가 꺼질 때(game:BindToClose) | 아직 서버에 있는 모두를 한꺼번에 저장하고, 함수는 진행 중인 모든 저장을 기다립니다. Roblox는 이 함수에 30초를 줍니다. |
요청할 때, PlayerData.SaveNow(player)로 | 구매처럼 잃으면 안 되는 일이 있은 뒤에. |
마지막 저장이 아직 진행 중일 때 플레이어가 같은 서버에 다시 들어오면, 새 불러오기는 그 저장이 끝날 때까지 기다리므로 예전 값을 읽을 수 없습니다.
2단계: 다른 스크립트에서 데이터 읽고 바꾸기
모듈을 불러오는 모든 서버 스크립트는 같은 테이블로 작업합니다.
| 호출 | 하는 일 |
|---|---|
PlayerData.Get(player) | 플레이어의 실시간 데이터 테이블, 또는 아직 불러오지 않았다면 nil. data.Coins += 10처럼 필드를 직접 바꾸면 다음 저장이 반영합니다. |
PlayerData.Loaded | 플레이어의 데이터가 준비되면, 불러오기에 실패한 경우를 포함해, 그 플레이어와 함께 발생합니다. BindableEvent로 보낸 테이블은 복사본으로 도착하므로 플레이어만 넘깁니다. |
PlayerData.CanSave(player) | 불러오기에 실패했다면 false. 무언가를 팔기 전에 확인하세요. 저장할 수 없는 구매는 플레이어가 나가면 사라집니다. |
PlayerData.SaveNow(player) | 바로 저장하고, 성공하면 true를 돌려줍니다. 실행을 양보합니다. |
저장된 데이터가 사는 곳은 모듈뿐이고, leaderstats는 표시일 뿐입니다. 리더보드 가이드처럼 만들고, Loaded 핸들러에서 PlayerData.Get(player)로 채우고, 값이 바뀌면 둘 다 업데이트하세요. 저장된 값을 leaderstats에서 다시 읽어 오지 말고, 두 번째 스크립트가 같은 키를 저장하게 두지 마세요.
플레이어들이 들어온 뒤에 모듈을 불러온 스크립트는 그들에 대한 Loaded를 놓칩니다. 핸들러를 연결한 다음, Players:GetPlayers()를 한 번 더 돌면서 PlayerData.Get(player)가 이미 테이블을 돌려주는 플레이어를 모두 처리하세요.
리더보드 가이드의 것 같은 예전 저장 스크립트를 바꾸는 중인가요? 그 값은 그 스크립트 자체의 스토어와 키에 남아 있으므로, 이 모듈은 모두를 기본값에서 시작하게 합니다. 출시 전에 STORE_NAME과 User_ 접두사를 예전 것으로 맞추거나(migrate는 SchemaVersion이 없는 데이터를 버전 1로 보고 빠진 필드를 채웁니다), 예전 값을 옮긴 다음 예전 스크립트를 지우세요.
클라이언트는 이 데이터를 절대 직접 바꾸지 않습니다. 상점 버튼은 RemoteEvent를 발생시키고, 서버가 CanSave를 확인하고, 가격을 플레이어의 Coins와 비교하고, 테이블을 바꾸고, SaveNow를 호출합니다. 상점 GUI 가이드가 이런 구매를 서버 쪽에서 만듭니다.
필드를 추가하는 완성된 예시는 클리커 시뮬레이터 가이드에 있습니다. DEFAULTS와 Data 타입에 PowerLevel과 Rebirths를 추가한 다음, PlayerData.Get이 돌려주는 테이블에서 바꿉니다. migrate가 예전 저장 데이터를 가진 플레이어에게 새 필드를 줍니다.
3단계: 데이터를 불러오지 못했다고 플레이어에게 알리기
데이터를 불러오지 못한 플레이어는 이 세션이 저장되지 않는다는 것을 알아야 헛되이 플레이하지 않고 다시 접속할 수 있습니다. 이 LocalScript는 DataLoaded 속성을 지켜보다가 그 값이 false이면 배너를 보여 줍니다.
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local shown = false
local function showWarning()
if shown or player:GetAttribute("DataLoaded") ~= false then
return
end
shown = true
local gui = Instance.new("ScreenGui")
gui.Name = "DataWarning"
gui.ResetOnSpawn = false
local label = Instance.new("TextLabel")
label.AnchorPoint = Vector2.new(0.5, 0)
label.Position = UDim2.new(0.5, 0, 0, 12)
label.Size = UDim2.new(0.8, 0, 0, 48)
label.BackgroundColor3 = Color3.fromRGB(110, 28, 28)
label.TextColor3 = Color3.new(1, 1, 1)
label.TextScaled = true
label.Text = "Your saved progress could not be loaded. Nothing you do in this server will be saved, so rejoin later."
label.Parent = gui
gui.Parent = player:WaitForChild("PlayerGui")
end
-- 서버는 이 플레이어의 데이터를 불러오려고 시도한 뒤 DataLoaded를 한 번 설정합니다
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
4단계: Studio에서 저장 테스트하기
Studio 접근을 켠 테스트 복사본에서 하세요.
- 저장할 무언가를 자신에게 주세요.
Main의 require 줄 아래에 다음을 추가하세요:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - Play를 누르세요. Output 창(Window 메뉴 또는 Script 탭)에 여러분의 이름과 100이(처음 실행할 때) 표시되고,
Could not load경고는 없습니다. - Stop을 누르세요. 테스트를 끝내면 서버가 닫히고, 모듈은 닫히기 전에 여러분을 저장합니다.
- 다시 Play를 누르세요. Output에 지난번보다 100 많은 200이 표시되어야 합니다. 같은 숫자가 다시 나온다면 저장이 실패한 것이니 그 위의 경고를 읽으세요.
- 실패 경로를 테스트하세요. Studio 접근을 끄고 Play를 누르세요. 몇 초 동안 재시도한 뒤 Output에
Could not load User_...와 100이 표시되고, 3단계의 배너가 나타납니다. 테스트를 멈추고 접근을 다시 켠 뒤 Play를 누르세요. Output에 300이 표시됩니다. 저장된 200에 100을 더한 값이며, 실패한 세션이 여러분의 데이터를 덮어쓰지 않았기 때문입니다. Main에서 테스트 줄을 지우세요.
플레이어 데이터가 사라지는 이유
저장 시스템이 진행 상황을 잃는 흔한 경우는 다음과 같습니다. 모듈은 처음 네 줄과 스키마에 관한 줄을 코드로 막습니다. 나머지는 무엇을 어떻게 저장하느냐에 달려 있고, 마지막 줄에는 세션 잠금이 필요합니다.
| 무슨 일이 일어나나 | 결과 | 예방법 |
|---|---|---|
| 불러오기가 실패했는데 스크립트가 그래도 저장함 | 기본값이 실제 진행 상황을 덮어씀: 전부 지워짐 | 불러오기에 실패한 플레이어는 절대 저장하지 않기 |
PlayerRemoving에서만 저장함 | 서버가 다운되거나 꺼지면 저장을 놓침 | 자동 저장과, 자기 저장을 기다리는 BindToClose |
pcall이 없거나 재시도가 없음 | 실패한 요청 하나가 스크립트를 멈추거나 저장을 잃음 | 시간 간격을 둔 몇 번의 재시도와 함께 pcall |
| 바뀔 때마다 저장함 | 요청이 대기열에 쌓이고, 대기열에 30개가 차면 새 요청은 버려짐 | 데이터를 메모리에 들고 타이머에 맞춰 저장하기 |
| 스토어가 저장할 수 없는 것을 저장함 | 저장할 때 오류가 나거나 값이 nil로 돌아옴 | 숫자, 문자열, 불리언과 그것들로 된 테이블을 저장하기 |
| 마이그레이션 없이 데이터 형태를 바꿈 | 예전 저장 데이터가 엉뚱한 필드로 불러와짐 | 스키마 버전과 마이그레이션 단계 |
| 두 스크립트가 같은 키를 저장함 | 저장할 때마다 서로의 필드를 덮어씀 | 키는 모듈 하나가 소유하기 |
| 두 서버가 같은 플레이어를 들고 있음 | 오래된 데이터를 가진 서버가 마지막에 저장해서 새 진행 상황을 덮어씀 | 세션 잠금 |
세션 잠금, "lock lost", 그리고 ProfileStore
플레이어는 한 번에 서버 하나에만 연결되지만, 새 서버에 들어올 때 예전 서버의 마지막 저장이 아직 진행 중일 수 있습니다. 느린 재시도, 텔레포트, 빠른 재접속 같은 경우입니다. 새 서버가 먼저 데이터를 불러오면 예전 데이터를 갖게 되고, 마지막에 저장하는 서버가 이깁니다. Roblox 문서는 교환이 있는 게임에서 이 틈이 아이템 복제의 흔한 원인이라고 지적합니다.
세션 잠금이 이 틈을 막습니다. 서버가 플레이어의 키를 불러올 때, 같은 UpdateAsync 호출에서 키의 메타데이터에 자신의 잠금 ID를 기록합니다. 만료되지 않았고 자신이 걸지 않은 잠금을 발견한 다른 서버는 그 키를 불러오지도 저장하지도 않습니다. 소유한 서버는 자동 저장할 때마다 잠금을 갱신하고 마지막 저장에서 풉니다. 갱신을 멈추면 잠금이 만료되고 다른 서버가 가져갈 수 있습니다.
"lock lost"의 뜻
세션 잠금이 있는 시스템에서 서버가 잠금을 잃었다는 것은, 잠금이 만료되었거나 빼앗겨서 이제 다른 서버가 플레이어의 키를 소유한다는 뜻입니다. 그 서버의 복사본은 오래되었을 수 있으므로 그 플레이어의 저장을 멈춰야 합니다. 보통의 대응은 다시 접속하라는 메시지와 함께 플레이어를 킥하는 것입니다. 플레이어로서 "lock lost"를 봤다면, 그것은 그 게임 자체의 저장 시스템이 띄운 메시지이며 설명할 수 있는 것은 그 게임의 개발자뿐입니다.
세션 잠금이 필요할까?
이 가이드의 모듈은 세션을 잠그지 않습니다. 잠금이 없을 때 현실적인 최악의 경우는 이렇습니다. 드문 경쟁 상황에서 플레이어는 예전 서버의 마지막 성공한 저장 이후에 그 서버에서 얻은 것을 잃습니다. 복제나 손실이 플레이어에게 실제로 무언가를 잃게 할 때 잠금을 추가하세요. 교환, developer products, 희귀 아이템, 잦은 텔레포트 같은 경우입니다.
| 선택지 | 무엇인가 | 알아 둘 점 |
|---|---|---|
| 이 가이드의 모듈 | 불러오기, 메모리 캐시, 재시도, 자동 저장, 종료 시 저장, 스키마 버전, 잠금 없음 | 끝까지 읽고 고칠 수 있을 만큼 짧음 |
| 플레이어 데이터와 구매를 위한 Roblox 예제 | 세션 잠금, 키별 순서대로의 재시도, 구매 영수증 처리를 갖춘 Roblox의 참조 코드 | Roblox는 이 코드가 인기 게임에서 검증된 것이 아니며 폭넓은 테스트 없이 그대로 쓰면 안 된다고 말함 |
| ProfileStore | ProfileService의 후속인 무료 오픈 소스 커뮤니티 모듈로, 세션 잠금과 자동 저장을 중심으로 만들어짐 | Roblox가 만든 것이 아님. 기존 게임을 옮기려면 이미 저장된 데이터의 마이그레이션이 필요함 |
어떤 외부 모듈이든 Roblox는 누가 소유하는지, 유지 관리되는지, 그 모듈 없이 내 데이터에 어떻게 접근할지를 확인하라고 권합니다. 같은 문서는 DataStore2를 새 게임에서는 쓰지 않는 것이 좋은 오래된 라이브러리로 부릅니다.
데이터 스토어 제한
아래는 2026년 9월 30일 기준 Roblox 문서의 제한입니다. Roblox는 이 값을 바꾸므로, 정확한 숫자에 기대기 전에 오류 코드와 제한 페이지(영어)를 확인하세요.
| 요청 유형 | 일반 스토어 | 정렬된 스토어 |
|---|---|---|
읽기: GetAsync, UpdateAsync의 읽기 | 60 + 40 × 플레이어 수 | 60 + 40 × 플레이어 수 |
쓰기: SetAsync, IncrementAsync, UpdateAsync의 쓰기 | 60 + 40 × 플레이어 수 | 30 + 5 × 플레이어 수 |
목록: ListKeysAsync, 정렬된 스토어는 GetSortedAsync | 5 + 2 × 플레이어 수 | 5 + 2 × 플레이어 수 |
삭제: RemoveAsync | 60 + 40 × 플레이어 수 | 30 + 5 × 플레이어 수 |
플레이어가 20명이면 서버는 1분에 일반 쓰기를 860번 할 수 있습니다. 이 모듈의 자동 저장은 그중 약 7번을 쓰고, 나가는 플레이어마다 한 번씩 더 씁니다. 예산을 다 써 버리는 것은 코인을 주울 때마다 저장하는 방식입니다. 두 번째 예산은 게임 전체에 적용되며 Open Cloud와 공유됩니다. 1분에 읽기 300번에 접속 중인 플레이어당 40번, 쓰기 300번에 플레이어당 20번입니다.
| 제한 | 값 |
|---|---|
| 스토어 이름, 키 이름, scope | 각각 50자 |
| 키 하나의 값 | JSON으로 4 194 304자 |
| 모든 서버에서 키 하나 읽기 | 1분에 25MB |
| 모든 서버에서 키 하나에 쓰기 | 1분에 4MB, 요청마다 다음 KB로 올림 |
| 대기 중인 요청 | 대기열당 30개. 그 이상이면 요청이 301-306 오류로 실패 |
| 게임 전체 저장 공간 | 500MB에 지금까지의 사용자 한 명당 1MB 추가 |
플레이어 데이터의 크기는 #HttpService:JSONEncode(data)로 재고, 라이브 서버의 남은 예산은 DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite)로 보세요. 4초 캐시가 응답한 GetAsync 호출은 계산되지 않습니다. Studio의 Run 모드에는 더 낮을 수도 있는 자체 제한이 있으므로, Roblox는 요청 제한을 테스트할 때 Team Create를 권합니다.
버전과 백업
일반 데이터 스토어는 기록을 대신 보관해 줍니다. UTC 기준 매시간 키에 처음 쓴 것이 버전으로 저장되고, 그 시간의 이후 쓰기는 서로를 덮어씁니다. 예전 버전은 더 새로운 쓰기로 대체된 지 30일 뒤에 만료되고, 가장 최신 버전은 절대 만료되지 않습니다. 정렬된 스토어는 버전을 보관하지 않습니다.
플레이어 한 명을 되돌리려면 Data Stores Manager(Creations, 여러분의 게임, Configure > Data Stores Manager)를 열고 그 플레이어의 키를 고른 다음 이전 버전을 고르고 Revert를 누르세요. Edit 권한이 필요합니다. 플레이어가 오프라인일 때 하세요. 그렇지 않으면 그 세션을 가진 서버가 되돌린 값 위에 자기 복사본을 저장합니다. 서버 스크립트에서는 ListVersionsAsync와 GetVersionAsync로 예전 버전을 찾아 읽은 다음, 그것을 현재 값으로 다시 쓰면 됩니다.
데이터 저장 방식을 바꾸는 업데이트를 게시하기 전에, Roblox는 Open Cloud Snapshot Data Stores API로 스냅샷을 만들라고 권합니다(게임당 하루 한 번). 스냅샷이 없으면 UTC 3:30의 잘못된 저장이 3:00 이후 그 키에 기록된 모든 것을 덮어씁니다. 같은 시간대 버전에 들어가기 때문입니다.
자주 발생하는 오류와 해결 방법
데이터 스토어 오류는 Studio의 Output 창에 나타나며, 모듈은 시도가 실패할 때마다 Roblox 오류 문구가 담긴 경고를 출력합니다. 스크립트 오류 가이드가 Output을 읽는 법 전반을 설명합니다.
StudioAccessToApisNotAllowed(오류 403)
"Can't write to DataStore from Studio because API access is not enabled." 플레이스를 게시한 다음, 테스트 복사본에서 File > Experience Settings > Security의 Enable Studio Access to API Services를 켜세요.
DataStore request was added to queue
서버가 예산이 허용하는 것보다 빨리 요청을 보내거나 같은 키에 너무 자주 쓰고 있습니다. 보통 바뀔 때마다 또는 반복문 안에서 저장하기 때문입니다. 대기열에 요청이 30개 차면 새 요청은 301-306 오류로 실패합니다. 데이터를 메모리에 들고 타이머에 맞춰 저장하세요.
CantStoreValue(오류 104), 또는 필드가 nil로 돌아옴
테이블 안에 Instance, Vector3, Color3처럼 스토어가 저장할 수 없는 것이 있습니다. 대신 이름, ID, 또는 단순한 숫자를 저장하고 불러올 때 오브젝트를 다시 만드세요.
ValueTooLarge(오류 105)
키 하나에 JSON으로 4 194 304자보다 많이 들어 있습니다. #HttpService:JSONEncode(data)로 재 보고, 다시 만들 수 있는 것은 빼거나 데이터를 고정된 키 여러 개로 나누세요.
오류는 없는데 데이터가 저장되지 않음
모듈의 Could not load 경고를 찾아보세요. 불러오기에 실패한 뒤에는 일부러 저장하지 않습니다. 그게 아니라면 값을 LocalScript에서 바꿨을 가능성이 큰데, 그것은 서버에 절대 닿지 않습니다. 또는 다른 스크립트가 같은 키를 저장하고 있습니다.
다시 접속할 때마다 데이터가 초기화됨
키가 세션마다 바뀌거나(player.Name으로 만들었거나 STORE_NAME을 바꿨음), 불러오기가 실패해서 기본값을 보고 있거나, 아무도 모듈을 불러오지 않아서 아예 실행되지 않는 경우입니다. Output을 확인하고 Main이 PlayerData를 불러오는지 확인하세요.
RoCode로 만들어 보기
직접 만들기 싫다면 RoCode가 지금 열려 있는 플레이스에 바로 만들어 줄 수 있습니다. RoCode는 Roblox가 아닌 독립 AI 에이전트로, Roblox Studio 플러그인을 통해 작동합니다. 다른 스크립트처럼 DataStoreService를 쓰는 Luau를 작성하고 Explorer에 스크립트를 만듭니다. RoCode 자체는 데이터 스토어에 절대 접근하지 않지만, 플러그인 3.9 이상에서는 짧은 플레이 테스트를 위해 Play를 누를 수 있고, 그때 여러분의 스크립트는 다른 테스트와 똑같이 실행됩니다.
내 게임에 저장 기능을 추가해 줘. Coins, Level, Inventory를 자동 저장과 서버 종료 시 저장이 있는 PlayerData 모듈에 저장하고, 이미 있는 leaderstats에 Coins를 보여 줘.
- Search Scripts와 Read Script로 기존 leaderstats와 DataStore 코드를 찾아서, 두 번째 저장 스크립트를 추가하는 대신 이미 있는 것을 확장할 수 있습니다. 큰 플레이스라면 메시지에 스크립트나 폴더 이름을 적어 주세요.
- Create Script로 ModuleScript와 그것을 불러오는 Script를 만들거나, Edit Script로 기존 스크립트를 고칩니다
- 작성한 모든 스크립트에 Check Script를 실행합니다. Studio 안에서 짧은 경고 목록과 함께 하는 컴파일 확인이며, 타입 검사나 테스트 실행은 아닙니다
- 변경을 묶음으로 보내며, 각 묶음은 Studio의 실행 취소(undo) 지점입니다
테스트 복사본에서 Studio Access to API Services를 켜는 것은 여전히 직접 해야 합니다. RoCode는 이 설정을 바꿀 수 없습니다. 플러그인 3.9 이상에서는 짧은 플레이 테스트로 오류를 읽고, 플러그인 3.9.11 이상에서는 테스트 캐릭터를 조종해 게임이 작동하는지 확인할 수 있지만, 스스로 확인하기로 정한 것만 확인하므로 직접 플레이해서 Coins, Level, Inventory가 저장되고 불러와지는지 확인하세요. 테스트에서 저장이 실패했다면 Check Output이 여러분이 실행한 플레이 테스트의 Server 줄을 읽을 수 있습니다. 저장 기능은 보통 핵심 게임 루프가 이미 작동할 때 추가합니다. AI로 한 번에 시스템 하나씩 Roblox 게임 만들기가 이 순서를 보여 줍니다. RoCode가 Studio에 연결되는 방법.
자주 묻는 질문
Roblox Studio에서 DataStore를 켜려면 어떻게 하나요?
플레이스를 게시하고 File > Experience Settings > Security를 열어 Enable Studio Access to API Services를 켜고 Save를 누르세요. 별도의 테스트 게임에서 하세요. 그러면 Studio가 그 게임의 라이브 서버와 같은 데이터 스토어를 쓰기 때문입니다.
Roblox는 플레이어 데이터를 자동으로 저장하나요?
아니요. 서버 스크립트가 DataStoreService로 저장하지 않는 한 플레이어에 대한 어떤 것도 세션이 끝난 뒤 남지 않으며, leaderstats도 마찬가지입니다.
ProfileStore와 DataStoreService 직접 사용 중 무엇을 골라야 하나요?
ProfileStore도 데이터 스토어 위에 만들어졌으므로, 문제는 세션 잠금을 다른 사람이 작성하고 유지 관리해 주기를 원하느냐입니다. 교환, 유료 아이템, 잦은 텔레포트가 있다면 라이브러리든 Roblox 참조 예제든 잠금을 쓸 가치가 있습니다. 더 작은 게임이라면 이런 모듈이 읽고 고치기 더 쉽습니다.
플레이어 데이터를 초기화하거나 지우려면 어떻게 하나요?
Data Stores Manager에서 키를 찾아 Mark for Deletion을 고르세요. 대기 기간 안에는 취소할 수 있습니다. 또는 서버 스크립트에서 그 키에 RemoveAsync를 호출하세요. 플레이어가 오프라인일 때 하세요. 그렇지 않으면 그 서버의 다음 저장이 데이터를 다시 씁니다. 테스트 복사본에서는 STORE_NAME을 바꾸면 모두가 처음부터 시작합니다. 라이브 게임에서는 절대 하지 마세요.
출처와 더 읽을거리
- Roblox Creator Docs: Data stores (영어). Studio 접근, GetAsync, SetAsync, UpdateAsync, set과 update
- Roblox Creator Docs: Best practices for data stores (영어). 플레이어당 키 하나, 메모리의 데이터, 점점 길어지는 간격의 재시도, 외부 모듈
- Roblox Creator Docs: Data store error codes and limits (영어). 오류 코드, 서버와 게임의 요청 제한, 크기, 처리량, 저장 공간 제한
- Roblox Creator Docs: Versioning, listing and caching (영어). 시간 단위 버전, 스냅샷, 4초 캐시, 저장할 수 있는 것
- Roblox Creator Docs: Implement player data and purchasing systems (영어). 참조 예제, 세션 잠금, 실패한 불러오기, 180초마다 자동 저장
- Roblox Creator Docs: Data Stores Manager (영어). 키 보기, 버전 되돌리기, 데이터 삭제
- Roblox Engine API: DataModel:BindToClose (영어). 종료에 주어지는 30초
코드 검증 방법: 이 페이지의 모든 스크립트는 Roblox API 정의를 적용한 Luau의 엄격한 타입 검사기(luau-lsp, 2026년 11월 20일)를 통과합니다. 타입 검사는 잘못 쓴 API 이름과 잘못된 타입을 찾아내지만 게임 로직의 오류는 찾지 못하므로, 게시하기 전에 Studio에서 직접 테스트하세요.