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.

Note

Hosted matches are intended for developers who already have a networking game service but who want to use Game Center to find players for a match. Because you need to design and implement your own networking code, you can define your own protocols to connect to your server.

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.

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.

Parameters

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.

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.

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.

Parameters

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.

Parameters

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

players

If matchmaking was successful, this parameter contains an array of GKPlayer 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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

player

The GKPlayer object that identifies the player whose reachability status has changed.

reachable

YEStrue if a new player has been discovered locally, NOfalse 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.

Parameters

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

YEStrue if a new player has been discovered locally, NOfalse 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.