GKPlayer 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
GKPlayer.h

Overview

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.

Tasks

Loading Player Details

Identifying the Player

Player Details

Player Photos

Properties

alias

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

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

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

displayName

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

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

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

isFriend

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

@property(readonly, nonatomic) BOOL isFriend
Discussion

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

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

playerID

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

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

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

Class Methods

loadPlayersForIdentifiers:withCompletionHandler:

Loads information from Game Center about a list of players.

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

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
GKPlayer.h

Instance Methods

loadPhotoForSize:withCompletionHandler:

Loads a photo of this player from Game Center.

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

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
GKPlayer.h

Constants

Player Photo Sizes

The size of a photo loaded by Game Center.

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

Load a small photo.

Available in OS X v10.8 and later.

Declared in GKPlayer.h.

GKPhotoSizeNormal

Load a normal sized photo.

Available in OS X v10.8 and later.

Declared in GKPlayer.h.

Notifications

GKPlayerDidChangeNotificationName

Posted when a player object’s data changes.
Availability
Declared In
GKPlayer.h