Class: GKLeaderboard
Overview
A GKLeaderboard object is used to read data from a leaderboard stored on Game Center. 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.
Instance Attribute Summary (collapse)
-
- category
The named leaderboard to retrieve information from.
-
- groupIdentifier
The identifier for the group the leaderboard is part of.
-
- loading
readonly
A Boolean value that indicates whether the leaderboard object is retrieving scores.
-
- localPlayerScore
readonly
The score earned by the local player.
-
- maxRange
readonly
The size of the leaderboard.
-
- playerScope
A filter used to restrict the search to a subset of the players on Game Center.
-
- range
The numerical score rankings to return from the search.
-
- scores
readonly
The list of scores returned by the search.
-
- timeScope
A filter used to restrict the search to scores that were posted within a specific period of time.
-
- title
readonly
The localized title for the leaderboard.
Class Method Summary (collapse)
-
+ loadLeaderboardsWithCompletionHandler:
Loads the list of leaderboards from Game Center Use this class method to retrieve the list of leaderboards you configured on iTunes Connect.
-
+ setDefaultLeaderboard:withCompletionHandler:
Sets the default leaderboard for the local player.
Instance Method Summary (collapse)
-
- init
Initializes a default leaderboard request.
-
- initWithPlayerIDs:
Initializes a leaderboard request to retrieve the scores of a specific group of players.
-
- loadScoresWithCompletionHandler:
Retrieves a set of scores from Game Center.
Methods inherited from NSObject
#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version
Constructor Details
This class inherits a constructor from NSObject
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class NSObject
Instance Attribute Details
- (String) category
The named leaderboard to retrieve information from. If non-nil, Game Center only returns scores from the matching leaderboard. If nil, all scores previously reported by the game are searched. Default is nil.
- (String) groupIdentifier
The identifier for the group the leaderboard is part of. If your game was configured to be part of a group in iTunes Connect, this property holds the identifier you assigned to the group.
- (Boolean) loading (readonly)
A Boolean value that indicates whether the leaderboard object is retrieving scores. (read-only) The value of the loading property is YES if the leaderboard object has any pending requests for scores.
- (GKScore) localPlayerScore (readonly)
The score earned by the local player. (read-only) This property is invalid until a call to loadScoresWithCompletionHandler: is completed. Afterward, it contains a score object representing the local player’s score on the leaderboard given the filters you applied to the query.
- (Integer) maxRange (readonly)
The size of the leaderboard. (read-only) This property is invalid until a call to loadScoresWithCompletionHandler: is completed. Afterward, it contains the total number of entries available to return to your game given the filters you applied to the query.
- (GKLeaderboardPlayerScope) playerScope
A filter used to restrict the search to a subset of the players on Game Center. The playerScope property is ignored if the leaderboard request was initialized using the initWithPlayerIDs: method. Otherwise, the playerScope property determines which players are included in the request for high scores. The default is GKLeaderboardPlayerScopeGlobal. See Leaderboard Player Scope for more information.
- (NSRange) range
The numerical score rankings to return from the search. The range property is ignored if the leaderboard request was initialized using the initWithPlayerIDs: method. Otherwise, the range property is used to filter which scores are returned to your game. For example, if you specified a range of [1,10], after the search is complete, your game receives the best ten scores. The default range is [1,25].The minimum index is 1. The maximum length is 100.
- (Array) scores (readonly)
The list of scores returned by the search. (read-only) This property is invalid until a call to loadScoresWithCompletionHandler: is complete. Afterward, it contains the same score objects that were returned to the completion handler.
- (GKLeaderboardTimeScope) timeScope
A filter used to restrict the search to scores that were posted within a specific period of time. This property determines how far back in time to look for scores. The default value is GKLeaderboardTimeScopeAllTime. See Leaderboard Time Scope for more information.
- (String) title (readonly)
The localized title for the leaderboard. (read-only) If you initialized a new leaderboard object, this property is invalid until a call to loadScoresWithCompletionHandler: is complete. Afterward, it contains the localized title for the leaderboard identified by the category property.
Class Method Details
+ (Object) loadLeaderboardsWithCompletionHandler(completionHandler)
Loads the list of leaderboards from Game Center Use this class method to retrieve the list of leaderboards you configured on iTunes Connect. Use the properties of each leaderboard object, especially the category and title properties, to learn more about the leaderboard.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. Keep in mind that the completion handler may be called on a thread other than the one originally used to invoke the method. This means that the code in your block needs to be thread-safe.
+ (Object) setDefaultLeaderboard(categoryID, withCompletionHandler:completionHandler)
Sets the default leaderboard for the local player. The default leaderboard is used whenever your game uses a GKScore object to report a score to Game Center without explicitly setting the score object’s category property. The default leaderboard is normally set in iTunes Connect. However, your game can use this class method to override the default leaderboard that appears for the local player. This information is stored for each player on Game Center.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. Keep in mind that the completion handler may be called on a thread other than the one originally used to invoke the method. This means that the code in your block needs to be thread-safe.If an error occurs and was a network error, your game should periodically resend the request until it completes.
Instance Method Details
- (Object) init
Initializes a default leaderboard request. A leaderboard object initialized with this method uses the playerScope, timeScope, and range properties to search Game Center for scores.
- (Object) initWithPlayerIDs(playerIDs)
Initializes a leaderboard request to retrieve the scores of a specific group of players. A leaderboard object initialized with this method ignores the playerScope and range properties. Instead, it retrieves scores for the specific list of players whose identifiers are included in the playerIDs parameter.
- (Object) loadScoresWithCompletionHandler(completionHandler)
Retrieves a set of scores from Game Center. 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. Keep in mind that the completion handler may be called on a thread other than the one originally used to invoke the method. This means that the code in your block needs to be thread-safe.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.