Building a Game State Manager with State Machines

1. The Problem with Simple Flags

When first approaching this problem, a common instinct is to use a set of boolean flags to track the game's current state. For example:

bool is_in_menu = true;
bool is_playing = false;
bool is_paused = false;

while (game_is_running) {
    if (is_in_menu) {
        // process menu input, draw menu
    }
    if (is_playing && !is_paused) {
        // process game input, run physics, etc.
    }
    if (is_paused) {
        // draw pause overlay
    }
    // ...
}

This seems simple at first, but as you add more states (options menu, game over screen, loading screen), the number of flags and the complexity of the if conditions explode. It becomes difficult to manage, error-prone (what if is_in_menu and is_playing are both true?), and hard to debug.

The following video discusses this exact issue and introduces the concept of game states as a cleaner solution.

This tangled web of flags is a clear sign that we need a more structured approach.

2. Finite State Machines (FSMs)

The solution to this problem is a Finite State Machine (FSM). This is a model of computation that is perfect for what we're trying to achieve.

Conceptually, an FSM is defined by a few simple rules:

1. A finite number of states: The game can only be in a limited number of defined states (e.g., MENU, PLAYING, PAUSED).
2. One active state at a time: The game can't be in the menu and playing at the same time.
3. Transitions between states: The machine switches from one state to another based on inputs or events (e.g., pressing the 'Play' button transitions from MENU to PLAYING).

To understand these core principles more formally, watch the next short segment from the video by The Shaggy Dev.

3. A Simple Implementation: enum and switch

The most direct way to implement an FSM in C is by using an enum to define the states and a switch statement in the main loop to execute the logic for the current state.

First, we define our possible states:

// game.h (or a new state_manager.h)
typedef enum {
    GAME_STATE_MAIN_MENU,
    GAME_STATE_PLAYING,
    GAME_STATE_PAUSED,
    GAME_STATE_GAME_OVER
} GameStateEnum;

Then, in our main application structure, we would have a variable to hold the current state, and our game loop would use a switch to decide what to do.

// main.c
GameStateEnum current_state = GAME_STATE_MAIN_MENU;

while (game_is_running) {
    // --- Process Input ---
    // (Input handling might change current_state)

    // --- Update ---
    switch (current_state) {
        case GAME_STATE_MAIN_MENU:
            // update_main_menu();
            break;
        case GAME_STATE_PLAYING:
            // update_gameplay();
            break;
        case GAME_STATE_PAUSED:
            // update_pause_menu();
            break;
        // ... and so on
    }

    // --- Draw ---
    switch (current_state) {
        case GAME_STATE_MAIN_MENU:
            // draw_main_menu();
            break;
        case GAME_STATE_PLAYING:
        case GAME_STATE_PAUSED: // Draw the game world in both playing and paused states
            // draw_gameplay();
            if (current_state == GAME_STATE_PAUSED) {
                // draw_pause_overlay();
            }
            break;
        // ... and so on
    }
}

This is a huge improvement over boolean flags! The logic is much cleaner, and it's impossible for the game to be in an invalid combination of states. This approach is perfectly fine for simple games.

However, it has drawbacks. The logic for a single state (e.g., its input, update, and drawing code) is spread out across multiple switch statements. Furthermore, if a state needs its own data (like a timer for a charging attack, as mentioned in the Game Programming Patterns article), that data has to be stored in the main game struct, even if it's only used by one state.

4. A More Flexible Design: The State Pattern in C

To create a truly scalable system, we can use a design known as the State Pattern. In object-oriented languages like C++, you'd create a State interface and have separate classes for each state. In C, we can achieve the same level of encapsulation using a struct of function pointers.

The idea is to define a generic State structure that holds pointers to functions for the core behaviors: initializing, updating, drawing, and destroying.

// A generic state definition
typedef struct {
    void (*init)();
    void (*update)(float delta_time);
    void (*draw)(float delta_time);
    void (*destroy)();
} State;

Each actual state (like the main menu or gameplay) will be its own State instance, with its function pointers pointing to its own specific functions.

A StateManager will then manage a stack of these states. Using a stack is a powerful enhancement because it naturally handles nested states. For example, when you are in the PLAYING state and press pause, you can simply push the PAUSED state onto the stack. The game loop will now only run the update and draw functions for the state at the top of the stack (PAUSED). When you unpause, you pop the PAUSED state, and the PLAYING state is once again at the top, ready to resume.

The following article provides a complete C implementation of this exact concept. It's a fantastic resource that we will use to build our own state manager.

Implementing Our State Manager

Inspired by the article, let's create our own state_manager.h and state_manager.c. This implementation will be the core of our game's architecture.

state_manager.h

#ifndef STATE_MANAGER_H
#define STATE_MANAGER_H

// Represents a single game state with its own logic.
// The function pointers allow each state to define its own behavior.
typedef struct {
    void (*init)();
    void (*destroy)();
    void (*update)(float delta_time);
    void (*draw)(float delta_time);
} State;

// Manages a stack of game states.
void StateManager_Init();
void StateManager_Cleanup();

// Stack operations
void StateManager_Push(State* state);
void StateManager_Pop();
void StateManager_Change(State* state); // Convenience: pops current and pushes new

// Forward calls to the top state on the stack
void StateManager_Update(float delta_time);
void StateManager_Draw(float delta_time);




#endif // STATE_MANAGER_H

state_manager.c
This implementation uses a simple fixed-size array for the stack. The prdeving article shows how to make it dynamically resizable with realloc, which is a great improvement you can add later.

#include "state_manager.h"
#include <stdio.h>
#include <stdlib.h>




#define MAX_STATES 8

// The stack of states
static State* state_stack[MAX_STATES];
static int top = -1; // Index of the top of the stack

void StateManager_Init() {
    top = -1;
}

void StateManager_Cleanup() {
    // Pop and destroy all states on the stack
    while (top > -1) {
        StateManager_Pop();
    }
}

void StateManager_Push(State* state) {
    if (top + 1 >= MAX_STATES) {
        fprintf(stderr, "Error: State stack overflow.\n");
        return;
    }

    top++;
    state_stack[top] = state;

    // Call the state's init function if it has one (entry action)
    if (state->init) {
        state->init();
    }
}

void StateManager_Pop() {
    if (top < 0) return; // Stack is empty

    State* top_state = state_stack[top];

    // Call the state's destroy function if it has one (exit action)
    if (top_state->destroy) {
        top_state->destroy();
    }

    state_stack[top] = NULL;
    top--;
}

void StateManager_Change(State* state) {
    if (top > -1) {
        StateManager_Pop();
    }
    StateManager_Push(state);
}

void StateManager_Update(float delta_time) {
    if (top < 0) return;
    State* top_state = state_stack[top];
    if (top_state->update) {
        top_state->update(delta_time);
    }
}

void StateManager_Draw(float delta_time) {
    if (top < 0) return;
    State* top_state = state_stack[top];
    if (top_state->draw) {
        top_state->draw(delta_time);
    }
}

This design is clean and powerful. Each state's logic is fully encapsulated, and the init and destroy functions (called "entry" and "exit" actions in the Game Programming Patterns book) provide a clean way to set up and tear down a state when you transition.

Conclusion

Today we've laid a critical piece of our engine's foundation. We've moved beyond simple flags and implemented a robust system for managing the overall flow of our game.

Key Takeaways:

• Managing game flow with boolean flags is complex and error-prone.
• Finite State Machines (FSMs) provide a structured way to manage game states, ensuring only one state is active at a time and transitions are handled cleanly.
• A simple FSM can be implemented with an enum and a switch statement, which is fine for small projects.
• A more powerful, C-idiomatic implementation of the State Pattern uses a struct of function pointers to encapsulate all of a state's logic (init, update, draw, destroy).
• Using a stack to manage states naturally handles nested scenarios like pausing the game.

Preview of the Next Lesson:
We now have a StateManager, but we don't have any actual States to manage! Our next task will be to implement functions for transitioning between game states. We will create concrete implementations for a MainMenuState and a GameplayState and write the logic that allows us to switch between them, for example, by pushing the GameplayState when a "Play" button is "clicked" in the menu.