roblox-datastores

What this skill does

# roblox-datastores

Reference for Roblox `DataStoreService` — saving, loading, and managing player data on the server.

## Quick Reference

| Method | Signature | Notes |
|---|---|---|
| `GetDataStore` | `DSS:GetDataStore(name, scope?)` | Returns a `GlobalDataStore` |
| `GetOrderedDataStore` | `DSS:GetOrderedDataStore(name, scope?)` | For leaderboards |
| `GetAsync` | `store:GetAsync(key)` | Returns value or nil |
| `SetAsync` | `store:SetAsync(key, value)` | No return value needed |
| `UpdateAsync` | `store:UpdateAsync(key, fn)` | Atomic read-modify-write |
| `RemoveAsync` | `store:RemoveAsync(key)` | Deletes key, returns old value |
| `GetSortedAsync` | `orderedStore:GetSortedAsync(asc, pageSize)` | Returns `DataStorePages` |

---

## Basic Setup

```lua
-- Server Script (ServerScriptService)
local DataStoreService = game:GetService("DataStoreService")
local Players = game:GetService("Players")

local playerStore = DataStoreService:GetDataStore("PlayerData_v1")

local DEFAULT_DATA = {
    coins = 0,
    level = 1,
    xp = 0,
}
```

---

## Loading Data (GetAsync + pcall)

Always wrap datastore calls in `pcall`. They can fail due to network issues or rate limits.

```lua
local function loadData(player)
    local key = "player_" .. player.UserId
    local success, data = pcall(function()
        return playerStore:GetAsync(key)
    end)

    if success then
        local result = {}
        for k, v in pairs(DEFAULT_DATA) do result[k] = v end
        if data then
            for k, v in pairs(data) do result[k] = v end
        end
        return result
    else
        warn("Failed to load data for", player.Name, ":", data)
        return nil -- signal failure; do not give default data silently
    end
end
```

---

## Saving Data (SetAsync vs UpdateAsync)

Use `SetAsync` for simple overwrites. Use `UpdateAsync` when the value must be based on the current stored value (e.g., incrementing a counter safely across servers).

```lua
-- Simple save
local function saveData(player, data)
    local key = "player_" .. player.UserId
    local success, err = pcall(function()
        playerStore:SetAsync(key, data)
    end)
    if not success then
        warn("Failed to save data for", player.Name, ":", err)
    end
end

-- Atomic increment with UpdateAsync
local function addCoinsAtomic(userId, amount)
    local key = "player_" .. userId
    pcall(function()
        playerStore:UpdateAsync(key, function(current)
            current = current or { coins = 0 }
            current.coins = current.coins + amount
            return current
        end)
    end)
end
```

---

## Retry Logic

```lua
local MAX_RETRIES = 3
local RETRY_DELAY = 2

local function safeGet(store, key)
    for attempt = 1, MAX_RETRIES do
        local success, result = pcall(function()
            return store:GetAsync(key)
        end)
        if success then return true, result end
        warn(string.format("GetAsync attempt %d/%d failed: %s", attempt, MAX_RETRIES, result))
        if attempt < MAX_RETRIES then task.wait(RETRY_DELAY) end
    end
    return false, nil
end
```

---

## Auto-Save: PlayerRemoving + BindToClose

Server shutdown without `BindToClose` silently discards unsaved data.

```lua
local sessionData = {} -- [userId] = data table

Players.PlayerAdded:Connect(function(player)
    local data = loadData(player)
    if data then
        sessionData[player.UserId] = data
    else
        player:Kick("Could not load your data. Please rejoin.")
    end
end)

Players.PlayerRemoving:Connect(function(player)
    local data = sessionData[player.UserId]
    if data then
        saveData(player, data)
        sessionData[player.UserId] = nil
    end
end)

-- Flush all sessions on server shutdown
game:BindToClose(function()
    for userId, data in pairs(sessionData) do
        local key = "player_" .. userId
        pcall(function()
            playerStore:SetAsync(key, data)
        end)
    end
end)
```

---

## Ordered DataStores (Leaderboards)

Values must be positive integers.

```lua
local coinsLeaderboard = DataStoreService:GetOrderedDataStore("Coins_v1")

local function setLeaderboardScore(userId, coins)
    pcall(function()
        coinsLeaderboard:SetAsync("player_" .. userId, math.floor(coins))
    end)
end

local function getTopPlayers(count)
    local success, pages = pcall(function()
        return coinsLeaderboard:GetSortedAsync(false, count) -- false = descending
    end)
    if not success then return {} end

    local results = {}
    for rank, entry in ipairs(pages:GetCurrentPage()) do
        table.insert(results, { rank = rank, userId = entry.key, score = entry.value })
    end
    return results
end
```

---

## Data Versioning / Migration

Include a `_version` field and migrate in the load path.

```lua
local CURRENT_VERSION = 2

local function migrateData(data)
    local version = data._version or 1
    if version < 2 then
        data.coins = data.gold or 0  -- renamed field
        data.gold = nil
        data._version = 2
    end
    return data
end
```

Use a versioned datastore name (`PlayerData_v2`) for breaking schema changes.

---

## Common Mistakes

| Mistake | Consequence | Fix |
|---|---|---|
| No `pcall` around datastore calls | Unhandled error crashes the script | Always wrap in `pcall` |
| Saving on every `Changed` event | Hits rate limits (60 + numPlayers×10 writes/min) | Throttle; save on remove + periodic interval |
| No `BindToClose` handler | Data lost on server shutdown | Always flush all sessions in `BindToClose` |
| Giving default data on load failure | Player silently loses progress | Return `nil` on failure; kick or retry |
| `SetAsync` for atomic counters | Race condition across servers | Use `UpdateAsync` for read-modify-write |
| Storing Instances or functions | Data silently drops | Store only strings, numbers, booleans, plain tables |
| Reusing datastore name after schema change | Old shape clashes with new code | Append `_v2`, `_v3` to name on breaking changes |