Scenes

A scene is one level's worth of entities, saved to a file and loaded back.

The concept

Because an ECS world is just entities and plain-data components, a level can be serialized by writing out every entity's components and rebuilt by reading them back. That makes levels data rather than code, and lets tools such as the level editor author them. A scene manager decides which scene is active and how to switch between them.

What a scene contains

A scene stores what is needed to rebuild the world: entities and the plain data of their components, with references to other things (assets, parent entities) written as stable names instead of memory addresses. Runtime-only state, such as a loaded texture, is not saved but rebuilt on load from those names.

Identity across save and load

Entity ids are only meaningful inside one running program. When a scene is loaded, new entities get new ids, so anything that refers to another entity (a parent link, say) must be translated from the saved reference to the new one. Getting this remapping right is the hardest part of any serializer.

Switching scenes

Switching can mean destroying the old world and loading the new from disk, which is simple but slow, or keeping visited scenes in memory so returning is instant at the cost of RAM. Which is right depends on how big levels are and how often players move between them.

How ASGE does it

SceneSerializer

SceneSerializer writes every alive entity of a Registry to a TOML scene file (.asgescene) and populates a registry from one. Each component type has its own Serializer<T> specialization. Asset references are stored as virtual paths, which is why scenes survive being moved: see Filesystem & VFS.

SceneManager

SceneManager owns one Registry holding only the active scene's entities. LoadScene(virtualPath) makes a scene active, SaveScene(path) saves the active one, UnloadScene() clears it and RenameActiveScene() retags it for "Save As". Every other visited scene stays resident as an in-memory snapshot, so switching back is instant and does not re-read the file; EvictCachedScene() and ClearCache() drop snapshots. Entity handles change when a snapshot is restored, which TakeRestoredEntities() reports as an old-to-new map.

scenes.cpp

asge::game::scene::SceneManager scenes( vfs );

scenes.LoadScene( "scenes/level1.asgescene" );          // BoolResult
asge::ecs::Registry& registry = scenes.GetRegistry();   // the active scene's entities

Game owns a scene manager and exposes loading through the project API, so a typical game loads a project and scene instead of building one by hand.

Start

Theory

Reference

Examples