loadScores(completionHandler:)
Retrieves a set of scores from Game Center.
Declaration
func loadScores(completionHandler: (([GKScore]?, (any Error)?) -> Void)? = nil)Parameters
- completionHandler:
A block to call after retrieving the scores from the server.
The block receives the following parameters:
- scores
An array of
GKScoreobjects that holds the requested scores. If an error occurs, this value may be non-nil. In this case, the array holds whatever score data GameKit retrieves from Game Center before the error occurs.- error
If an error occurs, this error object describes the error. If the operation completes successfully, the value is
nil.
Discussion
When you call this method, it creates a new background task to handle the request. The method then returns control to your game. When the task completes, GameKit calls your completion handler on the main thread.
The code below 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 retrieve the top ten scores for today.
- (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.
- (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 in Game Center. If you post multiple load operations using the same leaderboard object, any properties that update by loading scores reflect the most recent query that completes. The order that achievement queries process is arbitrary.