GKMatch Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in iOS 4.1 and later.
Companion guide
Game Center Programming Guide
Declared in
GKMatch.h

Overview

A GKMatch object provides a peer-to-peer network between a group of devices that are connected to Game Center. Matches provide transmit both voice and game data. Your game never directly allocates GKMatch objects. Instead, it uses the GKMatchmaker class to programmatically find a match with other interested players or a GKMatchmakerViewController object to display a user interface to the player.

After your game receives a match object, set its delegate and then wait until the other participants are connected to the match. You can read the expectedPlayerCount property to determine how many players have not connected to the match.

Each device in the match is identified by the player identifier for the player authenticated on that device. Your game transmits its own data to other players by calling either the sendDataToAllPlayers:withDataMode:error: method or the sendData:toPlayers:withDataMode:error: method. To allow voice chat, call voiceChatWithName: to create one or more voice channels.

When you are finished with the match, call the match’s disconnect method.

Tasks

Getting and Setting the Delegate

Working with Other Players

Sending Data to Other Players

Joining a Voice Chat

Finishing the Match

Properties

delegate

The delegate for the match.

@property(nonatomic, assign) id<GKMatchDelegate> delegate
Discussion

You must set a delegate to receive data from other members of the match.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKMatch.h

expectedPlayerCount

The remaining number of players who have not yet connected to the match. (read-only)

@property(nonatomic, readonly) NSUInteger expectedPlayerCount
Discussion

The value of this property is decremented whenever a player connects to the match. When its value reaches 0, all expected players are connected, and your game can begin the match.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKMatch.h

playerIDs

The player identifiers for the players in the match. (read-only)

@property(nonatomic, readonly) NSArray *playerIDs
Discussion

The playerIDs property initially includes the player identifiers for any players already connected to the match; the array may initially be empty. As each new player connects to the match, that player’s identifier is added to the array.

Availability
  • Available in iOS 4.1 and later.
See Also
Declared In
GKMatch.h

Instance Methods

chooseBestHostPlayerWithCompletionHandler:

Determines the best player in the game to act as the server for a client-server match.

- (void)chooseBestHostPlayerWithCompletionHandler:(void (^)(NSString *playerID))completionHandler
Parameters
completionHandler

A block to be called after the score is reported.

The block receives the following parameter:

playerID

The player identifier for the player with the best estimated network performance, or nil if a player could not currently be determined.

Discussion

Calling this method causes Game Kit to attempt to estimate which player has the best overall network connection using a variety of metrics such as bandwidth, latency and network reliability. Typically, you call this method when your game implements a client-server model on top of the match’s peer-to-peer connection. See “Designing Your Network Game” in Game Center Programming Guide.

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 thread other than the one originally used to invoke the method. This means that the code in your block needs to be thread-safe.

Availability
  • Available in iOS 6.0 and later.
Declared In
GKMatch.h

disconnect

Disconnects the local player from the match.

- (void)disconnect
Discussion

Your game should call disconnect before removing the last strong reference to the match object. Calling disconnect notifies other players that you have left the match.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKMatch.h

rematchWithCompletionHandler:

Create a new match with the list of players from an existing match.

- (void)rematchWithCompletionHandler:(void (^)(GKMatch *match, NSError *error))completionHandler
Parameters
completionHandler

A block to be called after the match is created.

The block receives the following parameter:

match

The new match. If an error occurred, this parameter’s value is nil.

error

If an error occurred, this parameter holds an error object that describes the problem. If the match was successfully recreated, this parameter’s value is nil.

Discussion

Calling this method uses auto-matching to recreate a previous match. A new match with the same set of players is created and returned. If your game attempts to recreate matches using this method, each instance of your game on each device should call this method.

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 thread other than the one originally used to invoke the method. This means that the code in your block needs to be thread-safe.

Availability
  • Available in iOS 6.0 and later.
Declared In
GKMatch.h

sendData:toPlayers:withDataMode:error:

Transmits data to a list of connected players.

- (BOOL)sendData:(NSData *)data toPlayers:(NSArray *)*)playerIDs withDataMode:(GKMatchSendDataMode)mode error:(NSError **)error
Parameters
data

The bytes to be sent.

players

An array containing the identifier strings for the list of players who should receive the data.

mode

The mechanism used to send the data.

error

If the data could not be queued, on return, this parameter holds an NSError object describing the error.

Return Value

YES if the data was successfully queued for transmission; NO if the match was unable to queue the data.

Discussion

The match queues the data and transmits it when the network becomes available.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKMatch.h

sendDataToAllPlayers:withDataMode:error:

Transmits data to all players connected to the match.

- (BOOL)sendDataToAllPlayers:(NSData *)data withDataMode:(GKMatchSendDataMode)mode error:(NSError **)error
Parameters
data

The bytes to be sent.

mode

The mechanism used to send the data.

error

If the data could not be queued, on return, this parameter holds an NSError object describing the error.

Return Value

YES if the data was successfully queued for transmission; NO if the match was unable to queue the data.

Discussion

The match queues the data and transmits it when the network becomes available.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKMatch.h

voiceChatWithName:

Joins a voice channel.

- (GKVoiceChat *)voiceChatWithName:(NSString *)name
Parameters
name

The channel to join.

Return Value

An autoreleased voice chat object for the voice channel, or nil if an error occurred.

Discussion

Calling this method joins a voice channel, creating it if necessary. Your game should keep a strong reference to the voice chat object until the player leaves the channel. All participants who join a channel with the same name are connected to each other.

A single match can have multiple voice chat channels, and any player in the match can join multiple channels simultaneously. For example, a team-based game might create a channel for each team, and a single channel that includes all of the players.

Voice chat objects are dependent on the network connection provided by the match. When the player disconnects from the match, all voice channels associated with that match stop working. Typically, you should exit any voice channels and release any strong references to the channels before disconnecting from the match.

Parental controls may prevent a player from joining a voice chat. If the player is not permitted to join the voice channel, a nil object is returned to your application.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKMatch.h

Constants

Data Transmission Modes

The mechanism used to transmit data to other players.

enum {
   GKMatchSendDataReliable,
   GKMatchSendDataUnreliable
};
typedef NSInteger GKMatchSendDataMode;
Constants
GKMatchSendDataReliable

The data is sent continuously until it is successfully received by the intended recipients or the connection times out. Use this when you need to guarantee delivery and speed is not critical.

Reliable transmissions are delivered in the order they were sent.

Available in iOS 4.1 and later.

Declared in GKMatch.h.

GKMatchSendDataUnreliable

The data is sent once and is not sent again if a transmission error occurs. Use this for small packets of data that must arrive quickly to be useful to the recipient.

Data transmitted unreliably may be received out of order by recipients. Typically, you build your own game-specific error handling on top of this mechanism.

Available in iOS 4.1 and later.

Declared in GKMatch.h.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKMatch.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...