Leaderboards

A leaderboard ranks players on a numeric stat — high score, fastest time, season points. In Flock, leaderboards are config-driven: you point one at a field your game already writes through player data, and Flock keeps the standings from there. There’s no separate score-submission call.

Scope: leaderboards are defined per game; each entry belongs to a player.

Dashboard
Unity
Unreal

Create and manage leaderboards under Player Management → Leaderboards. A leaderboard is defined by:

Source — the player template and numeric field to rank on.
Direction — whether higher or lower values rank better (points vs. lap times).
Aggregation — keep each player’s best value, their latest, or the running sum.
Value type — integer, float, or duration.
Window — all-time, weekly, or seasonal. Seasonal boards follow the seasons you define alongside them, each with a start and end date.
Scope — one global board, or per-country standings.

From the same page you can maintain a live board: exclude a player (and lift the exclusion later), reset a board, or backfill it from the player data your game has already written.

A leaderboard’s structural definition — its source and how it ranks — is locked once the board is live. To rank something else, create a new leaderboard.

Scores flow in automatically: when your game writes the configured field through player data, the relevant leaderboards pick the change up — best, latest, or sum, per your aggregation. If you already track the stat, there’s nothing new to send.Boards are addressed by name — the same name you gave the board on the dashboard.

using Flock;
using Flock.Models;
using UnityEngine;

// Top of the board.
Standings top = await FlockClient.Instance.Leaderboard.GetStandingsAsync("weekly_score", limit: 20);
foreach (StandingEntry entry in top.Items)
    Debug.Log($"#{entry.Rank} {entry.PlayerName} — {entry.Score}");

// The signed-in player's own rank, and the players on either side of them.
PlayerRank mine = await FlockClient.Instance.Leaderboard.GetMyRankAsync("weekly_score");
Standings neighbours = await FlockClient.Instance.Leaderboard.GetAroundMeAsync("weekly_score", neighbours: 5);

GetByNameAsync returns the board’s configuration — value type, direction, aggregation, window type and scope — when you need to format scores or label the UI correctly.Windows. Every read defaults to the board’s live window. Pass FlockLeaderboardWindow.Season("season-id") for a finished season, or FlockLeaderboardWindow.Period("2026-W31") for one specific weekly period. Per-country boards take a country argument on the same calls.Sign-in. GetStandingsAsync and GetByNameAsync work signed out — standings are public. GetMyRankAsync and GetAroundMeAsync need a signed-in player and throw without one.PlayerRank.Rank and .Score are nullable: they come back null when the player has no entry on that board yet, which is not an error.Refused scores. A board can turn a score away even though the write succeeded. The write’s answer lists those boards in LeaderboardRefusals, each with its LeaderboardName, a Reason (LeaderboardRefusalReasons.ScoreBounds: outside what the board accepts; GainLimit: the player’s recent gains fill its allowance), Retryable and RetryAfterSeconds. Only UpdatePlayerDataAsync and UpdatePlayerDataFieldAsync report them, so an empty list elsewhere means “not reported here”, not “accepted”.progressId is the Id of the player-data record that holds the score.

using Flock;
using Flock.Models;
using UnityEngine;

// The board's settings say how to write its scores; FormatScore shows a duration board as a clock.
Leaderboard board = await FlockClient.Instance.Leaderboard.GetByNameAsync("weekly_score");
PlayerRank mine = await FlockClient.Instance.Leaderboard.GetMyRankAsync("weekly_score");
if (mine.Rank.HasValue)   // null: no entry on this board yet
    Debug.Log($"#{mine.Rank} with {board.FormatScore(mine.Score)}");

// A write's answer lists the boards that turned its score away.
PlayerData saved = await FlockClient.Instance.Commands.UpdatePlayerDataFieldAsync(progressId, "score", 1200);
foreach (LeaderboardRefusal refusal in saved.LeaderboardRefusals)
    Debug.Log($"{refusal.LeaderboardName} refused the score: {refusal.Reason}");

#include "FlockSubsystem.h"

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);
FFlockLeaderboardProvider* Boards = Sdk->GetLeaderboardProvider();

// Top of the board.
Boards->GetStandings(TEXT("weekly_score"),
    [](TFlockResult<FFlockStandings> Top)
    {
        for (const FFlockStandingEntry& Entry : Top.Value.Items)
        {
            UE_LOG(LogTemp, Log, TEXT("#%d %s"), Entry.Rank, *Entry.PlayerName);
        }
    });

// The signed-in player's own rank, and the players on either side of them.
Boards->GetMyRank(TEXT("weekly_score"), [](TFlockResult<FFlockPlayerRank> Mine) {});
Boards->GetAroundMe(TEXT("weekly_score"), [](TFlockResult<FFlockStandings> Neighbours) {});

GetByName returns the board’s configuration — value type, direction, aggregation, window type and scope — when you need to format scores or label the UI correctly. Its FormatScore renders a duration board as a clock rather than raw seconds.

// The board's settings say how to write its scores; the rank says where the player stands.
const TWeakObjectPtr<UFlockSubsystem> Flock = Sdk;
Sdk->GetLeaderboardProvider()->GetByName(TEXT("weekly_score"), [Flock](TFlockResult<FFlockLeaderboard> Board)
{
    if (!Board.bSuccess || !Flock.IsValid())
    {
        return;
    }
    Flock->GetLeaderboardProvider()->GetMyRank(TEXT("weekly_score"),
        [Leaderboard = Board.Value](TFlockResult<FFlockPlayerRank> Mine)
        {
            if (Mine.bSuccess && Mine.Value.Ranked)   // false: no entry on this board yet
            {
                UE_LOG(LogTemp, Display, TEXT("#%d with %s"), Mine.Value.Rank, *Leaderboard.FormatScore(Mine.Value.Score));
            }
        });
});

A Show My Rank custom event, Flock Get My Rank for weekly_high_score, a Branch on Ranked, then Format Score into Print String — Show the player's own rank, once they have one on the board.

In Blueprint the same calls are Flock Get Leaderboard, Flock Get Leaderboard Standings, Flock Get My Rank and Flock Get Standings Around Me, under Flock | Leaderboard.Windows. Every read defaults to the board’s live window. Pass FFlockLeaderboardWindow::Season("season-id") for a finished season, or FFlockLeaderboardWindow::Period("2026-W31") for one specific weekly period. Per-country boards take a country argument on the same calls.Sign-in. GetStandings and GetByName work signed out — standings are public. GetMyRank and GetAroundMe need a signed-in player and fail without one.FFlockPlayerRank carries a Ranked flag: it is false when the player has no entry on that board yet, which is a valid result rather than an error. Check it before reading Rank or Score.Refused scores. A board can turn a score away even though the write succeeded. The write’s answer lists those boards in LeaderboardRefusals, each with its LeaderboardName, a Reason (score_bounds: outside what the board accepts; gain_limit: the player’s recent gains fill its allowance; compare with the Flock Refusal Reason nodes or FlockLeaderboardRefusalReasons), Retryable and RetryAfterSeconds (-1 when the server gave none). Only Update Player Data and Update Player Data Field report them, so an empty list elsewhere means “not reported here”, not “accepted”.

Pair a seasonal leaderboard with a segment of your top players to reward them when the season closes.

Getting Started

Concepts

Features

Reference