Class

GKTurnBasedMatch

An object used to implement turn-based matches between sets of players on Game Center.

Declaration

@interface GKTurnBasedMatch : NSObject

Overview

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.

Topics

Retrieving Existing Matches

+ loadMatchesWithCompletionHandler:

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

Creating a New Match

+ findMatchForRequest:withCompletionHandler:

Programmatically searches for a new match to join.

- acceptInviteWithCompletionHandler:

Programmatically accept an invitation to a turn-based match.

- declineInviteWithCompletionHandler:

Programmatically decline an invitation to a turn-based match.

- rematchWithCompletionHandler:

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

Retrieving Information About the Match

participants

Information about the players participating in the match.

currentParticipant

The participant whose turn it is to act next.

matchData

Game-specific data that reflects the details of the match.

matchDataMaximumSize

Returns the limit the Game Center servers place on the size of the match data.

message

A message displayed to all players in the match.

creationDate

The date that the match was created.

matchID

A string that uniquely identifies the match.

status

The current state of the match.

GKTurnBasedMatchStatus

The different states that a match can enter.

Retrieving the Match’s Custom Data

- loadMatchDataWithCompletionHandler:

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

Handling the Current Player’s Turn

- saveCurrentTurnWithMatchData:completionHandler:

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

- endTurnWithNextParticipants:turnTimeout:matchData:completionHandler:

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

Leaving a Match

- participantQuitInTurnWithOutcome:nextParticipants:turnTimeout:matchData:completionHandler:

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

- participantQuitOutOfTurnWithOutcome:withCompletionHandler:

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

Ending a Match

- endMatchInTurnWithMatchData:scores:achievements:completionHandler:

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

Deleting a Match from Game Center

- removeWithCompletionHandler:

Programmatically removes a match from Game Center.

Transferring Information with Exchanges

- saveMergedMatchData:withResolvedExchanges:completionHandler:

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

GKExchangeTimeoutDefault

The exchange will timeout after one day if no reply is received.

GKExchangeTimeoutNone

The exchange will not timeout.

activeExchanges

Returns the exchanges that are active for the local player.

completedExchanges

The exchanges that have been completed and need to be merged by the local participant.

exchangeDataMaximumSize

The maximum amount of data allowed for an exchange.

exchangeMaxInitiatedExchangesPerPlayer

Limits the number of exchanges the player can have initiated at once.

exchanges

The current exchanges that are in progress for the match.

Sending Messages Between Players

- setLocalizableMessageWithKey:arguments:

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

Constants

Turn Timeouts

Common values for turn timeouts.

Deprecated Methods

- participantQuitInTurnWithOutcome:nextParticipant:matchData:completionHandler:

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

Deprecated
- endTurnWithNextParticipant:matchData:completionHandler:

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

Deprecated

Relationships

Inherits From

See Also

Turn-based Games

GKTurnBasedExchange

The exchange information sent between players even when a player is not the current player.

GKTurnBasedExchangeReply

The player’s response to an exchange.

GKTurnBasedParticipant

The information that describes a participant in a turn-based match.

GKTurnBasedEventListener

The protocol you implement to handle exchanges and match-related events for turn-based games.