Godot 4 state machine for a player: enum or nodes, with code

A state machine is a variable that says what the character is doing right now, plus one place that decides when that changes. Use one when a player has three or more modes that react differently to the same input: running, jumping, falling, getting hit. With only idle and run, two booleans are fine.

This guide writes the same player twice in GDScript for Godot 4.5.1, once as an enum with a match and once as a node per state. Both run the same scripted session of 359 physics ticks, about 6 seconds, with a run, two jumps, a hit and a drop off a ledge. They end up in the same state with the same position on every tick. The picture plays that session. The character is the Pilot from Pinglets, our desktop pet.

Booleans like is_jumping, is_hurt and is_running can be true at the same time, and every new feature adds a check to each of them. A state machine rules that out: the character is in exactly one state, so it cannot be hurt and jumping.

Declare the states in an enum, keep the current one in a variable, and match on it in _physics_process. Each branch reads input and calls _enter when something changes. _enter is the one place where a transition does work: it sets the jump velocity or starts the hurt timer.

Read the direction once, before the match, so every state sees the same value. The state logic runs first and move_and_slide() last, because is_on_floor() describes the previous move. Needs the input actions move_left, move_right and jump.

There is no animation code here. To add it, play the clip inside _enter. The animation then always matches the state, because nothing else picks it.

Make one node per state and put them under a StateMachine node that is a child of the player. The machine holds the current state, calls its physics_update every tick, and switches when the state returns the name of another state. Returning &"" means stay.

Order matters. A parent runs its _physics_process before its children, so by default the player would move first and the state would set velocity for the next tick, one tick late. Setting process_physics_priority = -1 on the machine makes it run first. With that line the node version matches the enum version on all 359 ticks. Without it, the positions differed on 282 of 359 ticks, starting at tick 11.

A state is a small script that extends the base class. Run reads the direction, sets the horizontal speed and returns the name of the next state when something changes. It never switches itself, so every transition in the project is a return line you can search for.

Jump sets velocity.y in enter, which runs once. Hurt starts a 0.3 second timer and never reads input, so the jump pressed on tick 212 of the session did nothing: the character stayed in Hurt for 22 ticks, from tick 205, because it also waits to touch the floor.

The player script gives each state its reference in _ready, then starts the machine. Children run _ready before their parent, which is why the player does it and not the machine. In the scene tree the states are plain Node children, so adding a state means adding a node and a script, and initial is set in the Inspector.

Start with the enum. Switch to nodes when a single state needs its own variables, timers or child nodes, such as a dash with a cooldown or an attack with a hitbox, or when two people edit different states.

The cost is files. The same behavior took 64 lines in one file as an enum and 137 lines in 8 files as nodes, counting blanks and comments. In return each node state can be tested alone, and the same machine and base class work for an enemy. For a three state enemy, nodes are too much.

Godot also has a state machine inside AnimationTree. That one picks animations. It does not replace the gameplay state; the gameplay state tells it which animation to play.

Write the table before the code: for every state, which events matter and where they lead. A cell that says ignored means the state never reads that input.

Two rows carry most of the value. Hurt ignores everything, which is what makes a hit feel like a hit; the rest of that feeling is in the game feel checklist. Jump and Fall ignore the jump press, which is why there is no double jump until you add one on purpose. Coyote time is a rule about Fall: allow a jump for a few frames. Add it there and nowhere else, as described in coyote time and jump buffering.

Every grounded state needs the exit to Fall when the floor disappears. Skip it and a character on a moving platform keeps the idle animation in the air.

Write the input as a script and record the state on every tick. record.gd extends SceneTree, builds both players in code, presses move_right and jump on chosen ticks with Input.action_press, waits one process_frame per tick and writes the states to a file. Run it with godot --headless --fixed-fps 60 --script record.gd. In this session the states first change on these ticks: Run 10, Jump 75, Fall 95, Hurt 205.

hurt() is called by whatever hit the player. Connect that with a signal, as in signals and the event bus, so the enemy does not need to know the player's states. A trace like this is also a regression test: store it, change the code, and diff. Keep the session short and make it hit every arrow of the table once.

The mistakes that cost the most time: