A set of parameters for a new live or turn-based match.


class GKMatchRequest : NSObject


Initialize a match request object and pass it to another object to actually create the match. The type of object you pass it to depends on the type of match you want and whether you want to display the standard matchmaking user interface. See Table 1.

Table 1

The class of object that receives the match request object.

Live match

Turn-based match

Creating a match using the standard user interface



Creating a match programmatically for a custom user interface



When creating a match request, you are required to set the minimum and maximum players allowed for the match. Listing 1 shows a simple match request with the minimum, maximum, and default number of players set to 2.

Listing 1

A simple match request

GKMatchRequest *request = [[GKMatchRequest alloc] init];
request.minPlayers = 2;
request.maxPlayers = 2;
request.defaultNumberOfPlayers = 2;

If you are implementing a complete custom user interface, you need to allow players to invite their friends to a match. Typically, this means that your game presents an interface that shows all the players currently in the match, with empty slots for positions to be filled. A player can then pick one or more of those empty slots and issue an invitation to a specific player. To accomplish this, your game needs to be able to send the invitations and receive notifications when the invitations are processed.

You handle both of these problems by assigning more information to the match request. You need to assign a list of players to invite and an invitee handler. As each invitation is processed, your handler is called. Listing 2 shows a typical implementation of the match request to handle this. In this example, a match request is created and a list of player identifiers is assigned to the request. Also, this code provides a custom invitation message; in your game, you should allow the player to customize this message.

When a response is received, if the response is equal to GKInviteeResponseAccepted, the player is added to the match. In this case, the user interface code (not shown here) is updated to show that this player is now part of the match. If any other response is received, the player is removed from the user interface so that the slot appears empty again. Optionally, a more sophisticated example might display a specific error message to the player detailing why the invitation was not accepted; see GKMatchRequest for details.

Listing 2

Programmatically adding friends to a match

- (void)inviteFriends: (NSArray*) friends
    GKMatchRequest *request = [[GKMatchRequest alloc] init];
    request.minPlayers = 2;
    request.maxPlayers = 4;
    request.recipients = friends;
    request.inviteMessage = @"Your Custom Invitation Message Here";
    request.recipientResponseHandler = ^(GKPlayer *player, GKInviteeResponse response)
            [self updateUIForPlayer: player accepted: (response == GKInviteeResponseAccepted)];


Determining the Number of Players Allowed in the Game

class func maxPlayersAllowedForMatch(of: GKMatchType) -> Int

Returns the maximum number of players allowed in the match request for a given match type.

enum GKMatchType

The kind of match being created.

var maxPlayers: Int

The maximum number of players that may join the match.

var minPlayers: Int

The minimum number of players that may join the match.

var defaultNumberOfPlayers: Int

The default number of players for the match.

Setting an Invite Message

var inviteMessage: String?

The string displayed on another player’s device when invited to join a match.

Creating Subsets of Players

var playerGroup: Int

A number identifying a subset of players allowed to join the match.

var playerAttributes: UInt32

A mask that specifies the role that the local player would like to play in the game.

Inviting an Initial Group of Players

var recipients: [GKPlayer]?

A list of player identifiers for players to invite to the match.

var recipientResponseHandler: ((GKPlayer, GKInviteRecipientResponse) -> Void)?

A block to be called when a response from an invited player is returned to your game.

enum GKInviteRecipientResponse

Possible responses from an invitation to a remote player.

Deprecated Methods and Properties

var playersToInvite: [String]?

A list of player identifiers for players to invite to the match.

var inviteeResponseHandler: ((String, GKInviteeResponse) -> Void)?

A block to be called when a response from an invited player is returned to your game.

typealias GKInviteeResponse

Possible responses from an invitation to a remote player.


Inherits From

Conforms To

See Also

Real-Time Matches

class GKMatch

A peer-to-peer network between a group of devices that are connected to Game Center.

class GKVoiceChat

A voice channel that allows a set of players in a match to speak with each other.