Class

GKStateMachine

A finite-state machine—a collection of state objects that each define logic for a particular state of gameplay and rules for transitioning between states.

Declaration

@interface GKStateMachine : NSObject

Overview

In GameplayKit, you subclass GKState to define each state and the rules for allowed transitions between states, and use a GKStateMachine instance to manage a machine that combines several states. This system provides a way to organize code in your game by organizing state-dependent actions into methods that run when entering a state, when exiting a state, and periodically while in a state (for example, on every animation frame your game renders).

You can use state machines to govern various aspects of a game. For example:

  • An enemy character might use a state machine with Chase, Flee, Dead, and Respawn states, each of which drives the enemy’s behavior, with state transitions determined by player actions and elapsed time.

  • An automated turret might use a state machine with Ready, Firing, and Cooldown states, controlling when it seeks out nearby targets and how often it fires.

  • A game user interface might use Menu, Playing, Paused, and GameOver states, each of which determines what UI elements are shown and what other game elements are running.

To build a state machine, first define a distinct subclass of GKState for each possible state of the machine. In each state class, the isValidNextState: method determines which other state classes the machine may transition into from that state. Then, create a state machine object by constructing instances of the state classes and passing them to one of the methods listed in Creating a State Machine. Finally, set the machine in motion by choosing an initial state for it to enter with the enterState: method.

To define state-dependent behavior, override the didEnterWithPreviousState:, updateWithDeltaTime:, and willExitWithNextState: methods in each GKState subclass.

  • The state machine notifies the current state whenever a state change happens. Use the didEnterWithPreviousState: and willExitWithNextState: methods to perform actions in response to a state change. For example, an enemy character entering the Flee state might change its appearance to indicate that is has become vulnerable to attack by the player.

  • When you call a state machine’s updateWithDeltaTime: method, the state machine calls the updateWithDeltaTime: method of its current state. Use this method to organize per-frame update code by state. For example, an enemy character in the Chase state can update its position to pursue the player, and an enemy in the Flee state can update its position to evade the player.

For more information about state machines, read State Machines in GameplayKit Programming Guide.

Topics

Creating a State Machine

- initWithStates:

Initializes a state machine with the specified states.

+ stateMachineWithStates:

Creates a state machine with the specified states.

Working with States

currentState

The state machine’s current state.

- canEnterState:

Returns a Boolean value indicating whether it is valid for the state machine to transition from its current state to a state of the specified class.

- enterState:

Attempts to transition the state machine from its current state to a state of the specified class.

- stateForClass:

Returns the state object in the state machine corresponding to the specified class.

- updateWithDeltaTime:

Tells the current state object to perform per-frame updates.

Relationships

Inherits From

See Also

State Machines

GKState

The abstract superclass for defining state-specific logic as part of a state machine.