Building a Visual State Machine

Introduction to the Visual State Machine

In previous modules, you implemented horizontal movement, acceleration, gravity, ground detection (`grounded`), and a solid collision system along both axes. However, a character that glides statically across the screen or whose animations flicker uncontrollably lacks the tactile and aesthetic polish essential to a retro 2D platformer. To make gameplay feel responsive and lively, your character's visual presentation must accurately reflect underlying physics and mechanics on every single frame.

A common beginner pitfall is hardcoding sprite assignments directly into keyboard checks (such as `if (keyboard_check(vk_right)) sprite_index = spr_player_run;`). This approach quickly devolves into spaghetti code: sprites flicker, jump animations cancel prematurely, characters run in midair, or frames freeze whenever opposing keys are pressed at the same time. To resolve this cleanly and scalably in GameMaker, we will build a dedicated Visual Finite State Machine (visual FSM).

Concept: Finite State Machines (FSM) Applied to Animation

A Finite State Machine is a computational model stipulating that an entity can occupy exactly one state from a finite set at any given time. In our context, the character cannot be running and idling simultaneously, nor can it be in a rising fall state. Driven by input conditions—such as horizontal speed `hsp`, vertical speed `vsp`, and floor contact `grounded`—the machine transitions between states and updates relevant visual properties (`sprite_index`, `image_speed`, and `image_xscale`).

In modern GameMaker, the cleanest, most performant way to represent states is using enumerators (`enum`). An enum maps descriptive names to sequential integers under the hood. This eliminates slow, typo-prone string comparisons (like `state = "running"`) and allows the compiler to evaluate state checks instantly.

Standardizing Graphic Assets and Collisions

Before writing any visual logic, you must follow a golden rule of 2D platformer development: maintain spatial and dimensional consistency across all sprites assigned to a single object. When you change an instance's `sprite_index`, GameMaker automatically swaps the default collision mask and origin to match the new sprite unless configured otherwise. If your running sprite is 32 pixels tall with a bottom-centered origin, but your jump sprite is 40 pixels tall with a centered origin, the character will sink into the floor or float mid-jump, completely breaking collision consistency.

💡 Critical Rule: To prevent your character from getting stuck inside platforms or walls when swapping sprites, assign a dedicated collision sprite in the 'Collision Mask' property of 'obj_player' (for instance, a simple rectangle named 'spr_player_mask'), or ensure every animation sprite shares the exact same origin and bounding box dimensions down to the pixel.

Variable Setup in the Create Event

Inside the Create event of `obj_player`, you already have kinematic variables from earlier modules (`hsp`, `vsp`, `walk_spd`, `grav`, `jump_spd`, `grounded`). Now, define your state enumerator, the variable tracking the active state, and a variable tracking the previous frame's state. The previous-state variable allows you to detect the exact frame a transition occurs so you can reset `image_index` to zero, preventing animations from starting midway through their loops.

// ----------------------------------------------------------------------------
// OBJECT: obj_player
// EVENT: Create
// ----------------------------------------------------------------------------

// Movement and physics variables (established in modules 4 and 5)
hsp = 0;
vsp = 0;
walk_spd = 4;
grav = 0.4;
jump_spd = -8.5;
grounded = false;

// Player visual state definitions
enum PLAYER_STATE {
    IDLE,
    RUN,
    JUMP,
    FALL
}

// Current and previous state initialization
state = PLAYER_STATE.IDLE;
state_previous = PLAYER_STATE.IDLE;

// Horizontal sprite facing (1 = right, -1 = left)
facing = 1;

Notice that we declare `facing = 1`. While GameMaker provides the built-in variable `image_xscale` to flip instance rendering, storing your intended direction in an explicit helper variable (`facing`) before assigning it decouples raw player input from final rendering and prevents unintended scaling bugs.

Determining State in the Step Event

The Step event execution flow must follow a strict sequence of stages. Changing sprites while resolving collisions leads to inconsistent collision data. The recommended canonical pipeline is:

Here is the complete state evaluation and visual assignment block. Place it at the end of the Step event in `obj_player`, immediately after resolving horizontal and vertical collisions with floors and walls.

// ----------------------------------------------------------------------------
// OBJECT: obj_player
// EVENT: Step (Final section: Visual State Machine)
// ----------------------------------------------------------------------------

// --- STAGE 4: STATE EVALUATION BASED ON PHYSICS CONDITIONS ---
if (grounded) {
    // If the player is on a solid surface
    if (hsp == 0) {
        state = PLAYER_STATE.IDLE;
    } else {
        state = PLAYER_STATE.RUN;
    }
} else {
    // If the player is airborne (not grounded)
    if (vsp < 0) {
        state = PLAYER_STATE.JUMP;
    } else {
        state = PLAYER_STATE.FALL;
    }
}

// --- STAGE 5: VISUAL APPLICATION AND ANIMATION CONTROL ---
// If the state changed this frame, reset the animation index
if (state != state_previous) {
    image_index = 0;
}

// Sprite selection based on the evaluated state
switch (state) {
    case PLAYER_STATE.IDLE:
        sprite_index = spr_player_idle;
        image_speed = 1.0;
        break;
        
    case PLAYER_STATE.RUN:
        sprite_index = spr_player_run;
        // Optional tweak: sync animation speed with actual movement speed
        image_speed = 1.0;
        break;
        
    case PLAYER_STATE.JUMP:
        sprite_index = spr_player_jump;
        image_speed = 1.0;
        break;
        
    case PLAYER_STATE.FALL:
        sprite_index = spr_player_fall;
        image_speed = 1.0;
        break;
}

// --- HORIZONTAL ORIENTATION (FACING) ---
// Only update facing if the player is actively moving
if (hsp != 0) {
    facing = sign(hsp);
}

// Apply horizontal visual scale while preserving the base magnitude
image_xscale = facing;

// Update previous state record for the next frame
state_previous = state;