Interface ILeaderboardTopEntryService

Locator-registered, HUD-bindable read model for a board's top-1 entry. Lets the HUD Builder author a leaderboard "current leader" element entirely through a service chain, with the board id passed as an authored chain argument — no scene component required.

Namespace: Serenity.Leaderboard.Application.Interfaces

Assembly: Serenity.Leaderboard.Application.dll

Syntax

public interface ILeaderboardTopEntryService : IService, IFoundationSettings

Remarks

ILeaderboardService is fully async end-to-end, but a HUD binding only ever reads a synchronous member chain. Every read here is served from an internally refreshed per-board cache, never from a synchronous call into ILeaderboardService. A board that has never been read before returns false and self-primes: the implementation kicks off a background fetch for it, so the HUD shows its authored fallback text until that first fetch lands, then serves the cached result on every subsequent read.

includeLocalPlayerScore lets the local player's live score stand in for the cached top when it STRICTLY beats it per the board's configured sort direction (higher wins under Descending, lower wins under Ascending) — a tie always keeps the existing record holder.

The HUD Builder renders includeLocalPlayerScore as a checkbox, so it always writes an explicit true/false — but a hand-edited binding asset with an empty bool argument still fails chain resolution at build time, per HudArgumentParser's unchanged contract.

Methods

TryGetDisplayText(BoardId, LeaderboardFieldSelection, string, bool, out string)

Attempts to render a board's effective top entry into a single display string. See TryGetTopValue(BoardId, bool, out float) for the caching and overlay contract.

Declaration

bool TryGetDisplayText(BoardId board, LeaderboardFieldSelection fields, string separator, bool includeLocalPlayerScore, out string text)

Parameters

Type	Name	Description
BoardId	board	The board to read. A board read for the first time self-primes and returns false.
LeaderboardFieldSelection	fields	The fields to render, in authored order. An invalid selection fails the call.
string	separator	The text inserted between rendered fields. Null or empty falls back to a single space.
bool	includeLocalPlayerScore	Whether the local player's live score may overlay the cached top.
string	text	The composed text, or empty when composition fails or no value is available yet.

Returns

Type	Description
bool	true when an effective top entry is available and composition succeeds; otherwise false.

TryGetTopDisplayName(BoardId, bool, out string)

Attempts to read a board's effective top entry's display name. See TryGetTopValue(BoardId, bool, out float) for the caching and overlay contract.

Declaration

bool TryGetTopDisplayName(BoardId board, bool includeLocalPlayerScore, out string displayName)

Parameters

Type	Name	Description
BoardId	board	The board to read. A board read for the first time self-primes and returns false.
bool	includeLocalPlayerScore	Whether the local player's live score may overlay the cached top.
string	displayName	The effective top entry's display name, or empty when no value is available yet.

Returns

Type	Description
bool	true when an effective top entry is available; otherwise false.

TryGetTopValue(BoardId, bool, out float)

Attempts to read a board's effective top value: the cached leaderboard top, or the local player's live score when includeLocalPlayerScore is on and it strictly beats the cached top.

Declaration

bool TryGetTopValue(BoardId board, bool includeLocalPlayerScore, out float value)

Parameters

Type	Name	Description
BoardId	board	The board to read. A board read for the first time self-primes and returns false.
bool	includeLocalPlayerScore	Whether the local player's live score may overlay the cached top.
float	value	The effective top value, or 0 when no value is available yet.

Returns

Type	Description
bool	true when an effective top entry is available; otherwise false.