Mac Developer Library

Developer

GameKit Framework Reference GKMatchRequest Class Reference

Options
Deployment Target:

On This Page
Language:

GKMatchRequest

Inheritance


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


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

  • 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 OS X v10.9 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 OS X v10.8 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 OS X v10.8 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 OS X v10.8 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 OS X v10.8 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. 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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

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

  • playersToInvite playersToInvite (OS X v10.10) 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 OS X v10.8 and later.

    Deprecated in OS X v10.10.

  • 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. For more information, see Game Center Programming Guide.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

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

    Deprecated in OS X v10.10.

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

    • Hosted

      GKMatchTypeHosted

      A match hosted on your private server.

      Available in OS X v10.8 and later.

    • TurnBased

      GKMatchTypeTurnBased

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

      Available in OS X v10.8 and later.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

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

    • InviteRecipientResponseDeclined

      GKInviteRecipientResponseDeclined

      The player rejected the invitation.

      Available in OS X v10.10 and later.

    • InviteRecipientResponseFailed

      GKInviteRecipientResponseFailed

      The invitation was unable to be delivered.

      Available in OS X v10.10 and later.

    • InviteRecipientResponseIncompatible

      GKInviteRecipientResponseIncompatible

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

      Available in OS X v10.10 and later.

    • InviteRecipientResponseUnableToConnect

      GKInviteRecipientResponseUnableToConnect

      The invitee could not be contacted.

      Available in OS X v10.10 and later.

    • InviteRecipientResponseNoAnswer

      GKInviteRecipientResponseNoAnswer

      The invitation timed out without an answer.

      Available in OS X v10.10 and later.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

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

    • GKInviteeResponseDeclined

      GKInviteeResponseDeclined

      The player rejected the invitation.

      Available in OS X v10.8 and later.

    • GKInviteeResponseFailed

      GKInviteeResponseFailed

      The invitation was unable to be delivered.

      Available in OS X v10.8 and later.

    • GKInviteeResponseIncompatible

      GKInviteeResponseIncompatible

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

      Available in OS X v10.8 and later.

    • GKInviteeResponseUnableToConnect

      GKInviteeResponseUnableToConnect

      The invitee could not be contacted.

      Available in OS X v10.8 and later.

    • GKInviteeResponseNoAnswer

      GKInviteeResponseNoAnswer

      The invitation timed out without an answer.

      Available in OS X v10.8 and later.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.