StateMachine

The StateMachine system tracks the top-level flow of the game: which scene is active, which menu is overlaid, where to return when the player dismisses a pause. The bundles use it for boot / main-menu / playing / paused / settings / credits / complete.

Open it from Inspector → Systems → StateMachine → Open.

Schema

Each state has:

• An id (snake_case, starts with a lowercase letter).
• A pushdown flag: when on, entering this state pushes the previous state onto a stack so popping resumes the underlying state with its scene intact.

The descriptor also stores an initial state (the state the game enters on boot, typically boot or main_menu).

Pushdown vs replace

Most states are replace: leaving menu and entering play means menu is gone, the menu scene tears down, play boots fresh. Default behavior.

Pushdown is the right shape for overlays. Pause menu, settings menu opened mid-game, an inventory overlay. Entering pause pushes “playing” onto a stack so dismissing pause snaps back to the exact scene state (camera position, enemy AI, music timestamp) without rebooting.

Without pushdown, you’d have to manually save and restore the gameplay scene every time the player opens a menu. Pushdown does it for free.

The bundles use it consistently:

• Platformer: pause, settings, controls, credits, game_over are all pushdown. boot, main_menu, playing, complete are replace.
• Narrative: settings and credits are pushdown overlays on top of main_menu or dialogue. boot, main_menu, dialogue, complete are replace.
• Top-down RPG: pause, settings, inventory pushdown on top of hub or forest. boot, main_menu, hub, forest, combat, complete are replace.

Common patterns

Pause from gameplay: gameplay scene listens for Esc, transitions to pause. Because pause is pushdown, the gameplay scene stays mounted under it. Pause exits via “Resume” (pop) or “Quit to Main Menu” (replace back to main_menu).

Settings from the menu and mid-game: settings is a single pushdown state. Both main_menu and pause push it. “Back” pops, returning the player to wherever they came from.

Game over: game-over is pushdown so the death screen sits on top of the level. Respawn pops; Quit replaces back to main_menu.

Editing the config by hand

The descriptor entry:

[systems.StateMachine.config]
initialState = "boot"
states = [
  { id = "boot",       pushdown = false },
  { id = "main_menu",  pushdown = false },
  { id = "playing",    pushdown = false },
  { id = "pause",      pushdown = true  },
  { id = "settings",   pushdown = true  },
  { id = "credits",    pushdown = true  },
  { id = "game_over",  pushdown = true  },
  { id = "complete",   pushdown = false },
]

Validation: state ids are unique, match ^[a-z][a-z0-9_]*$, and the initialState must be a registered state. Invalid configs block the save.