Leaderboard
The Leaderboard API provides functionality for managing competitive leaderboards in Highrise Studio.
Use Leaderboard for:
- Player rankings and scores
- High score tracking
- Competitive game statistics
- Multiple leaderboards (daily, weekly, all-time, etc.)
IMPORTANT: Leaderboard API is only available on the SERVER side.
Key Features:
- Set or increment player scores
- Retrieve individual entries or ranked ranges
- Support for multiple leaderboards via leaderboardId
- Automatic ranking system
- Player-specific convenience methods
Rate Limiting: Leaderboard functions have rate limits. Excessive calls will return LeaderboardError.RequestThrottled.
Methods
Deletes a specific entry from a leaderboard.
Leaderboard.DeleteEntry("global_scores", entryId, function(error)
if error == LeaderboardError.None then
print("Entry deleted")
end
end)
Parameters
leaderboardId
entryId
callback
Returns
Deletes a player's entry from a leaderboard. Convenience method equivalent to: DeleteEntry(leaderboardId, player.user.id, callback)
Leaderboard.DeleteEntryForPlayer("global_scores", player, function(error)
if error == LeaderboardError.None then
print("Player entry removed")
end
end)
Parameters
Returns
Retrieves a range of leaderboard entries starting from a specific rank. Returns entries sorted by rank.
-- Get top 10 entries
Leaderboard.GetEntries("global_scores", 1, 10, function(entries, error)
if error == LeaderboardError.None then
print("Top 10 Players:")
for i, entry in ipairs(entries) do
print(entry.rank .. ". " .. entry.name .. " - " .. entry.score)
end
end
end)
Parameters
leaderboardId
fromRank
limit
callback
Returns
Retrieves a specific entry from a leaderboard by entry ID.
Leaderboard.GetEntry("global_scores", entryId, function(entry, error)
if error == LeaderboardError.None and entry ~= nil then
print("Rank #" .. entry.rank .. ": " .. entry.name .. " - " .. entry.score)
end
end)
Parameters
leaderboardId
entryId
callback
Returns
Retrieves a player's entry from a leaderboard. Convenience method equivalent to: GetEntry(leaderboardId, player.user.id, callback)
Leaderboard.GetEntryForPlayer("global_scores", player, function(entry, error)
if error == LeaderboardError.None and entry ~= nil then
print(player.name .. " is rank #" .. entry.rank .. " with " .. entry.score)
else
print("Player not on leaderboard")
end
end)
Parameters
Returns
Increments the score for a leaderboard entry. If the entry doesn't exist, it will be created with the incremented score. Returns the updated entry with new rank and score.
Leaderboard.IncrementScore("daily_scores", player.user.id, player.name, 10, function(entry, error)
if error == LeaderboardError.None then
print("New score: " .. entry.score .. " | Rank: " .. entry.rank)
end
end)
Parameters
leaderboardId
entryId
name
score
callback
Returns
Increments a player's score on a leaderboard. Convenience method that uses player.user.id as entryId and player.name as name.
-- Add 5 points to player's score
Leaderboard.IncrementScoreForPlayer("global_scores", player, 5, function(entry, error)
if error == LeaderboardError.None then
print("New rank: #" .. entry.rank .. " with " .. entry.score .. " points")
end
end)
Parameters
leaderboardId
player
score
callback
Returns
Resets a leaderboard, removing all entries. Use this for seasonal resets or clearing old data.
Leaderboard.Reset("daily_scores", function(error)
if error == LeaderboardError.None then
print("Leaderboard reset successfully")
end
end)
Parameters
leaderboardId
callback
Returns
Sets the score for a leaderboard entry. If the entry doesn't exist, it will be created. Returns the updated entry with new rank and score.
Leaderboard.SetScore("weekly_scores", player.user.id, player.name, 1000, function(entry, error)
if error == LeaderboardError.None then
print(entry.name .. " is rank #" .. entry.rank .. " with " .. entry.score .. " points")
end
end)
Parameters
leaderboardId
entryId
name
score
callback
Returns
Sets a player's score on a leaderboard. Convenience method that uses player.user.id as entryId and player.name as name.
-- Set player's score to 1500
Leaderboard.SetScoreForPlayer("weekly_scores", player, 1500, function(entry, error)
if error == LeaderboardError.None then
print(entry.name .. " is now rank #" .. entry.rank)
end
end)
Parameters
leaderboardId
player
score
callback
Returns
Updated 13 days ago
