iOS Developer Library

Developer

GameKit Framework Reference GKScore Class Reference

Options
Deployment Target:

On This Page
Language:

GKScore

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. More...

Inheritance


Import Statement


import GameKit @import GameKit;

Availability


Available in iOS 4.1 and later.
  • context context Property

    An integer value used by your game.

    Declaration

    Swift

    var context: UInt64

    Objective-C

    @property(assign, nonatomic) 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.

    Import Statement

    import GameKit

    Availability

    Available in iOS 5.0 and later.

  • date date Property

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

    Declaration

    Swift

    var date: NSDate! { get }

    Objective-C

    @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.

    Import Statement

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var formattedValue: String! { get }

    Objective-C

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

    Discussion

    This property is invalid on a newly initialized score object. On a score returned from GameKit, 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.

    Import Statement

    import GameKit

    Availability

    Available in iOS 4.0 and later.

    See Also

    value

  • player player Property

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

    Declaration

    Swift

    var player: GKPlayer! { get }

    Objective-C

    @property(readonly, retain, nonatomic) GKPlayer *player

    Discussion

    When you initialize a new score object, the player 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 player property identifies the player who recorded that score.

    Import Statement

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • rank rank Property

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

    Declaration

    Swift

    var rank: Int { get }

    Objective-C

    @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.

    Import Statement

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • value value Property

    The score earned by the player.

    Declaration

    Swift

    var value: Int64

    Objective-C

    @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.

    Import Statement

    import GameKit

    Availability

    Available in iOS 4.0 and later.

    See Also

    formattedValue

  • Reports a list of scores to Game Center

    Declaration

    Swift

    class func reportScores(_ scores: [AnyObject]!, withCompletionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    + (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, GameKit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    import GameKit

    Availability

    Available in iOS 6.0 and later.

  • Submit a list of scores and all eligible challenges.

    Declaration

    Swift

    class func reportScores(_ scores: [AnyObject]!, withEligibleChallenges challenges: [AnyObject]!, withCompletionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    + (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 GameKit 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, GameKit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    import GameKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var shouldSetDefaultLeaderboard: Bool

    Objective-C

    @property(nonatomic, assign) BOOL shouldSetDefaultLeaderboard

    Discussion

    If the value of this property is YEStrue, 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 NOfalse, the default leaderboard is not changed by reporting the score. The default value of this property is NOfalse.

    Import Statement

    import GameKit

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func challengeComposeControllerWithMessage(_ message: String!, players players: [AnyObject]!, completionHandler completionHandler: GKChallengeComposeCompletionBlock!) -> UIViewController!

    Objective-C

    - (UIViewController *)challengeComposeControllerWithMessage:(NSString *)message players:(NSArray *)players completionHandler:(GKChallengeComposeCompletionBlock)completionHandler

    Parameters

    message

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

    players

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

    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 UIViewController 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, GameKit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    import GameKit

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    init!(leaderboardIdentifier initializer: String!)

    Objective-C

    - (instancetype)initWithLeaderboardIdentifier:(NSString *)initializer

    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.

    Import Statement

    import GameKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    init!(leaderboardIdentifier identifier: String!, player player: GKPlayer!)

    Objective-C

    - (instancetype)initWithLeaderboardIdentifier:(NSString *)identifier player:(GKPlayer *)player

    Parameters

    identifier

    Identifies the leaderboard that the score is being sent to.

    player

    The GKPlayer object identifying 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.

    Import Statement

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • The identifier for the leaderboard.

    Declaration

    Swift

    var leaderboardIdentifier: String!

    Objective-C

    @property(copy, nonatomic) NSString *leaderboardIdentifier

    Import Statement

    import GameKit

    Availability

    Available in iOS 7.0 and later.

  • category category (iOS 7.0) Property

    The leaderboard that this score belongs to.

    Declaration

    Objective-C

    @property(copy, nonatomic) NSString *category

    Discussion

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

    Import Statement

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 7.0.

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

    Declaration

    Swift

    func challengeComposeControllerWithPlayers(_ playerIDs: [AnyObject]!, message message: String!, completionHandler completionHandler: GKChallengeComposeCompletionBlock!) -> UIViewController!

    Objective-C

    - (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 UIViewController 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, GameKit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    import GameKit

    Availability

    Available in iOS 7.0 and later.

    Deprecated in iOS 8.0.

  • Returns an initialized score object.

    Declaration

    Objective-C

    - (instancetype)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.

    Import Statement

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 7.0.

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

    Declaration

    Swift

    init!(leaderboardIdentifier identifier: String!, forPlayer playerID: String!)

    Objective-C

    - (instancetype)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.

    Import Statement

    import GameKit

    Availability

    Available in iOS 7.0 and later.

    Deprecated in iOS 8.0.

  • Issues a score challenge to a set of players.

    Declaration

    Objective-C

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

    Parameters

    playerIDs

    An array of NSString objects that contains the 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 choose which friends will receive the challenge, and only issue a challenge when the player wishes to do so.

    Import Statement

    Availability

    Available in iOS 6.0 and later.

    Deprecated in iOS 7.0.

  • playerID playerID (iOS 8.0) Property

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

    Declaration

    Swift

    var playerID: String! { get }

    Objective-C

    @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.

    Import Statement

    import GameKit

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 8.0.

  • Reports a score to Game Center.

    Declaration

    Objective-C

    - (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, GameKit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 7.0.