Turn-Based Matches

Game Center Imposes Limits on the Match

Table 10-4 describes some 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.

Joining a New Match

For players, a new match begins when the player joins a match. As with other forms of matchmaking, your game describes the match it wants to create 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 participant.

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 participant expected to take a turn.

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

}

- (void)turnBasedMatchmakerViewControllerWasCancelled:(GKTurnBasedMatchmakerViewController *)viewController

{

    [self dismissViewControllerAnimated:YES completion:nil];

}

- (void)turnBasedMatchmakerViewController:(GKTurnBasedMatchmakerViewController *)viewController didFailWithError:(NSError *)error

{

    [self dismissViewControllerAnimated:YES completion:nil];

}

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

    }

}

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

    }];

}

Working With Existing Matches

If you display the standard matchmaking user interface, then the player also 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 did when a new match was created. Note that in this case, the player may not be the current participant.

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.

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.

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 participant, 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 that 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.

  This strategy is recommended as a last restort. Payers lose all of the 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 participant 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 date 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 permanently 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 participant 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 should 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 on both OS X and iOS, use network data encoding techniques to avoid byte ordering problems.

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

        }

      }];

}

- (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 participant 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 because 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 participants 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 participant.

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 participant. Bob may still view the match, but may not take actions.

Occasionally a player may resign the game when they are not the current participant. 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 participants 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.

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 participant 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 sharedEventHandler].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 only delivered 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 the match’s data may have been updated by the event.