Mac Developer Library

Developer

GameKit Framework Reference GKTurnBasedMatch Class Reference

Options
Deployment Target:

On This Page
Language:

GKTurnBasedMatch

Inheritance


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in OS X v10.8 and later.

The GKTurnBasedMatch class allows your game to implement turn-based matches between sets of players on Game Center. A turn-based match uses a store-and-forward approach to share data between the participants. When a player participating in the match performs actions that advance the state of the match, your game describes the new state of the match and decides which player acts next. The next player to act is notified by a push notification. Later, when the next player launches your game, you download the match data from Game Center and continue the match. Players take turns acting (based on whatever internal logic your game implements) until the match ends. One advantage of turn-based matches is that a player may participate in multiple matches simultaneously.

Your game never directly creates GKTurnBasedMatch objects, because a match always represents an existing match that is stored by Game Center. Instead, match objects are created for your game by Game Kit. A match object may hold a newly created match (for a match that has not started yet) or a match that is already under way. Here are ways your game acquires match objects:

A match object contains a few essential properties:

  • The participants property contains an array of GKTurnBasedParticipant objects. Each identifies a player in the match along with the current status of that player.

  • The currentParticipant property contains the GKTurnBasedParticipant object for the player who must act to advance the state of the match.

  • The matchData property holds binary data that describes the current state of the match. The format of the data contained in this object is something you design when you create your game; Game Kit only manages storing and forwarding of this data.

When a player views a particular match, your game should take the match object and call its loadMatchDataWithCompletionHandler: method to retrieve the match data. After the match data is downloaded from Game Center, your game parses the data and displays the game’s user interface. A player may want to view the match even when it is another player’s turn to act; your game should expect this and allow the player to view the state of the match without allowing them to act. When the current player views the match, your game should both show them the state of the match and provide a user interface to allow the player to take a turn. The current player is expected to perform actions that change the state of the match. These actions are based on the internal logic of your game’s rules. The player continues to act until he or she takes an action that requires another person in the match to act in order to advance the match. For example, in a game like Chess, moving a piece on the board and passing control to the other participant happen simultaneously. A more complex game might allow the current player to take multiple actions before the match reaches a state in which control is ceded to another player.

If the player takes an action that is irrevocable (but control is not yet passed to another player), you update the match data by calling the saveCurrentTurnWithMatchData:completionHandler: method.

Once the player takes an action that requires another player to act, your game should determine which player needs to act next. Then, it should encode the state of the match into an NSData object and call the match object’s endTurnWithNextParticipants:turnTimeout:matchData:completionHandler: method to set the next player to act. The next player is automatically informed that the match is waiting on his or her actions in order to continue the match.

As the match progresses, players may leave the match. For example, this situation might occur if your game determines that this player has been eliminated from the match. Or your game might offer a user interface to allow players to resign from matches. If the local player resigns from the match and is also the match’s current player, your game must call the match object’s participantQuitInTurnWithOutcome:nextParticipant:matchData:completionHandler: method. As it does when the player takes a turn, your game passes in the state of the match and the next player to act. Your game also provides a match outcome — essentially, a numerical value that indicates the reason why that player left the match. If your game allows players to resign from matches when it is not that player’s turn, your game calls the match object’s participantQuitOutOfTurnWithOutcome:withCompletionHandler: method to allow the player to leave the match.

Eventually, a match ends. When your game logic dictates that a match should end, your game calls the match object’s endMatchInTurnWithMatchData:completionHandler: method. Your game must ensure that all participants in the match have a valid match outcome before ending the match.

Even after a match ends, its data is still stored on Game Center; this allows players to view previous victories and defeats. A player may choose to delete the match using the standard user interface, but your game can also programmatically remove a match by calling the match object’s removeWithCompletionHandler: method. In all cases, the decision to delete a match should be made by a player; the removeWithCompletionHandler: method exists to allow your game to present a custom user interface for viewing and working with matches.

Subclassing Notes

The GKTurnBasedMatch class may not be subclassed.

  • Loads the turn-based matches involving the local player and creates a match object for each match.

    Declaration

    Swift

    class func loadMatchesWithCompletionHandler(_ completionHandler: (([AnyObject]!, NSError!) -> Void)!)

    Objective-C

    + (void)loadMatchesWithCompletionHandler:(void (^)(NSArray *matches, NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called after the matches are retrieved from the server.

    The block receives the following parameters:

    matches

    An array of GKTurnBased Match objects containing the match objects for matches that the local player is playing in, or nil if there are no matches to load. If an error occurred, this value may be non-nil. In this case, the array holds whatever match data could be retrieved from Game Center before the error occurred.

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Loads a specific match.

    Declaration

    Swift

    class func loadMatchWithID(_ matchID: String!, withCompletionHandler completionHandler: ((GKTurnBasedMatch!, NSError!) -> Void)!)

    Objective-C

    + (void)loadMatchWithID:(NSString *)matchID withCompletionHandler:(void (^)(GKTurnBasedMatch *match, NSError *error))completionHandler

    Parameters

    matchID

    The identifier for the turn-based match.

    completionHandler

    A block to be called after the match is retrieved from the server.

    The block receives the following parameters:

    match

    If the operation completed successfully, this parameter holds the match. If an error occurred, the value is nil.

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Programmatically searches for a new match to join.

    Declaration

    Swift

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

    Objective-C

    + (void)findMatchForRequest:(GKMatchRequest *)request withCompletionHandler:(void (^)(GKTurnBasedMatch *match, NSError *error))completionHandler

    Parameters

    request

    A match request that specifies the properties that the new match must fulfill.

    completionHandler

    A block to be called after the match is successfully created.

    The block receives the following parameters:

    match

    A newly initialized match object that contains a list of players for the match. If an error occurred, this value is nil.

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    When this method is called, it creates a 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.

    This method may either create a new match or it may place the player into an existing match that needs a new player to advance the match further. Regardless of how the player is placed in the match, the local player is always the current participant in the returned match. Your game should immediately display the match in its user interface and allow the player to take a turn.

    To be consistent with older servers and versions of iOS, the minimum number of players specified by the GKMatchRequest object is set to be equal to the maximum number of players when looking for a match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Programmatically accept an invitation to a turn-based match.

    Declaration

    Swift

    func acceptInviteWithCompletionHandler(_ completionHandler: ((GKTurnBasedMatch!, NSError!) -> Void)!)

    Objective-C

    - (void)acceptInviteWithCompletionHandler:(void (^)(GKTurnBasedMatch *match, NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called after the match is successfully created.

    The block receives the following parameters:

    match

    A newly initialized match object that contains a list of players for the match. If an error occurred, this value is nil.

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Programmatically decline an invitation to a turn-based match.

    Declaration

    Swift

    func declineInviteWithCompletionHandler(_ completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)declineInviteWithCompletionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called after the match is successfully created.

    The block receives the following parameter:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Create a new turn-based match with the same participants as an existing match.

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    completionHandler

    A block to be called after the match is successfully created.

    The block receives the following parameters:

    match

    A newly initialized match object that contains a list of players for the match. If an error occurred, this value is nil.

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.9 and later.

  • The date that the match was created. (read-only)

    Declaration

    Swift

    var creationDate: NSDate! { get }

    Objective-C

    @property(readonly, retain, atomic) NSDate *creationDate

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • The participant whose turn it is to act next. (read-only)

    Declaration

    Swift

    var currentParticipant: GKTurnBasedParticipant! { get }

    Objective-C

    @property(readonly, retain, atomic) GKTurnBasedParticipant *currentParticipant

    Discussion

    The current participant is the only participant that is allowed to update the match data.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • matchID matchID Property

    A string that uniquely identifies the match. (read-only)

    Declaration

    Swift

    var matchID: String! { get }

    Objective-C

    @property(readonly, retain, atomic) NSString *matchID

    Discussion

    This string is not intended to be displayed to players. Your game should use this string whenever it needs to identify a specific match. For example, if you want your game to store additional information on a device or in iCloud, it might store it in a database using the match ID as a key.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • message message Property

    A message displayed to all players in the match.

    Declaration

    Swift

    var message: String!

    Objective-C

    @property(readwrite, copy, atomic) NSString *message

    Discussion

    The message property is displayed by the standard user interface; this allows your game to use the message to inform players of the current state of the match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Information about the players participating in the match. (read-only)

    Declaration

    Swift

    var participants: [AnyObject]! { get }

    Objective-C

    @property(readonly, retain, atomic) NSArray *participants

    Discussion

    The elements of this array are GKTurnBasedParticipant objects representing each participant in the match. Your game uses these objects to retrieve more information about the participants in the match. Your game also uses one of the objects in this array as a parameter whenever it calls a method that sets a different participant to act in the match.

    The size of the array and the order in which the participants appear in the array are set when the match is first created, and never changes. When a match is first created, some participants may not hold actual players yet. Game Center searches for a player to fill that spot in the match only after your game sets that participant as the current player.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • status status Property

    The current state of the match. (read-only)

    Declaration

    Swift

    var status: GKTurnBasedMatchStatus { get }

    Objective-C

    @property(readonly, atomic) GKTurnBasedMatchStatus status

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Returns the limit the Game Center servers place on the size of the match data. (read-only)

    Declaration

    Swift

    var matchDataMaximumSize: Int { get }

    Objective-C

    @property(readonly, atomic) NSUInteger matchDataMaximumSize

    Discussion

    Game Kit returns an error if your game sends updated data larger than this value.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • matchData matchData Property

    Game-specific data that reflects the details of the match. (read-only)

    Declaration

    Swift

    var matchData: NSData! { get }

    Objective-C

    @property(readonly, retain, atomic) NSData *matchData

    Discussion

    Although Game Center knows who is participating in the match and who is expected to act next, it does not know anything about your game’s internal logic. Your game provides the match data and all the programming logic required to interpret it. This data should include the current state of the game and provide any necessary details about what actions the current player is expected to take. It can also be helpful for your game to record information about recent moves made by other players. The game can then replay those moves visually for the player to show exactly how the match reached the state it is in now.

    Your game never directly updates the match state associated with this property. Instead, when the data is updated to reflect the actions of the current player, your game serializes the updated state into memory and calls one of the match’s instance methods that transmit the updated state to Game Center.

    The value of this property is nil until after your game calls the loadMatchDataWithCompletionHandler: method and the load task is complete. After this task completes, the matchData property holds the data that the last player to act transmitted to Game Center.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Loads the game-specific data associated with a match, including all exchanges.

    Declaration

    Swift

    func loadMatchDataWithCompletionHandler(_ completionHandler: ((NSData!, NSError!) -> Void)!)

    Objective-C

    - (void)loadMatchDataWithCompletionHandler:(void (^)(NSData *matchData, NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called after the match data is retrieved from the server.

    The block receives the following parameters:

    matchData

    The data stored on Game Center that reflects the current state of the match. If an error occurred, this value is nil.

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Update the match data without advancing the game to another player.

    Declaration

    Swift

    func saveCurrentTurnWithMatchData(_ matchData: NSData!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)saveCurrentTurnWithMatchData:(NSData *)matchData completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    matchData

    A serialized blob of data reflecting the game-specific state for the match. Do not pass nil as an argument.

    completionHandler

    A block to be called after the data is uploaded to Game Center.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    This method updates the match data stored on Game Center. Call this method when the current player takes an action that advances the state of the match but does not end the player’s turn. For example, if your game has a fog-of-war mechanic, you might call this method when the player revealed new information on the map.

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

  • Updates the data stored on Game Center for the current match.

    Declaration

    Swift

    func endTurnWithNextParticipants(_ nextParticipants: [AnyObject]!, turnTimeout timeout: NSTimeInterval, matchData matchData: NSData!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)endTurnWithNextParticipants:(NSArray *)nextParticipants turnTimeout:(NSTimeInterval)timeout matchData:(NSData *)matchData completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    nextParticipants

    An array of GKTurnBasedParticipant objects reflecting the order in which the players should act next. Each object in the array must be one of the objects stored in the match’s participants property.

    timeout

    The length of time the next player has to complete their turn.

    matchData

    A serialized blob of data reflecting the game-specific state for the match. Do not pass nil as an argument.

    completionHandler

    A block to be called after the data is uploaded to Game Center.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    If the next player to act does not take their turn in the specified interval, the next player in the array receives a notification to act. This process continues until a player takes a turn or the last player in the list is notified.

    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 OS X v10.9 and later.

  • Updates the data stored on Game Center for the current match.

    Declaration

    Objective-C

    - (void)endTurnWithNextParticipant:(GKTurnBasedParticipant *)nextParticipant matchData:(NSData *)matchData completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    nextParticipant

    The next player in the match who needs to take an action. It must be one of the object’s stored in the match’s participants property.

    matchData

    A serialized blob of data reflecting the game-specific state for the match. Do not pass nil as an argument.

    completionHandler

    A block to be called after the data is uploaded to Game Center.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in OS X v10.8 and later.

    Deprecated in OS X v10.9.

  • Resigns the current player from the match without ending the match.

    Declaration

    Swift

    func participantQuitInTurnWithOutcome(_ matchOutcome: GKTurnBasedMatchOutcome, nextParticipants nextParticipants: [AnyObject]!, turnTimeout timeout: NSTimeInterval, matchData matchData: NSData!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)participantQuitInTurnWithOutcome:(GKTurnBasedMatchOutcome)matchOutcome nextParticipants:(NSArray *)nextParticipants turnTimeout:(NSTimeInterval)timeout matchData:(NSData *)matchData completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    matchOutcome

    The end outcome of the current player in the match. Do not pass nil as an argument.

    nextParticipants

    An array of GKTurnBasedParticipant objects that contains participant objects reflecting the order in which the players should act next. Each object in the array must be one of the objects stored in the match’s participants property.

    timeout

    The length of time the next player has to complete their turn.

    matchData

    A serialized blob of data reflecting the game-specific state for the match.

    completionHandler

    A block to be called after the data is uploaded to the server.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    Your game calls this method on an instance of your game that is processing the current player’s turn, but that player has left the match. For example, the player may have willingly resigned from the match or that player may have been eliminated by the other players (based on your game’s internal logic).

    If the next player to act does not take their turn in the specified interval, the next player in the array receives a notification to act. This process continues until a player takes a turn or the last player in the list is notified.

    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 OS X v10.9 and later.

  • Resigns the current player from the match without ending the match.

    Declaration

    Objective-C

    - (void)participantQuitInTurnWithOutcome:(GKTurnBasedMatchOutcome)matchOutcome nextParticipant:(GKTurnBasedParticipant *)nextParticipant matchData:(NSData *)matchData completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    matchOutcome

    The end outcome of the current player in the match. Do not pass nil as an argument.

    nextParticipant

    The next player in the match who needs to take an action. It must be one of the object’s stored in the match’s participants property.

    matchData

    A serialized blob of data reflecting the game-specific state for the match.

    completionHandler

    A block to be called after the data is uploaded to the server.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    Your game calls this method on an instance of your game that is processing the current player’s turn, but that player has left the match. For example, the player may have willingly resigned from the match or that player may have been eliminated by the other players (based on your game’s internal logic).

    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;

    Availability

    Available in OS X v10.8 and later.

    Deprecated in OS X v10.9.

  • Resigns the player from the match when that player is not the current player. This action does not end the match

    Declaration

    Swift

    func participantQuitOutOfTurnWithOutcome(_ matchOutcome: GKTurnBasedMatchOutcome, withCompletionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)participantQuitOutOfTurnWithOutcome:(GKTurnBasedMatchOutcome)matchOutcome withCompletionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    matchOutcome

    The end outcome of the current player in the match. Do not pass nil as an argument.

    completionHandler

    A block to be called after the player’s status is updated on Game Center.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    If the local player decided they wanted to resign from the match but is not the current participant in the match, your game calls 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 OS X v10.8 and later.

  • Ends the match while submitting all of the scores and achievements.

    Declaration

    Swift

    func endMatchInTurnWithMatchData(_ matchData: NSData!, scores scores: [AnyObject]!, achievements achievements: [AnyObject]!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)endMatchInTurnWithMatchData:(NSData *)matchData scores:(NSArray *)scores achievements:(NSArray *)achievements completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    matchData

    A serialized blob of data reflecting the current state for the match. Do not pass nil as an argument.

    scores

    An array of GKScore objects containing the final scores for every participant in the match.

    achievements

    An array of GKAchievement objects containing the achievements acquired by each participant in the match.

    completionHandler

    A block to be called after the scores are saved to the server.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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.

    This method ends the current match and submits scores and achievements for all of the participants. The scores can submitted to multiple leaderboards. The GKTurnBasedMatchOutcome status must be set for each participant before calling this method.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • Ends the match.

    Declaration

    Swift

    func endMatchInTurnWithMatchData(_ matchData: NSData!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)endMatchInTurnWithMatchData:(NSData *)matchData completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    matchData

    A serialized blob of data reflecting the end state for the match. Do not pass nil as an argument.

    completionHandler

    A block to be called after the match is successfully ended.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    Calling this method ends the match for all players. This method may only be called by the current participant. Before your game calls this method, the matchOutcome property on each participant object stored in the participants property must have been set to a value other than GKTurnBasedMatchOutcomeNone.

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

  • Programmatically removes a match from Game Center.

    Declaration

    Swift

    func removeWithCompletionHandler(_ completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)removeWithCompletionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called after the match has been removed from Game Center.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    Even after a player’s participation in a match ends, the data associated with the match continues to be stored on Game Center. Storing the data on Game Center allows the player to continue to watch the match’s progress, or even see the final state of the match when it ends. However, players may also want to delete matches that they have finished playing. If you choose not to use the standard matchmaker user interface, your game should offer the ability to delete a finished match from Game Center. When a player chooses to delete a match from Game Center, call this method. It is a programming error to call this method on a match that has the local player as an active participant.

    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 the task completes, the match is no longer visible to the local player whose device made the call. Other players involved in the match still see the match.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Saves the merged data for the current turn without ending the turn.

    Declaration

    Swift

    func saveMergedMatchData(_ matchData: NSData!, withResolvedExchanges exchanges: [AnyObject]!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)saveMergedMatchData:(NSData *)matchData withResolvedExchanges:(NSArray *)exchanges completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    matchData

    A serialized blob of data reflecting the current state for the match.

    exchanges

    An array of GKTurnBasedExchange objects that contains the resolved exchanges.

    completionHandler

    A block to be called after the scores are saved to the server.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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 this method is called, the data sent is marked as being resolved. This means that the data has been merged into the match data. If other players currently have the game running, they will receive a handleTurnEventForMatch call to indicate that matchData has changed. All completed exchanges must be resolved before ending a turn. If the completed exchanges have not been resolved, then calling endTurn, participantQuitInTurnWithOutCome, or endMatchInTurn will result in an error.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • Sends an exchange request to one or more participants.

    Declaration

    Swift

    func sendExchangeToParticipants(_ participants: [AnyObject]!, data data: NSData!, localizableMessageKey key: String!, arguments arguments: [AnyObject]!, timeout timeout: NSTimeInterval, completionHandler completionHandler: ((GKTurnBasedExchange!, NSError!) -> Void)!)

    Objective-C

    - (void)sendExchangeToParticipants:(NSArray *)participants data:(NSData *)data localizableMessageKey:(NSString *)key arguments:(NSArray *)arguments timeout:(NSTimeInterval)timeout completionHandler:(void (^)(GKTurnBasedExchange *exchange, NSError *error))completionHandler

    Parameters

    participants

    An array of GKTurnBasedParticipant objects containing the participants who are to receive the reminder.

    data

    The data to be exchanged between players.

    key

    The location of the alert message string in the Localizable.strings file for the current localization.

    arguments

    An array of NSString objects to be substituted using the format string.

    timeout

    The length of time the next player has to complete their turn.

    completionHandler

    A block to be called after the exchange request has been sent.

    The block receives the following parameters:

    exchange

    The updated exchange to be passed.

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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.

    Allows an exchange request to be sent to one or more participants. Each recipient receives a push notification that uses the supplied localizable message. An error is returned if any of the participants are inactive.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • Returns the exchanges that are active for the local player. (read-only)

    Declaration

    Swift

    var activeExchanges: [AnyObject]! { get }

    Objective-C

    @property(readonly, retain, atomic) NSArray *activeExchanges

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • The exchanges that have been completed and need to be merged by the local participant. (read-only)

    Declaration

    Swift

    var completedExchanges: [AnyObject]! { get }

    Objective-C

    @property(readonly, retain, atomic) NSArray *completedExchanges

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • The maximum amount of data allowed for an exchange. (read-only)

    Declaration

    Swift

    var exchangeDataMaximumSize: Int { get }

    Objective-C

    @property(readonly, atomic) NSUInteger exchangeDataMaximumSize

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • Limits the number of exchanges the player can have initiated at once. (read-only)

    Declaration

    Swift

    var exchangeMaxInitiatedExchangesPerPlayer: Int { get }

    Objective-C

    @property(readonly, atomic) NSUInteger exchangeMaxInitiatedExchangesPerPlayer

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • exchanges exchanges Property

    The current exchanges that are in progress for the match. (read-only)

    Declaration

    Swift

    var exchanges: [AnyObject]! { get }

    Objective-C

    @property(readonly, retain, atomic) NSArray *exchanges

    Discussion

    When an exchanges has been completed and resolved by merging it into the match data, it will be removed from this list.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • Send a reminder to one or more game participants.

    Declaration

    Swift

    func sendReminderToParticipants(_ participants: [AnyObject]!, localizableMessageKey key: String!, arguments arguments: [AnyObject]!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)sendReminderToParticipants:(NSArray *)participants localizableMessageKey:(NSString *)key arguments:(NSArray *)arguments completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    participants

    An array of GKTurnBasedParticipant objects containing the participants who are to receive the reminder.

    key

    The location of the alert message string in the Localizable.strings file for the current localization.

    arguments

    An array of objects to be substituted using the format string.

    completionHandler

    A block to be called after the reminder has been sent.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    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 this method is called, each recipient receives a push notification using the supplied localizable message. This allows the game to send reminders that a turn or exchange request needs action. The receiver will have a turn event generated for the current game.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • Allows the developer to display a message at the end of a turn or match.

    Declaration

    Swift

    func setLocalizableMessageWithKey(_ key: String!, arguments arguments: [AnyObject]!)

    Objective-C

    - (void)setLocalizableMessageWithKey:(NSString *)key arguments:(NSArray *)arguments

    Parameters

    key

    The location of the alert message string in the Localizable.strings file for the current localization.

    arguments

    An array of NSString objects to be substituted using the format string.

    Discussion

    Only the current player is able to set this message. The message sent is localized on the receiver side if the game is installed and on the sender side otherwise. The localized message identified through the key parameter can be formatted with the %@ and %n$@ specifiers. These specifiers use the objects designated in the arguments array.

    The localized message is evaluated locally from these keys and is sent as well so that devices that do not have the game installed will see the message in the sender’s localization.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.10 and later.

  • The different states that a match can enter.

    Declaration

    Swift

    enum GKTurnBasedMatchStatus : Int { case Unknown case Open case Ended case Matching }

    Objective-C

    enum { GKTurnBasedMatchStatusUnknown = 0, GKTurnBasedMatchStatusOpen = 1, GKTurnBasedMatchStatusEnded = 2, GKTurnBasedMatchStatusMatching = 3 }; typedef NSInteger GKTurnBasedMatchStatus;

    Constants

    • Unknown

      GKTurnBasedMatchStatusUnknown

      The match is in an unexpected state.

      Available in OS X v10.8 and later.

    • Open

      GKTurnBasedMatchStatusOpen

      The match is currently being played.

      Available in OS X v10.8 and later.

    • Ended

      GKTurnBasedMatchStatusEnded

      The match has been completed.

      Available in OS X v10.8 and later.

    • Matching

      GKTurnBasedMatchStatusMatching

      Game Center is still searching for other players to join the match.

      Available in OS X v10.8 and later.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • The different states for a particular participant in a match.

    Declaration

    Swift

    case Unknown case Invited case Declined case Matching case Active case Done

    Objective-C

    enum { GKTurnBasedParticipantStatusUnknown = 0, GKTurnBasedParticipantStatusInvited = 1, GKTurnBasedParticipantStatusDeclined = 2, GKTurnBasedParticipantStatusMatching = 3, GKTurnBasedParticipantStatusActive = 4, GKTurnBasedParticipantStatusDone = 5, }; typdef NSInteger GKTurnBasedParticipantStatus;

    Constants

    • Unknown

      GKTurnBasedParticipantStatusUnknown

      The current state of the participant is not known.

      Available in OS X v10.8 and later.

    • Invited

      GKTurnBasedParticipantStatusInvited

      The participant has been invited to a match, but has not yet responded to the invite.

      Available in OS X v10.8 and later.

    • Declined

      GKTurnBasedParticipantStatusDeclined

      The participant has declined a match invitation.

      Available in OS X v10.8 and later.

    • Matching

      GKTurnBasedParticipantStatusMatching

      The participant is waiting to be matched to a game.

      Available in OS X v10.8 and later.

    • Active

      GKTurnBasedParticipantStatusActive

      The participant is currently active in the match.

      Available in OS X v10.8 and later.

    • Done

      GKTurnBasedParticipantStatusDone

      The participant is done with the current session.

      Available in OS X v10.8 and later.

  • Descriptions for the different game result states for a given participant that has reached the done state.

    Declaration

    Swift

    enum GKTurnBasedMatchOutcome : Int { case None case Quit case Won case Lost case Tied case TimeExpired case First case Second case Third case Fourth case CustomRange }

    Objective-C

    enum { GKTurnBasedMatchOutcomeNone = 0, GKTurnBasedMatchOutcomeQuit = 1, GKTurnBasedMatchOutcomeWon = 2, GKTurnBasedMatchOutcomeLost = 3, GKTurnBasedMatchOutcomeTied = 4, GKTurnBasedMatchOutcomeTimeExpired = 5, GKTurnBasedMatchOutcomeFirst = 6, GKTurnBasedMatchOutcomeSecond = 7, GKTurnBasedMatchOutcomeThird = 8, GKTurnBasedMatchOutcomeFourth = 9, GKTurnBasedMatchOutcomeCustomRange = 0x00FF0000 }; typedef NSInteger GKTurnBasedMatchOutcome;

    Constants

    • None

      GKTurnBasedMatchOutcomeNone

      The participant has not finished a match.

      Available in OS X v10.8 and later.

    • Quit

      GKTurnBasedMatchOutcomeQuit

      Participant quit the match.

      Available in OS X v10.8 and later.

    • Won

      GKTurnBasedMatchOutcomeWon

      Participant won the match.

      Available in OS X v10.8 and later.

    • Lost

      GKTurnBasedMatchOutcomeLost

      Participant lost the match.

      Available in OS X v10.8 and later.

    • Tied

      GKTurnBasedMatchOutcomeTied

      Participant tied in the current match.

      Available in OS X v10.8 and later.

    • TimeExpired

      GKTurnBasedMatchOutcomeTimeExpired

      The game ended due to time running out.

      Available in OS X v10.8 and later.

    • First

      GKTurnBasedMatchOutcomeFirst

      The participant came in first.

      Available in OS X v10.8 and later.

    • Second

      GKTurnBasedMatchOutcomeSecond

      The participant came in second.

      Available in OS X v10.8 and later.

    • Third

      GKTurnBasedMatchOutcomeThird

      The participant came in third.

      Available in OS X v10.8 and later.

    • Fourth

      GKTurnBasedMatchOutcomeFourth

      The participant came in fourth.

      Available in OS X v10.8 and later.

    • CustomRange

      GKTurnBasedMatchOutcomeCustomRange

      Custom range available for an app to use for its own status results.

      Available in OS X v10.8 and later.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in OS X v10.8 and later.

  • Common values for turn timeouts.

    Declaration

    Swift

    var GKTurnTimeoutDefault: NSTimeInterval var GKTurnTimeoutNone: NSTimeInterval

    Objective-C

    extern NSTimeInterval GKTurnTimeoutDefault; extern NSTimeInterval GKTurnTimeoutNone;

    Constants

    • GKTurnTimeoutDefault

      GKTurnTimeoutDefault

      Indicates that the player has one week to take a turn.

      Available in OS X v10.9 and later.

    • GKTurnTimeoutNone

      GKTurnTimeoutNone

      Indicates that the player’s turn never times out.

      Available in OS X v10.9 and later.