An object used to read data from a leaderboard stored on Game Center.
- iOS 4.1+
- macOS 10.8+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 3.0+
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
load 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
load 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:
categoryproperty allows you to choose which leaderboard in App Store Connect is searched.
playerproperty 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.
timeproperty allows you to filter based on when the score was earned.
rangeproperty 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:
Start with the set of all possible scores.
Discard any scores that do not match the
For each player, keep the best score that player has earned and discard the rest.
Sort the scores from best to worst.
Use the range property to determine which scores are returned.