Class

GKMatchRequest

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

Declaration

@interface GKMatchRequest : NSObject

Overview

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

GKMatchmakerViewController

GKTurnBasedMatchmakerViewController

Creating a match programmatically for a custom user interface

GKMatchmaker

GKTurnBasedMatch

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)];
        };
...
}

Topics

Determining the Number of Players Allowed in the Game

+ maxPlayersAllowedForMatchOfType:

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

GKMatchType

The kind of match being created.

maxPlayers

The maximum number of players that may join the match.

minPlayers

The minimum number of players that may join the match.

defaultNumberOfPlayers

The default number of players for the match.

Setting an Invite Message

inviteMessage

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

Creating Subsets of Players

playerGroup

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

playerAttributes

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

Inviting an Initial Group of Players

recipients

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

recipientResponseHandler

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

GKInviteRecipientResponse

Possible responses from an invitation to a remote player.

Deprecated Methods and Properties

playersToInvite

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

Deprecated
inviteeResponseHandler

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

Deprecated
GKInviteeResponse

Possible responses from an invitation to a remote player.

Instance Properties

Relationships

Inherits From

See Also

Real-Time Matches

GKMatch

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

GKVoiceChat

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

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software