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


iOS, Mac Catalyst, tvOS
class GKMatchmakerViewController : UINavigationController
class GKMatchmakerViewController : NSViewController


To show a matchmaking screen, initialize a new GKMatchmakerViewController object and set the delegate. Configure the view controller’s other properties to match your specific needs, then present the new view controller and wait for the delegate to be called. The view controller’s delegate is notified when the matchmaking process is completed or canceled. In either situation, you dismiss the view controller. Listing 1 shows how to present the matchmaking user interface to the player.

Listing 1

Showing the standard matchmaking interface

- (IBAction)hostMatch: (id) sender
    GKMatchRequest *request = [[GKMatchRequest alloc] init];
    request.minPlayers = 2;
    request.maxPlayers = 2;
    GKMatchmakerViewController *mmvc = [[GKMatchmakerViewController alloc] initWithMatchRequest:request];
    mmvc.matchmakerDelegate = self;
    [self presentViewController:mmvc animated:YES completion:nil];

If the user is creating the match, your game initializes the matchmaker view controller by creating a GKMatchRequest object that describes the desired match. This match request is passed to the init(matchRequest:) method. When this view controller is displayed, the local player can invite other players into the match.

If your game receives an invitation from another player, it receives a GKInvite object representing the match the player was invited to. You initialize the matchmaker view controller by passing the GKInvite object received from Game Kit to the init(invite:) method. When this view controller is presented to the player, the player joins the existing match, but is not allowed to invite others to the match.

In iOS, you present and dismiss the view controller from another view controller in your game, using the methods provided by the UIViewController class. In macOS, you use the GKDialogController class to present and dismiss the view controller.


Initializing a Matchmaker View Controller

init?(invite: GKInvite)

Initializes a matchmaker view controller to respond to an invitation received from another player.

init?(matchRequest: GKMatchRequest)

Initializes a matchmaker view controller to create a new match.

Getting and Setting the Delegate

var matchmakerDelegate: GKMatchmakerViewControllerDelegate?

The delegate for the matchmaker view controller.

protocol GKMatchmakerViewControllerDelegate

A class implements the GKMatchmakerViewControllerDelegate protocol to receive notifications from a GKMatchmakerViewController object. The delegate is called if a new match has been successfully created, if the user cancels matchmaking, and if an error occurs. In all three cases, the delegate should dismiss the view controller.

Matchmaker View Controller Properties

var isHosted: Bool

A Boolean value that indicates whether the match is hosted or peer-to-peer.

var matchRequest: GKMatchRequest

The configuration for the desired match.

Adding Players to an Existing Match

func addPlayers(to: GKMatch)

Adds new players to an existing match instead of starting a new match.

Implementing Hosted Matches

func setHostedPlayer(GKPlayer, didConnect: Bool)

Updates a player’s status on the view to show that the player has connected or disconnected from your server.

Deprecated Methods and Properties

func setHostedPlayer(String, connected: Bool)

Updates a player’s status on the view to show that the player has connected or disconnected from your server.

var defaultInvitationMessage: String?

The default invitation message used to initialize an invitation.


See Also

Player Invitations

class GKMatchmaker

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

class GKTurnBasedMatchmakerViewController

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

class GKInvite

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