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.

// 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”.

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.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

SDKs

Features

Multiplayer

Reference