iOS Developer Library

Developer

GameKit Framework Reference GKPlayer Class Reference

Options
Deployment Target:

On This Page
Language:

GKPlayer

Inherits From


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later

GKPlayer objects provide information about a player on Game Center.

Every player account on Game Center is permanently assigned a unique player identifier string. Your game should use this string to store per-player information or to disambiguate between players. In most cases, Game Kit classes return player identifier strings to your game. For example, in a multiplayer match, the GKMatch object’s playerIDs property contains an array of the player identifiers for all the players connected to the match.

To load information about a set of players, your game calls the loadPlayersForIdentifiers:withCompletionHandler: method, passing in an array of identifier strings. Your completion handler is called after the player data is downloaded from Game Center. For performance and resource reasons, player objects returned by the loadPlayersForIdentifiers:withCompletionHandler: method do not include player photos. To load the photo associated with a player, call the player object’s loadPhotoForSize:withCompletionHandler: method.

  • Loads information from Game Center about a list of players.

    Declaration

    Swift

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

    Objective-C

    + (void)loadPlayersForIdentifiers:(NSArray *)identifiers withCompletionHandler:(void (^)(NSArray *players, NSError *error))completionHandler

    Parameters

    identifiers

    An array of NSString objects, each a unique identifier for a Game Center player.

    completionHandler

    A block to be called when the player data is retrieved from Game Center.

    The block receives the following parameters:

    players

    An array of GKPlayer objects, one per identifier. If an error occurred, this may be non-nil. In that case, the array holds whatever data Game Kit was able to retrieve for the requested players.

    error

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

    Discussion

    Listing 1 shows an example of how to load the GKPlayer objects associated with player identifiers.

    Listing 1Retrieving player details
    • - (void) loadPlayerData: (NSArray *) identifiers
    • {
    • [GKPlayer loadPlayersForIdentifiers:identifiers withCompletionHandler:^(NSArray *players, NSError *error) {
    • if (error != nil)
    • {
    • // Handle the error.
    • }
    • if (players != nil)
    • {
    • // Process the array of GKPlayer objects.
    • }
    • }];
    • }

    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.1 and later

  • playerID playerID Property

    A string assigned by Game Center to uniquely identify a player. (read-only)

    Declaration

    Swift

    var playerID: String! { get }

    Objective-C

    @property(readonly, retain, nonatomic) NSString *playerID

    Discussion

    The player identifier should never be displayed to the player. Use it only as a way to identify a particular player.

    Do not make assumptions about the contents of the player identifier string. Its format and length are subject to change.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • alias alias Property

    A string chosen by the player to identify themselves to other players. (read-only)

    Declaration

    Swift

    var alias: String! { get }

    Objective-C

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

    Discussion

    A player’s alias is used when a player is not a friend of the local player. Typically, you never display the alias string directly in your user interface. Instead use the displayName property.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • A string to display for the player. (read-only)

    Declaration

    Swift

    var displayName: String! { get }

    Objective-C

    @property(readonly, nonatomic) NSString *displayName

    Discussion

    The display name for a player depends on whether the player is a friend of the local player authenticated on the device. If the player is a friend of the local player, then the display name is the actual name of the player. If the player is not a friend, then the display name is the player’s alias.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

  • isFriend isFriend (iOS 8.0) Property

    A Boolean value that indicates whether this player is a friend of the local player. (read-only)

    Declaration

    Swift

    var isFriend: Bool { get }

    Objective-C

    @property(readonly, nonatomic) BOOL isFriend

    Discussion

    Players use the Game Center app to declare other players as friends.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 8.0

  • Loads a photo of this player from Game Center.

    Declaration

    Swift

    func loadPhotoForSize(_ size: GKPhotoSize, withCompletionHandler completionHandler: ((UIImage!, NSError!) -> Void)!)

    Objective-C

    - (void)loadPhotoForSize:(GKPhotoSize)size withCompletionHandler:(void (^)(UIImage *photo, NSError *error))completionHandler

    Parameters

    size

    A constant that determines the size of the photo to load.

    completionHandler

    A block to be called when the player data is retrieved from Game Center.

    The block receives the following parameters:

    photo

    An image for the player. If an error occurred, this may still be non-nil. In this case, the image reflects an image cached by Game Kit on the device.

    error

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

    Discussion

    Listing 2 shows a typical implementation for loading a player’s photo. There is no property that stores the returned photo. You must write your own code to associate player photos with GKPlayer objects.

    Listing 2Loading a player’s photo
    • - (void) loadPlayerPhoto: (GKPlayer*) player
    • {
    • [player loadPhotoForSize:GKPhotoSizeSmall withCompletionHandler:^(UIImage *photo, NSError *error) {
    • if (photo != nil)
    • {
    • [self storePhoto: photo forPlayer: player];
    • }
    • if (error != nil)
    • {
    • // Handle the error if necessary.
    • }
    • }];
    • }

    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 5.0 and later

  • The size of a photo loaded by Game Center.

    Declaration

    Swift

    typealias GKPhotoSize = Int

    Objective-C

    enum { GKPhotoSizeSmall = 0, GKPhotoSizeNormal, }; typedef NSInteger GKPhotoSize;

    Constants

    • GKPhotoSizeSmall

      GKPhotoSizeSmall

      Load a small photo.

      Available in iOS 5.0 and later

    • GKPhotoSizeNormal

      GKPhotoSizeNormal

      Load a normal sized photo.

      Available in iOS 5.0 and later

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 5.0 and later