🏆 Global Leaderboard

Configuration Required & Runtime Validation

Leaderboard functionality requires proper configuration in PlayerStateConfig!

Make sure your PlayerStateConfig.Server.Leaderboard section is properly configured:

Server = {
    Leaderboard = {
        Enabled = true,
        DataStoreName = "PlayerState_Leaderboards",
        TrackedStats = {"Coins", "Level", "HighScore"},
        SyncInterval = 60,
        UpdateOnPlayerLeave = true,
    },
}

Runtime Validation: Functions now validate configuration at runtime and will warn/return appropriate values if misconfigured:

• GetLeaderboard() returns empty array {}
• GetPlayerRank() returns nil
• UpdateLeaderboard() returns false

Client-synced rank/score (for UI)

When leaderboards are enabled, PlayerState syncs each player’s current leaderboard display info to the client via a replicated _LeaderboardRanks table.

What this gives you:

• Reliable UI data: the client can read {rank, score} for tracked stats without re-deriving it.
• Instant-feeling score: when a tracked stat changes (via Set, SetPath, SetValues, etc.), the synced score updates right away.
• Rank on refresh: rank updates on the normal server refresh cycle (based on SyncInterval).

Important:

• _LeaderboardRanks is temporary display data and is treated as non-persistent (it will not be saved into player data).
• On the client, use PlayerStateClient.GetLeaderboardInfo(statName) to read this value.

GetLeaderboard()

GetLeaderboard(statName, topCount) → {LeaderboardEntry}

Retrieves the top players for a specific leaderboard statistic.

Parameters: statName: string, topCount: number
Returns: {LeaderboardEntry} - Array of leaderboard entries sorted by score (highest first), or empty array if configuration issues

Example

-- Get top 10 coin leaders
local coinLeaderboard = PlayerState.GetLeaderboard("Coins", 10)
for i, entry in ipairs(coinLeaderboard) do
    print(`#{i}: User {entry.userId} - {entry.score} coins`)
end

-- Get top 100 high scores
local highScores = PlayerState.GetLeaderboard("HighScore", 100)
if #highScores > 0 then
    print(`Highest score: {highScores[1].score} by User {highScores[1].userId}`)
end

Note

Results are cached for 15 seconds to improve performance.

Configuration Validation

This function validates configuration at runtime:

• Returns empty array {} and warns if CONFIG.Leaderboard.Enabled = false
• Returns empty array {} and warns if the statName is not in CONFIG.Leaderboard.TrackedStats
• Requires the stat name to be properly configured before calling

---

GetPlayerRank()

GetPlayerRank(player, statName) → number?

Gets a player's current rank on a specific leaderboard.

Parameters: player: Player, statName: string
Returns: number? - Player's rank (1-based), or nil if not ranked, invalid player, or configuration issues

Example

-- Get player's coin rank
local coinRank = PlayerState.GetPlayerRank(player, "Coins")
if coinRank then
    print(`You're ranked #{coinRank} for coins!`)
else
    print("You're not yet ranked for coins")
end

-- Check multiple ranks
local levelRank = PlayerState.GetPlayerRank(player, "Level")
local scoreRank = PlayerState.GetPlayerRank(player, "HighScore")

if levelRank and scoreRank then
    print(`Level Rank: #{levelRank}, Score Rank: #{scoreRank}`)
end

Note

Returns nil if player has no score for this stat or if the player is invalid.

Configuration Validation

This function validates configuration at runtime:

• Returns nil and warns if CONFIG.Leaderboard.Enabled = false
• Returns nil and warns if the statName is not in CONFIG.Leaderboard.TrackedStats
• Returns nil if the player is invalid or not found
• Requires the stat name to be properly configured before calling

---

UpdateLeaderboard()

UpdateLeaderboard(player, statName, score) → boolean

Manually updates a player's leaderboard entry for a specific statistic.

Parameters: player: Player, statName: string, score: number
Returns: boolean - Success status, or false if configuration or validation issues

Example

-- Update player's coin leaderboard
local success = PlayerState.UpdateLeaderboard(player, "Coins", 5000)
if success then
    print("Leaderboard updated successfully")
else
    warn("Failed to update leaderboard")
end

-- Update multiple stats
PlayerState.UpdateLeaderboard(player, "Level", 25)
PlayerState.UpdateLeaderboard(player, "HighScore", 1200)

Note

This function immediately updates the leaderboard. Most stats are automatically updated when data changes, but you can use this for manual updates.

Configuration Validation

This function validates configuration at runtime:

• Returns false and warns if CONFIG.Leaderboard.Enabled = false
• Returns false and warns if the statName is not in CONFIG.Leaderboard.TrackedStats
• Returns false if the player is invalid
• Requires the stat name to be properly configured before calling
• Clears the cache for the updated stat to ensure fresh data

Leaderstats Integration

🏆 Automatic Leaderstats

PlayerState now automatically creates and manages leaderstats based on your data configuration:

-- In your DefaultData module, add leaderstats configuration:
local DefaultData = {
    Coins = 0,
    Level = 1,
    Experience = 0,
    Plot = {
        Likes = 0
    },

    -- Leaderstats configuration
    leaderstats = {
        ["💰 Coins"] = "Coins",
        ["⭐ Level"] = "Level",
        ["👍 Likes"] = "Plot.Likes"
    }
}

Features:

• Automatic Creation: Leaderstats are created when player data loads
• Real-time Sync: Updates automatically when data changes
• Type-Safe: Numbers use IntValue, others use StringValue
• Path Support: Supports nested paths like "Plot.Likes"

Leaderstats Protection

Direct modification of leaderstats paths is prevented. Change the source data instead!

-- ❌ This will fail
PlayerState.Set(player, "leaderstats", {...})

-- ✅ This updates the leaderstat automatically
PlayerState.Set(player, "Coins", 1000)