Class: GKMatchmaker

Inherits:
NSObject show all

Overview

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

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (GKMatchmaker) sharedMatchmaker

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

Returns:

Instance Method Details

- (Object) addPlayersToMatch(match, matchRequest:matchRequest, completionHandler:completionHandler)

Adds players to an existing match. 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. Keep in mind that the completion handler may be called on a different thread than the thread originally used to invoke the method. This means that the code in your block needs to be thread safe.

Parameters:

  • match (GKMatch) —

    A previously created match.

  • matchRequest (GKMatchRequest) —

    The parameters for the new match request.

  • completionHandler (Object) —

    A block to be called when matchmaking completes.The block takes the following parameter:errorIf matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

  • error (NSError *error) —

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

Returns:

- (Object) cancel

Cancels a pending matchmaking request. The completion handler receives a callback with a GKErrorCancelled error.

Returns:

- (Object) cancelInviteToPlayer(playerID)

Cancels a pending invitation to another player.

Parameters:

  • playerID (String) —

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

Returns:

- (Object) findMatchForRequest(request, withCompletionHandler:completionHandler)

Initiates a request to find players for a peer-to-peer 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. Keep in mind that the completion handler may be called on a different thread than the thread originally used to invoke the method. This means that the code in your block needs to be thread safe.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.

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:matchIf matchmaking was successful, this parameter contains the created match. Otherwise, this parameter is nil.errorIf matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

  • 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.

Returns:

- (Object) findPlayersForHostedMatchRequest(request, withCompletionHandler:completionHandler)

Initiates a request to find players for a hosted 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. Keep in mind that the completion handler may be called on a different thread than the thread originally used to invoke the method. This means that the code in your block needs to be thread safe. 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.

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:playersIf matchmaking was successful, this parameter contains an array of players to connect into the match. Otherwise, this parameter is nil.errorIf matchmaking was successful, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

  • players —

    If matchmaking was successful, this parameter contains an array of 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.

Returns:

- (Object) finishMatchmakingForMatch(match)

Informs Game Center that programmatic matchmaking has finished. 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.

Parameters:

  • match (GKMatch) —

    The match that has completed the matchmaking process.

Returns:

- (Object) matchForInvite(invite, completionHandler:completionHandler)

Creates a match from an accepted invitation. 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. Keep in mind that the completion handler may be called on a different thread than the thread originally used to invoke the method. This means that the code in your block needs to be thread safe.

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:matchIf the match was successfully created, this parameter contains the created match. Otherwise, this parameter is nil.errorIf the match was successfully created, this parameter contains nil. Otherwise, this parameter holds an error object that describes the error that occurred.

  • 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.

Returns:

- (Object) queryActivityWithCompletionHandler(completionHandler)

Initiates a search for activity in all player groups. 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. Keep in mind that the completion handler may be called on a different thread than the thread originally used to invoke the method. This means that the code in your block needs to be thread safe.

Parameters:

  • completionHandler —

    A block that takes the following parameters:activityThe amount of activity in the player group.errorIf the search completed successfully, this parameter is nil; otherwise, this parameter holds an error object that describes the error that occurred.

  • activity —

    The amount of activity in the player group.

  • error —

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

Returns:

- (Object) queryPlayerGroupActivity(playerGroup, withCompletionHandler:completionHandler)

Queries Game Center for the activity in a player group. 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. Keep in mind that the completion handler may be called on a different thread than the thread originally used to invoke the method. This means that the code in your block needs to be thread safe.

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:activityThe amount of activity in the player group.errorIf the search completed successfully, this parameter is nil; otherwise, this parameter holds an error object that describes the error that occurred.

  • activity —

    The amount of activity in the player group.

  • error —

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

Returns:

- (Object) startBrowsingForNearbyPlayersWithReachableHandler(reachableHandler)

Enables the matchmaking process to find nearby players. 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.

Parameters:

  • reachableHandler —

    A block called when the reachability for a player changes. The block takes the following parameters:playerIDThe player identifier for the player whose reachability status has changed.reachableYES if a new player has been discovered locally, NO if a previously discovered player has disappeared.

  • playerID —

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

  • reachable —

    YES if a new player has been discovered locally, NO if a previously discovered player has disappeared.

Returns:

- (Object) stopBrowsingForNearbyPlayers

Ends the search for nearby players.

Returns: