GKLocalPlayer Class Reference

Inherits from
GKPlayer : NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in iOS 4.1 and later.
Companion guide
Game Center Programming Guide
Declared in
GKLocalPlayer.h
Related sample code

Overview

The GKLocalPlayer class is a special subclass of GKPlayer that represents the authenticated player running your game on the device. At any given time, only one player may be authenticated on the device; this player must log out before another player can log in.

Your game must authenticate the local player before using any Game Center features. Authenticating the player ensures that the player has created an account and is connected to Game Center. To authenticate the local player, retrieve the shared instance of the local player by calling the localPlayer class method and set its authenticateHandler property.

You can see whether the local player is authenticated by reading the authenticated property. If authenticated is YES, then the local player’s other properties are valid, and you can call other Game Center methods.

Call the loadFriendsWithCompletionHandler: method to retrieve the player identifiers for the local player’s friends.

Tasks

Accessing the Shared Local Player

Authentication

Accessing Friends

Determining If the Player Is Underage

Working with the Default Leaderboard Category

Properties

authenticated

A Boolean value that indicates whether a local player is currently signed in to Game Center. (read-only)

@property(nonatomic, readonly, getter=isAuthenticated) BOOL authenticated
Availability
  • Available in iOS 4.1 and later.
Declared In
GKLocalPlayer.h

authenticateHandler

A handler called to process an authentication-related event.

@property(nonatomic, copy) void(^authenticateHandler)(UIViewController *viewController, NSError *error)
Parameters
viewController

This parameter is nil if the authentication process is complete. Otherwise, it contains a view controller that your game should display to the player.

error

This parameter contains an error object that describes any error that occurred.

Discussion

Your game should authenticate the player as early as possible after launching, ideally as soon as you can present a user interface to the player. For example, your game may be launched because the player accepted an invitation to join a match or to take a turn in a turn-based match, so you want your game to authenticate the player and process the match invitation as quickly as possible. After you set a handler, authentication begins automatically and is repeated when your game moves to the background and then back to the foreground.

During the authentication process, Game Kit calls your handler one or more times to handle specific authentication events. Your handler must handle three kinds of events:

  • If the device does not have an authenticated player, Game Kit passes a view controller to your authenticate handler. When presented, this view controller displays the authentication user interface. Your game should pause other activities that require user interaction (such as your game loop), present this view controller and then return. When the player finishes interacting with it, the view controller is dismissed automatically.

  • If the authentication process succeeded, theGKLocalPlayer singleton object’s authenticated property is set to YES and the object’s other properties are set to match those of the connected player.

  • If the authentication process failed, the GKLocalPlayer singleton object’s authenticated property is set to NO and the object’s other properties are cleared.

Each time the authentication handler is called, the data stored in the local player singleton object may have changed. A new player may have logged into the device or the player may have simply logged out from Game Center. Because of both of these possibilities, your authentication handler must be prepared to update any other objects that assume that a particular player is logged in. For more information, see “Authenticating the Local Player in a Multitasking Application” in Game Center Programming Guide.

Availability
  • Available in iOS 6.0 and later.
Declared In
GKLocalPlayer.h

friends

A list of player identifiers for the local player’s friends. (read-only)

@property(nonatomic, readonly, retain) NSArray *friends
Discussion

This property is invalid until a call to loadFriendsWithCompletionHandler: succeeds.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKLocalPlayer.h

underage

A Boolean value that declares whether the local player is underage. (read-only)

@property(nonatomic, readonly, getter=isUnderage) BOOL underage
Discussion

Some Game Center features are disabled if the local player is underage. Your game can also test this property if it wants to disable some of its own features based on the player’s age.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKLocalPlayer.h

Class Methods

localPlayer

Retrieves the shared instance of the local player.

+ (GKLocalPlayer *)localPlayer
Return Value

The local player object.

Discussion

You never directly create a local player object. Instead, you retrieve the singleton object by calling this class method.

Availability
  • Available in iOS 4.1 and later.
Related Sample Code
Declared In
GKLocalPlayer.h

Instance Methods

loadDefaultLeaderboardCategoryIDWithCompletionHandler:

Loads the category identifier for the local player’s default leaderboard.

- (void)loadDefaultLeaderboardCategoryIDWithCompletionHandler:(void (^)(NSString *categoryID, NSError *error))completionHandler
Parameters
completionHandler

A block to be called when the request completes.

The block receives the following parameters:

categoryID

The category ID string for the local player’s default leaderboard.

error

If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter 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 6.0 and later.
See Also
Declared In
GKLocalPlayer.h

loadFriendsWithCompletionHandler:

Retrieves a list of player identifiers for the local player’s friends.

- (void)loadFriendsWithCompletionHandler:(void (^)(NSArray *friends, NSError *error))completionHandler
Parameters
completionHandler

A block to be called when the request completes.

The block receives the following parameters:

friends

An array of player identifiers for the players that are friends of the local player. If an error occurred, this value can be non-nil. In that case, the array contains the data that Game Kit was able to download before the error occurred.

error

If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter 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.

Once this call is completed, the friends property of the shared local player object is set to the same list of players returned in the completion handler.

Availability
  • Available in iOS 4.1 and later.
See Also
Declared In
GKLocalPlayer.h

setDefaultLeaderboardCategoryID:completionHandler:

Sets the category identifier for the local player’s default leaderboard.

- (void)setDefaultLeaderboardCategoryID:(NSString *)categoryID completionHandler:(void (^)(NSError *error))completionHandler
Parameters
categoryID

The category ID string for one of your game’s leaderboards.

completionHandler

A block to be called when the request completes.

The block receives the following parameter:

error

If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter 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.

The default leaderboard is configured in iTunes Connect as part of configuring your game’s leaderboards. All players normally start with this leaderboard as the default leaderboard. Calling this method changes the default leaderboard only for the local player.

Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
GKLocalPlayer.h

Notifications

GKPlayerAuthenticationDidChangeNotificationName

Posted after the authenticated property of the shared local player object changes.
Availability
Declared In
GKLocalPlayer.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...