🏆 Leaderboard Functions

GetLeaderboardInfo()

GetLeaderboardInfo(statName) → LeaderboardInfo?

Gets your current leaderboard info (rank + score) for a tracked stat.

Parameters: statName: string
Returns: LeaderboardInfo? - { rank: number?, score: number?, statName: string }, or nil if unavailable

Example

local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

local info = PlayerState.GetLeaderboardInfo("Coins")
if info then
    print(`Coins leaderboard: rank={info.rank}, score={info.score}`)
else
    print("No leaderboard info (not tracked / not enabled / not ready yet)")
end

Notes

• Requires server leaderboard to be enabled and the stat to be tracked in PlayerStateConfig.Server.Leaderboard.TrackedStats.
• The client reads from the server-synced _LeaderboardRanks table (replicated to the client).
• _LeaderboardRanks is temporary display data and is treated as non-persistent (it will not be saved into player data).
• Score feels instant: when a tracked stat changes, the synced score updates right away.
• Rank updates on the normal refresh cycle (based on the server sync interval).

---

GetLeaderboard()

GetLeaderboard(statName, limit?) → {LeaderboardEntry}

Gets the ranked leaderboard entries for a tracked stat. Automatically waits for data to load.

Parameters: statName: string, limit: number? (optional — max entries to return; omit for all)
Returns: {LeaderboardEntry} - Array of { userId: number, score: number, rank: number }, or {} if unavailable

Example

local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

local top10 = PlayerState.GetLeaderboard("Coins", 10)
for _, entry in top10 do
    print(`#{entry.rank}: User {entry.userId} — {entry.score} coins`)
end

local allEntries = PlayerState.GetLeaderboard("Coins")
print("Total entries:", #allEntries)

Notes

• Reads from the server-synced _Leaderboards table (replicated to the client).
• limit is clamped to the actual number of entries; invalid or non-positive limit returns all entries.
• Returns an empty table if the stat is not tracked, leaderboards are disabled, or data is not ready.