GKScore Class Reference

Inherits from
NSObject
Conforms to
NSCoding
NSObject (NSObject)
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in iOS 4.1 and later.
Companion guide
Game Center Programming 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

Properties

category

The leaderboard that this score belongs to.

@property(nonatomic, retain) NSString *category
Discussion

The category string must match an identifier for a leaderboard you created on iTunes Connect.

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

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(nonatomic, readonly, retain) 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.1 and later.
Declared In
GKScore.h

formattedValue

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

@property(nonatomic, readonly, retain) 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.1 and later.
See Also
Related Sample Code
Declared In
GKScore.h

playerID

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

@property(nonatomic, readonly, retain) 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(nonatomic, readonly, assign) 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.1 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(nonatomic, assign) 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.1 and later.
See Also
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 score objects 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.

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

Instance Methods

initWithCategory:

Returns an initialized score object.

- (id)initWithCategory:(NSString *)category
Parameters
category

An identifier for a specific leaderboard you’ve configured on iTunes Connect. Must not be nil.

Return Value

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

Discussion

Your game explicitly allocates and initializes a score object when it needs to report a new score to Game Center.

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

issueChallengeToPlayers:message:

Issues a score challenge to a set of players.

- (void)issueChallengeToPlayers:(NSArray *)playerIDs message:(NSString *)message
Parameters
playerIDs

An array of player identifiers for the players to challenge.

message

A text message to display to the players.

Discussion

Your game should only issue a challenge request in direct response to a player action. That is, your game should provide a user interface that allows the player to choose to issue a challenge, and only issue a challenge when the player wishes to do so.

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

reportScoreWithCompletionHandler:

Reports a score to Game Center.

- (void)reportScoreWithCompletionHandler:(void (^)(NSError *error))completionHandler
Parameters
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

The value property must be set before calling this method.

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.

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


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...