I built a small deckbuilder for a devchallenge jam, and like every first-time card game dev, I started with the thing that feels natural in Godot: signals and callbacks. card_played fires, which triggers on_card_played() on three other systems, one of which emits mana_spent, which triggers a UI update and also checks win conditions. It worked great for about two weeks. Then I added triggered abilities ("whenever a creature dies, draw a card") and the whole thing turned into a debugging nightmare where I genuinely could not tell you what order things happened in.
This post is about the rewrite: modeling turn structure, phases, and triggered abilities as an explicit finite-state machine (FSM), and why that unlocked undo/replay almost for free.
🔥 Why Callback Spaghetti Falls Apart
The core issue with signal-driven turn logic isn't that signals are bad — it's that turn order becomes implicit and distributed. Nobody owns "what happens next." Every system that connects to card_played is independently deciding when it's allowed to react, and Godot's signal dispatch order depends on connection order, which depends on scene tree instantiation order, which depends on... nothing you want to be debugging at 2am.
Concretely, this breaks down in three ways once your game grows past trivial complexity:
- Re-entrancy bugs. A triggered ability plays a card, which triggers another ability, which tries to play a card during the resolution of the first one. Your "current phase" variable gets stomped mid-resolution.
-
No single source of truth for "can I act right now?" UI buttons end up checking five different booleans (
is_resolving,is_my_turn,can_respond) that drift out of sync. - Undo is basically impossible. You can't cleanly rewind a cascade of signal emissions that already mutated game state in six different places.
The fix is to stop treating turn progression as "things that happen when events fire" and start treating it as a graph of named states with explicit, enumerable transitions.
🧱 The State Machine Itself
I modeled the turn as a strict phase sequence, with each phase being a distinct state object rather than a flag:
gdscript
enum Phase {
UNTAP,
UPKEEP,
DRAW,
MAIN,
COMBAT,
MAIN_2,
END,
CLEANUP,
}
class_name TurnStateMachine
extends RefCounted
var current_phase: Phase = Phase.UNTAP
var transition_table := {
Phase.UNTAP: Phase.UPKEEP,
Phase.UPKEEP: Phase.DRAW,
Phase.DRAW: Phase.MAIN,
Phase.MAIN: Phase.COMBAT,
Phase.COMBAT: Phase.MAIN_2,
Phase.MAIN_2: Phase.END,
Phase.END: Phase.CLEANUP,
Phase.CLEANUP: Phase.UNTAP,
}
signal phase_entered(phase: Phase)
signal phase_exited(phase: Phase)
func advance() -> void:
phase_exited.emit(current_phase)
current_phase = transition_table[current_phase]
phase_entered.emit(current_phase)
This alone doesn't look that different from what people already do. The real difference is the rule I enforced everywhere else in the codebase: nothing is allowed to mutate game state outside of a phase transition or an explicit action resolution. No system is allowed to "just react" whenever it feels like it. If something wants to happen, it has to go through the machine.
⚡ Triggered Abilities as Queued Transitions, Not Side Effects
The thing that actually broke my original signal-based design was triggered abilities. "Whenever a creature dies, draw a card" sounds simple until three creatures die simultaneously from one board wipe, and two of those deaths also trigger abilities that kill other creatures.
The fix: triggers don't execute immediately. They get pushed onto a resolution queue, and the state machine has a dedicated RESOLVING_TRIGGERS state that drains the queue one at a time, re-checking for new triggers after each resolution (this mirrors how Magic: The Gathering's actual rules engine handles the stack, and for good reason — it's a solved problem).
gdscript
var trigger_queue: Array[TriggeredAbility] = []
func queue_trigger(ability: TriggeredAbility) -> void:
trigger_queue.append(ability)
if current_phase != Phase.RESOLVING_TRIGGERS:
_enter_resolution_state()
func _enter_resolution_state() -> void:
var previous_phase := current_phase
current_phase = Phase.RESOLVING_TRIGGERS
while not trigger_queue.is_empty():
var ability := trigger_queue.pop_front()
ability.resolve()
# resolving may queue MORE triggers — loop keeps draining
current_phase = previous_phase
This single change killed an entire category of bugs. Because resolution is a loop inside one state rather than a chain of emitted signals, there's no ambiguity about ordering, and I can log the queue at any point to see exactly what's pending.
⏪ Undo and Replay, Almost for Free
Once every state mutation happens through a small set of commands rather than ad-hoc function calls, undo and replay stop being special features and become a natural consequence of the architecture. I used a lightweight command pattern where every action produces a reversible record:
gdscript
class_name GameCommand
extends RefCounted
func apply(state: GameState) -> void:
push_error("override me")
func revert(state: GameState) -> void:
push_error("override me")
class DrawCardCommand extends GameCommand:
var player_id: int
var drawn_card_id: String
func apply(state: GameState) -> void:
drawn_card_id = state.decks[player_id].pop_front()
state.hands[player_id].append(drawn_card_id)
func revert(state: GameState) -> void:
state.hands[player_id].erase(drawn_card_id)
state.decks[player_id].push_front(drawn_card_id)
The turn engine keeps a flat history list. "Undo" is just revert() on the last command. Replay for the jam's leaderboard verification is just replaying the command list from an empty GameState and checking the hash at the end matches. I didn't design the command log for replay specifically — it fell out of needing undo during the "take back a misclick" phase of playtesting, and the replay feature was maybe 40 lines of glue on top.
🤔 The Trade-offs (Because Nothing's Free)
To be fair about the cost: this architecture is more boilerplate upfront. Every single action — drawing a card, dealing damage, tapping a permanent — needs its own command class instead of a quick one-liner in a signal handler. For a jam with a 72-hour timer, that felt expensive on day one.
It also makes animation sequencing trickier, because visual feedback wants to happen during state changes, not strictly before or after. I ended up having commands emit a visual_hint payload that the presentation layer consumes asynchronously, decoupled from the actual state mutation timing — the state machine doesn't wait on animations, ever.
And if your game genuinely has no triggered abilities, no undo requirement, and a fixed linear turn order, you may not need any of this. Signals are fine for a tic-tac-toe clone. The complexity is earned, not default.
💬 Over to You
If you've shipped a card or board game with any kind of "stack" of triggered effects — how did you handle simultaneous triggers and ordering? Did you go full FSM, or find a lighter-weight trick that worked for your scope? I'd genuinely like to know what breaks first in other people's designs, because mine was ordering, and I suspect that's not universal.
Top comments (0)