A node-based finite state machine for Godot 4: one node per state, transitions by signal, and a slime enemy that idles, roams, chases, telegraphs a leap, staggers when hit and dies.

The label over each slime is its current state; the list on the right is every transition as it happens.

Features

• Two small scripts. StateMachine (about 70 lines) and State (about 30) are the whole system. Everything else is the demo.
• One node per state. Add a child node, attach a script that extends State, and its node name is its state name. The Scene tree shows the whole machine at a glance.
• Transitions by signal. A state leaves by emitting transitioned.emit("Chase"). States never reference each other or the machine, so you can add or remove one without touching the rest.
• Forced transitions from outside. change_state("Hitstun") lets a hit, a cutscene or a trigger interrupt whatever the AI was doing.
• Four hooks per state: enter(), exit(), update(delta) every frame and physics_update(delta) every physics frame.
• A state_changed(from, to) signal for debug labels, logs, analytics or animation.
• A complete enemy to learn from: six states, NavigationAgent2D chasing, a telegraphed leap that only hits on landing, and a vulnerable window after it.

Requirements

• Godot 4.7 or later, standard build (GDScript only, no .NET needed).
• Tested on Godot 4.7.2 stable on Windows. Earlier 4.x versions are untested.
• Uses the Compatibility renderer, so it runs on older GPUs too.

Quick Start

1. Press F5.
2. Move with WASD. Swing with Space or a left click.
3. Walk toward a slime and watch its label: Idle or Roam, then Chase, then Attack when it gets close.
4. Step out of the way of the leap, then hit it while it is pale blue.
5. Press R to restart.

Known Limitations

• One state at a time. There are no nested (hierarchical) or parallel states.
• Transitions are by node name. A typo in transitioned.emit("Chsae") is silently ignored, so keep names consistent.
• The demo room is open, so navigation is a single rectangle. Bake a real NavigationPolygon for levels with walls inside.
• Slimes always know where the player is within range; there is no line of sight.
• Tested on Godot 4.7.2 on Windows only.

License

MIT for the code. See LICENSE.

Third-Party Assets

The knight, sword and slime sprites are from Tiny Dungeon by Kenney, released under CC0 1.0. Details in THIRD_PARTY_ASSETS.md, and the pack's original license is in assets/kenney_tiny-dungeon/License.txt.

Learn How It Works

Want to understand how this works instead of just copying it?

CodingQuests teaches you how to build systems like this step by step in Godot, with interactive lessons and real projects.

• 2D Top-Down Enemy AI builds this six-state machine: idle, roam, chase, the telegraphed leap, hitstun and death, with NavigationAgent2D pathfinding. The first 2 lessons are free.
• State Machine AI for 3D Enemies takes the same idea into 3D. The first 4 lessons are free.

Source code, integration instructions and issue tracker: https://github.com/CodingQuests/godot-state-machine