ml::SceneManager< StateEnum > Class Template Reference

State-driven scene router for Malena applications. More...

#include <SceneManager.h>

Static Public Member Functions
template<typename App>
static void	attach (App &app)
	Wire SceneManager into the application's state machine.
static void	back ()
	Navigate to the previously visited state.
static void	bind (StateEnum state, Core &scene)
	Bind an existing scene instance to a state (eager).
template<typename SceneType, typename... Args>
static void	bindLazy (StateEnum state, Args &&... args)
	Bind a lazily-constructed scene type to a state.
static void	clear ()
	Clear all bindings and history.
static StateEnum	current ()
	Return the currently active state.
static bool	has (StateEnum state)
	Return true if a scene has been bound to state.
static bool	isActive (StateEnum state)
	Return true if state is currently the active scene.
static void	start (StateEnum state)
	Activate the initial scene without recording a history entry.

Detailed Description

template<typename StateEnum>
class ml::SceneManager< StateEnum >

State-driven scene router for Malena applications.

SceneManager<StateEnum> binds scenes (any Core-derived object or lazily-constructed type) to application state enum values. When the app calls setState(), SceneManager intercepts the transition via onStateEnter / onStateExit and performs the scene swap automatically — removing the outgoing scene from CoreManager and adding the incoming one.

Design contract

• setState() on the application is the only navigation primitive. SceneManager reacts to it; it does not replace it.
• back() is the one exception — it calls setState() with the previously visited state, keeping the state machine as the single source of truth.
• Scenes bound by reference (bind) are always in memory. Scenes bound lazily (bindLazy) are constructed on first visit and destroyed on back() or when another scene replaces them.

Typical setup

// AppManifest.h
struct AppManifest : public ml::Manifest
{
    enum class State { MainMenu, Game, Settings };
};
 
// MyApp.h
class MyApp : public ml::ApplicationWith<AppManifest>
{
    using Scenes = ml::SceneManager<AppManifest::State>;
 
    MainMenuScene _mainMenu;   // eager — always in memory
    SettingsScene _settings;   // eager
    // GameScene is lazy — only allocated when visited
 
public:
    MyApp() : ml::ApplicationWith<AppManifest>(1280, 720, 32, "My Game") {}
 
    void initialization() override
    {
        Scenes::bind    (State::MainMenu,  _mainMenu);
        Scenes::bind    (State::Settings,  _settings);
        Scenes::bindLazy<GameScene>(State::Game);
 
        Scenes::attach(*this);            // wire into the app's state machine
        Scenes::start (State::MainMenu);  // first scene, no history entry
    }
 
    void registerEvents() override
    {
        // Navigation is just setState — SceneManager handles the rest
        _mainMenu.playButton().onClick([this]{
            setState(State::Game);
        });
        _mainMenu.settingsButton().onClick([this]{
            setState(State::Settings);
        });
        _settings.backButton().onClick([]{
            Scenes::back();    // returns to MainMenu, calls setState internally
        });
    }
};

Lazy scenes

Lazy scenes are heap-allocated on first visit and freed when they are navigated away from. This is useful for heavy scenes (lots of textures, many components) that should not occupy memory while inactive.

Scenes::bindLazy<GameScene>(State::Game);          // no args
Scenes::bindLazy<GameScene>(State::Game, level);   // constructor args forwarded

History and back()

Every setState() call pushes the departing state onto a history stack. back() pops it and calls setState() with that value. The initial scene set via start() is NOT pushed — it acts as the history root.

Template Parameters

StateEnum

The enum class declared in your app manifest's State typedef. Must match the enum used by the app's own StateManager.

See also

ApplicationWith, StateManager, CoreManager, Core

Definition at line 108 of file SceneManager.h.

Member Function Documentation

attach()

template<typename StateEnum>

template<typename App>

void ml::SceneManager< StateEnum >::attach ( App & app )

inlinestatic

Wire SceneManager into the application's state machine.

Registers onStateEnter and onStateExit callbacks on app so that every future setState() call automatically triggers a scene swap. Also stores a reference to setState() so that back() can navigate without the caller holding an app reference.

Call this once in initialization(), before start().

Template Parameters

App	Any class that exposes: onStateEnter(std::function<void(StateEnum)>) onStateExit(std::function<void(StateEnum)>) setState(StateEnum) addComponent(Core&) removeComponent(Core&) [or via CoreManager]

Parameters

app	The application instance to attach to.

Definition at line 223 of file SceneManager.h.

back()

template<typename StateEnum>

void ml::SceneManager< StateEnum >::back ( )

inlinestatic

Navigate to the previously visited state.

Pops the history stack and calls setState() with the recovered state. Does nothing if history is empty (i.e., already at the root).

Note

This calls setState() on the application, which fires onStateExit and onStateEnter as normal. The scene swap happens automatically through those callbacks.

Definition at line 283 of file SceneManager.h.

bind()

template<typename StateEnum>

void ml::SceneManager< StateEnum >::bind ( StateEnum state, Core & scene )

inlinestatic

Bind an existing scene instance to a state (eager).

The scene is always in memory. SceneManager does not own it — lifetime management is the caller's responsibility (typically a member of Application).

Parameters

state	The application state that activates this scene.
scene	Reference to a Core-derived scene object.

Definition at line 158 of file SceneManager.h.

bindLazy()

template<typename StateEnum>

template<typename SceneType, typename... Args>

void ml::SceneManager< StateEnum >::bindLazy ( StateEnum state, Args &&... args )

inlinestatic

Bind a lazily-constructed scene type to a state.

The scene is heap-allocated on first visit and destroyed when navigated away from. Constructor arguments are forwarded at construction time.

Template Parameters

SceneType	A Core-derived type to construct on demand.
Args	Constructor argument types (deduced).

Parameters

state	The application state that activates this scene.
args	Arguments forwarded to SceneType's constructor.

Scenes::bindLazy<GameScene>(State::Game);
Scenes::bindLazy<LevelScene>(State::Level, levelIndex);

Definition at line 181 of file SceneManager.h.

clear()

template<typename StateEnum>

void ml::SceneManager< StateEnum >::clear ( )

inlinestatic

Clear all bindings and history.

Call before rebuilding the scene set (e.g., after Application::reset()). Does NOT deactivate the current scene — call deactivate(current()) first if needed.

Definition at line 325 of file SceneManager.h.

current()

template<typename StateEnum>

StateEnum ml::SceneManager< StateEnum >::current ( )

inlinestatic

Return the currently active state.

Returns

The state whose scene is currently shown.

Definition at line 304 of file SceneManager.h.

has()

template<typename StateEnum>

bool ml::SceneManager< StateEnum >::has ( StateEnum state )

inlinestatic

Return true if a scene has been bound to state.

Parameters

state

State to check.

Definition at line 316 of file SceneManager.h.

isActive()

template<typename StateEnum>

bool ml::SceneManager< StateEnum >::isActive ( StateEnum state )

inlinestatic

Return true if state is currently the active scene.

Parameters

state

State to check.

Definition at line 310 of file SceneManager.h.

start()

template<typename StateEnum>

void ml::SceneManager< StateEnum >::start ( StateEnum state )

inlinestatic

Activate the initial scene without recording a history entry.

Call after attach() and all bind() / bindLazy() calls. The initial scene is treated as the history root — back() cannot navigate past it.

Parameters

state

The state whose scene should be shown first.

Definition at line 264 of file SceneManager.h.

---

The documentation for this class was generated from the following file:

• Engine/Scenes/SceneManager.h