An object that communicates with Game Center about the local player’s progress toward completing an achievement.


class GKAchievement : NSObject


Achievements are a great way to provide your players with feedback and a sense of accomplishment. However, you can’t just add an achievement to your game programmatically. There are several steps that you must accomplish to add achievements to your game:

  1. Before you add achievements, add code to authenticate the local player. See Working with Players in Game Center.

  2. Design your game’s achievements. See Designing an Achievement.

  3. Go to App Store Connect and configure the achievements for your game. You provide all of the data needed to display achievements to the player. See Configuring Achievements in iTunes Connect.

  4. Add code to report the local player’s progress to Game Center. By storing the progress on Game Center, you also make the player’s progress visible in the Game Center app. To report the local player’s progress on an achievement, your game updates the percentComplete property of an achievement object and calls the object’s report(_:withCompletionHandler:) class method. Use this method when reporting one or multiple achievements.

  5. Add code to load the local player’s previous progress on achievements from Game Center. To request the local player’s progress on achievements, call the loadAchievements(completionHandler:) class method. Load the local player’s progress shortly after the player is successfully authenticated.

By default, when an achievement is completed, GameKit displays a notification banner to the player. If your game wants to display its own achievement user interface, you can prevent the banner from being displayed by setting the showsCompletionBanner property of the achievement object to false before reporting the player’s progress.

To clear all progress the local player has made on achievements, call the resetAchievements(completionHandler:) class method.


Retrieving Achievement Progress from Game Center

class func loadAchievements(completionHandler: (([GKAchievement]?, Error?) -> Void)?)

Loads previously submitted achievement progress for the local player from Game Center.

Initializing an Achievement Object

init(identifier: String)

Initializes a new achievement object for the local player.

init(identifier: String, player: GKPlayer)

Initializes an achievement object for a specific player.

Configuring an Achievement

var identifier: String

A string used to uniquely identify the specific achievement the object refers to.

var percentComplete: Double

A percentage value that states how far the player has progressed on this achievement.

Reading the State of an Achievement

var isCompleted: Bool

A Boolean value that states whether the player has completed the achievement.

var lastReportedDate: Date

The last time that progress on the achievement was successfully reported to Game Center.

Reporting Progress on Achievements

class func report([GKAchievement], withEligibleChallenges: [GKChallenge], withCompletionHandler: ((Error?) -> Void)?)

Reports a list of achievements and limits the challenges those achievements may complete.

Displaying a Notification Banner For an Achievement

var showsCompletionBanner: Bool

A Boolean value that states whether a banner is displayed when the achievement is completed.

Resetting the Player’s Progress on Achievements

class func resetAchievements(completionHandler: ((Error?) -> Void)?)

Resets all achievement progress for the local player.

Issuing Achievement Challenges

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

Provides a challenge compose view controller with a preformatted message for the achievement and pre-selected GKPlayer objects.

Identifying a Player

var player: GKPlayer

A GKPlayer object used to identify the player who earned the achievement.

Deprecated Methods and Properties

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

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

var isHidden: Bool

A Boolean value that states whether this achievement is normally kept secret from the player.

init(identifier: String?, forPlayer: String)

Initializes an achievement for a specific player.

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

Issue an achievement challenge to a list of players.

var playerID: String

A string used to identify the player who earned the achievement.

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

Reports the player’s progress to Game Center.

func selectChallengeablePlayerIDs([String]?, withCompletionHandler: (([String]?, Error?) -> Void)?)

Finds the subset of players that can earn an achievement.



Inherits From

See Also


class GKAchievementDescription

An object holding text and images used to describe an achievement for an app.