GKPlayer Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/GameKit.framework |
| Availability | Available in iOS 4.1 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
-
playerIDproperty
Player Details
-
aliasproperty -
displayNameproperty -
isFriendproperty
Player Photos
Properties
alias
A string chosen by the player to identify themselves to other players. (read-only)
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 iOS 4.1 and later.
Declared In
GKPlayer.hdisplayName
A string to display for the player. (read-only)
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 iOS 6.0 and later.
Declared In
GKPlayer.hisFriend
A Boolean value that indicates whether this player is a friend of the local player. (read-only)
Discussion
Players use the Game Center app to declare other players as friends.
Availability
- Available in iOS 4.1 and later.
Declared In
GKPlayer.hplayerID
A string assigned by Game Center to uniquely identify a player. (read-only)
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 iOS 4.1 and later.
Declared In
GKPlayer.hClass Methods
loadPlayersForIdentifiers:withCompletionHandler:
Loads information from Game Center about a list of players.
Parameters
- identifiers
An array of
NSStringobjects, 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
GKPlayerobjects, 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. Keep in mind that the completion handler may be called on a thread other than the one originally used to invoke the method. This means that the code in your block needs to be thread-safe.
Availability
- Available in iOS 4.1 and later.
Declared In
GKPlayer.hInstance Methods
loadPhotoForSize:withCompletionHandler:
Loads a photo of this player from Game Center.
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. Keep in mind that the completion handler may be called on a thread other than the one originally used to invoke the method. This means that the code in your block needs to be thread-safe.
Availability
- Available in iOS 5.0 and later.
Declared In
GKPlayer.hConstants
Player Photo Sizes
The size of a photo loaded by Game Center.
enum {
GKPhotoSizeSmall = 0,
GKPhotoSizeNormal,
};
typedef NSInteger GKPhotoSize;
Constants
Notifications
GKPlayerDidChangeNotificationName
Availability
- Available in iOS 4.1 and later.
Declared In
GKPlayer.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)