iOS Developer Library

Developer

GameKit Framework Reference GKMatch Class Reference

Options
Deployment Target:

On This Page
Language:

GKMatch

Inheritance


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later.

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.

  • delegate delegate Property

    The delegate for the match.

    Declaration

    Swift

    unowned(unsafe) var delegate: GKMatchDelegate!

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var expectedPlayerCount: Int { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • players players Property

    An array of GKPlayer objects that represent the players in the match. (read-only)

    Declaration

    Swift

    var players: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *players

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • playerIDs playerIDs (iOS 8.0) Property

    An array of NSString objects containing the player identifiers for remote players in the match. (read-only)

    Declaration

    Swift

    var playerIDs: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *playerIDs

    Discussion

    The playerIDs property initially includes the player identifiers for any remote 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. The player identifier for the local player is not included in this array.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 8.0.

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

    Declaration

    Swift

    func chooseBestHostingPlayerWithCompletionHandler(_ completionHandler: ((GKPlayer!) -> Void)!)

    Objective-C

    - (void)chooseBestHostingPlayerWithCompletionHandler:(void (^)(GKPlayer *player))completionHandler

    Parameters

    completionHandler

    A block to be called after the best player has been determined.

    The block receives the following parameter:

    player

    The GKPlayer object that identifies 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.

    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 8.0 and later.

  • Transmits data to a list of connected players.

    Declaration

    Swift

    func sendData(_ data: NSData!, toPlayers players: [AnyObject]!, dataMode mode: GKMatchSendDataMode, error error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)sendData:(NSData *)data toPlayers:(NSArray *)players dataMode:(GKMatchSendDataMode)mode error:(NSError **)error

    Parameters

    data

    The bytes to be sent.

    players

    An array of GKPlayer objects 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

    YEStrue if the data was successfully queued for transmission; NOfalse if the match was unable to queue the data.

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • Transmits data to all players connected to the match.

    Declaration

    Swift

    func sendDataToAllPlayers(_ data: NSData!, withDataMode mode: GKMatchSendDataMode, error error: NSErrorPointer) -> Bool

    Objective-C

    - (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

    YEStrue if the data was successfully queued for transmission; NOfalse if the match was unable to queue the data.

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func chooseBestHostPlayerWithCompletionHandler(_ completionHandler: ((String!) -> Void)!)

    Objective-C

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

    Parameters

    completionHandler

    A block to be called after the best player has been determined.

    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.

    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.

    Deprecated in iOS 8.0.

  • Transmits data to a list of connected players.

    Declaration

    Swift

    func sendData(_ data: NSData!, toPlayers playerIDs: [AnyObject]!, withDataMode mode: GKMatchSendDataMode, error error: NSErrorPointer) -> Bool

    Objective-C

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

    Parameters

    data

    The bytes to be sent.

    playerIDs

    An array of NSString objects 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

    YEStrue if the data was successfully queued for transmission; NOfalse if the match was unable to queue the data.

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 8.0.

  • Joins a voice channel.

    Declaration

    Swift

    func voiceChatWithName(_ name: String!) -> GKVoiceChat!

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • Disconnects the local player from the match.

    Declaration

    Swift

    func disconnect()

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func rematchWithCompletionHandler(_ completionHandler: ((GKMatch!, NSError!) -> Void)!)

    Objective-C

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

Data Types

  • The mechanism used to transmit data to other players.

    Declaration

    Swift

    enum GKMatchSendDataMode : Int { case Reliable case Unreliable }

    Objective-C

    enum { GKMatchSendDataReliable, GKMatchSendDataUnreliable }; typedef NSInteger GKMatchSendDataMode;

    Constants

    • Reliable

      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.0 and later.

    • Unreliable

      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.0 and later.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.