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

Overview

The GKMatchmaker class is used to programmatically create matches to other players and to receive match invitations sent by other players.

Matches can be either peer-to-peer or hosted. A peer-to-peer match is fully supported in Game Kit by the GKMatch class. A GKMatch object provides all of the network connections between the devices and routes the network data through Game Center if necessary. In contrast, a hosted match uses matchmaking to find the players for a match, but your game implements its own networking between the participants, routing through your own server if necessary.

To receive invitations from other players, your game must provide an invitation handler. After your game successfully authenticates the local player, it should immediately set the inviteHandler property. The invite handler is called immediately if your game was launched in response to a push notification.

To programmatically search for other players, start by creating a GKMatchRequest object that describes the match you are interested in. Then, call the shared matchmaker’s findMatchForRequest:withCompletionHandler: method to create a peer-to-peer match, or its findPlayersForHostedMatchRequest:withCompletionHandler: method to create a hosted match. In either case, Game Center matches players into a match and calls your completion handler. If the match does not have enough players (for example, you invited a specific list of players and some declined the invitation), you can create another match request and call the addPlayersToMatch:matchRequest:completionHandler: method to add more participants to the match. Once the match is complete, call the finishMatchmakingForMatch: method.

If you implement programmatic matchmaking and invite specific players to the match, you should also implement an invitee response handler. This handler is notified as invitations are processed, allowing you to update your game’s custom user interface to display which players are connected to the match.

Tasks

Retrieving the Shared Matchmaker

Receiving Invitations From Other Players

Matching Players

Looking For Nearby Players

Properties

inviteHandler

A block to be called when an invitation to join a match is accepted by the local player.

@property(nonatomic, copy) void (^inviteHandler)(GKInvite *acceptedInvite, NSArray *playerIDsToInvite)
Discussion

The block takes the following parameters:

acceptedInvite

The invitation accepted by the player.

playerIDsToInvite

An array of NSString objects containing player identifiers for additional players to invite into the game.

Your block should respond to the invitation in one of two ways:

If your game receives an invitation while it is already running, it should transition to multiplayer play. It should clean up any existing content, such as ending the current match the player is playing, and then process the invitation.

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

Class Methods

sharedMatchmaker

Returns the singleton matchmaker instance.

+ (GKMatchmaker *)sharedMatchmaker
Return Value

The shared matchmaker instance.

Discussion

Games do not create a GKMatchmaker object. Instead, they retrieve the shared singleton by calling this method.

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

Instance Methods

addPlayersToMatch:matchRequest:completionHandler:

Adds players to an existing match.

- (void)addPlayersToMatch:(GKMatch *)match matchRequest:(GKMatchRequest *)matchRequest completionHandler:(void (^)(NSError *error))completionHandler
Parameters
match

A previously created match.

matchRequest

The parameters for the new match request.

completionHandler

A block to be called when matchmaking completes.

The block takes the following parameter:

error

If matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

Discussion

This method updates an existing match object by adding additional players.

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

cancel

Cancels a pending matchmaking request.

- (void)cancel
Discussion

The completion handler receives a callback with a GKErrorCancelled error.

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

cancelInviteToPlayer:

Cancels a pending invitation to another player.

- (void)cancelInviteToPlayer:(NSString *)playerID
Parameters
playerID

The player identifier for a player previously invited to the match.

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

findMatchForRequest:withCompletionHandler:

Initiates a request to find players for a peer-to-peer match.

- (void)findMatchForRequest:(GKMatchRequest *)request withCompletionHandler:(void (^)(GKMatch *match, NSError *error))completionHandler
Parameters
request

The configuration for the desired match.

completionHandler

A block to be called when the match has been created. This block receives the following parameters:

match

If matchmaking was successful, this parameter contains the created match. Otherwise, this parameter is nil.

error

If matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

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.

On iOS 6, if the match request’s playersToInvite property is non-NIL, Game Center sends invitations only out to the players listed in the property. If the playersToInvite property is NIL, then it searches for any waiting players that match the request. If your game wants to perform programmatic matchmaking for the remaining slots, it should call the addPlayersToMatch:matchRequest:completionHandler: method with a match request whose playersToInvite property is NIL.

Prior to iOS 6, the match request’s playersToInvite property is ignored and this method only searches for available players.

Availability
  • Available in OS X v10.8 and later.
See Also
Declared In
GKMatchmaker.h

findPlayersForHostedMatchRequest:withCompletionHandler:

Initiates a request to find players for a hosted match.

- (void)findPlayersForHostedMatchRequest:(GKMatchRequest *)request withCompletionHandler:(void (^)(NSArray *playerIDs, NSError *error))completionHandler
Parameters
request

The configuration for the desired match.

completionHandler

A block to be called when the match has been created. This block receives the following parameters:

playerIDs

If matchmaking was successful, this parameter contains an array of NSString objects containing the players to connect into the match. Otherwise, this parameter is nil.

error

If matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

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. When your completion handler is called, your game should connect those players to your own server.

On iOS 6, if the match request’s playersToInvite property is non-NIL, Game Center sends invitations only out to the players listed in the property. If the playersToInvite property is NIL, then it searches for any waiting players that match the request. Prior to iOS 6, the match request’s playersToInvite property is ignored and this method only searches for available players.

Availability
  • Available in OS X v10.8 and later.
See Also
Declared In
GKMatchmaker.h

finishMatchmakingForMatch:

Informs Game Center that programmatic matchmaking has finished.

- (void)finishMatchmakingForMatch:(GKMatch *)match
Parameters
match

The match that has completed the matchmaking process.

Discussion

If your game uses programmatic matchmaking, it makes a series of calls to the findMatchForRequest:withCompletionHandler: and addPlayersToMatch:matchRequest:completionHandler: methods to fill a match with players. When the match has the proper number of players, call thefinishMatchmakingForMatch: method before starting the match.

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

matchForInvite:completionHandler:

Creates a match from an accepted invitation.

- (void)matchForInvite:(GKInvite *)invite completionHandler:(void (^)(GKMatch *match, NSError *error))completionHandler
Parameters
invite

The invitation accepted by the player.

completionHandler

A block to be called when the match has been created. This block receives the following parameters:

match

If the match was successfully created, this parameter contains the created match. Otherwise, this parameter is nil.

error

If the match was successfully created, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

Discussion

When using this method to create a match, your game should display its own user interface to inform the player that he or she has been connected to a match.

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.9 and later.
Declared In
GKMatchmaker.h

queryActivityWithCompletionHandler:

Initiates a search for activity in all player groups.

- (void)queryActivityWithCompletionHandler:(void (^)(NSInteger activity, NSError *error))completionHandler
Parameters
completionHandler

A block that takes the following parameters:

activity

The number of match requests for all player groups during the previous 60 seconds.

error

If the search completed successfully, this parameter is nil; otherwise, this parameter holds an error object that describes the error that occurred.

Discussion

A query allows your game to see how many players have recently searched for a match, across all player groups.

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

queryPlayerGroupActivity:withCompletionHandler:

Queries Game Center for the activity in a player group.

- (void)queryPlayerGroupActivity:(NSUInteger)playerGroup withCompletionHandler:(void (^)(NSInteger activity, NSError *error))completionHandler
Parameters
playerGroup

A number that uniquely identifies a subset of players of your game.

completionHandler

A block that is called when the search completes. The block takes the following parameters:

activity

The number of match requests for the player group during the previous 60 seconds.

error

If the search completed successfully, this parameter is nil; otherwise, this parameter holds an error object that describes the error that occurred.

Discussion

A query allows your game to see how many players have recently searched for a match. As a result, you can present a user interface that shows the relative activity in each player group. For example, if one group sees less activity than others, you might display a warning so that players are aware that finding a match may take longer.

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

startBrowsingForNearbyPlayersWithReachableHandler:

Enables the matchmaking process to find nearby players through Bluetooth or WiFi (same subnet only).

- (void)startBrowsingForNearbyPlayersWithReachableHandler:(void (^)(NSString *playerID, BOOL reachable))reachableHandler
Parameters
reachableHandler

A block called when the reachability for a player changes. The block takes the following parameters:

playerID

The player identifier for the player whose reachability status has changed.

reachable

YES if a new player has been discovered locally, NO if a previously discovered player has disappeared.

Discussion

You only use this method when you are implementing programmatic matchmaking. After enabling browsing for nearby players, use the responses to populate your user interface with information about nearby players. If a player wants to invite a player to a game, add that player’s player identifier to a match request and call either the findMatchForRequest:withCompletionHandler: to create a match or addPlayersToMatch:matchRequest:completionHandler: method to update a match.

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

stopBrowsingForNearbyPlayers

Ends the search for nearby players.

- (void)stopBrowsingForNearbyPlayers
Availability
  • Available in OS X v10.9 and later.
Declared In
GKMatchmaker.h