state.gd
simplified
Loading…
The shape every state follows. Every concrete state must implement these methods.
Architectural Pattern · №01
The State Machine
At any given moment, you’re in a state of mind, unfortunately, it didn’t come with a debugger.
01 · What is a state?
You already have a state machine in your head.
calm
frustrated
happy
Before anything else, consider this: you have emotions.
It all starts with a State. So what is a State?
Your mind already understands this pattern. At any given moment, you exist in a dominant emotional State. Calm, frustrated, focused, distracted; a dominant emotion dictates how you feel and heavily influences your behavior.
Then something happens... a trigger, a message, a thought, a memory. And just like that, you transition. Calm becomes irritated. Focus becomes distraction.
Those are States, and your mind is a State machine. Transitioning from one State to another.
You don’t feel everything equally at once, you transition from one State at a time. (Human beings are more complex than this, but we simplify to make the pattern clear.) And each State changes how you respond to the world around you.
Now, let’s build on that. An @abstract State is a template. Machines don’t have emotions like we do,
so we define what a State is for them. The @abstract State acts as a blueprint script like the idea of an emotion dictionary.
Every real State follows the same structure defined by this script:
enter — process — exit
These are called functions (or func in code). Every emotion has an enter:
the moment it begins. A process: how it shapes your thoughts and actions. And an exit:
the point where something shifts and transitions you into something new.
That structure is what allows a machine to process States. Turning something abstract into something predictable.
calm
calm_state
pseudo-code
Three files. A simplified version of the pattern, using real GDScript. Important bit, each of these scripts inherits from the @abstract State script mentioned earlier. That's how we enforce rules to make every new State created; idle_state, move_state have the same base funcs -- enter, process, exit Skip if you're comfortable with the concept — section 02 shows the full version.
If you're curious, here it is in real code.
Three files. A simplified version of the pattern, using real GDScript. Read them if you want to see how the shape above becomes actual code. Skip if you're comfortable with the concept — section 02 shows the full version.
idle_state.gd
simplified
Loading…
Idle: do nothing, watch for input. When a direction is pressed, hand off to Move.
move_state.gd
simplified
Loading…
Move: drive velocity from input. When the input stops, hand back to Idle.
02 · Before & after
Same behaviour. Different shape.
The comments inside each file are the main teaching surface — read them as you go. Toggle between Before and After, then use the file switcher to see how the pattern is split across small, focused files.
procedural.gd
before
Loading…the‑botanist / objects / state_machine
after
Loading…03 · The pattern in action
See the machine run.
Here is the pattern running in a real game. Character transitions between states as input changes, each state's enter and exit firing at the moment of change. No simulation — this is actual Godot, actual GDScript, actual state machine.
Recording coming soon
A short clip of the state machine running in The Botanist.
Recording of the state machine running in The Botanist.
04 · Guidance
When to reach for it. When not to.
Reach for the pattern when…
- You have three or more distinct modes of behaviour that share an actor.
- Different modes need different enter / exit side effects — animations, timers, sounds.
- You want to add modes later without touching the existing ones.
- You want the same machine to drive a different actor (Player → NPC).
Don't reach for it when…
- You have one
if. One is not a state machine crisis. - The behaviour is continuous, not modal — a vehicle's speed curve, a rotation lerp.
- Your "states" are really just boolean flags that can all coexist.
- You haven't felt the pain the pattern solves. Write it procedurally first.
05 · Pairs naturally with
What to read next.
06 · Further reading
Straight from the source.
The official Godot documentation is the best reference for every concept on this page. We link generously and quote sparingly — the docs deserve your attention directly.