GKAchievementDescription Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in OS X v10.8 and later.
Companion guide
Declared in
GKAchievementDescription.h

Overview

An GKAchievementDescription object holds text and images used to describe an achievement. When you develop your game, you create localized achievement descriptions in iTunes Connect. At runtime, your game retrieves these descriptions from Game Center. Usually your game downloads the achievement descriptions when it wants to present a custom achievement user interface to the player.

To retrieve a set of achievement description objects for your game, call the loadAchievementDescriptionsWithCompletionHandler: class method. For performance reasons, achievement images are downloaded separately. To download am achievement description’s completion image, call that object’s loadImageWithCompletionHandler: method.

The incompleteAchievementImage and placeholderCompletedAchievementImage class methods provide standard images your game can use to present achievement progress to the player.

Tasks

Retrieving Achievement Descriptions

Reading and Writing Achievement Properties

Working with Achievement Images

Retrieving Group Information

Properties

achievedDescription

A localized description to be used after the local player has completed the achievement. (read-only)

@property(copy, readonly, nonatomic) NSString *achievedDescription
Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h

groupIdentifier

The identifier for the group the achievement description is part of. (read-only)

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

If your game is configured to be part of a game group in iTunes Connect, this property holds the identifier you assigned to the achievement in the game group. If the game is not part of a game group, this property is nil.

Availability
  • Available in OS X v10.9 and later.
Declared In
GKAchievementDescription.h

hidden

A Boolean value that states whether this achievement is initially visible to players. (read-only)

@property(getter=isHidden, assign, readonly, nonatomic) BOOL hidden
Discussion

If the value of this property is NO, this achievement is always visible to the player. If YES, the achievement is not displayed in any of the standard achievement user interface screens. It remains hidden until the first time your game reports progress towards completing this achievement.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h

identifier

A unique string used to identify the achievement. (read-only)

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

The GKAchievementDescription property holds the identifier string you created for the achievement on iTunes Connect.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h

image

An image to display for the completed achievement. (read-only)

@property(nonatomic, retain, readonly) UIImage *image
Discussion

The value of this property is undefined until after the image is loaded. See loadImageWithCompletionHandler:.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h

maximumPoints

The number of points the player earns by completing this achievement. (read-only)

@property(assign, readonly, nonatomic) NSInteger maximumPoints
Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h

replayable

A Boolean value that states whether this achievement can be earned multiple times. (read-only)

@property(nonatomic, getter=isReplayable, assign, readonly) BOOL replayable
Discussion

If the value of this property is NO, then the achievement may only be earned once. After the achievement is earned, Game Center ignores any further progress submitted for it. If the value of this property is YES, then the achievement is considered earned each time your game reports progress to Game Center that completes the achievement. This means that any appropriate banners are displayed to the player again, challenges based on the achievement are completed, and so on.

Availability
  • Available in OS X v10.9 and later.
Declared In
GKAchievementDescription.h

title

A localized title for the achievement. (read-only)

@property(copy, readonly, nonatomic) NSString *title
Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h

unachievedDescription

A localized description of the achievement to be used when the local player has not completed the achievement. (read-only)

@property(copy, readonly, nonatomic) NSString *unachievedDescription
Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h

Class Methods

incompleteAchievementImage

A common image for incomplete achievements.

+ (UIImage *)incompleteAchievementImage
Return Value

An image object.

Discussion

On OS X, this class method returns an NSImage object but otherwise works identically.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h

loadAchievementDescriptionsWithCompletionHandler:

Downloads the achievement descriptions from Game Center.

+ (void)loadAchievementDescriptionsWithCompletionHandler:(void (^)(NSArray *descriptions, NSError *error))completionHandler
Parameters
completionHandler

A block to be called when the download is completed.

The block receives the following parameters:

descriptions

An array of GKAchievementDescription objects containing the achievements in your game. If an error occurred, this value may be non-nil. In this case, the array holds whatever descriptions were downloaded by Game Kit before the error occurred.

error

If an error occurred, this error 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 OS X v10.8 and later.
Declared In
GKAchievementDescription.h

placeholderCompletedAchievementImage

A common image for completed achievements.

+ (UIImage *)placeholderCompletedAchievementImage
Return Value

An image object.

Discussion

When an achievement is completed, your game can display this image until the custom image for an achievement finishes loading.

On OS X, this class method returns an NSImage object but otherwise works identically.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h

Instance Methods

loadImageWithCompletionHandler:

Loads the image property for a completed achievement.

- (void)loadImageWithCompletionHandler:(void (^)(UIImage *image, NSError *error))completionHandler
Parameters
completionHandler

A block to be called when the download is completed.

The block receives the following parameters:

image

The downloaded image. If an error occurred, this value is nil.

error

If an error occurred, this error object describes the error. If the operation completed successfully, this value is nil.

Discussion

Your game should call loadImageWithCompletionHandler: for each achievement the user has completed. Your game should display the placeholder image until the image is successfully downloaded. After the block is called, the description’s image property holds the same image object that is returned to the block.

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.

On OS X, this class method returns an NSImage object but otherwise works identically.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKAchievementDescription.h