An object used to read data from a leaderboard stored on Game Center.


@interface GKLeaderboard : NSObject


Your game uses GKLeaderboard objects when it wants to retrieve localized information about a specific leaderboard or to retrieve scores from a leaderboard. Typically, you do this when you want the data needed to implement your own custom leaderboard user interface.

During the development process, you create the leaderboards for your game on App Store Connect.

To retrieve information about the available leaderboards, use the loadLeaderboardsWithCompletionHandler: class method.

To request score data from Game Center, your game allocates and initializes a GKLeaderboard object, configures its search properties, and then calls the object’s loadScoresWithCompletionHandler: method. GameKit retrieves the score data from Game Center and calls your completion handler.

The search properties are used to filter the score data returned to your game:

  • The category property allows you to choose which leaderboard in App Store Connect is searched.

  • The playerScope property allows you to restrict the search to a local player’s friends. Optionally, you can also explicitly initialize a leaderboard object to search for scores for a specific group of players.

  • The timeScope property allows you to filter based on when the score was earned.

  • The range property allows you to pick scores within a specific range. For example, the range [1,10] returns the best ten scores.

The algorithm used by the GKLeaderboard object is as follows:

  1. Start with the set of all possible scores.

  2. Discard any scores that do not match the playerScope, timeScope and category properties.

  3. For each player, keep the best score that player has earned and discard the rest.

  4. Sort the scores from best to worst.

  5. Use the range property to determine which scores are returned.



- init

Initializes a default leaderboard request.

- initWithPlayers:

Initializes a leaderboard request to retrieve the scores of a specific group of players.

Determining the Available Leaderboards to Display

+ loadLeaderboardsWithCompletionHandler:

Loads the list of leaderboards from Game Center

Customizing the Leaderboard Request


A filter used to restrict the search to a subset of the players on Game Center.


The scope of players to be searched for scores.


The numerical score rankings to return from the search.


A filter used to restrict the search to scores that were posted within a specific period of time.


The period of time to which a player’s best score is restricted.


The named leaderboard to retrieve information from.

- loadImageWithCompletionHandler:

The image associated with the default leaderboard.

Retrieving High Scores

- loadScoresWithCompletionHandler:

Retrieves a set of scores from Game Center.


A Boolean value that indicates whether the leaderboard object is retrieving scores.


The localized title for the leaderboard.


An array of GKScore objects that contains the scores returned by the search.


The score earned by the local player.


The size of the leaderboard.

Retrieving Group Information


The identifier for the group the leaderboard is part of.

Deprecated Methods and Properties


The named leaderboard to retrieve information from.

+ setDefaultLeaderboard:withCompletionHandler:

Sets the default leaderboard for the local player.

- initWithPlayerIDs:

Initializes a leaderboard request to retrieve the scores of a specific group of players.

+ loadCategoriesWithCompletionHandler:

Loads the list of leaderboard categories along with their corresponding localized titles.



Inherits From

See Also



An object that organizes leaderboards into logical and coherent groups.


An object containing information for a score that was earned by the player.