Instance Method

loadScores(completionHandler:)

Retrieves a set of scores from Game Center.

Declaration

func loadScores(completionHandler: (([GKScore]?, Error?) -> Void)? = nil)

Parameters

completionHandler

A block to be called after the scores are retrieved from the server.

The block receives the following parameters:

scores

An array of GKScore objects that holds the requested scores. If an error occurred, this value may be non-nil. In this case, the array holds whatever score data could be retrieved from Game Center before the error occurred.

error

If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

Discussion

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

Listing 1 shows an example leaderboard data query. The method for this query initializes a new leaderboard object and configures the playerScope, timeScope, and range properties to grab the top ten scores earned today.

Listing 1

Retrieving the top ten scores

- (void) retrieveTopTenScores
{
    GKLeaderboard *leaderboardRequest = [[GKLeaderboard alloc] init];
    if (leaderboardRequest != nil)
    {
        leaderboardRequest.playerScope = GKLeaderboardPlayerScopeGlobal;
        leaderboardRequest.timeScope = GKLeaderboardTimeScopeToday;
        leaderboardRequest.identifier = @"Combined.LandMaps"
        leaderboardRequest.range = NSMakeRange(1,10);
        [leaderboardRequest loadScoresWithCompletionHandler: ^(NSArray *scores, NSError *error) {
            if (error != nil)
            {
                // Handle the error.
            }
            if (scores != nil)
            {
                // Process the score information.
            }
            }];
    }
}

You can create a leaderboard request that retrieves scores for a specific list of players you are interested in.

Listing 2

Retrieving the top scores for players in a match

- (void) receiveMatchBestScores: (GKMatch*) match
{
    GKLeaderboard *leaderboardRequest = [[GKLeaderboard alloc] initWithPlayers: match.players];
        leaderboardRequest.timeScope = GKLeaderboardTimeScopeAllTime;
        leaderboardRequest.identifier = @"Combined.LandMaps"
        leaderboardRequest.range = NSMakeRange(1,10);
    if (query != nil)
    {
        [query loadScoresWithCompletionHandler: ^(NSArray *scores, NSError *error) {
            if (error != nil)
            {
                // Handle the error.
            }
            if (scores != nil)
            {
                // Process the score information.
            }
        }];
    }
}

You can call this method multiple times; each call represents a different query against the scores stored on Game Center. If you post multiple load operations using the same leaderboard object, any properties that are updated by loading scores reflect the last query that completed. The order that achievement queries are processed is arbitrary.

See Also

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.