SceneManager.h

Go to the documentation of this file.

// Copyright (c) 2025 Dave R. Smith.
// Malena Framework — Licensed under PolyForm Noncommercial 1.0.0; commercial use requires a paid license. See LICENSE.
 
//
// SceneManager.h
//
 
#ifndef MALENA_SCENEMANAGER_H
#define MALENA_SCENEMANAGER_H
 
#pragma once
 
#include <Malena/Core/malena_export.h>
#include <Malena/Core/Core.h>
#include <Malena/Utilities/EnumClassHash.h>
#include <unordered_map>
#include <functional>
#include <vector>
#include <memory>
#include <type_traits>
 
namespace ml
{
    template<typename StateEnum>
    class SceneManager
    {
        // ── Internal scene entry ────────────────────────────────────────────

        struct SceneEntry
        {
            Core*                    scene;    
            std::function<Core*()>   factory;  
            std::unique_ptr<Core>    owned;    
 
            bool isLazy()   const { return static_cast<bool>(factory); }
            bool isActive() const { return scene != nullptr; }

            Core* get() const { return scene; }
        };
 
        // ── Per-instance storage ────────────────────────────────────────────
 
        std::unordered_map<StateEnum, SceneEntry, EnumClassHash> _bindings;
        std::vector<StateEnum>        _history;
        StateEnum                     _current{};
        bool                          _started  = false;
        bool                          _attached = false;

        std::function<void(Core&)>       _add;

        std::function<void(Core&)>       _remove;

        std::function<void(StateEnum)>   _setter;

        std::function<void(StateEnum)>   _sync;
 
    public:
 
        // ── Lifetime ──────────────────────────────────────────────────────────
 
        SceneManager() = default;
 
        // Non-copyable, non-movable: attach() captures `this` into the owner's
        // callbacks, so the instance must keep a stable address while attached.
        SceneManager(const SceneManager&)            = delete;
        SceneManager& operator=(const SceneManager&) = delete;
        SceneManager(SceneManager&&)                 = delete;
        SceneManager& operator=(SceneManager&&)      = delete;
 
        // ── Bind ────────────────────────────────────────────────────────────

        void bind(StateEnum state, Core& scene)
        {
            scene.setEnabled(false);
            _bindings[state] = SceneEntry{ &scene, nullptr, nullptr };
        }

        template<typename SceneType, typename... Args>
        void bindLazy(StateEnum state, Args&&... args)
        {
            static_assert(std::is_base_of_v<Core, SceneType>,
                "[SceneManager] bindLazy: SceneType must derive from ml::Core.");
 
            // Capture args by value so the factory is self-contained
            _bindings[state] = SceneEntry
            {
                nullptr,
                [capturedArgs = std::make_tuple(std::forward<Args>(args)...)]() mutable -> Core*
                {
                    return std::apply([](auto&&... a) -> Core*
                    {
                        return new SceneType(std::forward<decltype(a)>(a)...);
                    }, capturedArgs);
                },
                nullptr
            };
        }
 
        // ── Attach ──────────────────────────────────────────────────────────

        template<typename Owner>
        void attach(Owner& owner)
        {
            _attached = true;
 
            // Store navigation primitives
            _setter = [&owner](StateEnum s) { owner.setState(s); };
            _sync   = [&owner](StateEnum s) { owner.syncState(s); };
            _add    = [&owner](Core& s)     { owner.addComponent(s); };
            _remove = [&owner](Core& s)     { owner.removeComponent(s); };
 
            // Hook into the owner's state machine — SceneManager reacts to transitions
            owner.onStateExit([this](StateEnum leaving)
            {
                deactivate(leaving);
            });
 
            owner.onStateEnter([this](StateEnum entering)
            {
                activate(entering);
            });
        }
 
        // ── Start ───────────────────────────────────────────────────────────

        void start(StateEnum state)
        {
            _current = state;
            _started = true;
            if (_sync) _sync(state);  // sync owner state machine without triggering callbacks
            activate(state);          // show first scene — no history push
        }
 
        // ── Navigation ──────────────────────────────────────────────────────

        void back()
        {
            if (_history.empty()) return;
 
            StateEnum previous = _history.back();
            _history.pop_back();
 
            // Call setState without re-pushing to history
            // We set _current ahead of time so activate() knows not to push
            _current = previous;
 
            if (_setter)
                _setter(previous);
        }
 
        // ── Query ───────────────────────────────────────────────────────────

        StateEnum current() const { return _current; }

        bool isActive(StateEnum state) const { return _started && _current == state; }

        bool has(StateEnum state) const { return _bindings.count(state) > 0; }

        void clear()
        {
            _bindings.clear();
            _history.clear();
            _started  = false;
            _attached = false;
            _add    = nullptr;
            _remove = nullptr;
            _setter = nullptr;
            _sync   = nullptr;
        }
 
    private:
 
        // ── Internal transition helpers ─────────────────────────────────────

        void activate(StateEnum state)
        {
            auto it = _bindings.find(state);
            if (it == _bindings.end()) return;
 
            SceneEntry& entry = it->second;
 
            if (entry.isLazy())
            {
                // Construct on demand if not already alive
                if (!entry.owned)
                {
                    entry.owned.reset(entry.factory());
                    entry.scene = entry.owned.get();
                }
            }
 
            if (entry.scene && _add)
            {
                entry.scene->setEnabled(true);
                _add(*entry.scene);
            }
        }

        void deactivate(StateEnum state)
        {
            auto it = _bindings.find(state);
            if (it == _bindings.end()) return;
 
            SceneEntry& entry = it->second;
 
            if (entry.scene && _remove)
            {
                _remove(*entry.scene);
                entry.scene->setEnabled(false);
            }
 
            // Push to history so back() can return
            _history.push_back(state);
            _current = state; // will be overwritten by activate() shortly
 
            if (entry.isLazy())
            {
                // Free the lazy instance — next visit will reconstruct
                entry.scene = nullptr;
                entry.owned.reset();
            }
        }
    };
 
} // namespace ml
 
#endif // MALENA_SCENEMANAGER_H