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


class 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 loadLeaderboards(completionHandler:) 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 loadScores(completionHandler:) 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.




Initializes a default leaderboard request.

init(players: [GKPlayer])

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

Determining the Available Leaderboards to Display

Customizing the Leaderboard Request

var playerScope: GKLeaderboard.PlayerScope

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

enum GKLeaderboard.PlayerScope

The scope of players to be searched for scores.

var range: NSRange

The numerical score rankings to return from the search.

var timeScope: GKLeaderboard.TimeScope

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

enum GKLeaderboard.TimeScope

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

var identifier: String?

The named leaderboard to retrieve information from.

func loadImage(completionHandler: ((UIImage?, Error?) -> Void)?)

The image associated with the default leaderboard.

Retrieving High Scores

var isLoading: Bool

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

var title: String?

The localized title for the leaderboard.

var scores: [GKScore]?

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

var localPlayerScore: GKScore?

The score earned by the local player.

var maxRange: Int

The size of the leaderboard.

Retrieving Group Information

var groupIdentifier: String?

The identifier for the group the leaderboard is part of.

Deprecated Methods and Properties

var category: String?

The named leaderboard to retrieve information from.

class func setDefault(String?, withCompletionHandler: ((Error?) -> Void)?)

Sets the default leaderboard for the local player.

init?(playerIDs: [String]?)

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

class func loadCategories(completionHandler: (([String]?, [String]?, Error?) -> Void)?)

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



Inherits From

Conforms To

See Also


class GKLeaderboardSet

An object that organizes leaderboards into logical and coherent groups.

class GKScore

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