Mac Developer Library

Developer

GameKit Framework Reference GKMatchmaker Class Reference

Options
Deployment Target:

On This Page
Language:

GKMatchmaker

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

Inheritance


Conforms To


Import Statement


import GameKit @import GameKit;

Availability


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

    import GameKit

    Availability

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

    import GameKit

    Availability

    Available in OS X v10.9 and later.

    See Also

    inviteHandler

  • inviteHandler inviteHandler (OS X v10.10) Property

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

    Declaration

    Swift

    var inviteHandler: ((GKInvite!, [AnyObject]!) -> Void)!

    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

    import GameKit

    Availability

    Available in OS X v10.8 and later.

    Deprecated in OS X v10.10.

  • 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

    import GameKit

    Availability

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

    import GameKit

    Availability

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

    import GameKit

    Availability

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

    Prior to iOS 6, the match request’s playersToInvite property is ignored and this method only searches for available players.

    Import Statement

    import GameKit

    Availability

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

    import GameKit

    Availability

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

    import GameKit

    Availability

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

    import GameKit

    Availability

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

    import GameKit

    Availability

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

    import GameKit

    Availability

    Available in OS X v10.9 and later.

    Deprecated in OS X v10.10.

  • 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

    import GameKit

    Availability

    Available in OS X v10.8 and later.

    Deprecated in OS X v10.10.

    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

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • Ends the search for nearby players.

    Declaration

    Swift

    func stopBrowsingForNearbyPlayers()

    Objective-C

    - (void)stopBrowsingForNearbyPlayers

    Import Statement

    import GameKit

    Availability

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

    import GameKit

    Availability

    Available in OS X v10.9 and later.

    Deprecated in OS X v10.10.