Class

GKScore

An object containing information for a score that was earned by the player.

Declaration

class GKScore : NSObject

Overview

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.

Scores and leaderboards work together to help you create a better game. Whenever a new GKScore object is created, it is associated with a leaderboard. You must ensure that the score being sent to a leaderboard is compatible with the leaderboard scoring format set in App Store Connect. See Leaderboards and Leaderboard Sets for information on how to create a leaderboard in App Store Connect.

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 report(completionHandler:) method. The mechanism your game uses to calculate scores is up to you to design; scores are only compared within your game.

Topics

Initializing a Score

init(leaderboardIdentifier: String)

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

init(leaderboardIdentifier: String, player: GKPlayer)

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

Score Properties

var context: UInt64

An integer value used by your game.

var date: Date

The date and time when the score was earned.

var formattedValue: String?

Returns the player’s score as a localized string.

var leaderboardIdentifier: String

The identifier for the leaderboard.

var player: GKPlayer

The player identifier for the player that earned the score.

var rank: Int

The position of the score in the results of a leaderboard search.

var value: Int64

The score earned by the player.

Changing the Default Leaderboard

var shouldSetDefaultLeaderboard: Bool

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

Issuing a Score Challenge

func challengeComposeController(withMessage: String?, players: [GKPlayer]?, completionHandler: GKChallengeComposeCompletionBlock?) -> UIViewController

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

Deprecated Methods and Properties

var category: String?

The leaderboard that this score belongs to.

Deprecated
func challengeComposeController(withPlayers: [String]?, message: String?, completionHandler: GKChallengeComposeCompletionBlock?) -> UIViewController?

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

Deprecated
init(category: String?)

Returns an initialized score object.

Deprecated
init(leaderboardIdentifier: String, forPlayer: String)

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

Deprecated
func issueChallenge(toPlayers: [String]?, message: String?)

Issues a score challenge to a set of players.

Deprecated
var playerID: String

The player identifier for the player that earned the score.

Deprecated
func report(completionHandler: ((Error?) -> Void)?)

Reports a score to Game Center.

Deprecated

Relationships

Inherits From

See Also

Leaderboards

class GKLeaderboard

An object used to read data from a leaderboard stored on Game Center.

class GKLeaderboardSet

An object that organizes leaderboards into logical and coherent groups.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software