iOS Developer Library

Developer

GameKit Framework Reference GKMatchmaker Class Reference

Options
Deployment Target:

On This Page
Language:

GKMatchmaker

Inherits From


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later

The GKMatchmaker class is used to programmatically create matches to other players and to receive match invitations sent by other players.

Matches can be either peer-to-peer or hosted. A peer-to-peer match is fully supported in Game Kit by the GKMatch class. A GKMatch object provides all of the network connections between the devices and routes the network data through Game Center if necessary. In contrast, a hosted match uses matchmaking to find the players for a match, but your game implements its own networking between the participants, routing through your own server if necessary.

To receive invitations from other players, your game must provide an invitation handler. After your game successfully authenticates the local player, it should immediately set the inviteHandler property. The invite handler is called immediately if your game was launched in response to a push notification.

To programmatically search for other players, start by creating a GKMatchRequest object that describes the match you are interested in. Then, call the shared matchmaker’s findMatchForRequest:withCompletionHandler: method to create a peer-to-peer match, or its findPlayersForHostedMatchRequest:withCompletionHandler: method to create a hosted match. In either case, Game Center matches players into a match and calls your completion handler. If the match does not have enough players (for example, you invited a specific list of players and some declined the invitation), you can create another match request and call the addPlayersToMatch:matchRequest:completionHandler: method to add more participants to the match. Once the match is complete, call the finishMatchmakingForMatch: method.

If you implement programmatic matchmaking and invite specific players to the match, you should also implement an invitee response handler. This handler is notified as invitations are processed, allowing you to update your game’s custom user interface to display which players are connected to the match.

  • Returns the singleton matchmaker instance.

    Declaration

    Swift

    class func sharedMatchmaker() -> GKMatchmaker!

    Objective-C

    + (GKMatchmaker *)sharedMatchmaker

    Return Value

    The shared matchmaker instance.

    Discussion

    Games do not create a GKMatchmaker object. Instead, they retrieve the shared singleton by calling this method.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • Creates a match from an accepted invitation.

    Declaration

    Swift

    func matchForInvite(_ invite: GKInvite!, completionHandler completionHandler: ((GKMatch!, NSError!) -> Void)!)

    Objective-C

    - (void)matchForInvite:(GKInvite *)invite completionHandler:(void (^)(GKMatch *match, NSError *error))completionHandler

    Parameters

    invite

    The invitation accepted by the player.

    completionHandler

    A block to be called when the match has been created. This block receives the following parameters:

    match

    If the match was successfully created, this parameter contains the created match. Otherwise, this parameter is nil.

    error

    If the match was successfully created, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

    Discussion

    When using this method to create a match, your game should display its own user interface to inform the player that he or she has been connected to a match.

    When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

    See Also

    inviteHandler

  • inviteHandler inviteHandler (iOS 7.0) Property

    A block to be called when an invitation to join a match is accepted by the local player.

    Declaration

    Objective-C

    @property(nonatomic, copy) void (^inviteHandler)( GKInvite *acceptedInvite, NSArray *playerIDsToInvite)

    Discussion

    The block takes the following parameters:

    acceptedInvite

    The invitation accepted by the player.

    playerIDsToInvite

    An array of NSString objects containing player identifiers for additional players to invite into the game.

    Your block should respond to the invitation in one of two ways:

    • Display the standard user interface by initializing a new GKMatchmakerViewController object, passing the invitation object and the list of player identifiers as parameters.

    • Create a match programmatically by calling the matchForInvite:completionHandler: method on the shared matchmaker instance.

    If your game receives an invitation while it is already running, it should transition to multiplayer play. It should clean up any existing content, such as ending the current match the player is playing, and then process the invitation.

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 7.0

  • Adds players to an existing match.

    Declaration

    Swift

    func addPlayersToMatch(_ match: GKMatch!, matchRequest matchRequest: GKMatchRequest!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)addPlayersToMatch:(GKMatch *)match matchRequest:(GKMatchRequest *)matchRequest completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    match

    A previously created match.

    matchRequest

    The parameters for the new match request.

    completionHandler

    A block to be called when matchmaking completes.

    The block takes the following parameter:

    error

    If matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

    Discussion

    This method updates an existing match object by adding additional players.

    When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • Cancels a pending matchmaking request.

    Declaration

    Swift

    func cancel()

    Objective-C

    - (void)cancel

    Discussion

    The completion handler receives a callback with a GKErrorCancelled error.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • Cancels a pending invitation to another player.

    Declaration

    Swift

    func cancelPendingInviteToPlayer(_ player: GKPlayer!)

    Objective-C

    - (void)cancelPendingInviteToPlayer:(GKPlayer *)player

    Parameters

    player

    The GKPlayer object that identifies a player previously invited to the match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

  • Initiates a request to find players for a peer-to-peer match.

    Declaration

    Swift

    func findMatchForRequest(_ request: GKMatchRequest!, withCompletionHandler completionHandler: ((GKMatch!, NSError!) -> Void)!)

    Objective-C

    - (void)findMatchForRequest:(GKMatchRequest *)request withCompletionHandler:(void (^)(GKMatch *match, NSError *error))completionHandler

    Parameters

    request

    The configuration for the desired match.

    completionHandler

    A block to be called when the match has been created. This block receives the following parameters:

    match

    If matchmaking was successful, this parameter contains the created match. Otherwise, this parameter is nil.

    error

    If matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

    Discussion

    When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

    On iOS 6, if the match request’s playersToInvite property is non-NIL, Game Center sends invitations only out to the players listed in the property. If the playersToInvite property is NIL, then it searches for any waiting players that match the request. If your game wants to perform programmatic matchmaking for the remaining slots, it should call the addPlayersToMatch:matchRequest:completionHandler: method with a match request whose playersToInvite property is NIL.

    Listing 1 shows how to programmatically request a match. The code creates a match request, retrieves the matchmaker singleton object and asks it to find a match for the player. The match’s completion handler is called when a match is found or if an error occurs. If a match is returned to the completion handler, the match is assigned to a property. As before, your game executes code to determine whether the match is ready to begin.

    Listing 1Programmatically finding a match
    • - (IBAction)findProgrammaticMatch: (id) sender
    • {
    • GKMatchRequest *request = [[GKMatchRequest alloc] init];
    • request.minPlayers = 2;
    • request.maxPlayers = 4;
    • [[GKMatchmaker sharedMatchmaker] findMatchForRequest:request withCompletionHandler:^(GKMatch *match, NSError *error) {
    • if (error)
    • {
    • // Process the error.
    • }
    • else if (match != nil)
    • {
    • self.myMatch = match; // Use a retaining property to retain the match.
    • match.delegate = self;
    • if (!self.matchStarted && match.expectedPlayerCount == 0)
    • {
    • self.matchStarted = YES;
    • // Insert game-specific code to begin the match.
    • }
    • }
    • }];
    • }

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

    See Also

    – cancel

  • Initiates a request to find players for a hosted match.

    Declaration

    Swift

    func findPlayersForHostedRequest(_ request: GKMatchRequest!, withCompletionHandler completionHandler: (([AnyObject]!, NSError!) -> Void)!)

    Objective-C

    - (void)findPlayersForHostedRequest:(GKMatchRequest *)request withCompletionHandler:(void (^)(NSArray *players, NSError *error))completionHandler

    Parameters

    request

    The configuration for the desired match.

    completionHandler

    A block to be called when the match has been created. This block receives the following parameters:

    players

    If matchmaking was successful, this parameter contains an array of GKPlayer objects containing the players to connect into the match. Otherwise, this parameter is nil.

    error

    If matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

    Discussion

    When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread. When your completion handler is called, your game should connect those players to your own server.

    On iOS 6, if the match request’s playersToInvite property is non-NIL, Game Center sends invitations only out to the players listed in the property. If the playersToInvite property is NIL, then it searches for any waiting players that match the request. Prior to iOS 6, the match request’s playersToInvite property is ignored and this method only searches for available players.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

  • Informs Game Center that programmatic matchmaking has finished.

    Declaration

    Swift

    func finishMatchmakingForMatch(_ match: GKMatch!)

    Objective-C

    - (void)finishMatchmakingForMatch:(GKMatch *)match

    Parameters

    match

    The match that has completed the matchmaking process.

    Discussion

    If your game uses programmatic matchmaking, it makes a series of calls to the findMatchForRequest:withCompletionHandler: and addPlayersToMatch:matchRequest:completionHandler: methods to fill a match with players. When the match has the proper number of players, call thefinishMatchmakingForMatch: method before starting the match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

  • Initiates a search for activity in all player groups.

    Declaration

    Swift

    func queryActivityWithCompletionHandler(_ completionHandler: ((Int, NSError!) -> Void)!)

    Objective-C

    - (void)queryActivityWithCompletionHandler:(void (^)(NSInteger activity, NSError *error))completionHandler

    Parameters

    completionHandler

    A block that takes the following parameters:

    activity

    The number of match requests for all player groups during the previous 60 seconds.

    error

    If the search completed successfully, this parameter is nil; otherwise, this parameter holds an error object that describes the error that occurred.

    Discussion

    A query allows your game to see how many players have recently searched for a match, across all player groups.

    When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

  • Queries Game Center for the activity in a player group.

    Declaration

    Swift

    func queryPlayerGroupActivity(_ playerGroup: Int, withCompletionHandler completionHandler: ((Int, NSError!) -> Void)!)

    Objective-C

    - (void)queryPlayerGroupActivity:(NSUInteger)playerGroup withCompletionHandler:(void (^)(NSInteger activity, NSError *error))completionHandler

    Parameters

    playerGroup

    A number that uniquely identifies a subset of players of your game.

    completionHandler

    A block that is called when the search completes. The block takes the following parameters:

    activity

    The number of match requests for the player group during the previous 60 seconds.

    error

    If the search completed successfully, this parameter is nil; otherwise, this parameter holds an error object that describes the error that occurred.

    Discussion

    A query allows your game to see how many players have recently searched for a match. As a result, you can present a user interface that shows the relative activity in each player group. For example, if one group sees less activity than others, you might display a warning so that players are aware that finding a match may take longer.

    When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • Cancels a pending invitation to another player.

    Declaration

    Swift

    func cancelInviteToPlayer(_ playerID: String!)

    Objective-C

    - (void)cancelInviteToPlayer:(NSString *)playerID

    Parameters

    playerID

    The player identifier for a player previously invited to the match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

    Deprecated in iOS 8.0

  • Initiates a request to find players for a hosted match.

    Declaration

    Swift

    func findPlayersForHostedMatchRequest(_ request: GKMatchRequest!, withCompletionHandler completionHandler: (([AnyObject]!, NSError!) -> Void)!)

    Objective-C

    - (void)findPlayersForHostedMatchRequest:(GKMatchRequest *)request withCompletionHandler:(void (^)(NSArray *playerIDs, NSError *error))completionHandler

    Parameters

    request

    The configuration for the desired match.

    completionHandler

    A block to be called when the match has been created. This block receives the following parameters:

    playerIDs

    If matchmaking was successful, this parameter contains an array of NSString objects containing the players to connect into the match. Otherwise, this parameter is nil.

    error

    If matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

    Discussion

    When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread. When your completion handler is called, your game should connect those players to your own server.

    On iOS 6, if the match request’s playersToInvite property is non-NIL, Game Center sends invitations only out to the players listed in the property. If the playersToInvite property is NIL, then it searches for any waiting players that match the request. Prior to iOS 6, the match request’s playersToInvite property is ignored and this method only searches for available players.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 8.0

    See Also

    – cancel

  • Enables the matchmaking process to find nearby players through Bluetooth or WiFi (same subnet only).

    Declaration

    Swift

    func startBrowsingForNearbyPlayersWithHandler(_ reachableHandler: ((GKPlayer!, Bool) -> Void)!)

    Objective-C

    - (void)startBrowsingForNearbyPlayersWithHandler:(void (^)(GKPlayer *player, BOOL reachable))reachableHandler

    Parameters

    reachableHandler

    A block called when the reachability for a player changes. The block takes the following parameters:

    player

    The GKPlayer object that identifies the player whose reachability status has changed.

    reachable

    YEStrue if a new player has been discovered locally, NOfalse if a previously discovered player has disappeared.

    Discussion

    You only use this method when you are implementing programmatic matchmaking. After enabling browsing for nearby players, use the responses to populate your user interface with information about nearby players. If a player wants to invite a player to a game, add that player’s player identifier to a match request and call either the findMatchForRequest:withCompletionHandler: to create a match or addPlayersToMatch:matchRequest:completionHandler: method to update a match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

  • Ends the search for nearby players.

    Declaration

    Swift

    func stopBrowsingForNearbyPlayers()

    Objective-C

    - (void)stopBrowsingForNearbyPlayers

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

  • Enables the matchmaking process to find nearby players through Bluetooth or WiFi (same subnet only).

    Declaration

    Swift

    func startBrowsingForNearbyPlayersWithReachableHandler(_ reachableHandler: ((String!, Bool) -> Void)!)

    Objective-C

    - (void)startBrowsingForNearbyPlayersWithReachableHandler:(void (^)(NSString *playerID, BOOL reachable))reachableHandler

    Parameters

    reachableHandler

    A block called when the reachability for a player changes. The block takes the following parameters:

    playerID

    The player identifier for the player whose reachability status has changed.

    reachable

    YEStrue if a new player has been discovered locally, NOfalse if a previously discovered player has disappeared.

    Discussion

    You only use this method when you are implementing programmatic matchmaking. After enabling browsing for nearby players, use the responses to populate your user interface with information about nearby players. If a player wants to invite a player to a game, add that player’s player identifier to a match request and call either the findMatchForRequest:withCompletionHandler: to create a match or addPlayersToMatch:matchRequest:completionHandler: method to update a match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

    Deprecated in iOS 8.0