Saving & Loading Data

개요

DataStore를 활용하면 플레이어의 레벨, 경험치, 보유 골드 등 핵심 데이터를 저장하고 불러올 수 있습니다. 이를 통해 플레이어의 진행 상태를 지속적으로 유지하며, RPG와 같은 육성 요소가 포함된 게임을 제작할 수 있습니다.

사용 방법

지원되는 데이터 타입

데이터 타입	지원 여부
number	O
string	O
bool	O
table	O
object	지원되지 않습니다.
함수	지원되지 않습니다.

기본 구조

DataStoreService의 GetDataStore을 사용하여 지정된 이름의 DataStore 객체를 가져올 수 있으며, DataStore 객체에 키-값(Key-Value) 형식으로 데이터를 저장하거나 불러올 수 있습니다.

• Key (키): 데이터를 식별하는 고유한 이름 (예: PlayerGold)

• Value (값): 저장할 데이터 (예: 1000)

기능	설명
GetDataStore(name)	이름에 해당하는 Datastore 객체를 가져오기
GetAsync(key)	Datastore 객체에서 키에 해당하는 데이터를 불러오기
SetAsync(key, value)	Datastore 객체에서 키에 데이터를 저장 (덮어쓰기)

데이터 스토어 가져오기

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

저장하기

local function SaveData(player)
    local success, errorMessage = pcall(function()
        local saveValue = 1 
        
        -- Key : PlayerName / Value : SaveValue
        GoldStore:SetAsync(player.UserId, saveValue) 
    end)

    if not success then
        print("errorMessage : ", errorMessage)
    end
end

불러오기

local function LoadData(player)
    local success, errorMessageOrLoadValue = pcall(function()
       -- Key : PlayerName
        return GoldStore:GetAsync(player.UserId)
    end)

    if not success then
        print("errorMessage : ", errorMessageOrLoadValue)
    else
        local loadValue = errorMessageOrLoadValue
        print(player.Name, "Load PlayerGold : ", loadValue)
    end
end

전체 코드 예시

다음 코드는 플레이어가 게임에 입장할 때, 서버에 저장된 데이터를 불러오고, 저장된 값이 없으면 초기값을 설정한 후, 해당 값을 플레이어의 Attribute로 할당합니다.

이후, 저장 함수가 호출되면, Attribute에 설정된 현재 값을 서버에 저장합니다.

DataManager = {}

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

-- 저장하거나 불러올 다양한 데이터 타입 정의
local PlayerData =
{
    { Name = "PlayerGold", InitValue = 0, Store = nil },
}

for i = 1, #PlayerData do
    PlayerData[i].Store = DataStoreService:GetDataStore(PlayerData[i].Name) 
end

--------------------------------------------------------
-- 현재 값을 서버에저장합니다.
function DataManager:SavePlayerData(player)
    repeat wait() until player:GetAttribute("IsDataLoaded")    
    
    print(player, "> SavePlayerData")        
    
    local text = ">>>> Save : "
    
    for i = 1, #PlayerData do
        local playerData = PlayerData[i]
        local store = playerData.Store        
        
        local success, errorMessageOrLoadValue = pcall(function()
            -- 플레이어의 Attribute 값을 읽고 서버에 저장
            local currentValue = player:GetAttribute(playerData.Name)
            
            store:SetAsync(player.UserId, currentValue) 
            
            return currentValue
        end)
    
        if not success then
            text = text .. "errorMessage : " .. errorMessageOrLoadValue
        else
            local loadValue = errorMessageOrLoadValue
            
            if i > 1 then
                text = text .. ", "
            end
            text = text .. player.Name .. " / Save " .. playerData.Name .. " : " .. tostring(loadValue)
        end
    end
            
    print(player, text)
end
-- 플레이어가 게임을 떠날 때 자동 저장 처리
Players.PlayerRemoving:Connect(function(player) DataManager:SavePlayerData(player) end)

--------------------------------------------------------
-- 서버에 저장된 값을 불러옵니다.
function DataManager:LoadPlayerData(player)
    print(player, "> LoadPlayerData")    
    
    local text = ">>>> Load : "    
    
    for i = 1, #PlayerData do
        local playerData = PlayerData[i]
        local store = playerData.Store        
        
        local success, errorMessageOrLoadValue = pcall(function()            
            return store:GetAsync(player.UserId)
        end)
    
        if not success then
            text = text .. "errorMessage : " .. errorMessageOrLoadValue
        else
            local loadValue = errorMessageOrLoadValue
            
            -- 저장된 값이 없으면 초기값(InitValue)을 설정 후 서버에 저장
            if loadValue == nil then      
                loadValue = playerData.InitValue    
                            
                store:SetAsync(player.UserId, loadValue) 
            end    
            
            -- 불러온 값을 플레이어의 Attribute로 설정
            player:SetAttribute(playerData.Name, loadValue)
            
            if i > 1 then
                text = text .. ", "
            end
            text = text .. player.Name .. " / Load " .. playerData.Name .. " : " .. tostring(loadValue)
        end
    end
    
    player:SetAttribute("IsDataLoaded", true)
    
    print(player, text)
end

--------------------------------------------------------
-- 플레이어가 게임에 입장시, 데이터를 불러옵니다.
local function LoadPlayerDataWhenEnter(player)
    local function onAddCharacter(character)
        print(player.Name ..  " LoadPlayerDataWhenEnter")    
        
        DataManager:LoadPlayerData(player)    
    end
    player.CharacterAdded:Connect(onAddCharacter)    
end
Players.PlayerAdded:Connect(LoadPlayerDataWhenEnter)

--------------------------------------------------------
-- 데이터 불러오기 예제
local function LoadExample(player)
    DataManager:LoadPlayerData(player)
end

-- 데이터 저장하기 예제
local function SaveExample(player)        
    -- 저장 전에 값 변경하는 예제 코드
    for i = 1, #PlayerData do
        local playerData = PlayerData[i]
        
        local currentValue = player:GetAttribute(playerData.Name)         
        
        if currentValue ~= nil then
            local newValue = currentValue + 1
            
            player:SetAttribute(playerData.Name, newValue) 
        end
    end        
    
    DataManager:SavePlayerData(player)
end

• LoadPlayerDataWhenEnter(player)

  • 플레이어가 게임에 접속하면 호출

• DataManager:LoadPlayerData(player)

  • 서버에서 저장된 플레이어 데이터를 불러옴(GetAsync)

    • 저장된 값이 없으면 초기값(InitValue)을 설정 후 서버에 저장

    • 불러온 값을 플레이어의 Attribute로 설정

• DataManager:SavePlayerData(player)

  • 플레이어의 Attribute 값을 읽고 서버에 저장(SetAsync)

  • PlayerRemoving 이벤트를 통해 플레이어가 게임을 떠날 때 자동 저장 처리

활용 예시

DataStore에서 데이터를 저장하거나 불러올 때 Key 값을 어떻게 설정하느냐에 따라 개별 유저 데이터 뿐만 아니라 게임 전체 데이터를 관리할 수도 있습니다.

예를 들어, Key 값을 Player.Name 대신 RaceGameLeaderBoard와 같은 형식으로 설정하면, 특정 플레이어의 데이터가 아닌 서버에 저장된 랭킹 정보를 관리할 수 있습니다.

이러한 방식으로, 리더보드, 이벤트 진행 상태, 서버 설정 등과 같은 게임 전역 데이터를 저장하고 불러올 수 있습니다.

퍼블리시 및 테스트 환경의 동작 차이

퍼블리시 후 모바일 환경에서는 실제 서버에 데이터를 저장하고 불러옵니다. 반면, 스튜디오 테스트 환경에서는 데이터를 로컬에 임시 저장하며, 스튜디오 종료 시 해당 데이터는 자동으로 삭제됩니다.

주의 사항

• 데이터 로딩이 완료되기 전에 플레이어가 게임을 진행하면 오류가 발생할 수 있으므로, 로딩이 완료될 때까지 로딩 UI를 표시하세요.

• 저장할 데이터는 가급적 작고 단순한 구조로 설계하세요.

• 과도한 요청은 데이터 저장 실패를 유발할 수 있으므로, 짧은 시간 내 반복 저장을 방지하세요.

  • API 호출은 분당 150회를 초과할 수 없습니다. 초과 요청시 서버에 제한이 발생할 수 있습니다.

• 갑작스러운 게임 종료나 서버 충돌로 인해 데이터가 손실될 수 있으므로 주기적으로 데이터가 저장되도록 구현하세요.

• 저장 또는 불러오기가 실패할 수 있으므로, pcall을 사용하여 오류를 방지하고 재시도 로직을 추가하세요.