ASGE
← API Reference Class

asge::game::scene::SceneManager

Owns one Registry holding only the active scene's entities, and switches which scene is "active" without reloading one it has already visited.

#include <SceneManager.hpp>

Every other visited scene stays resident as an in-memory snapshot (see m_Snapshots) rather than as live entities in the shared Registry, so exactly one scene's entities are ever enumerable at a time and a switch back to a snapshotted scene is a fast in-memory restore, not a disk read.

Private Types

#enum class PendingKindprivate
None
Load
Unload

Private Attributes

#SceneSerializer m_Serializer { m_Vfs }private
#ecs::Registry m_Registryprivate
#std::optional< str::String > m_CurrentScenePathprivate
#std::unordered_map< str::String, ecs::Registry > m_Snapshotsprivate
#std::unordered_map< str::String, std::unordered_map< ecs::Entity, ecs::Entity > > m_SuspendedHandlesprivate
#std::unordered_map< ecs::Entity, ecs::Entity > m_RestoredEntitiesprivate
#PendingKind m_PendingKind { PendingKind::None }private
#str::String m_PendingPathprivate

Private Member Functions

#void CopyEntityComponents(ecs::Registry const &inSrc, ecs::Entity inSrcEntity, ecs::Registry &inDst, ecs::Entity inDstEntity) const noexceptprivate
#Result< std::unordered_map< ecs::Entity, ecs::Entity > > CopyEntities(ecs::Registry const &inSrc, std::vector< ecs::Entity > const &inEntities, ecs::Registry &inDst) const noexceptprivate
#void SuspendScene(str::String const &inSceneId) noexceptprivate
#void RestoreScene(str::String const &inSceneId, ecs::Registry const &inSnapshot) noexceptprivate
#BoolResult LoadSceneCommon(str::String const &inSceneId, std::function< BoolResult(ecs::Registry &)> const &inLoad) noexceptprivate

Public Member Functions

#explicit SceneManager(filesystem::VirtualFileSystem const &inVfs) noexcept
#BoolResult LoadScene(str::String const &inVirtualPath, LoadContext *outCtx=nullptr) noexcept

Makes inVirtualPath the active scene — instantly if already resident, otherwise loaded from disk and tagged.

No-op if already active.

Parameters
outCtx

If non-null, is cleared, then filled (file index -> entity) when this call actually read the scene from disk; stays empty for a scene that was already active or restored from a snapshot.

Returns

Ok on success; a failed disk load disturbs nothing resident.

#BoolResult LoadSceneFromFile(filesystem::Path const &inPath, LoadContext *outCtx=nullptr) noexcept

LoadScene()'s counterpart for a scene file addressed by a real filesystem path rather than a VFS one — symmetric with SaveScene().

The SceneId its entities are tagged with defaults to inPath's string form.

Returns

Ok on success; a failed disk load disturbs nothing resident.

#void UnloadScene() noexcept

Destroys every entity belonging to the active scene, leaving nothing active.

#void RenameActiveScene(str::String const &inNewVirtualPath) noexcept

Makes inNewVirtualPath the active scene's identity going forward, retagging every currently-active entity's SceneId to match so ActiveEntities()/SaveScene() keep seeing them under the new path.

Touches neither disk nor the Registry's actual entity set.

Used for "Save As" (retags a populated active scene under a new path) and, paired with a prior UnloadScene(), for starting a scene from scratch nothing active left to retag, so this just establishes the identity newly-created entities get tagged under.

#BoolResult SaveScene(filesystem::Path const &inPath, SaveContext *outCtx=nullptr) const noexcept

Saves only the active scene's entities to inPath, not every resident scene.

Parameters
outCtx

If non-null, receives each live entity's index in the saved file.

#std::unordered_map< ecs::Entity, ecs::Entity > TakeRestoredEntities() noexcept

After a LoadScene() that restored a snapshot, each entity's handle before that scene was suspended -> its handle now (suspending and restoring copy entities, so handles change); empty otherwise.

Returns it and clears it.

#void EvictCachedScene(str::String const &inVirtualPath) noexcept

Drops inVirtualPath's snapshot so the next LoadScene() for it rereads from disk.

No-op if it isn't snapshotted, including if it's the active scene — use UnloadScene() for that.

#void ClearCache() noexcept

Drops every snapshotted scene, leaving the active one untouched — see EvictCachedScene().

#std::size_t CachedSceneCount() const noexcept

How many distinct scenes are snapshotted besides the active one.

#void RequestLoad(str::String const &inVirtualPath) noexcept

Queues a scene load for the next ApplyPendingTransition() call, overwriting any pending one.

#void RequestUnload() noexcept

Queues an unload for the next ApplyPendingTransition() call.

#bool HasPendingTransition() const noexcept

True if a RequestLoad()/RequestUnload() transition is still waiting to apply.

#BoolResult ApplyPendingTransition() noexcept

Applies the queued transition, if any — a no-op returning Ok when nothing is pending.

#std::vector< ecs::Entity > EntitiesInScene(str::String const &inVirtualPath) const noexcept

Every entity tagged with inVirtualPath's SceneId in the live Registry.

Empty for a merely snapshotted (resident-but-inactive) scene, since it has no live entities to tag — see ActiveEntities().

#std::vector< ecs::Entity > ActiveEntities() const noexcept

EntitiesInScene() for the active scene, or empty if none is active.

#Result< ecs::Entity > CreateEntity() noexcept

Creates a fresh entity already tagged with the active scene's SceneId, so it shows up in ActiveEntities() and SaveScene() without the caller having to tag it by hand.

Returns

The new entity, or an error if no scene is active.

#Result< ecs::Entity > DuplicateEntity(ecs::Entity inEntity) noexcept

Creates a new entity carrying a copy of every serializable component inEntity has, tagged into the active scene.

Returns

The new entity, or an error if no scene is active or inEntity isn't currently alive.

#ecs::Registry & GetRegistry() noexcept

The Registry backing only the active scene — other resident scenes are snapshotted, not here.

#ecs::Registry const & GetRegistry() const noexcept

Read-only access to the active scene's Registry — see GetRegistry().

#std::optional< str::String > const & CurrentScenePath() const noexcept

Virtual path the active scene was loaded from, or nullopt if none.