Adopt GameplayKit Protocols in Your Game Model

Three key protocols define the interface GameplayKit uses to reason about the state of your game.

• The GKGameModel protocol applies to objects that represent a distinct state of your gameplay model. In the FourInARow example, the AAPLBoard class is a good candidate for adopting this protocol.

• The GKGameModelPlayer protocol is an abstraction of the objects that represent players in your game. In the example, the AAPLPlayer class works well for this case.

• The GKGameModelUpdate protocol is for objects that describe a transition between two game states. In the example, there is no such object—the addChip method performs the transition. In this case, adopting the GKGameModelUpdate protocol requires creating a new class.

The code listings below show how to extend the model classes in the FourInARow example to adopt the GameplayKit protocols. First, Listing 5-2 adds an AAPLMove class that adopts the GKGameModelUpdate protocol.

The GKGameModelUpdate protocol requires one property: value. The strategist assigns a score to this property when weighing the desirability of each possible move. For the rest of your implementation of this protocol, create properties or methods that describe a move in terms particular to your game. In the FourInARow game, the only information needed to specify a move is which column to drop a chip into.

Next, Listing 5-3 adds GKGameModelPlayer conformance to the AAPLPlayer class.

The AAPLPlayer class simply exposes the integer value of its AAPLChip enumeration as its playerId property.

Adding GKGameModel conformance to the AAPLBoard class requires three areas of functionality: keeping track of players, handling and scoring moves, and copying state information. Listing 5-4 shows the first of these areas.

The players getter always returns the two players in the game. For the FourInARow game, the number and identity of players is constant, so this array is stored in the AAPLPlayer class. The activePlayer getter simply maps to the currentPlayer property already implemented in the AAPLBoard class.

A critical part of a GKGameModel implementation is simulating each player’s prospective moves. Listing 5-5 shows how the AAPLBoard class handles these tasks.

The gameModelUpdatesForPlayer: method returns the possible moves for the specified player. Each possible move is an instance of your game’s implementation of the GKGameModelUpdate protocol—in this example, the Move class. The FourInARow game implements this method by returning an array of AAPLMove objects corresponding to each non-full column.

The applyGameModelUpdate: method takes a GKGameModelUpdate object and performs whatever game actions that object specifies. In this example, a game model update is a AAPLMove object, so the board applies a move by calling its addChip: method to drop a chip of the current player’s color in the column specified by the AAPLMove object. This method is also responsible for letting GameplayKit know the order of turns in your game, so that when the strategist plans several turns ahead it knows which player is moving on which turn. This example is a two-player game, so the applyGameModelUpdate: method switches the activePlayer property to the current player’s opponent on each move.

For the minmax strategist to determine which of the possible moves is the best choice, your game model must indicate when it represents a more or less desirable state of the game, as shown in Listing 5-6.

The first step in enabling a strategist to select optimal moves is identifying when a game model represents a win or a loss. You provide this information in the isWinForPlayer: and isLossForPlayer: methods. In the FourInARow example, the runCountsForPlayer method provides a convenient way to test for wins—as the name of the game suggests, the player wins with a run of four chips in a row.

Because this game is for two players only, a loss for the player is by definition a win for the player’s opponent, and vice versa, so you can implement the isLossForPlayer: method in terms of the isWinForPlayer: method. (In a game with more than two players, this assumption might not be true. For example, a winner might be determined only after all other players have lost.)

Armed with only the knowledge of winning and losing game states, the minmax strategist can play the game. The GKMinmaxStrategist class automatically ignores possible moves after a win or loss, and it weighs its decisions based on how many moves in the future an expected win or loss is. However, at this point the strategist does not play the game very well, because there are a number of possible states of the game with equal numbers of possible future wins or losses.

To improve the strategist’s gameplay, use the scoreForPlayer: method to implement a heuristic—an estimate of how desirable the current state of the board is to the player. Alternately, a score represents an estimate of how likely the player is to win, or how soon, the player can win. The FourInARow example uses a heuristic based on its runCountsForPlayer method, assuming that, for example, a player with two runs of two chips each is more likely to win soon than a player with no runs. Because the player’s success or failure is related to that of the opponent, the scoreForPlayer: method totals the player’s number and length of runs and subtracts from it the opponent’s number and length of runs.

Finally, a game model class must support copying itself and its internal state, so that the strategist can make multiple copies of a board for examining the results of possible future moves. Listing 5-7 shows how the AAPLBoard class copies itself.

The setGameModel: method copies the internal state of one GKGameModel object to another. Here, the AAPLBoard class simply copies its _cells array and currentPlayer property. The GKGameModel protocol requires conformance to the NSCopying protocol, so the copyWithZone: method uses the setGameModel: method to turn a new AAPLBoard instance into a copy.

To simulate possible moves, the strategist uses several copies of your GKGameModel class and calls the setGameModel: method many times. For example, looking ahead six turns in the FourInARow game (which has up to seven possible moves at any given time) requires examining hundreds of thousands of board states. (Rather than continually creating new instances of your game model class, GameplayKit makes only a few copies, and reuses those instances with the setGameModel: method. This optimization improves memory efficiency.)

Use a Strategist Object to Plan Moves

After you’ve adopted GKGameModel and related protocols in your gameplay model classes, using the minmax strategist requires only a few simple steps. To see how these steps are implemented in the FourInARow game, download the sample code project.

1. Keep a GKMinmaxStrategist instance in whatever controller code manages your gameplay model—for example, a view controller or SpriteKit scene.

2. Use the GKMinmaxStrategist object’s gameModel property to point to the current state of your game—that is, your model object that implements the GKGameModel protocol.

   Typically, you can do this only once, when initializing a new game, because the gameModel property will refer to the same GKGameModel object even as that object’s internal state changes. However, if you begin using a different instance of your model class (for example, when resetting the board for a new game), be sure to set the gameModel property again.

3. Set the maxLookAheadDepth property to the number of consecutive future moves you want to plan for.

   In general, deeper lookahead results in a stronger computer-controlled player. However, deeper lookahead also exponentially increases the amount of work the strategist must do to plan a move. Choose a lookahead depth that provides the desired level of difficulty for your game without sacrificing performance.

   For example, the FourInARow game requires four chips in a row to win. Therefore, if a computer-controlled player always makes the optimal move, it should theoretically always be able to either win or force a draw when the lookahead depth is seven—four of the strategist’s own turns plus the intervening three opponent turns. (Whether that theory holds true depends on the robustness of your scoreForPlayer: method.) For this game, a lookahead depth of seven results in a search space of nearly a million possible board states.

4. To plan the computer-controlled player’s next move, use the bestMoveForPlayer: method. This method returns a GKGameModelUpdate object (in the FourInARow example, an AAPLMove object) corresponding to the chosen move. To perform the move, use your gameplay model’s applyGameModelUpdate: method.

   Alternatively, use one of the other methods listed in GKMinmaxStrategist Class Reference, which provide options for handling cases with multiple “best” moves or randomizing moves.