Turn-Based Matches

In a turn-based match, the players of the match do not need to be simultaneously connected to Game Center to play a match together. Instead, the game uses a store-and-forward approach; one player takes a turn before passing the next play to another player. The players continue to take turns until the match ends with only one player able to make changes to the game at a time.

Turn-based matches have many useful characteristics that make them great for implementing board games and other similar styles of games; for example:

In iOS 7, exchanges are introduced to turn-based matches. Exchanges allow two or more players to take an action, even when it is not their turn. This allows developers to create more complex and diverse turn-based games than are currently possible by allowing more than just the local player to make changes to the game. Some possible uses for exchanges are:

You can build a game by adding exchanges to the existing turn-based gaming model or create a game solely through the use of exchanges. This chapter first describes how to implement a traditional turn-based match and then adds information about exchanges later.

When you implement turn-based matches in your game, the list of players, the data for matches, and other details are all stored on Game Center. Your game downloads this information as needed. Game Center is primarily responsible for storing data. You are responsible for providing the game logic that uses this infrastructure. In particular, you define:

Checklist for Implementing a Turn-Based Match

To add turn-based support to your game, you write code to handle the following activities:

Every Match Has a List of Participants

Think of a turn-based match on Game Center as a board game in the middle of a table. Around the table are empty seats, waiting to be filled by potential players. The number of players is set when the match is first created and never changes.

When a match begins, only some of the seats may be filled by players. The other seats may be reserved for specific players or to be filled by Game Center’s matching service. For example, consider Figure 10-1. Mary has created a new match with four seats. Because Mary created the match, she performs the first turn and then play passes to another player.

Figure 10-1  Mary starts a new match

At this point, Game Center sees that this match needs a new player to continue play. When Bob searches for a match, Game Center sees that Bob wants to play the same game as Marry and assigns Bob as a new player of Mary’s match. Because this game was waiting on a new player to continue the match, it is now Bob’s turn.

../Art/match_and_fill-3_2x.png

Game Center always tracks the players of a match in a specific order. That order never changes for the duration of the match, regardless of which device your game is running on. In this example, if Mary is in the first seat (slot), she stays in the first seat for the entire game.

Every match has the concept of the current player. The current player changes throughout the match and represents the player whose turn it is to act. When that player finishes taking a turn, your game chooses another player to act. That player is notified that it is now his or her turn and becomes the current player.

The Match Data Represents the State of the Match

Your game sends to Game Center match data that describes the state of a match. Game Center sets a limit on the size of this match data but otherwise does not care about its contents. Your game should store whatever data is necessary to preserve the match state.

At any time, a player in the match can launch your game to view the match. When a player launches the game, your game loads the match data, interprets it, and displays it to the player.

Figure 10-2  The current player wants to view the match

Only the current player is allowed to change the match data. Provide the current player with a user interface that allows them to take actions in the game. As the player takes actions, your game updates the match data and transmits it back to Game Center.

../Art/store_and_forward-3_2x.png

Your Game Decides the Rules of Play

When you design a turn-based game, you create the rules that dictate play. You decide exactly what actions a player is allowed to take and when play passes to another player. When play passes to another player, you decide which player plays next.

As an example, consider chess. The player with the white pieces moves first. After white moves, play passes to the player controlling the black pieces. After black makes a move, play passes back to white. The players alternate turns until the match ends in either a checkmate or a stalemate. The rules dictate that play alternates and each player makes a single move each time.

The rules that chess uses for players are very consistent, but Game Center allows you to design more flexible games. For example, each time a player takes a turn, you can show them a different user interface screen and present the player with different options for play. A player’s turn can be as simple as making a single decision or as complex as choosing what to build, deciding where to send resources, and engaging in combat with another player. Your game tracks the moves a player makes and the moves they are allowed to make as part of your match data.

Consider another popular style of strategy game: the 4X game that encourages players to explore, expand, exploit, and exterminate. In this style of game, multiple types of turns are used at different points in the match. Here is one possible way to organize this:

Figure 10-3 shows how this hypothetical game’s logic is processed. It has three distinct kinds of player turns, each with a different user interface, possible user actions, and data to be stored in the match data.

Figure 10-3  A turn flowchart for a hypothetical 4X game

Whenever a player takes a turn, the match data indicates what type of turn the player takes. After a player takes a turn, their actions are stored in the match data. The design also avoids passing turns to other players for nontrivial reasons. Every player makes multiple decisions at once before passing control to another player. When the final player completes a turn, that player’s game client processes everyone’s turns simultaneously, writing any necessary changes to the match data. Although this kind of design is not required, it keeps the game moving by avoiding small, trivial player turns.

Save the Match Data Whenever Important Events Occur

The current player’s device can save the data to Game Center immediately whenever any action is taken, without transferring control to another player. You should save match data whenever anything interesting happens. Consider the following list as critical places where data should be sent to Game Center:

Implementing a Turn-Based Match Using Game Kit

To implement turn-based support in your game, you use the classes listed in Table 10-1.

Table 10-1  Classes in Game Kit used to implement turn-based match support

Class Name

Class Function

GKTurnBasedMatch

Describes a turn-based match stored on Game Center. You use this object to inspect the current state of the match and to update the state of the match when the current player takes a turn.

GKMatchRequest

Describes the characteristics of a match and may include an initial list of players to invite.

GKTurnBasedParticipant

Describes a player in a match. Most of its properties are read-only, but the matchOutcome property is not; you assign an outcome to this property when a player leaves a match.

GKTurnBasedMatchmakerViewController

Provides a standard user interface that allows the local player to create new matches or view existing matches.

GKTurnBasedEventHandler

Handles events when the player receives an invitation to join a match or a notification that an existing match has been updated. There is a single event handler object provided to you by Game Kit. After the player is authenticated, you assign an event handler to this singleton object. The exact events delivered to your game vary depending upon whether your game is currently the foreground app on the device. When your game is in the foreground, it receives all events related to turn-based matches. If not running in the foreground, your game is launched or brought to the foreground only when important events are received.

Game Center Imposes Limits on the Match

Table 10-2 describes two of the important limits you need to consider when designing your game. These limits are subject to change and can both be queried at runtime.

Table 10-2  Important match limits

Item

Limit

Runtime Access

Number of Players

16

Call the maxPlayersAllowedForMatchOfType: class method of the GKMatchRequest class.

Size of Match Data

64k

Read the matchDataMaximumSize property of the GKTurnBasedMatch object.

Joining a New Match

For players, a new match begins when the player joins a match. As with other forms of matchmaking, your game starts the process by creating a GKMatchRequest object, as described in “Creating Any Kind of Match Starts with a Match Request.” A match request does not guarantee that a new match is going to be created; it may also match the player into an existing match that has an empty position as the current player.

You can choose to display a standard user interface provided by Game Center or implement your own custom user interface. Regardless of which technique you use, the match returned to your game always has the local player as the current player expected to take a turn.

Showing the Standard Matchmaking User Interface

You use a GKTurnBasedMatchmakerViewController object to display the standard user interface. Listing 10-1 shows a typical implementation.

Listing 10-1  Displaying the standard interface to join a turn-based match

- (IBAction)joinChessMatch: (id) sender
{
    GKMatchRequest *request = [[GKMatchRequest alloc] init];
    request.minPlayers = 2;
    request.maxPlayers = 2;
 
    GKTurnBasedMatchmakerViewController *mmvc = [[GKTurnBasedMatchmakerViewController alloc] initWithMatchRequest:request];
    mmvc.turnBasedMatchmakerDelegate = self;
 
    [self presentViewController:mmvc animated:YES completion:nil];
}

The presenting view controller in this example implements the GKTurnBasedMatchmakerViewControllerDelegate pattern. For matchmaking, you need to handle three of the protocol’s methods.

The turnBasedMatchmakerViewControllerWasCancelled: delegate method is called when the player dismisses the matchmaking screen by tapping the Cancel button. In most cases, you should simply return to the previous screen in your game. A minimal version of this code can be found in Listing 10-2.

Listing 10-2  Implementing the cancellation method

- (void)turnBasedMatchmakerViewControllerWasCancelled:(GKTurnBasedMatchmakerViewController *)viewController
{
    [self dismissViewControllerAnimated:YES completion:nil];
}

The turnBasedMatchmakerViewController:didFailWithError: delegate method is called when matchmaking encounters an error while trying to find the match. For example, the device may have lost its network connection. Your implementation should also return to your game’s previous screen. A minimal version of this code can be found in Listing 10-3.

Listing 10-3  Implementing the error handling method

- (void)turnBasedMatchmakerViewController:(GKTurnBasedMatchmakerViewController *)viewController didFailWithError:(NSError *)error
{
    [self dismissViewControllerAnimated:YES completion:nil];
}

Finally, the turnBasedMatchmakerViewController:didFindMatch: method is called when a match has been found or created. The match object is returned to your delegate. Typically, your game dismisses the matchmaker view controller and immediately starts its own user interface to allow the player to play a turn. The implementation in Listing 10-4 uses a custom segue to show the gameplay screen. The match is passed as the sender so that it can be passed as an input to the new view controller.

Listing 10-4  Implementing the match found method

- (void)turnBasedMatchmakerViewController:(GKTurnBasedMatchmakerViewController *)viewController didFindMatch:(GKTurnBasedMatch *)match
{
    [self dismissViewControllerAnimated:YES completion:nil];
    [self performSegueWithIdentifier:@"GamePlayScene" sender:match];
}
 
- (void )prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender
{
    if ([segue.identifier isEqualToString:@"GamePlayScene"])
    {
        MyGamePlayViewController* gameVC = (MyGamePlayViewController*) segue.destinationViewController;
        gameVC.delegate = self;
        gameVC.match = (GKTurnBasedMatch*) sender;
    }
}

Implementing a Custom Match Interface

To create your own custom match interface, you typically use methods on the GKTurnBasedMatch class. Listing 10-5 shows a trivial implementation of this technique. It creates a new match request and then uses it to find a new match. (Typically, if your game was implementing a custom match interface, it might set other properties of the request object, such as the playersToInvite property.) If a match is found, it transitions to the gameplay screen.

Listing 10-5  Finding a turn-based match programmatically

- (IBAction)findProgrammaticMatch: (id) sender
{
    GKMatchRequest *request = [[GKMatchRequest alloc] init];
    request.minPlayers = 4;
    request.maxPlayers = 16;
    [GKTurnBasedMatch findMatchForRequest: request withCompletionHandler:^(GKTurnBasedMatch *match, NSError *error)
    {
        if (match)
            [self performSegueWithIdentifier:@"GamePlayScene" sender:match];
    }];
}

One common scenario is supported automatically by Game Center. When a match ends, you can call its rematchWithCompletionHandler: instance method to create a new match with the same participants.

Handling Invitations Programmatically

If a match request includes a list of players to invite, then those players are added to the list of players in the newly created match. However, invitations are not actually delivered until one of those players becomes the current player. When that happens, a push notification is sent to the player. The process for handling notifications is described later in “Responding to Match Notifications.” For now, all you need to know is that you can display your own interface that allows the player to accept or decline the match invitation. You call the match object’s acceptInviteWithCompletionHandler: method to accept the invitation or its declineInviteWithCompletionHandler: method to decline the invitation.

Working with Existing Matches

If you display the standard matchmaking user interface, then the player sees existing matches as well. The player can choose an existing match already in progress and perform other common tasks. If the player picks an existing match, the turnBasedMatchmakerViewController:didFindMatch: method is called, exactly as it was called when a new match was created. Note that in this case, the player may not be the current player.

A player can choose to resign from a match from within the standard user interface. Your delegate must implement a turnBasedMatchmakerViewController:playerQuitForMatch: method to handle a player resignation. Your game must set a match outcome for the resigning player, and if necessary, choose another player to act in the match. For more information, see “Setting the Match Outcome When a Participant Leaves a Match.”

If you implemented a custom matchmaking user interface, you need to provide equivalent functionality that allows a player to manage the list of matches. Listing 10-6 shows how to retrieve a list of matches that the local player is participating in.

Listing 10-6  Retrieving the list of matches the local player is participating in

- (void) loadMatches
{
    [GKTurnBasedMatch loadMatchesWithCompletionHandler:^(NSArray *matches, NSError *error) {
      if (matches)
          {
// Use the match data to populate your user interface.
          }
     }];
}

Table 10-3 lists the most common actions a player might want to perform on a match.

Table 10-3  Common actions to perform on a match

Action

Implementation

View a match

Present your gameplay user interface, using the match object as an input. See Listing 10-4 for inspiration on how to implement this.

Delete a completed match

Call the match object’s removeWithCompletionHandler: method.

Resign from a match

Set the player’s outcome and then call a method to resign from the match. See “Setting the Match Outcome When a Participant Leaves a Match.”

End a match for all participants

Set outcomes for all of the players and then call the match’s endMatchInTurnWithMatchData:completionHandler: method. See “Ending a Match.”

Create a rematch

Call the rematchWithCompletionHandler: method on an ended match.

Retrieving Information About a Match

When a player decides to view a match, your game reads the properties of the match to determine the current state of the match. Table 10-4 lists the most common properties you need to access.

Table 10-4  Important properties of a match object

Property

Description

matchID

A string that uniquely identifies the match. If you want to store match-specific data elsewhere, use this string as a key. Your game could also save this ID and use it later to load this specific match. To load a specific match, call the loadMatchWithID:withCompletionHandler: class method.

status

States whether the match is still in progress.

message

A text string your game sets to provide a human-readable status for the match. Typically, you update this property before changing the current player. The message is displayed by the standard user interface. If you display a custom interface, you should also display the message.

participants

An array of GKTurnBasedParticipant objects. The objects in the array are always stored in the same order. You read the properties of participant objects to build your user interface. These objects are also used as inputs to certain methods on the match object. Table 10-5 lists the most common properties used to implement your game.

currentParticipant

The participant object for the next player expected to act in the match. This object is always one of the objects stored in the participants array.

Table 10-5 lists the most common participant properties used to implement your game.

Table 10-5  Important properties of a participant object

Property

Description

playerID

The player identifier for the player, assuming this seat is filled. Use it to load display names and photos for the player.

status

Declares whether or not this seat is filled and, if it is, declares whether the player is still active in the match.

timeoutDate

The time at which the player must act before forfeiting a turn. Your game decides what happens when a turn is forfeited. For some games, a forfeited turn might end the match. For other games, you might choose a reasonable set of default actions for the player, or simply do nothing.

matchOutcome

When a player leaves a match, this property describes what happened to the player. The player may have won or lost the match.

Working with Match Data

When a match is first created, the match data is empty. But once the match begins and players start taking turns, your game is expected to provide match data that makes sense for your game. The match data is an NSData object and its size is limited, so you need to be creative and encode your game’s data so that it fills as little space as possible.

In general, the match data needs to store enough information so that your game can display the current state of the match. If the player is the current player, then the match data should also store enough data so that your game knows what kind of turn the player may take. Here are a few possible strategies you can follow when designing your match data format:

  • Encode only player actions: In this design, your match data simply consists of the moves made by the players. For example, in chess, you know that white goes first, moves always alternate, and a piece moves from one board position to another. This makes it easy for you to encode each move as the starting and ending position of the piece moved. The rest of the data (who made the moves) can be completely inferred. When your game loads the match data, it quickly replays the moves to generate the current board position.

    This strategy works best for games with a small number of possible kinds of actions and a small number of moves per match. Also, with this model, it is very possible for your game to replay the moves in its user interface, allowing players to see exactly what moves other opponents made to get the board into the new state. Showing a player these moves makes it very easy for a player to understand how the game got to the current state.

  • Encode only the current state of the match: For very complex games, the actual state required to encode the game could be very large. In this case, you may need to encode the current state of the match without worrying about the actions that generated that match data. This is particularly true for very complex games where the list of moves might grow too large to fit in the available storage space.

    This strategy is recommended as a last resort. Players lose all context of what happened on previous turns of the match. For games with long timeouts between turns, players may grow bored or frustrated if they cannot remember the state of a match they were playing. This is particularly true when players participate in multiple matches simultaneously.

  • Encode the current state of the match and a set of recent player actions: This is a hybrid strategy that borrows elements from the other two strategies. Essentially, the match data stored on Game Center consists of a recent snapshot of the match plus other data that encodes recent actions since that last snapshot was taken. When the data that records the actions grows too large, your game replays some of those moves to update the match snapshot and then deletes those moves from its list of actions.

    With this strategy, you typically need to determine which actions the current player has seen (based on when they last took a turn). When your game flattens the match data, it never removes any data that hasn’t been seen by all the participants. This allows all participants to see the moves their opponents made.

And here are some other general guidelines:

  • Avoid using the NSCoder class except for the most trivial of games. Although useful for general-purpose apps, the NSCoder class may not archive data in a compact enough format for your game. You cannot precisely predict the size of the archive it produces. Instead, you allocate your own block of memory and perform your own data serialization.

  • Encode individual items as compactly as needed. For example, in a 16-player game, you can encode the participant number of the player in 4 bits. Balance the need for compactness with the need for readability in your code. For example, a chess position could be encoded in as little as 6 bits, but in practice a chess match does not approach the match data limit.

  • If your game runs in both OS X and iOS, use network data encoding techniques to avoid byte ordering problems.

Loading Match Data

When you need to load the match data, you call the match object’s loadMatchDataWithCompletionHandler: method to retrieve the match data. When the completion handler is called, you receive the match data. After the operation completes, the match object’s matchData property is also updated to point at the same data object.

Listing 10-7  Loading the match data from Game Center

- (void) loadAndDisplayMatchData
{
    [this.myMatch loadMatchDataWithCompletionhandler: ^(NSData *matchData, NSError *error) {
        if (matchData)
        {
// App-specific routine to decode the match data.
            this.gameData = [MyMatchDataClass initWithData: matchData];
            // Display the match.
        }
      }];
}

Saving Match Data

If the player takes an action that is irrevocable (but control is not yet passed to another player), encode the updated match data and send it to Game Center by calling the saveCurrentTurnWithMatchData:completionHandler: method.

Listing 10-8  Saving the match data to Game Center

- (void) updateMatchData
{
// App-specific routine to encode the match data.
    NSData *updatedMatchData = [this.gameData encodeMatchData];
    [this.myMatch saveCurrentTurnWithMatchData: updatedMatchData completionHandler ^(NSError *error) {
        if (error)
        {
            // Handle the error.
        }
      }];
}

Advancing the State of the Match

Eventually, the current player takes an action that either ends the match or requires another participant to act. Typically, your game updates the message property of the match object, encodes the match data, and determines who acts next in the match. Usually, this means encoding the list of all participants in the match in the order they will act next. The reason you do this is that sometimes players drop from a match without forfeiting; they just stop playing. You don’t want the match to end because it is stuck waiting forever for an absent player. Instead, you encode the list of participants so that if one participant forfeits a turn, the match advances to another participant.

Listing 10-9 shows a typical structure for this code, deferring some of the specific steps to app-specific routines that are based on your game’s actual structure. Those methods represent the places where you need to provide specific implementations in your game. The advanceTurn method first sets a new message, then encodes the current match data as before. Finally, it calculates the order in which participants should act and calls the endTurnWithNextParticipants:turnTimeout:matchData:completionHandler: method to actually pass control to that list of players.

Listing 10-9  Advancing to the next participant in a match

- (void) advanceTurn
{
    NSData *updatedMatchData = [this.gameData encodeMatchData];
    NSArray *sortedPlayerOrder = [this.gameData encodePlayerOrder];
    this.MyMatch.message = [this.gameData matchAppropriateMessage];
    [this.myMatch endTurnWithNextParticipants: sortedPlayerOrder turnTimeOut: GKTurnTimeoutDefault
                  matchData: updatedMatchData completionHandler ^(NSError *error) {
        if (error)
        {
            // Handle the error.
        }
      }];
}

Setting the Match Outcome When a Participant Leaves a Match

As the match progresses, participants may leave the match. For example, your game logic might determine that a participant has been eliminated from the match.

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:nextParticipants:turnTimeout:matchData:completionHandler: method. This method is similar to the endTurnWithNextParticipants:turnTimeout:matchData:completionHandler: method in that it gives control to another participant. Because of this, you are required to update the match data and provide a participant list. However, your game also provides a match outcome for the player that just exited the match — essentially, a numerical value that indicates why that player left the match. The participant object for that player is updated to include this new match state. Once a participant has exited the match, your game may not make that player the current player.

Game Kit provides some standard values you can use to set the match outcome. See “Setting the Match Outcome” in GKTurnBasedParticipant Class Reference.

For example, in Figure 10-4, Bob has just been eliminated from the match. The game chooses to set an outcome of GKTurnBasedMatchOutcomeFourth and make Mary the new current player. Bob may still view the match, but may not take actions.

Figure 10-4  Bob has been eliminated from the match

Occasionally a player may resign the game when they are not the current player. To handle this, your game calls the match object’s participantQuitOutOfTurnWithOutcome:withCompletionHandler: method. You provide a match outcome but do not provide new match data or a participant list.

Ending a Match

Eventually, your game logic is going to decide that the match is over. All participants in the match must have a valid match outcome before ending the match. Your game calls the match object’s endMatchInTurnWithMatchData:completionHandler: method to formally end the match. This method is similar to the other methods that update the match state, but in this case you do not provide a list of participants because no further actions are allowed in this match. You do update the saved match data to describe how the match ended. Players can still select this match from the matchmaking user interface; your game should display the match ending but not allow the player to take actions.

../Art/set_match-2_2x.png

Responding to Match Notifications

A player can receive notifications about turn-based matches. For example, the most common notification a player receives is when that player becomes the current player for a match (and is expected to take action). In all cases, after a player accepts a notification, your game is called to handle the event. It should process the event and display an appropriate user interface specific to your game.

Your game receives turn-based match events by installing an event handler. As with other similar handlers, you almost always install this handler as soon as the local player is authenticated. If your game was launched specifically to handle an event, the event handler is called immediately.

- (void) installTurnBasedEventHandler
{
    [GKTurnBasedEventHandler sharedTurnBasedEventHandler].delegate = self;
}

To respond to events, your event handler implements the methods defined by the GKTurnBasedEventHandlerDelegate protocol. Table 10-6 lists the events. Events received via a push notification launch your game or bring your game to the foreground (if necessary) and are then delivered to the game. Foreground events are delivered only if your game was running in the foreground when the event was received.

When an event is received, your game should pause what it is doing and display a user interface that allows the player to decide whether to load the notification’s match for display. Even if this match is already loaded, you should reload the match’s data, because it may have been updated by the event.

Table 10-6  Turn-based event handler methods

Event

Event Type

Event Handler Method

Player receives an invitation

Push

handleInviteFromGameCenter:

It becomes the player’s turn

Push

handleTurnEventForMatch:didBecomeActive:

A match ended

Push

handleMatchEnded:

It becomes someone else’s turn

Foreground

handleTurnEventForMatch:didBecomeActive:

A player updated the match data

Foreground

handleTurnEventForMatch:didBecomeActive:

A player receives an exchange request

Push

player:receivedExchangeRequest:forMatch:

A player cancels an exchange request

Push

player:receivedExchangeCancellation:forMatch:

All players have responded or timed out while responding to an exchange

Push

player:receivedExchangeReplies:forCompletedExchange:forMatch:

By default, when your game receives a notification, a badge is added to the game icon. Add GKGameCenterBadgingDisabled to your Info.plist to change this behavior. See “Cocoa Keys” for details.

Adding Exchanges to a Turn-Based Match

Add exchanges to your game to expand what your game can do. Exchanges allow players other than the current player to affect the current turn. Whether through trading items with another player or directly affecting the current player’s turn, exchanges provide for greater flexibility in how you design your game.

Anatomy of an Exchange

In the basic turn-based match, control of the game moves from player to player, following rules defined by the app. Only the current player can affect the match, with all other players relegated to observing the match. This works very well for certain types of games, but as a game turn becomes more complicated, it is not uncommon for multiple players needing to interact at the same time. Turn-based matches can quickly become bogged down when each player must perform a small action in order for a turn to be completed. Exchanges provide you with a way to create complex turns without slowing down the pace of the match.

Using exchanges, you can design your game so that players other than the current player can take actions during a turn. An exchange is an interaction between the exchange initiator and one or more exchange recipients. The following workflow is used for an exchange:

  • The initiator sends an exchange request to a recipient.

  • The recipients is notified that they have received an exchange request.

  • The recipient acts on the exchange request and sends their action back to the initiator.

  • The initiator is notified of the completed exchange.

  • The current player is notified of the completed exchange and updates the match data.

Sending an Exchange Request

Depending on how you design your game, any player can initiate an exchange request, whether they are the current player or not. For example, during Mary’s turn, Fred decides that he wants to trade cards with Kelly. Fred chooses the cards he wants to trade to Kelly and what he wants in return. He then sends the exchange request to Kelly. After the request is sent, an update is sent to Mary so that the match can be updated. See Figure 10-5 .

Figure 10-5  Initializing a trade through an exchange

When a player sends an exchange request, several pieces of information are required to successfully send the request. There is no particular order in which this information needs to be collected. For example, your game may ask who the sender wants to trade with before asking which cards to trade, or the sender could choose cards to give and then designate who will receive the cards.

  • The sender chooses whom to send the exchange request to.

  • The nature of the request has to be determined. Is the player asking to trade cards, asking for help in attacking another player, or something else?

  • The amount of time the recipients have to respond to the exchange request must be set. You can allow the sender to choose this or set a hard time limit.

The amount of data that you can send is limited to a maximum of 1k. The data must be comprehensive enough that the receiving player’s game can act and present the data to the player in a way that makes sense in the context of your game. When the exchange request is sent, ensure that the current player also receives the request data so that the current match can be updated. Listing 10-10 shows a basic exchange request. The recipient of the exchange is placed into an array and the request is sent to the player listed in the recipients array.

Listing 10-10  Sending an exchange request to another player

- (void) exchangeRequest (GKTurnBasedParticipant receiver)
{
     NSArray *recipients = @[receiver];
     [self sendExchangeToParticipants:recipients data:data localizableMessageKey:key arguments:arguments timeout:timeout completionHandler:^(GKTurnBasedExchange *exchange, NSError *error) {
          // refresh your match data
     }];
}

Before any recipients respond to an exchange request, the sender can cancel the request. When the sender cancels an exchange, a push notification is sent to all of the recipients telling them that the exchange has been canceled.

Listing 10-11  Canceling an exchange request

-(void)player:(GKPlayer *)player exchangeCanceled:(GKTurnBasedExchange *)exchange match:(GKTurnBasedMatch *)match
{
     // update your match data to show the canceled request
}

Responding to an Exchange Request

After an exchange request is created, the players in the recipients array receive a push notification. Opening the game will present the exchange message. The recipient can choose to respond to the exchange request or let it time out. Figure 10-6 shows Kelly accepting Fred’s trade and responding to his exchange request. After the exchange is completed, the exchange result is sent to the current player. The exchange is reconciled at the end of the current player’s turn.

Figure 10-6  Accepting a trade through an exchange

Listing 10-12 shows a basic reply format. The recipient responds to the exchange request and sends any relevant data back to the original sender. Your game also needs to send the results of the exchange to the current player so that they can update the match.

Listing 10-12  Replying to an exchange request

-(void) replyToExchange
{
     [self replyWithLocalizableMessageKey:key arguments:arguments data:data completionHandler:^(NSError *error) {
          // refresh your match data
     }
}