> For the complete documentation index, see [llms.txt](https://assetstore.essentialkit.voxelbusters.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://assetstore.essentialkit.voxelbusters.com/features/game-services/playmaker/use-cases/use-case-4-leaderboard-load-scores.md).

# Leaderboard Load Scores (Top / Player Centered)

## Goal

Load leaderboard scores and iterate cached entries to build a custom leaderboard UI.

## Prerequisite

Make sure the player is authenticated first. Use `use-case-1-auth-bootstrap.md`.

## Actions used

* `GameServicesCreateLeaderboard` (cache a leaderboard handle)
* `GameServicesConfigureLeaderboard` (scope/time/query size)
* `GameServicesLeaderboardLoadTopScores` or `GameServicesLeaderboardLoadPlayerCenteredScores`
* `GameServicesGetLeaderboardLoadScoresSuccessResult` (on success; gives `scoreCount`)
* `GameServicesGetLeaderboardLoadScoresError` (on failure)
* `GameServicesGetLeaderboardScoreInfo` (iterate entries)
* (Optional paging) `GameServicesLeaderboardLoadNextPage`, `GameServicesLeaderboardLoadPreviousPage`

## Variables

* `leaderboardId` (String) e.g. `"top_scores"`
* `scoreCount` (Int), `scoreIndex` (Int)
* Per entry: `playerDisplayName` (String), `rank` (Int), `scoreValue` (Int), `formattedScore` (String)

## Flow

1. State: `CreateLeaderboard`
   * Action: `GameServicesCreateLeaderboard` (input: `leaderboardId`)
2. State: `ConfigureLeaderboard` (optional)
   * Action: `GameServicesConfigureLeaderboard`
   * Inputs: `playerScope`, `timeScope`, `querySize`
3. State: `LoadScores`
   * Action: `GameServicesLeaderboardLoadTopScores` (or `...LoadPlayerCenteredScores`)
   * Events:
     * `successEvent` → `GetScoresMetadata`
     * `failureEvent` → `GetLeaderboardLoadScoresError`
4. State: `GetScoresMetadata`
   * Action: `GameServicesGetLeaderboardLoadScoresSuccessResult` → `scoreCount`
   * Set `scoreIndex = 0`
5. Loop:
   * While `scoreIndex < scoreCount`:
     * Action: `GameServicesGetLeaderboardScoreInfo` (input: `scoreIndex`)
     * Add entry to UI
     * `scoreIndex++`

## Notes

* Use paging actions when `scoreCount` is at your `querySize` and you want more results.
* To show native UI instead of building your own, use `GameServicesShowLeaderboardsUI` / `GameServicesShowLeaderboardUI`.