8. Leaderboards
Create a board
Open the app on SDK Apps, choose Leaderboards, then New leaderboard.
| Setting | Choices |
|---|---|
| Key | Its name in code, e.g. weekly_wins. Cannot be changed later |
| Name | What players see |
| Sort | Highest first, or Lowest first (times, golf) |
| How scores combine | Best: keep the player's best score. Latest: keep the last score submitted. Sum: add every submit, for wins or points |
| Resets | Never, Daily, Weekly or Monthly, in the board's Time zone. Weekly boards also have Week starts |
| Keep periods | How many finished periods stay readable, so you can pay rewards for last week |
| Let players' devices submit scores | Off by default. See "Scores from the client" below |
Ties are ranked by who reached the score first.
Submit scores from your server
A score usually decides rewards, so it comes from your game server, which saw the match happen. Give each submit a requestId, usually your match id. If a submit is retried after a network error, the same id is counted once, which matters most for Sum boards.
Script 8.1: Server: submit the winner's score
using System;
using System.Threading.Tasks;
using MultiConnect.App;
public static class MatchScores
{
public static async Task SubmitWin(string matchId, string winnerPlayerId)
{
var result = await McAppServer.SubmitScoreAsync("weekly_wins", winnerPlayerId, 1, requestId: matchId + ":win");
if (result.Ok && result.Value != null)
Console.WriteLine($"{winnerPlayerId} now has {result.Value.score} wins, rank {result.Value.rank}");
else
Console.WriteLine("Score not saved: " + result.Message);
}
}
changed in the answer is false when nothing changed, for example when a Best board already held a better score.
Read a board in the game
Reading needs no sign-in. When a player is signed in, me holds their own entry.
| Call | Returns |
|---|---|
McLeaderboards.GetTopAsync(board, limit, offset, periodsAgo) |
The top entries (up to 100 per call; use offset to page) |
McLeaderboards.GetAroundMeAsync(board, range, periodsAgo) |
The signed-in player and range players above and below |
McLeaderboards.GetPlayersAsync(board, playerIds, periodsAgo) |
The given players only, up to 100: friends, a clan, a match |
periodsAgo = 0 is the current day, week or month, 1 the one before, and so on, as far back as Keep periods.
Script 8.2: Show the top 10
using MultiConnect.App;
using UnityEngine;
public class LeaderboardScreen : MonoBehaviour
{
private async void OnEnable()
{
var page = await McLeaderboards.GetTopAsync("weekly_wins", limit: 10);
if (!page.Ok || page.Value == null)
{
Debug.Log("Leaderboard unavailable: " + page.Message);
return;
}
foreach (var entry in page.Value.entries)
Debug.Log($"{entry.rank}. {entry.displayName} {entry.score}");
if (page.Value.me.rank > 0)
Debug.Log($"You: #{page.Value.me.rank} with {page.Value.me.score}");
Debug.Log("Resets at " + page.Value.periodEnd);
}
}
On a server, McAppServer.GetTopAsync, GetAroundAsync(board, playerId, …) and GetPlayersAsync read the same data. For example, a server can read last week's top 10 and send them gifts (section 12).
Scores from the client
For a board where a cheated score costs nothing, you can turn on Let players' devices submit scores. Set Lowest allowed and Highest allowed for a single submit. The client then calls McLeaderboards.SubmitScoreAsync(board, score).
Never open a board that pays rewards: a modified client can send any score inside the limits.
Manage boards
Open a board on the dashboard to:
- see any period;
- search for a player;
- remove an entry;
- clear the current period, with Clear current period.

