state Folder

Folders Index

folder	commands
folder	components
folder	listeners
folder	types

Files Index

file	helios/engine/state/_module.ixx
	Aggregate module for state-to-ID mapping utilities. More...
file	Bindings.ixx
	Compile-time bindings mapping state types to their transition ID types. More...
file	CombinedStateToIdMapPair.ixx
	Combined policy mapping two state types to IDs using 2D indexing. More...
file	StateCommandHandler.ixx
	Base class for state command handlers. More...
file	StateManager.ixx
	Generic state manager and transition orchestrator. More...
file	StateToIdMap.ixx
	Policy mapping states to IDs. More...
file	StateToIdMapPair.ixx
	Combined policy mapping two state types to IDs. More...
file	StateTransitionListener.ixx
	Interface for state transition observers. More...
file	TypedStateCommandHandler.ixx
	Typed interface for state command handling. More...

Description

helios::engine::state

Generic, template-based state management system with rule-based transitions.

Overview

This module provides a complete state management framework including:

• State machines with rule-based transitions and guards
• Commands for requesting immediate or timer-deferred state changes via the command buffer
• Listeners for reacting to state transitions
• ID mapping utilities for associating states with viewports/menus

All components are parameterized by state type, enabling reuse for different state enums (e.g., GameState, MatchState).

Core Components

State Management

Class	Description
StateManager<StateType>	Rule-based state machine with listener support
StateTransitionRule<StateType>	Defines valid transitions with optional guards
StateTransitionListener<StateType>	Interface for transition observers
LambdaStateListener<StateType>	Lambda-based listener implementation
StateCommand<StateType>	Command for requesting immediate transitions
DelayedStateCommand<StateType>	Timer-deferred transition command
StateTransitionRequest<StateType>	Encapsulates source state and transition ID
StateTransitionContext<StateType>	Full context (from, to, transitionId) passed to listeners
StateComponent<StateType>	Stores current state on entities
StateTypeId	Runtime type identifier for state types
Bindings	Compile-time specializations mapping state types to transition ID types

ID Mapping

Class	Description
StateToIdMap<TState, TId>	Maps a single state type to ID lists
StateToIdMapPair<LState, RState, TId>	Combines two state maps, returns union
CombinedStateToIdMapPair<LState, RState, TId>	Maps state pairs directly

Type Trait Specialization

To use StateManager<YourState>, you must specialize StateTransitionId:

 // In your bindings module:

 template<>

 struct helios::engine::state::types::StateTransitionId<GameState> {

  using Type = GameStateTransitionId;

 };

Usage

Defining Rules

 using namespace helios::engine::state;

 using namespace helios::engine::state::types;

 

 constexpr StateTransitionRule<GameState> gameStateRules[] = {

  {GameState::MainMenu, GameStateTransitionId::StartGame, GameState::Running},

  {GameState::Running, GameStateTransitionId::Pause, GameState::Paused},

  {GameState::Paused, GameStateTransitionId::Resume, GameState::Running},

  {GameState::Running, GameStateTransitionId::GameOver, GameState::MainMenu,

  // Optional guard:

  [](auto& ctx, auto& req) { return ctx.session().lives() == 0; }

  }

 };

Creating the Manager

 // Register manager with rules via GameWorld

 auto& gameStateManager = gameWorld.registerManager<StateManager<GameState>>(gameStateRules);

 

 gameStateManager.addStateListener(

  std::make_unique<LambdaStateListener<GameState>>(

  [](auto& ctx, GameState from) { /* onExit */ },

  [](auto& ctx, auto transitionCtx) { /* onTransition */ },

  [](auto& ctx, GameState to) { /* onEnter */ }

  )

 );

Requesting Transitions

 updateContext.queueCommand<StateCommand<GameState>>(

  StateTransitionRequest<GameState>{

  GameState::Running,

  GameStateTransitionId::Pause

  }

 );

Transition Flow

1. StateCommand (or DelayedStateCommand) is submitted to the command buffer 2. The command is routed to StateManager via the registered handler in CommandHandlerRegistry 3. StateManager::flush() processes the last pending command (earlier commands are discarded) 4. The command's from state is validated against the current session state 5. Matching rule is found and guard is evaluated 6. Listeners and session state are updated in order:

• onStateExit(from)
• onStateTransition(context)
• Session state updated via StateComponent<T>
• onStateEnter(to) (session already reflects the new state)

Delayed Transitions

DelayedStateCommand<StateType> pairs a StateTransitionRequest with a GameTimerId. On submission, the manager extracts the request and processes it as a regular StateCommand:

 updateContext.queueCommand<DelayedStateCommand<MatchState>>(

  StateTransitionRequest<MatchState>{

  MatchState::Countdown,

  MatchStateTransitionId::PlayerSpawnRequest

  },

  GameTimerId::CountdownTimer

 );

Reset Behavior

StateManager::reset() is intentionally a no-op — clearing the pending queue would discard transitions required by the reset itself.

ID Mapping

For viewport/menu activation based on state:

 CombinedStateToIdMapPair<GameState, MatchState, ViewportId> viewportPolicy;

 

 viewportPolicy.add(GameState::Running, MatchState::Playing, ViewportId("game"));

 viewportPolicy.add(GameState::Paused, MatchState::Undefined, ViewportId("pause"));

 

 viewportPolicy.freeze();

---

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.