Interface ILeaderboardService

Service interface for submitting scores to and querying leaderboards.

Namespace: Serenity.Leaderboard.Application.Interfaces

Assembly: Serenity.Leaderboard.Application.dll

Syntax

public interface ILeaderboardService : IService, IFoundationSettings

Remarks

Operations on an unregistered board never throw: they log a warning and return an empty/no-op result, matching the framework's never-throw-in-runtime philosophy.

Methods

ClearAsync(BoardId, CancellationToken)

Clears every entry from a board.

Declaration

Task ClearAsync(BoardId board, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
BoardId	board	The board to clear.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task

GetAroundPlayerAsync(BoardId, PlayerId, int, CancellationToken)

Gets the entries surrounding a player's position on a board.

Declaration

Task<LeaderboardPage> GetAroundPlayerAsync(BoardId board, PlayerId player, int radius, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
BoardId	board	The board to query.
PlayerId	player	The player to center the window on.
int	radius	The number of entries to include on each side of the player.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<LeaderboardPage>	A page containing the windowed entries.

GetPlayerRankAsync(BoardId, PlayerId, CancellationToken)

Gets a player's ranked entry on a board.

Declaration

Task<RankedEntry?> GetPlayerRankAsync(BoardId board, PlayerId player, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
BoardId	board	The board to query.
PlayerId	player	The player to look up.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<RankedEntry?>	The player's ranked entry, or null when the player has no entry on the board.

GetTopAsync(BoardId, int, LeaderboardRankingMode, CancellationToken)

Gets the top-ranked entries for a board.

Declaration

Task<LeaderboardPage> GetTopAsync(BoardId board, int count, LeaderboardRankingMode rankingMode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
BoardId	board	The board to query.
int	count	The maximum number of entries to return.
LeaderboardRankingMode	rankingMode	BestPerPlayer collapses the result to one row per player, ranked by their best entry (matches the three-argument overload). AllEntries returns every stored row as its own ranked entry — a player may occupy more than one rank.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<LeaderboardPage>	A page containing the top-ranked entries.

GetTopAsync(BoardId, int, CancellationToken)

Gets the top-ranked entries for a board, ranked over each player's best entry.

Declaration

Task<LeaderboardPage> GetTopAsync(BoardId board, int count, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
BoardId	board	The board to query.
int	count	The maximum number of entries to return.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<LeaderboardPage>	A page containing the top-ranked entries.

SubmitAsync(LeaderboardSubmission, CancellationToken)

Submits a score to the leaderboard identified by the submission's board.

Declaration

Task SubmitAsync(LeaderboardSubmission submission, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
LeaderboardSubmission	submission	The submission data.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task