roblox-datastores

Roblox DataStores

Persist data across sessions in Roblox with DataStoreService: loading on join, saving on leave and shutdown, safe updates, retries, and ordered stores for leaderboards. Server-side only.

When to use

• Use to save/load player progress (coins, inventory, levels), build persistent leaderboards, or fix data loss, overwrites, and throttling.
• Use when server code calls DataStoreService, GetDataStore, GetAsync, SetAsync, UpdateAsync, or GetOrderedDataStore.

When not to use: general scripting, services, remotes, the client/server split → roblox-luau. High-frequency temporary state (matchmaking, per-round) → memory stores (a different service). Engine-agnostic persistence theory → save-systems.

Core workflow

1. Enable Studio access once. In a published place, File → Experience Settings → Security → Enable Studio Access to API Services (use a separate test place; Studio hits the same live data as players). DataStores work only from server Scripts, never LocalScripts.
2. Get a store, then read/write by key. DataStoreService:GetDataStore("Name"); key per player is usually "Player_" .. player.UserId.
3. Wrap every call in pcall. GetAsync/SetAsync/UpdateAsync are network calls that can fail; an unguarded failure errors the thread and risks data loss.
4. Load on PlayerAdded, save on PlayerRemoving, and also BindToClose. A leaving player and a shutting-down server both need a final save.
5. Prefer UpdateAsync for read-modify-write (multi-server safe) over SetAsync (blind overwrite). On a failed load, do not overwrite with defaults — abort the save so you don't wipe good data.
6. Use OrderedDataStore for ranked data (leaderboards) via GetSortedAsync. Test by joining, changing data, rejoining, and confirming it persisted.

Patterns

1. Load on join (pcall-guarded)

local DataStoreService = game:GetService("DataStoreService")
local Players = game:GetService("Players")
local store = DataStoreService:GetDataStore("PlayerData")

local DEFAULT = { Coins = 0, Level = 1 }

Players.PlayerAdded:Connect(function(player)
    local key = "Player_" .. player.UserId
    local ok, data = pcall(function()
        return store:GetAsync(key)
    end)

    if not ok then
        -- Load FAILED (network). Do not treat as a new player; flag so we never save
        -- over their real data with defaults.
        warn("Load failed for", player.Name, data)
        player:SetAttribute("DataLoaded", false)
        return
    end

    player:SetAttribute("DataLoaded", true)
    local profile = data or DEFAULT          -- nil == genuinely new player
    applyToLeaderstats(player, profile)
end)