GameplayKit Namespace

The GameplayKit namespace provides classes for high-level game-playing mechanics such as pathfinding, rules engines, and AI opponents.

Classes

GKAgent

A GKComponent that can move and has goals.

GKAgent2D

A GKAgent whose movement is restricted to two dimensions.

GKAgent3D

A 3D agent that responds to goals.

GKAgentDelegate

Delegate object that provides methods relating to synchronizing the state of a GKAgent with external constraints, goals, and representations.

GKAgentDelegate_Extensions

Extension methods to the IGKAgentDelegate interface to support all the methods from the GKAgentDelegate protocol.

GKARC4RandomSource

Random generator based on the ARC4 algorithm. Often a good choice.

GKBehavior

A collection of GKGoal objects and weights, together defining a cohesive game behavior.

GKBillowNoiseSource

A GKCoherentNoiseSource whose output is similar to Perlin noise but with more rounded features.

GKCheckerboardNoiseSource

A GKNoiseSource whose output consists of alternating black and white squares.

GKCircleObstacle

A GKObstacle defined by a location and a radius.

GKCoherentNoiseSource

A GKNoiseSource whose output varies smoothly and continuously.

GKComponent

Abstract superclass for components, including GKAgent objects, in an Entity-Component architecture (see remarks).

GKComponentSystem<TComponent>

Holds GKComponent objects of a specific subtype and updates them periodically.

GKCompositeBehavior

A GKBehavior that combines other GKBehavior objects.

GKConstantNoiseSource

A GKNoiseSource whose output is a single value.

GKCylindersNoiseSource

A GKNoiseSource whose output consists of concentric cylindrical shells. Appropriate for wood-grain textures.

GKDecisionNode

An element in a GKDecisionTree.

GKDecisionTree

A tree of questions, answers, and actions.

GKEntity

A type that is composed of a number of GKComponent objects in an Entity-Component architecture.

GKGameModel

Describes gameplay in a way that can be optimized with a GKMinMaxStrategist.

GKGameModel_Extensions

Extension methods to the IGKGameModel interface to support all the methods from the GKGameModel protocol.

GKGameModelPlayer_Extensions

Extension methods to the IGKGameModelPlayer interface to support all the methods from the IGKGameModelPlayer protocol.

GKGaussianDistribution

A GKRandomDistribution that produces a Gaussian (normal) distribution.

GKGoal

Influences the movement of one or more GKAgent objects.

GKGraph

A mathematical graph used for navigability and pathfinding.

GKGraphNode

The base class for nodes in a GKGraph.

GKGraphNode2D

A GKGraphNode that contains a 2D floating-point position.

GKGraphNode3D

A GKGraphNode that exists in three-dimensional space.

GKGridGraph

A GKGraph in which movement is constrained to an integer grid

GKGridGraphNode

A GKGraphNode that contains a 2D integer position.

GKHybridStrategist

A IGKStrategist that combines Monte Carlo Tree Search and local search via MinMax.

GKLinearCongruentialRandomSource

A fast GKRandomSource. Low-order bits are somewhat less random than in GKARC4RandomSource.

GKMersenneTwisterRandomSource

A slow GKRandomSource with very good randomness.

GKMeshGraph<NodeType>
GKMinMaxStrategist

Game AI that evaluates potential game states, scores them, and attempts to maximize it's own score while minimizing it's opponents.

GKMonteCarloStrategist

A strategist that reaches a solution that is probably close to optimal in a deterministic amount of time.

GKNoise

Uses a GKNoiseSource to procedurally generate an infinite three-dimensional noise field.

GKNoiseMap

Slices a finite, two-dimensional rectangle from a GKNoise object's infinite, three-dimensional noise field.

GKNoiseSource

Abstract base class for procedural noise generators.

GKNSPredicateRule

A GKRule that uses a NSPredicate to determine if it's action should be called.

GKObstacle

Abstract class representing areas that GKAgent objects cannot traverse.

GKObstacleGraph

A GKGraph that generates a space-filling network for representation, allowing smooth, but inefficient, paths.

GKObstacleGraph<NodeType>
GKOctree<ElementType>

A data structure that efficiently organizes three-dimensional elements.

GKOctreeNode

A node in a GKOctree<ElementType>. Automatically managed by the GKOctree<ElementType> as objects are added and removed.

GKPath

Holds a 2D polygonal path that can be followed by a GKAgent.

GKPerlinNoiseSource

A GKCoherentNoiseSource that generates improved Perlin noise.

GKPolygonObstacle

A GKObstacle with an arbitrarily complex shape.

GKQuadTree

A data structure that efficiently organizes objects in two-dimensional space.

GKQuadTreeNode

A node in a quadtree.

GKRandomDistribution

Defines a probability distribution. This class defines a uniform distribution (all values equally likely), while subclasses GKGaussianDistribution and GKShuffledDistribution provide different likelihoods.

GKRandomSource

Base class for game-appropriate pseudo-random number generators. Do not use for cryptographic or security purposes.

GKRidgedNoiseSource

A GKCoherentNoiseSource whose output is similar to Perlin noise but with sharp boundaries.

GKRTree<ElementType>

A data structure for efficiently searching objects arranged in two-dimensional space.

GKRule

A single element, comprising a predicate and an action, that represents a discrete rule in a GKRuleSystem.

GKRuleSystem

Maintains a collection of GKRule objects, activating them as appropriate.

GKScene

Associates GameplayKit objects with a SpriteKit SKScene.

GKSCNNodeComponent

A GKComponent that operates on a SCNNode.

GKShuffledDistribution

A GKRandomDistribution that shuffles a collection in a manner that makes sequences of similar values unlikely (minimal hot/cold streaks).

GKSKNodeComponent
GKSphereObstacle

A GKObstacle that is an impassable spherical volume.

GKSpheresNoiseSource

A GKNoiseSource whose output consists of concentric shells. Appropriate for wood-grain textures.

GKState

An abstract class representing a discrete state in a GKStateMachine.

GKStateMachine

Holds GKState objects and manages transitions between them.

GKVoronoiNoiseSource

A GKNoiseSource whose output divides space into cells surrounding seed points. Appropriate for crystalline textures.

NSArray_GameplayKit
SCNNode_GameplayKit
SKNode_GameplayKit

Structs

GKBox

An axis-aligned rectangular three-dimensional box.

GKQuad
GKTriangle

Interfaces

IGKAgentDelegate

Interface representing the required methods (if any) of the protocol GKAgentDelegate.

IGKGameModel

The current game state. Particularly useful in conjunction with GKMinMaxStrategist.

IGKGameModelPlayer

A uniquely-identified player of a game. Developers must implement GetPlayerId(IGKGameModelPlayer).

IGKGameModelUpdate

A valid game move. The minimal data necessary to transition a valid IGKGameModel into a valid subsequent state.

IGKRandom

Interface for GameplayKit pseudo-random number generators.

IGKSceneRootNodeType
IGKStrategist

Interface for a game strategist (AI).

Enums

GKMeshGraphTriangulationMode

Holds options for how nodes should be generated in a GKMeshGraph<NodeType>.

GKRTreeSplitStrategy

Remarks

Introduced in iOS 9, GameplayKit provides classes for high-level game-playing mechanics such as pathfinding, rules engines (both fuzzy and classical), and a prebuilt AI opponent in the form of GKMinMaxStrategist.

AI Opponent

The minimax theorem, first stated by John von Neumann in 1928, holds that in a two-person, zero-sum, game with finite strategies, there exists some optimal play (or plays) that simultaneously maximizes the expected value for the current player and minimizes the expected value for the opposing player. In other words, in such games, there is a "best move" (although, of course, even the best move might lead to a loss or a tie, depending upon the state of the game).

GameplayKit implements the minimax algorithm in its GKMinMaxStrategist class and related classes (especially GKGameModel). The GKMinMaxStrategist is an optimized version of the minimax algorithm that uses memory efficiently and pares the search-tree at terminal nodes, but developer's should be aware that the algorithm can be costly: minimax algorithm's time efficiency is O(b^m) where b is the number of states in a single look-ahead "ply" and m is the number of plies searched (see P:MonoTouch>GameplayKit.GKMinMaxStrategist.MaxLookAheadDepth). The algorithm's space efficiency is O(m).

The minimax theorem applies to a very large number of games, from trivial ones such as Nim and Tic-Tac-Toe, to complex games such as Chess and Go. However, games such as Chess and Go have so many possible game states and plies that the expense of calculating the optimal move quickly becomes astronomical. Even in such cases, the GKMinMaxStrategist may be used to evaluate several hundred or thousand moves and, if the developer can accurately program an estimate of the strength or weakness of a given game state, produce a strong opponent.

The GKMinMaxStrategist does not need to be subclassed by the developer. Rather, the developer implements three interfaces and passes these to the GKMinMaxStrategist:

ClassPurpose
IGKGameModel Developers implement this interface in order to model the game and it's current state. In a board game, for instance, this will typically be the board and all pieces and a reference to the active player. In addition, if it is to be used with GKMinMaxStrategist, this class must implement the functions that describes potential moves (M:GameplayKit.GKGameModule.GetGameModelUpdates*) and evaluates them in terms of desirability (IsWin, IsLoss, GetScore).
IGKGameModelUpdate This class describes a game "move" and contains enough information to transition the IGKGameModel between it's current state and a valid new one. Many thousand instances of this class may be required by the GKMinMaxStrategist, so the developer should take care to make it lightweight.
IGKGameModelPlayer The GKMinMaxStrategist relies on the value of M:GameplayKit.IGKGameModelPlayer.GetPlayerID*) to distinguish between players.

The key method of the GKMinMaxStrategist is GetBestMove. When this method is called, the following sequence of calls occurs:

First, the IGKGameModelPlayer objects are retrieved. Then, starting with the current game state, and while the ply depth is less than MaxLookAheadDepth, the set of legal possible moves from the current state is returned by M:GameplayKit.GKMinMaxStrategist.GetGameModelUpdates*. Then, for each of these moves, it may be necessary for the GKMinMaxStrategist to allocate new memory; if so, M:GameplayKit.GKMinMaxStrategist.Copy* is called. Then, on one of the many GKGameModel objects being managed by the GKMinMaxStrategist, a potential move is executed with calls to SetGameModel and M:GameplayKit.IGKGameModel.ApplyGameState*.

The GKMinMaxStrategist then evaluates each of the potential moves by calling, first, IsWin and IsLoss. If either of these methods returns true, the GKMinMaxStrategist marks that game state as a terminal node and will not attempt to investigate it further in later plies. If neither method returns true, though, the method M:GameplayKit.GKGameModel_Extensions.Score* is called.

The developer should write a M:GameplayKit.GKGameModel_Extensions.Score* method to return a value between MinScore (-16777216) and MaxScore (+16777216). Higher values represent game states that are better for the GetActivePlayer. In simple games where the entire game tree can be searched because IsWin or IsLoss always return true within MaxLookAheadDepth, the M:GameplayKit.GKGameModel_Extensions.Score* method can simply return 0, because the GKMinMaxStrategist can calculate the best move based on the winning and losing moves. However, this is only likely to be the case in quite-easy games and, in general, crafting a well-performing M:GameplayKit.GKGameModel_Updates.Score* function will require both game-playing and programming expertise. In terms of programming, the M:GameplayKit.GKGameModel_Updates.Score* method is called many times during the search of the game-tree and needs to be efficient, as well as accurate.

Developers should note that the GKMinMaxStrategist may allocate many copies of IGKGameModelPlayer and IGKGameModel as well as many IGKGameModelUpdate objects. Developers should rely on value, not reference, equality, and should exercise care when it comes to these objects manipulating global or static state.