iOS Developer Library

Developer

GameKit Framework Reference GKAchievementDescription Class Reference

Options
Deployment Target:

On This Page
Language:

GKAchievementDescription

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.

Inheritance


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later.
  • Downloads the achievement descriptions from Game Center.

    Declaration

    Swift

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

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var identifier: String! { get }

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • title title Property

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

    Declaration

    Swift

    var title: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var unachievedDescription: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var achievedDescription: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var maximumPoints: Int { get }

    Objective-C

    @property(assign, readonly, nonatomic) NSInteger maximumPoints

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • image image (iOS 7.0) Property

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

    Declaration

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 7.0.

  • hidden hidden Property

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

    Declaration

    Swift

    var hidden: Bool { get }

    Objective-C

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

    Discussion

    If the value of this property is NOfalse, this achievement is always visible to the player. If YEStrue, 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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later.

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

    Declaration

    Swift

    var replayable: Bool { get }

    Objective-C

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

    Discussion

    If the value of this property is NOfalse, 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 YEStrue, 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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

  • A common image for incomplete achievements.

    Declaration

    Swift

    class func incompleteAchievementImage() -> UIImage!

    Objective-C

    + (UIImage *)incompleteAchievementImage

    Return Value

    An image object.

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • A common image for completed achievements.

    Declaration

    Swift

    class func placeholderCompletedAchievementImage() -> UIImage!

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • Loads the image property for a completed achievement.

    Declaration

    Swift

    func loadImageWithCompletionHandler(_ completionHandler: ((UIImage!, NSError!) -> Void)!)

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var groupIdentifier: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.