GKScore Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in iOS 4.1 and later.
Companion guide
Declared in
GKChallenge.h
GKScore.h
Related sample code

Overview

A GKScore class holds information for a score that was earned by the player. Your game creates GKScore objects to post scores to a leaderboard on Game Center. When your game retrieves score information from a leaderboard, those scores are returned as GKScore objects.

To report a score to Game Center, your game allocates and initializes a new object, sets the value property to the score the player earned, and then calls the reportScoreWithCompletionHandler: method. The mechanism your game uses to calculate scores is up to you to design; scores are only compared within your game.

Tasks

Initializing a Score Object

Score Properties

Reporting a New Score

Changing the Default Leaderboard

Issuing a Score Challenge

Initializing Leaderboards with a Score

Properties

context

An integer value used by your game.

@property(nonatomic, assign) uint64_t context
Discussion

The context property is stored and returned to your game, but is otherwise ignored by Game Center. It allows your game to associate an arbitrary 64-bit unsigned integer value with the score data reported to Game Center. You decide how this integer value is interpreted by your game. For example, you might use the context property to store flags that provide game-specific details about a player’s score, or you might use the context as a key to other data stored on the device or on your own server. The context is most useful when your game displays a custom leaderboard user interface.

Availability
  • Available in iOS 5.0 and later.
Declared In
GKScore.h

date

The date and time when the score was earned. (read-only)

@property(readonly, retain, nonatomic) NSDate *date
Discussion

When you initialize the new score object, the date property is automatically set to the current date and time.

Availability
  • Available in iOS 4.0 and later.
Declared In
GKScore.h

formattedValue

Returns the player’s score as a localized string. (read-only)

@property(readonly, copy, nonatomic) NSString *formattedValue
Discussion

This property is invalid on a newly initialized score object. On a score returned from Game Kit, it contains a formatted string based on the player’s score. You determine how a score is formatted when you define the leaderboard on iTunes Connect.

Never convert the value property into a string directly; always use this method to receive the formatted string.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
GKScore.h

leaderboardIdentifier

The identifier for the leaderboard.

@property(copy, nonatomic) NSString *leaderboardIdentifier
Availability
  • Available in iOS 7.0 and later.
Declared In
GKScore.h

playerID

The player identifier for the player that earned the score. (read-only)

@property(readonly, retain, nonatomic) NSString *playerID
Discussion

When you initialize a new score object, the playerID property is set to the identifier for the local player. If the score object was returned to your game by loading scores from Game Center, the playerID property identifies the player who recorded that score.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKScore.h

rank

The position of the score in the results of a leaderboard search. (read-only)

@property(readonly, assign, nonatomic) NSInteger rank
Discussion

The value of this property is only valid on score objects returned from Game Center. The rank property represents the position of the score in the returned results, with 1 being the best score, 2 being the second best, and so on.

Availability
  • Available in iOS 4.0 and later.
Declared In
GKScore.h

shouldSetDefaultLeaderboard

A Boolean value that indicates whether this score should also update the default leaderboard.

@property(nonatomic, assign) BOOL shouldSetDefaultLeaderboard
Discussion

If the value of this property is YES, when the score is reported to Game Center, Game Center also updates the local player’s default leaderboard to match the value stored in the category property of the score object. This matches the behavior of the GKLeaderboard class’s setDefaultLeaderboard:withCompletionHandler: class method. If the value of this property is NO, the default leaderboard is not changed by reporting the score. The default value of this property is NO.

Availability
  • Available in iOS 5.0 and later.
Declared In
GKScore.h

value

The score earned by the player.

@property(assign, nonatomic) int64_t value
Discussion

You can use any algorithm you want to calculate scores in your game. Your game must set the value property before reporting a score, otherwise an error is returned.

The value provided by a score object is interpreted by Game Center only when formatted for display. You determine how your scores are formatted when you define the leaderboard on iTunes Connect.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
GKScore.h

Class Methods

reportScores:withCompletionHandler:

Reports a list of scores to Game Center

+ (void)reportScores:(NSArray *)scores withCompletionHandler:(void (^)(NSError *error))completionHandler
Parameters
scores

An array of GKScore objects that contains the scores to report to Game Center.

completionHandler

A block to be called after the score is reported.

The block receives the following parameter:

error

If an error occurred, this parameter holds an error object that describes the problem. If the score was successfully reported, this parameter’s value is nil.

Discussion

Use this class method whenever you need to submit multiple scores at the same time. Calling this method reports each of the scores, exactly as if you called the reportScoreWithCompletionHandler: method on each score object in the array. However, the entire operation can typically be processed more efficiently using this method, and the completion handler is only called once.

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.

Availability
  • Available in iOS 6.0 and later.
Declared In
GKScore.h

reportScores:withEligibleChallenges:withCompletionHandler:

Submit a list of scores and all eligible challenges.

+ (void)reportScores:(NSArray *)scores withEligibleChallenges:(NSArray *)challenges withCompletionHandler:(void (^)(NSError *error))completionHandler
Parameters
scores

An array of GKScore objects that contains all of the scores to be reported.

challenges

An array of GKChallenge objects that represents all challenges associated with the reported scores. If an error occurred, this parameter may be non-nil, in which case the array holds whatever challenge information Game Kit was able to fetch.

completionHandler

A block to be called when the download is completed.

The block receives the following parameter:

error

If an error occurred, this object describes the error. If the operation completed successfully, this 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.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKChallenge.h

Instance Methods

challengeComposeControllerWithPlayers:message:completionHandler:

Provides a challenge compose view controller with pre-selected player identifiers and a preformatted, player-editable message.

- (UIViewController *)challengeComposeControllerWithPlayers:(NSArray *)playerIDs message:(NSString *)message completionHandler:(GKChallengeComposeCompletionBlock)completionHandler
Parameters
playerIDs

An array of NSString objects that contains the player identifiers that the challenge is to be sent to.

message

The preformatted, player-editable message that is being sent to other players.

completionHandler

A block to be called after the view controller has been displayed. Contains the reason the handler was called and all player identifiers that the challenge was sent to.

Return Value

A UIVewController view containing the player identifiers and a player-editable message.

Discussion

The view controller returned is presented modally from the top view controller. After the view controller is displayed and the player sends or cancels the challenge, the completion handler block is called.

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.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKChallenge.h

initWithLeaderboardIdentifier:

Returns an initialized score object using the local player and the current date.

- (id)initWithLeaderboardIdentifier:(NSString *)identifier
Parameters
initializer

Identifies the leaderboard that the score is being sent to.

Return Value

An initialized score object, or nil if an error occurred.

Discussion

Your game explicitly allocates and initializes a score object using the current player and date when it needs to report a new score to Game Center.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKScore.h

initWithLeaderboardIdentifier:forPlayer:

Returns an initialized score object for the specified leaderboard and player.

- (id)initWithLeaderboardIdentifier:(NSString *)identifier forPlayer:(NSString *)playerID
Parameters
identifier

Identifies the leaderboard that the score is being sent to.

playerID

The identifier of the player who’s score is being initialized.

Return Value

An initialized score object, or nil if an error occurred.

Discussion

Your game explicitly allocates and initializes a score object using the designated player and current date when it needs to report a new score to Game Center.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKScore.h