iOS Developer Library

Developer

GameKit Framework Reference GKMatchRequest Class Reference

Options
Deployment Target:

On This Page
Language:

GKMatchRequest

Inherits From


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later

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 1The 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 1A 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 Class Reference for details.

Listing 2Programmatically 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)];
  • };
  • ...
  • }
  • Returns the maximum number of players allowed in the match request for a given match type.

    Declaration

    Swift

    class func maxPlayersAllowedForMatchOfType(_ matchType: GKMatchType) -> Int

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

  • The maximum number of players that may join the match.

    Declaration

    Swift

    var maxPlayers: Int

    Objective-C

    @property(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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • The minimum number of players that may join the match.

    Declaration

    Swift

    var minPlayers: Int

    Objective-C

    @property(assign) NSUInteger minPlayers

    Discussion

    The minimum number of players must be at least 2.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • The default number of players for the match.

    Declaration

    Swift

    var defaultNumberOfPlayers: Int

    Objective-C

    @property(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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

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

    Declaration

    Swift

    var inviteMessage: String!

    Objective-C

    @property(copy) NSString *inviteMessage

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

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

    Declaration

    Swift

    var playerGroup: Int

    Objective-C

    @property(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. Setting the playerGroup property to 0 allows the player to be matched into any waiting match. Set the playerGroup property to a nonzero number to match the player only with players whose match request shares the same player group number. 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.

    Listing 3 shows how you might configure a match request that uses a player group. In this example, the player group value is calculated by choosing both the map the player wants to play on and the rules set under which the player wants to play. A constant for each is chosen and the two are bitwise ORed together to create a unique number for the player group. Game Center only searches for other players with the same map and group combination.

    Listing 3Creating a player group based on the map and rule set
    • GKMatchRequest *request = [[GKMatchRequest alloc] init];
    • request.minPlayers = 2;
    • request.maxPlayers = 4;
    • request.playerGroup = MyMap_Forest | MyRulesCaptureTheFlag;

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    var playerAttributes: UInt32

    Objective-C

    @property(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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

  • playersToInvite playersToInvite (iOS 8.0) Property

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

    Declaration

    Swift

    var playersToInvite: [AnyObject]!

    Objective-C

    @property(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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 8.0

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

    Declaration

    Swift

    var recipients: [AnyObject]!

    Objective-C

    @property(retain) NSArray *recipients

    Discussion

    The property holds an array of GKPlayer objects, each of which contains 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 GKMatchRequestmaxPlayers 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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

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

    Declaration

    Swift

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

    Objective-C

    @property(copy) void (^recipientResponseHandler)( GKPlayer *player, GKInviteRecipientResponse response)

    Discussion

    The block takes the following parameters:

    player

    The GKPlayer object associated with the invited player.

    GKInviteeRecipientResponse

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

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

    Declaration

    Swift

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

    Objective-C

    @property(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 (Deprecated in iOS 8).

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

    Deprecated in iOS 8.0

  • The kind of match being created.

    Declaration

    Swift

    enum GKMatchType : UInt { case PeerToPeer case Hosted case TurnBased }

    Objective-C

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

    Constants

    • PeerToPeer

      GKMatchTypePeerToPeer

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

      Available in iOS 6.0 and later

    • Hosted

      GKMatchTypeHosted

      A match hosted on your private server.

      Available in iOS 6.0 and later

    • TurnBased

      GKMatchTypeTurnBased

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

      Available in iOS 6.0 and later

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

  • Possible responses from an invitation to a remote player.

    Declaration

    Swift

    enum GKInviteRecipientResponse : Int { case InviteRecipientResponseAccepted case InviteRecipientResponseDeclined case InviteRecipientResponseFailed case InviteRecipientResponseIncompatible case InviteRecipientResponseUnableToConnect case InviteRecipientResponseNoAnswer }

    Objective-C

    enum { GKInviteRecipientResponseAccepted = 0, GKInviteRecipientResponseDeclined = 1, GKInviteRecipientResponseFailed = 2, GKInviteRecipientResponseIncompatible = 3, GKInviteRecipientResponseUnableToConnect = 4, GKInviteRecipientResponseNoAnswer = 5, }; typedef NSInteger GKInviteRecipientResponse;

    Constants

    • InviteRecipientResponseAccepted

      GKInviteRecipientResponseAccepted

      The player accepted the invitation.

      Available in iOS 8.0 and later

    • InviteRecipientResponseDeclined

      GKInviteRecipientResponseDeclined

      The player rejected the invitation.

      Available in iOS 8.0 and later

    • InviteRecipientResponseFailed

      GKInviteRecipientResponseFailed

      The invitation was unable to be delivered.

      Available in iOS 8.0 and later

    • InviteRecipientResponseIncompatible

      GKInviteRecipientResponseIncompatible

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

      Available in iOS 8.0 and later

    • InviteRecipientResponseUnableToConnect

      GKInviteRecipientResponseUnableToConnect

      The invitee could not be contacted.

      Available in iOS 8.0 and later

    • InviteRecipientResponseNoAnswer

      GKInviteRecipientResponseNoAnswer

      The invitation timed out without an answer.

      Available in iOS 8.0 and later

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

  • Possible responses from an invitation to a remote player.

    Deprecated in iOS 8. Use GKInviteeRecipientResponse enum instead.

    Declaration

    Swift

    typealias GKInviteeResponse = GKInviteRecipientResponse

    Objective-C

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

    Constants

    • GKInviteeResponseAccepted

      GKInviteeResponseAccepted

      The player accepted the invitation.

      Available in iOS 6.0 and later

    • GKInviteeResponseDeclined

      GKInviteeResponseDeclined

      The player rejected the invitation.

      Available in iOS 6.0 and later

    • GKInviteeResponseFailed

      GKInviteeResponseFailed

      The invitation was unable to be delivered.

      Available in iOS 6.0 and later

    • GKInviteeResponseIncompatible

      GKInviteeResponseIncompatible

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

      Available in iOS 6.0 and later

    • GKInviteeResponseUnableToConnect

      GKInviteeResponseUnableToConnect

      The invitee could not be contacted.

      Available in iOS 6.0 and later

    • GKInviteeResponseNoAnswer

      GKInviteeResponseNoAnswer

      The invitation timed out without an answer.

      Available in iOS 6.0 and later

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later