Docs/Services/Leaderboards

Leaderboards

Real-time rankings and high scores. Create global, friends-only, or time-based leaderboards with automatic updates.

Real-time Updates

Scores update instantly across all connected clients.

Time-based Resets

Daily, weekly, monthly, or all-time leaderboards.

Social Leaderboards

Show scores for friends only.

Multiple Scores

Players can have scores in multiple leaderboards.

Create leaderboards in the Dashboard first. Define the leaderboard ID, sort order, and reset schedule.

Code Examples

1// Submit a score
2var result = await Ondara.Leaderboards.Submit("high_scores", 5000);
3
4if (result.IsSuccess)
5{
6    Debug.Log($"Score submitted! New rank: #{result.Value.Rank}");
7    Debug.Log($"Is new best: {result.Value.IsNewBest}");
8}
9
10// Submit with metadata (e.g., level, character used)
11await Ondara.Leaderboards.Submit("high_scores", 5000, new Dictionary<string, object>
12{
13    { "level", "world_3" },
14    { "character", "knight" },
15    { "time", 120.5f }
16});

Leaderboard Entry Object

1public class LeaderboardEntry
2{
3    public string PlayerId { get; }      // Unique player identifier
4    public string PlayerName { get; }    // Display name
5    public int Rank { get; }             // Position on leaderboard (1-indexed)
6    public long Score { get; }           // The score value
7    public float Percentile { get; }     // Top X% of all players
8    public DateTime SubmittedAt { get; } // When score was submitted
9    public Dictionary<string, object> Metadata { get; } // Custom data
10}

Best Practices

Validate Scores Server-side
Enable score validation in dashboard settings to prevent cheating.
Use Metadata for Context
Store level, character, or game mode with scores for richer leaderboards.
Show Nearby Rankings
Players engage more when they see beatable scores just above them.
Multiple Time Frames
Daily/weekly resets give new players a chance to compete.

Cloud Save Economy