Leaderboard configuration

Configure Server.Leaderboard in PlayerStateConfig. API usage: Server leaderboard · Leaderstats & paths.

Leaderboard config required

Without a proper Leaderboard section, leaderboard functions return nil, {}, or false and may warn in the console.

Basic setup

-- PlayerStateConfig.lua
local Config = {
    Server = {
        Leaderboard = {
            Enabled = true,
            DataStoreName = "PlayerState_Leaderboards",
            TrackedStats = {
                "Coins",
                "Level",
                "HighScore",
                "Plot.Likes",
                "Stats.TotalPlayTime",
            },
            SyncInterval = 60,
            UpdateOnPlayerLeave = true,
        },
    },
}

Options

Setting	Default	Description
Enabled	true	Must be true for leaderboards to work
DataStoreName	"PlayerState_Leaderboards"	Base name for leaderboard DataStores
TrackedStats	{ "Coins", "Level", ... }	Numeric paths to track
SyncInterval	60	Sync interval in seconds
UpdateOnPlayerLeave	true	Update when players leave

TrackedStats

Only numeric paths that exist in your data (or reconcile defaults) are valid:

TrackedStats = {
    "Coins",
    "Plot.Likes",
    "Stats.TotalPlayTime",
}

• Nested paths use dot notation.
• An empty array disables tracking.

DataStore names

Each stat gets an OrderedDataStore derived from DataStoreName:

• "Coins" → PlayerState_Leaderboards_Coins
• "Plot.Likes" → PlayerState_Leaderboards_Plot_Likes

DataStore limits

Roblox rate limits apply. Use a sensible SyncInterval for your player count.

Automatic vs manual updates

• Automatic (recommended): Tracked stats sync on the configured interval and on leave when UpdateOnPlayerLeave is true.
• Manual: PlayerState.UpdateLeaderboard(player, statName, score) for special cases.

Testing

Leaderboard = {
    Enabled = true,
    DataStoreName = "PlayerState_Leaderboards_TEST",
    TrackedStats = { "Coins", "Level" },
    SyncInterval = 30,
    UpdateOnPlayerLeave = true,
}

Runtime validation

At runtime, PlayerState checks Enabled and whether the stat is in TrackedStats. Misconfiguration returns safe defaults and console warnings instead of throwing.

local board = PlayerState.GetLeaderboard("Coins", 10) -- OK if Coins is tracked

Back to Configuration.