Leaderstats and paths

How to wire leaderstats to persisted fields and how dot-path APIs fit together.

Leaderstats integration

PlayerState reads a leaderstats table from DefaultData. Keys are display names; values are paths (top-level keys or dotted paths).

local DefaultData = {
    Coins = 0,
    Level = 1,
    Plot = { Likes = 0 },

    leaderstats = {
        ["Coins"] = "Coins",
        ["Level"] = "Level",
        ["Likes"] = "Plot.Likes",
    },
}

Leaderstats instances are created when profile data loads and stay in sync when the backing values change—never mutate leaderstats directly; update the underlying data (Set, SetPath, batch ops).

Full API behaviour: Leaderboard & leaderstats (server replica + automatic leaderstats) and Setup for defaults.

Client-side leaderboard UI

Configured global leaderboards (top-N across the game) are separate from HUD leaderstats. See Leaderboard APIs on the server and Client leaderboard for read helpers.

Path notation

PlayerState uses ValuePath strings with dots for nested reads and writes (SetPath / GetPath, batches, dictionaries, arrays). Paths are parsed with caching on the server; see Performance for cache notes.

Path examples

PlayerState.SetPath(player, "Settings.MusicEnabled", false)
PlayerState.SetPath(player, "Plot.Buildings.House.Level", 3)

PlayerState.BatchSetValues(player, {
    { path = "Stats.Combat.Weapons.Sword.Damage", value = 25 },
    { path = "Inventory.Tools.Pickaxe.Durability", value = 100 },
})

PlayerState.AddToArray(player, "Achievements", "first_win")
PlayerState.SetInDict(player, "Plot.Buildings", "Windmill", buildingData)

Setting normally creates missing intermediate tables. Fields under ServerOnlyRoots persist but are not on the player Replica — see Server-only data.

Where to read more

• Basic usage and advanced patterns
• Server paths API · Batch
• Best practices