helios/engine/state/README.md File
Namespaces Index
| namespace | state |
|
Generic, template-based state management system. More... | |
File Listing
The file content with the documentation metadata removed is:
# 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`:
```cpp
// In your bindings module:
template<>
struct helios::engine::state::types::StateTransitionId<GameState> {
using Type = GameStateTransitionId;
};
```
## Usage
### Defining Rules
```cpp
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
```cpp
// 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
```cpp
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`:
```cpp
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:
```cpp
CombinedStateToIdMapPair<GameState, MatchState, ViewportId> viewportPolicy;
viewportPolicy.add(GameState::Running, MatchState::Playing, ViewportId("game"));
viewportPolicy.add(GameState::Paused, MatchState::Undefined, ViewportId("pause"));
viewportPolicy.freeze();
```
---
<details>
<summary>Doxygen</summary><p>
@namespace helios::engine::state
@brief Generic, template-based state management system.
@details Provides a complete framework for managing application state with rule-based transitions, guards, listeners, and ID mapping utilities. All components are parameterized by state type for maximum reuse.
</p></details>
Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.