Class

GKMatchmaker

An object that programmatically creates matches with other players and receives match invitations sent by other players.

Declaration

@interface GKMatchmaker : NSObject

Overview

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.

Topics

Retrieving the Shared Matchmaker

+ sharedMatchmaker

Returns the singleton matchmaker instance.

Receiving Invitations from Other Players

- matchForInvite:completionHandler:

Creates a match from an accepted invitation.

Matching Players

- cancel

Cancels a pending matchmaking request.

- cancelPendingInviteToPlayer:

Cancels a pending invitation to another player.

- findMatchForRequest:withCompletionHandler:

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

- findPlayersForHostedRequest:withCompletionHandler:

Initiates a request to find players for a hosted match.

- finishMatchmakingForMatch:

Informs Game Center that programmatic matchmaking has finished.

- queryActivityWithCompletionHandler:

Initiates a search for activity in all player groups.

- queryPlayerGroupActivity:withCompletionHandler:

Queries Game Center for the activity in a player group.

Looking for Nearby Players

- startBrowsingForNearbyPlayersWithHandler:

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

- stopBrowsingForNearbyPlayers

Ends the search for nearby players.

Deprecated Methods and Properties

- cancelInviteToPlayer:

Cancels a pending invitation to another player.

Deprecated
- findPlayersForHostedMatchRequest:withCompletionHandler:

Initiates a request to find players for a hosted match.

Deprecated
inviteHandler

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

Deprecated
- startBrowsingForNearbyPlayersWithReachableHandler:

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

Deprecated

Relationships

Inherits From

See Also

Player Invitations

GKMatchmakerViewController

A user interface for inviting friends to a match or for allowing Game Center to fill the remaining players needed for a match.

GKTurnBasedMatchmakerViewController

A user interface that allows players to manage the turn-based matches that they are participating in.

GKInvite

A matchmaking invitation sent by another player to the local player.