GKMatchRequest Class Reference

Inherits from	NSObject
Conforms to	NSObject (NSObject)
Framework	/System/Library/Frameworks/GameKit.framework
Availability	Available in iOS 4.1 and later.
Companion guide	Game Center Programming Guide
Declared in	GKMatchmaker.h

Overview

A GKMatchRequest object is used to specify the parameters for a new live or turn-based match. You initialize a match request object, then pass it to another object to actually create the match. The kind of object you pass it to depends on which kind 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`	`GKTurnBasedMatch`
Creating a match programmatically for a custom user interface	`GKMatchmaker`	`GKTurnBasedMatchmakerViewController`

Tasks

Determining the Number of Players Allowed in the Game

Setting an Invite Message

Creating Subsets of Players

Inviting an Initial Group of Players

Properties

defaultNumberOfPlayers

The default number of players for the match.

@property(nonatomic, assign) NSUInteger defaultNumberOfPlayers

Discussion

If this property is not set, then the default number of players is equal to the value stored in the maxPlayers property. The default number of players determines the number of invitees shown in the standard matchmaking user interface. The player can choose to override this to add or remove slots.

Availability

Available in iOS 6.0 and later.

Declared In

GKMatchmaker.h

inviteeResponseHandler

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

@property(nonatomic, copy) void(^inviteeResponseHandler)(NSString *playerID, GKInviteeResponse response)

Discussion

The block takes the following parameters:

playerID: The identifier for the player.
GKInviteeResponse: The nature of the response. See “Invitee Responses.”

An invitee response handler is called whenever you programmatically invite specific players to join a match. It is called once for each player invited to the match. Typically, your game uses the responses to update the custom user interface. For example, you want the player to be able to perform any of the following tasks:

Start the match.
Invite an additional set of specific players.
Use matchmaking to fill the remaining match slots.

Availability

Available in iOS 6.0 and later.

Declared In

GKMatchmaker.h

inviteMessage

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

@property(nonatomic, copy) NSString *inviteMessage

Availability

Available in iOS 6.0 and later.

Declared In

GKMatchmaker.h

maxPlayers

The maximum number of players that may join the match.

@property(nonatomic, assign) NSUInteger maxPlayers

Discussion

The maximum number of players must be equal or greater than the minimum number of players. The maximum number of players may be no more than value returned by the maxPlayersAllowedForMatchOfType: method for the kind of match you plan to create.

Availability

Available in iOS 4.1 and later.

Declared In

GKMatchmaker.h

minPlayers

The minimum number of players that may join the match.

@property(nonatomic, assign) NSUInteger minPlayers

Discussion

The minimum number of players must be at least 2.

Availability

Available in iOS 4.1 and later.

Declared In

GKMatchmaker.h

playerAttributes

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

@property(nonatomic, assign) uint32_t playerAttributes

Discussion

If this value is 0 (the default), this property is ignored. If the value is nonzero, then automatching uses the value as a mask that restricts the role the player can play in the group. Automatching with player attributes matches new players into the game so that the bitwise OR of the masks of all the players in the resulting match equals 0xFFFFFFFF.

For more information, see Game Center Programming Guide.

Availability

Available in iOS 4.1 and later.

Declared In

GKMatchmaker.h

playerGroup

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

@property(nonatomic, assign) NSUInteger playerGroup

Discussion

If your game sets the playerGroup property, only players whose requests share the same playerGroup value are automatched by Game Center. The value of a player group is arbitrary. For example, you could define different playerGroup values to implement any of the following filters:

A game could restrict players based on skill level.
A game that provides multiple game modes could use it to filter players into the specific game they want to play.
A game that provides bonus content through in-app purchase could match players who own the same content with each other.

Availability

Available in iOS 4.1 and later.

Declared In

GKMatchmaker.h

playersToInvite

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

@property(nonatomic, retain) NSArray *playersToInvite

Discussion

The property holds an array of NSString objects, each of which is an identifier for a player on Game Center. If the value of the property is non-nil, when you use the request to create a match, Game Center invites those players to the match. If nil (the default), no players are invited. The exact behavior for matchmaking depends on the kind of match being created and the class used to create the match. For more information, see Game Center Programming Guide.

Availability

Available in iOS 4.1 and later.

Declared In

GKMatchmaker.h

Class Methods

maxPlayersAllowedForMatchOfType:

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

+ (NSUInteger)maxPlayersAllowedForMatchOfType:(GKMatchType)matchType

Parameters

matchType: The kind of match. See “Match Type.”

Return Value

The maximum number of allowed players for that type of match.

Availability

Available in iOS 6.0 and later.

Declared In

GKMatchmaker.h

Constants

Match Type

The kind of match being created.

enum {
   GKMatchTypePeerToPeer,
   GKMatchTypeHosted,
   GKMatchTypeTurnBased
};
typedef NSUInteger GKMatchType;

Constants

GKMatchTypePeerToPeer

A peer-to-peer match hosted by Game Center. It is represented by a GKMatch object.

Available in iOS 6.0 and later.

Declared in GKMatchmaker.h.

GKMatchTypeHosted

A match hosted on your private server.

Available in iOS 6.0 and later.

Declared in GKMatchmaker.h.

GKMatchTypeTurnBased

A turn-based match hosted by Game Center. It is represented by a GKTurnBasedMatch object.

Available in iOS 6.0 and later.

Declared in GKMatchmaker.h.

Invitee Responses

Possible responses from an invitation to a remote player.

enum {
   GKInviteeResponseAccepted           = 0,
   GKInviteeResponseDeclined           = 1,
   GKInviteeResponseFailed             = 2,
   GKInviteeResponseIncompatible       = 3,
   GKInviteeResponseUnableToConnect    = 4,
   GKInviteeResponseNoAnswer           = 5,
};
typedef NSInteger GKInviteeResponse;

Constants

GKInviteeResponseAccepted

The player accepted the invitation.

Available in iOS 6.0 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseDeclined

The player rejected the invitation.

Available in iOS 6.0 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseFailed

The invitation was unable to be delivered.

Available in iOS 6.0 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseIncompatible

The invitee is not running a compatible version of your game.

Available in iOS 6.0 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseUnableToConnect

The invitee could not be contacted.

Available in iOS 6.0 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseNoAnswer

The invitation timed out without an answer.

Available in iOS 6.0 and later.

Declared in GKMatchmaker.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.