Protocol

GKGameModel

Implement this protocol to describe your gameplay model so that a strategist object can plan game moves.

Declaration

@protocol GKGameModel

Overview

You adopt this protocol to describe the gameplay of your turn-based game for use by a GKStrategist object. The strategist uses your game model class (that is, the class you create to adopt this protocol), along with other custom classes you create (adopting the GKGameModelPlayer and GKGameModelUpdate protocols), to find optimal moves.

GameplayKit relies on your game model class for several parts of its strategy algorithm.

  • Identifying possible changes to the game state. Your gameModelUpdatesForPlayer: method and your move class (a custom class implementing the GKGameModelUpdate protocol) describe the set of moves available during a given player’s turn.

  • Simulating future moves on a copy of the game. Your setGameModel: method allows GameplayKit to work with a separate instance of the game model—that is, not the one representing the actual game in play—and your applyGameModelUpdate: uses the information in your move class to perform hypothetical moves on that separate copy of the game.

  • Rating the desirability of possible future states of the game. Each time GameplayKit performs a hypothetical move in its copy of the game model, it calls your isWinForPlayer:, isLossForPlayer:, or scoreForPlayer: method to evaluate that state of the game from the perspective of a particular player.

When you use a strategist to plan moves in your game, it uses your game model to combine these parts into a strategy: By identifying, performing, and rating the success of possible future moves, the strategist can choose a move most likely to result in a future win. This process involves using the copyWithZone: and setGameModel: methods to evaluate many possible states of a game model—for best results, ensure that your game model class contains only the information critical to describing your game and that it can copy that state quickly.

For more information about describing your gameplay model and using a strategist, see The Minmax Strategist in GameplayKit Programming Guide.

Topics

Keeping Track of Players

players

The players currently in the game.

Required.

activePlayer

The player whose turn it currently is in the game.

Required.

Evaluating a Game Model

- gameModelUpdatesForPlayer:

Returns the set of moves available to the specified player.

Required.

- scoreForPlayer:

Returns a number rating the desirability of the game model’s current state from the perspective of the specified player.

- isLossForPlayer:

Returns a Boolean value indicating whether the specified player has lost the game.

- isWinForPlayer:

Returns a Boolean value indicating whether the current state of the game model reflects a win for the specified player.

Modifying a Game Model

- applyGameModelUpdate:

Updates the internal state of the game model to reflect the specified changes.

Required.

- unapplyGameModelUpdate:

Updates the internal state of the game model to remove the effect of the specified changes.

- setGameModel:

Sets the game model’s internal state to that of the specified game model.

Required.

Constants

Game Model Score Limits

Limits to values returned by the scoreForPlayer: method.

Relationships

Inherits From

See Also

Strategists

GKStrategist

A general interface for objects that provide artificial intelligence for use in turn-based (and similar) games.

GKMinmaxStrategist

An AI that chooses moves in turn-based games using a deterministic strategy.

GKMonteCarloStrategist

An AI that chooses moves in turn-based games using a probabilistic strategy.

GKGameModelPlayer

Implement this protocol to describe a player in your turn-based game so that a strategist object can plan game moves.

GKGameModelUpdate

Implement this protocol to describe a move in your turn-based game so that a strategist object can plan game moves.