GKMatchRequest Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in OS X v10.8 and later.
Companion 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

GKTurnBasedMatchmakerViewController

Creating a match programmatically for a custom user interface

GKMatchmaker

GKTurnBasedMatch

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 OS X v10.9 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 OS X v10.9 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 OS X v10.9 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 OS X v10.8 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 OS X v10.8 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 0xFFFFFFFF (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 OS X v10.8 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 OS X v10.8 and later.
Declared In
GKMatchmaker.h

playersToInvite

A list of player identifiers 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. No automatching is done and the GKMatchRequest maxPlayers and minPlayers properties are ignored. 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 OS X v10.8 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 OS X v10.9 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 OS X v10.8 and later.

Declared in GKMatchmaker.h.

GKMatchTypeHosted

A match hosted on your private server.

Available in OS X v10.8 and later.

Declared in GKMatchmaker.h.

GKMatchTypeTurnBased

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

Available in OS X v10.8 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 OS X v10.8 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseDeclined

The player rejected the invitation.

Available in OS X v10.8 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseFailed

The invitation was unable to be delivered.

Available in OS X v10.8 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseIncompatible

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

Available in OS X v10.8 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseUnableToConnect

The invitee could not be contacted.

Available in OS X v10.8 and later.

Declared in GKMatchmaker.h.

GKInviteeResponseNoAnswer

The invitation timed out without an answer.

Available in OS X v10.8 and later.

Declared in GKMatchmaker.h.