# 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. ``` class GKStateMachine ``` ## Overview In GameplayKit, you subclass [`GKState`](/documentation/GameplayKit/GKState) to define each state and the rules for allowed transitions between states, and use a [`GKStateMachine`](/documentation/GameplayKit/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`](/documentation/GameplayKit/GKState) for each possible state of the machine. In each state class, the [`isValidNextState(_:)`](/documentation/GameplayKit/GKState/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 below. Finally, set the machine in motion by choosing an initial state for it to enter with the [`enter(_:)`](/documentation/GameplayKit/GKStateMachine/enter(_:)) method. To define state-dependent behavior, override the [`didEnter(from:)`](/documentation/GameplayKit/GKState/didEnter(from:)), [`update(deltaTime:)`](/documentation/GameplayKit/GKState/update(deltaTime:)), and [`willExit(to:)`](/documentation/GameplayKit/GKState/willExit(to:)) methods in each [`GKState`](/documentation/GameplayKit/GKState) subclass. - The state machine notifies the current state whenever a state change happens. Use the [`didEnter(from:)`](/documentation/GameplayKit/GKState/didEnter(from:)) and [`willExit(to:)`](/documentation/GameplayKit/GKState/willExit(to:)) 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 [`update(deltaTime:)`](/documentation/GameplayKit/GKStateMachine/update(deltaTime:)) method, the state machine calls the [`update(deltaTime:)`](/documentation/GameplayKit/GKState/update(deltaTime:)) 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](https://developer.apple.com/library/archive/documentation/General/Conceptual/GameplayKit_Guide/StateMachine.html#//apple_ref/doc/uid/TP40015172-CH7) in [GameplayKit Programming Guide](https://developer.apple.com/library/archive/documentation/General/Conceptual/GameplayKit_Guide/index.html#//apple_ref/doc/uid/TP40015172). ## Topics ### Creating a State Machine [`- initWithStates:`](/documentation/GameplayKit/GKStateMachine/init(states:)) Initializes a state machine with the specified states. [`+ stateMachineWithStates:`](/documentation/GameplayKit/GKStateMachine/stateMachineWithStates:) Creates a state machine with the specified states. ### Working with States [`currentState`](/documentation/GameplayKit/GKStateMachine/currentState) The state machine’s current state. [`- canEnterState:`](/documentation/GameplayKit/GKStateMachine/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:`](/documentation/GameplayKit/GKStateMachine/enter(_:)) Attempts to transition the state machine from its current state to a state of the specified class. [`- stateForClass:`](/documentation/GameplayKit/GKStateMachine/stateForClass:) Returns the state object in the state machine corresponding to the specified class. [`- updateWithDeltaTime:`](/documentation/GameplayKit/GKStateMachine/update(deltaTime:)) Tells the current state object to perform per-frame updates. ### Instance Methods [`state(forClass:)`](/documentation/GameplayKit/GKStateMachine/state(forClass:)) ## Relationships ### Inherits From [`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class) ### Conforms To [`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible) [`CVarArg`](/documentation/Swift/CVarArg) [`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible) [`Hashable`](/documentation/Swift/Hashable) [`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol) [`Equatable`](/documentation/Swift/Equatable) --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)