Class SceneManager

Namespace

KeenEyes

Assembly

KeenEyes.Core.dll

Manages scene spawning, unloading, and entity scene membership.

public sealed class SceneManager

Inheritance

object

SceneManager

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This is an internal manager class that handles scene lifecycle operations. The public API is exposed through Scenes.

Scenes are entity hierarchies with a root entity marked by KeenEyes.Scenes.SceneRootTag. Entities can belong to multiple scenes through reference counting via KeenEyes.Scenes.SceneMembership.ReferenceCount.

This class is thread-safe: all operations can be called concurrently from multiple threads.

Properties

LoadedCount

Gets the number of currently loaded scenes.

public int LoadedCount { get; }

Property Value

int

Methods

AddToScene(Entity, Entity)

Adds an entity to a scene with an initial reference count of 1.

public void AddToScene(Entity entity, Entity scene)

Parameters

entity Entity

The entity to add to the scene.

scene Entity

The scene root to add the entity to.

Remarks

Use this to associate an entity with a scene for the first time. For entities that need to be in multiple scenes, use TransitionEntity(Entity, Entity) after the initial add.

Exceptions

InvalidOperationException

Thrown when either entity is not alive, when scene is not a valid scene root, or when the entity already has scene membership.

GetLoaded()

Gets all currently loaded scene root entities.

public IEnumerable<Entity> GetLoaded()

Returns

IEnumerable<Entity>

An enumerable of all loaded scene root entities.

Remarks

Returns a snapshot to allow safe iteration while scenes may be loaded/unloaded.

GetScene(string)

Gets a loaded scene by name.

public Entity GetScene(string name)

Parameters

name string

The name of the scene to find.

Returns

Entity

The scene root entity, or KeenEyes.Entity.Null if no scene with that name is currently loaded.

Remarks

If multiple instances of a scene with the same name are loaded, returns the most recently spawned instance.

IsLoaded(string)

Checks if a scene with the given name is currently loaded.

public bool IsLoaded(string name)

Parameters

name string

The name of the scene to check.

Returns

bool

true if the scene is loaded; otherwise, false.

MarkPersistent(Entity)

Marks an entity as persistent across scene unloads.

public void MarkPersistent(Entity entity)

Parameters

entity Entity

The entity to mark as persistent.

Remarks

Entities with KeenEyes.Scenes.PersistentTag are never despawned by Unload(Entity) operations, regardless of their KeenEyes.Scenes.SceneMembership.ReferenceCount.

Exceptions

InvalidOperationException

Thrown when the entity is not alive.

RemoveFromScene(Entity, Entity)

Removes an entity from a scene by decrementing its reference count.

public bool RemoveFromScene(Entity entity, Entity scene)

Parameters

entity Entity

The entity to remove from the scene.

scene Entity

The scene to remove the entity from.

Returns

bool

true if the entity was removed; false if the entity is not alive, has no scene membership, or is not in the specified scene.

Remarks

If the reference count reaches zero and the entity does not have KeenEyes.Scenes.PersistentTag, the entity and its descendants are despawned.

Spawn(string)

Spawns a new scene instance with the given name.

public Entity Spawn(string name)

Parameters

name string

The name of the scene to spawn.

Returns

Entity

The root entity of the spawned scene.

Remarks

Creates a new scene root entity with KeenEyes.Scenes.SceneRootTag and KeenEyes.Scenes.SceneMetadata. Multiple instances of the same scene name can be spawned; each gets a unique KeenEyes.Scenes.SceneMetadata.SceneId.

The most recently spawned instance with a given name is returned by GetScene(string).

Exceptions

ArgumentNullException

Thrown when name is null.

TransitionEntity(Entity, Entity)

Transitions an entity to another scene, incrementing its reference count.

public void TransitionEntity(Entity entity, Entity toScene)

Parameters

entity Entity

The entity to transition.

toScene Entity

The scene root to transition to.

Remarks

If the entity already has KeenEyes.Scenes.SceneMembership, its KeenEyes.Scenes.SceneMembership.ReferenceCount is incremented.

If the entity does not have KeenEyes.Scenes.SceneMembership, it is added with the target scene as origin and reference count of 1.

Use this when an entity needs to exist in multiple scenes simultaneously (e.g., an NPC following the player between areas).

Exceptions

InvalidOperationException

Thrown when either entity is not alive or when toScene is not a valid scene root.

Unload(Entity)

Unloads a scene and despawns its entities.

public bool Unload(Entity sceneRoot)

Parameters

sceneRoot Entity

The root entity of the scene to unload.

Returns

bool

true if the scene was unloaded; false if it was not a valid scene root.

Remarks

For each entity with KeenEyes.Scenes.SceneMembership referencing this scene:

• If the entity has KeenEyes.Scenes.PersistentTag, it is skipped (never despawned).
• Otherwise, KeenEyes.Scenes.SceneMembership.ReferenceCount is decremented.
• If the reference count reaches zero, the entity and its descendants are despawned.

The scene root entity itself is always despawned.