iOS Developer Library

Developer

GameKit Framework Reference GKMatchmakerViewController Class Reference

Options
Deployment Target:

On This Page
Language:

GKMatchmakerViewController

Inherits From


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later

The GKMatchmakerViewController class is used to present a standard user interface to the player. This interface allows them to invite friends to a match or to allow Game Center to fill the remaining players needed for a match.

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 1Showing 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 initWithMatchRequest: 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 initWithInvite: 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.

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

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

    Declaration

    Swift

    init!(invite invite: GKInvite!)

    Objective-C

    - (id)initWithInvite:(GKInvite *)invite

    Parameters

    invite

    The invitation received from the other player.

    Return Value

    An initialized matchmaker view controller object. If an error occurred, NULL is returned.

    Discussion

    The user is allowed to join the match that the user was invited to, but is not allowed to invite others to the match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • Initializes a matchmaker view controller to create a new match.

    Declaration

    Swift

    init!(matchRequest request: GKMatchRequest!)

    Objective-C

    - (id)initWithMatchRequest:(GKMatchRequest *)request

    Parameters

    request

    A request containing the characteristics for the desired match.

    Return Value

    An initialized matchmaker view controller object. If an error occurred, NULL is returned.

    Discussion

    Your game uses the initWithMatchRequest: method when it wants the local user to create a new match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • The delegate for the matchmaker view controller.

    Declaration

    Swift

    unowned(unsafe) var matchmakerDelegate: GKMatchmakerViewControllerDelegate!

    Objective-C

    @property(nonatomic, assign) id< GKMatchmakerViewControllerDelegate > matchmakerDelegate

    Discussion

    A delegate is required to receive feedback when the match is created.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

  • The default invitation message used to initialize an invitation.

    Deprecation Statement

    Set the message on the match request instead.

    Declaration

    Objective-C

    @property(nonatomic, copy) NSString *defaultInvitationMessage

    Discussion

    Your game sets this property to change the default invitation text displayed when the local player creates a new invitation. The local player may edit the text before sending the invitation.

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 5.0 and later

    Deprecated in iOS 7.0

  • hosted hosted Property

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

    Declaration

    Swift

    var hosted: Bool

    Objective-C

    @property(nonatomic, assign, getter=isHosted) BOOL hosted

    Discussion

    The value of the hosted property determines which methods of the delegate are called when the match is complete. If YEStrue, this is a hosted match, and the delegate’s matchmakerViewController:didFindPlayers method is to provide the list of players to your game. If NOfalse, this is a peer-to-peer match, and matchmakerViewController:didCreateMatch is called with a GKMatch object. The default value is NOfalse.

    Hosted matches require you to provide a server that hosts the participants in the match. For more information on implementing hosted matches, see Real-Time Matches.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • The configuration for the desired match. (read-only)

    Declaration

    Swift

    var matchRequest: GKMatchRequest! { get }

    Objective-C

    @property(nonatomic, readonly, retain) GKMatchRequest *matchRequest

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func addPlayersToMatch(_ match: GKMatch!)

    Objective-C

    - (void)addPlayersToMatch:(GKMatch *)match

    Parameters

    match

    An existing match that you want to add players to.

    Discussion

    Your game calls this method prior to presenting the view controller to the player. Calling this method instructs the view controller to add new players to the provided match rather than creating a new match.

    When called, this method sets the delegate on the match to nil and updates the view controller’s user interface to display the players already connected to the match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setHostedPlayer(_ playerID: String!, connected connected: Bool)

    Objective-C

    - (void)setHostedPlayer:(NSString *)playerID connected:(BOOL)connected

    Parameters

    playerID

    The identifier string for a player that connected to the external server.

    connected

    A Boolean value that states whether the player is connected to the hosted match.

    Discussion

    When setting up a hosted match, each device should instantiate a matchmaker view controller and display it to the player. Then, when a new player connects to your server, your server should notify all participating devices already connected to your server. Each participating device should then call this method to update that player’s status in the matchmaking interface. Similarly, if a player disconnects from the server, your server should inform each device so that the devices can update their user interface.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 5.0 and later

    Deprecated in iOS 8.0

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

    Declaration

    Swift

    func setHostedPlayer(_ player: GKPlayer!, didConnect connected: Bool)

    Objective-C

    - (void)setHostedPlayer:(GKPlayer *)player didConnect:(BOOL)connected

    Parameters

    player

    The GKPlayer object identifying the player that connected to the external server.

    connected

    A Boolean value that states whether the player is connected to the hosted match.

    Discussion

    When setting up a hosted match, each device should instantiate a matchmaker view controller and display it to the player. Then, when a new player connects to your server, your server should notify all participating devices already connected to your server. Each participating device should then call this method to update that player’s status in the matchmaking interface. Similarly, if a player disconnects from the server, your server should inform each device so that the devices can update their user interface.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

  • Informs the controller that a player has joined a hosted match.

    Deprecation Statement

    Use setHostedPlayer:connected: instead.

    Declaration

    Objective-C

    - (void)setHostedPlayerReady:(NSString *)player

    Parameters

    player

    The identifier string for a player that connected to the external server.

    Discussion

    In a hosted match, when a new player connects to the server, your server should inform all participating devices connected to the match. Each participating device must separately call this method to update its matchmaking user interface.

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 5.0