Skip to main content
The SceneManager provides a powerful system for organizing your application into discrete scenes or screens. It maintains a stack of scenes and handles automatic lifecycle management, navigation, and state preservation.

​
Scene Class

The base class for all scenes in your application. A Scene represents a distinct screen or state (e.g., Menu, Game, Settings).

​
Constructor

Scene(const std::string& name)
​
name
const std::string&
required
Unique identifier for this scene

​
Lifecycle Methods

​
onCreate()

virtual void onCreate()
Called once when the scene is first created. Use this method to initialize data, load resources, or perform one-time setup that doesn’t depend on UI widgets.
This is called before onEnter() and only once per scene instance.

​
onEnter()

virtual void onEnter()
Called every time the scene becomes active. Use this method to set up UI widgets, start animations, or perform setup that should happen each time the scene is shown.
This can be called multiple times if the scene is pushed/popped.

​
onExit()

virtual void onExit()
Called when the scene becomes inactive. Use this method to clean up UI widgets, pause animations, or save temporary state. The scene may become active again later.
Always clean up widgets here to prevent memory leaks.

​
onDestroy()

virtual void onDestroy()
Called when the scene is permanently removed. Use this method to free resources, save permanent state, or perform final cleanup. The scene will not be used again.
This is called after onExit() and only once per scene instance.

​
Update and Render Methods

​
update()

virtual void update(float deltaTime)
Called every frame while the scene is active. Use this method to update game logic, animations, or any time-dependent behavior.
​
deltaTime
float
required
Time elapsed since the last update in seconds

​
render()

virtual void render()
Called every frame to render the scene. Use this method to draw backgrounds, game objects, or custom graphics. Call Scene::render() at the end to render all managed widgets.
The default implementation renders all widgets using WidgetManager.

​
getName()

const std::string& getName() const
​
return
const std::string&
The scene’s unique identifier

​
SceneManager Class

Singleton class that manages scene navigation and lifecycle.

​
getInstance()

static SceneManager& getInstance()
​
return
SceneManager&
Reference to the singleton instance

​
Scene Registration

​
registerScene()

void registerScene(const std::string& name, std::function<std::unique_ptr<Scene>()> creator)
Register a factory function that creates instances of a scene.
​
name
const std::string&
required
Unique name for the scene
​
creator
std::function<std::unique_ptr<Scene>()>
required
Factory function that returns a new scene instance
SceneManager::getInstance().registerScene("Menu", []() -> std::unique_ptr<Scene> {
    return std::make_unique<MenuScene>();
});
Use the REGISTER_SCENE macro for easier registration.

​
pushScene()

void pushScene(const std::string& name)
Creates a new instance of the named scene and pushes it onto the stack. The current scene (if any) will call onExit() and pause, while the new scene will call onCreate() and onEnter().
​
name
const std::string&
required
Name of the scene to push (must be registered)
The current scene remains in memory and can be returned to with popScene().

​
popScene()

void popScene()
Removes the current scene from the stack, calling onExit() and onDestroy(). If there was a previous scene, it will call onEnter() and resume.
Does nothing if the stack is empty.

​
replaceScene()

void replaceScene(const std::string& name)
Removes the current scene (calling onExit() and onDestroy()) and pushes a new scene onto the stack. This is useful for main navigation where you don’t want to return to the previous scene.
​
name
const std::string&
required
Name of the scene to replace with (must be registered)

​
clearScenes()

void clearScenes()
Calls onExit() and onDestroy() on all scenes in the stack, leaving the application with no active scene.
Use carefully - the application will have no UI after this call.

​
Update and Render

​
update()

void update(float deltaTime)
Calls update() on the current scene (if any). This should be called every frame from your main loop.
​
deltaTime
float
required
Time elapsed since the last update in seconds

​
render()

void render()
Calls render() on the current scene (if any). This should be called every frame from your draw callback.

​
Query Methods

​
getCurrentScene()

Scene* getCurrentScene() const
​
return
Scene*
Pointer to the current scene, or nullptr if no scenes are active

​
hasScenes()

bool hasScenes() const
​
return
bool
True if there are scenes in the stack, false otherwise

​
Helper Macros and Functions

​
REGISTER_SCENE

REGISTER_SCENE(name, sceneClass)
Convenience macro for scene registration.
​
name
string
required
String name for the scene
​
sceneClass
class
required
Class name of the scene (must inherit from Scene)
REGISTER_SCENE("Menu", MenuScene);
REGISTER_SCENE("Game", GameScene);
REGISTER_SCENE("Settings", SettingsScene);

​
Global Functions

void pushScene(const std::string& name);
void popScene();
void replaceScene(const std::string& name);
Convenience functions that call the corresponding SceneManager methods.

​
Example Usage

class MenuScene : public Scene {
public:
    MenuScene() : Scene("MenuScene") {}
    
    void onEnter() override {
        setupUI();
    }
    
    void onExit() override {
        WidgetManager::getInstance().clearAll();
    }
    
    void render() override {
        Draw::fill(Colors::DarkBlue);
        Scene::render(); // Renders all widgets
    }
};

// Register scenes
REGISTER_SCENE("Menu", MenuScene);
REGISTER_SCENE("Game", GameScene);

// Navigate between scenes
SceneManager::getInstance().pushScene("Menu");
SceneManager::getInstance().pushScene("Game");  // Menu pauses
SceneManager::getInstance().popScene();         // Back to Menu

Build docs developers (and LLMs) love

Get started for freeTalk to us