MultiConnectMultiConnectDocs Website home
MultiConnectSDK › SDK Apps

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: