Class

GKLeaderboard

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

Declaration

@interface GKLeaderboard : NSObject

Overview

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.

Topics

Initialization

- 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

playerScope

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

GKLeaderboardPlayerScope

The scope of players to be searched for scores.

range

The numerical score rankings to return from the search.

timeScope

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

GKLeaderboardTimeScope

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

identifier

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.

loading

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

title

The localized title for the leaderboard.

scores

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

localPlayerScore

The score earned by the local player.

maxRange

The size of the leaderboard.

Retrieving Group Information

groupIdentifier

The identifier for the group the leaderboard is part of.

Deprecated Methods and Properties

category

The named leaderboard to retrieve information from.

Deprecated
+ setDefaultLeaderboard:withCompletionHandler:

Sets the default leaderboard for the local player.

Deprecated
- initWithPlayerIDs:

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

Deprecated
+ loadCategoriesWithCompletionHandler:

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

Deprecated

Relationships

Inherits From

See Also

Leaderboards

GKLeaderboardSet

An object that organizes leaderboards into logical and coherent groups.

GKScore

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