Gondwana.Scenes.Scene Class Reference

Represents a game scene containing multiple layers of tiles, sprites, and game objects. A scene organizes content into layers with independent coordinate systems, parallax scrolling, and z-ordering, providing a complete environment for rendering and gameplay. More...

Inheritance diagram for Gondwana.Scenes.Scene:

Public Member Functions
	Scene ()
	Initializes a new instance of the Scene class with an empty layer collection.
SceneLayer	AddLayer (int columnCount, int rowCount, int width=32, int height=32, int zOrder=0, float parallax=1f, CoordinateSystemTypes coordinateSystem=CoordinateSystemTypes.Orthogonal)
	Creates and adds a new SceneLayer to this scene with the specified properties.
void	RemoveAllLayers ()
	Removes all layers from this scene.
void	RemoveLayer (SceneLayer sceneLayer)
	Removes the specified layer from this scene.
SceneLayer?	GetSceneLayerByID (string id)
	Retrieves a layer from this scene by its unique identifier.
RectangleF	GetWorldBoundsPx ()
	Computes a world-space pixel bounding rectangle that encloses all layers in the Scene. Each layer reports its own bounds via GetLayerBoundsPx(), and this method unions them together.
IEnumerator	GetEnumerator ()
	Returns an enumerator that iterates through the scene's layers.
virtual void	Dispose ()
	Releases all resources used by the Scene and removes it from the global scene collection.

Static Public Member Functions
static ? Scene	GetSceneByID (string id)
	Retrieves a scene from the global scene collection by its unique identifier.
static List< string >	GetAllSceneIDs ()
	Gets a list of unique identifiers for all active scenes in the global scene collection.
static ReadOnlyCollection< Scene >	GetAllScenes ()
	Gets a read-only collection of all active scenes in the global scene collection.
static void	ClearAllScenes ()
	Disposes all active scenes in the global scene collection, releasing all resources.

Protected Member Functions
virtual void	OnSceneLayerAdded (SceneLayer sceneLayer)
	Raises the SceneLayerAdded event and performs internal setup when a layer is added to the scene.
virtual void	OnSceneLayerRemoved (SceneLayer sceneLayer)
	Raises the SceneLayerRemoved event and performs internal cleanup when a layer is removed from the scene.
virtual void	OnSceneDisposing ()
	Raises the SceneDisposing event when the scene is being disposed.

Properties
TypedValueBag	ValueBag = new() [get]
	Gets the extensible value bag for storing arbitrary scene-specific metadata.
string	ID = Guid.NewGuid().ToString() [get, set]
	Gets or sets the unique identifier for this scene.
int	Count [get]
	Gets the total number of layers in this scene, including hidden layers.
bool	FullRefreshNeeded [get, set]
	Gets or sets a value indicating whether the entire scene needs to be refreshed on the next render.
ReadOnlyCollection< SceneLayer >	SceneLayers [get]
	Gets a read-only collection of all layers in this scene, in their current order.
ReadOnlyCollection< SceneLayer >	VisibleSceneLayers [get]
	Gets a read-only collection of visible layers sorted by z-order for rendering.
int	CountOfVisibleLayers [get]
	Gets the number of currently visible layers in this scene.
CollisionWorld	CollisionWorld = new() [get]
	Gets the collision world associated with this scene, used for physics and collision detection.
SceneLayer?	this[int i] [get]
	Gets the SceneLayer at the specified index in the layer collection.
SceneLayer?	this[string id] [get]
	Gets the SceneLayer with the specified unique identifier.
static Scene	Empty = new EmptyScene() [get]
	Gets the singleton empty scene instance.

Events
Action< SceneLayer >?	SceneLayerAdded
	Occurs when a SceneLayer is added to this scene.
Action< SceneLayer >?	SceneLayerRemoved
	Occurs when a SceneLayer is removed from this scene.
Action< Scene >?	SceneDisposing
	Occurs when this scene is being disposed.

Detailed Description

Represents a game scene containing multiple layers of tiles, sprites, and game objects. A scene organizes content into layers with independent coordinate systems, parallax scrolling, and z-ordering, providing a complete environment for rendering and gameplay.

The Scene class is the primary container for organizing game content into manageable layers. Each scene can contain multiple SceneLayer instances, each with its own coordinate system, tile grid, and rendering properties.

Scenes maintain a collision world for physics interactions, support serialization for save/load functionality, and provide extensible metadata storage through a ValueBag.

All scenes are automatically tracked in a global collection accessible via static methods such as GetAllScenes and GetSceneByID.

Constructor & Destructor Documentation

Scene()

Gondwana.Scenes.Scene.Scene

(

)

Initializes a new instance of the Scene class with an empty layer collection.

The constructor creates a new scene with a unique ID, initializes the collision world, and registers the scene in the global scene collection. The scene is ready to have layers added via AddLayer or other methods.

Member Function Documentation

AddLayer()

SceneLayer Gondwana.Scenes.Scene.AddLayer	(	int	columnCount,
		int	rowCount,
		int	width = 32,
		int	height = 32,
		int	zOrder = 0,
		float	parallax = 1f,
		CoordinateSystemTypes	coordinateSystem = CoordinateSystemTypes::Orthogonal )

Creates and adds a new SceneLayer to this scene with the specified properties.

Parameters

columnCount	The number of columns (tiles wide) in the layer's grid.
rowCount	The number of rows (tiles high) in the layer's grid.
width	The width of each tile in pixels. Default is 32.
height	The height of each tile in pixels. Default is 32.
zOrder	The rendering order for this layer relative to other layers. Lower values render first (behind). Default is 0.
parallax	The parallax scrolling factor for this layer. Values less than 1.0 create a background effect, values greater than 1.0 create a foreground effect. Default is 1.0 (no parallax).
coordinateSystem	The coordinate system type to use for this layer. Default is CoordinateSystemTypes.Orthogonal.

Returns

The newly created and added SceneLayer.

This method creates a new layer with the specified grid dimensions and visual properties, adds it to the scene's layer collection, and triggers the SceneLayerAdded event. The scene is marked for full refresh to ensure the new layer is rendered.

The returned layer reference can be used to further configure the layer, such as setting tiles, adding sprites, or adjusting visual properties.

ClearAllScenes()

void Gondwana.Scenes.Scene.ClearAllScenes ( )

static

Disposes all active scenes in the global scene collection, releasing all resources.

This method iterates through all active scenes and calls Dispose on each one, effectively clearing the entire scene collection. This is typically used during engine shutdown or when resetting the application state.

After calling this method, all scene references become invalid and should not be used. New scenes can be created after clearing.

Dispose()

virtual void Gondwana.Scenes.Scene.Dispose ( )

virtual

Releases all resources used by the Scene and removes it from the global scene collection.

This method performs orderly cleanup of the scene, including:

• Raising the SceneDisposing event
• Removing all layers via RemoveAllLayers
• Removing the scene from the global scene collection
• Clearing all event subscriptions

After disposal, the scene should not be used. This method can be overridden in derived classes to add custom cleanup logic, but the base implementation should be called to ensure proper resource release.

This method suppresses finalization to prevent the finalizer from running, as cleanup has already been performed.

GetAllSceneIDs()

List< string > Gondwana.Scenes.Scene.GetAllSceneIDs ( )

static

Gets a list of unique identifiers for all active scenes in the global scene collection.

Returns

A List<T> of scene ID strings.

This method returns the IDs of all scenes that have been created and not yet disposed. It excludes null entries and provides a snapshot of active scene identifiers at the time of the call.

GetAllScenes()

ReadOnlyCollection< Scene > Gondwana.Scenes.Scene.GetAllScenes ( )

static

Gets a read-only collection of all active scenes in the global scene collection.

Returns

A ReadOnlyCollection<T> containing all active Scene instances.

This method provides access to all scenes that have been created and not yet disposed. The collection includes all scenes except the singleton Empty scene. Changes to the underlying collection (such as creating or disposing scenes) will be reflected in subsequent calls to this method.

GetEnumerator()

IEnumerator Gondwana.Scenes.Scene.GetEnumerator

(

)

Returns an enumerator that iterates through the scene's layers.

Returns

An IEnumerator for iterating through SceneLayer instances.

This method enables enumeration of scene layers using non-generic enumerator interfaces, supporting scenarios where type information is not available at compile time. For type-safe enumeration, the generic IEnumerable<T>.GetEnumerator is preferred.

GetSceneByID()

? Scene Gondwana.Scenes.Scene.GetSceneByID ( string id )

static

Retrieves a scene from the global scene collection by its unique identifier.

Parameters

id	The unique ID of the scene to retrieve.

Returns

The Scene with the matching ID, or null if no scene with that ID exists.

This method searches the global collection of all active scenes. Scenes are automatically added to this collection when created and removed when disposed.

GetSceneLayerByID()

SceneLayer? Gondwana.Scenes.Scene.GetSceneLayerByID

(

string

id

)

Retrieves a layer from this scene by its unique identifier.

Parameters

id	The unique ID of the layer to retrieve.

Returns

The SceneLayer with the matching ID, or null if no layer with that ID exists in this scene.

This method performs a linear search through the scene's layers to find a matching ID. For frequent lookups, consider caching layer references or using the indexer syntax scene["layerID"] which calls this method internally.

GetWorldBoundsPx()

RectangleF Gondwana.Scenes.Scene.GetWorldBoundsPx

(

)

Computes a world-space pixel bounding rectangle that encloses all layers in the Scene. Each layer reports its own bounds via GetLayerBoundsPx(), and this method unions them together.

OnSceneDisposing()

virtual void Gondwana.Scenes.Scene.OnSceneDisposing ( )

protectedvirtual

Raises the SceneDisposing event when the scene is being disposed.

This method is called at the beginning of the Dispose method to notify subscribers that the scene is being destroyed. Derived classes can override this method to add custom disposal logic, but should call the base implementation to ensure the event is raised.

OnSceneLayerAdded()

virtual void Gondwana.Scenes.Scene.OnSceneLayerAdded ( SceneLayer sceneLayer )

protectedvirtual

Raises the SceneLayerAdded event and performs internal setup when a layer is added to the scene.

Parameters

sceneLayer

The SceneLayer that was added.

This method is called internally when a layer is added to the scene. It performs the following:

• Assigns this scene as the layer's parent scene
• Subscribes to layer events for change tracking
• Invalidates the visible layer cache
• Raises the SceneLayerAdded event

Derived classes can override this method to add custom behavior when layers are added, but should call the base implementation to ensure proper setup.

OnSceneLayerRemoved()

virtual void Gondwana.Scenes.Scene.OnSceneLayerRemoved ( SceneLayer sceneLayer )

protectedvirtual

Raises the SceneLayerRemoved event and performs internal cleanup when a layer is removed from the scene.

Parameters

sceneLayer

The SceneLayer that was removed.

This method is called internally when a layer is removed from the scene. It performs the following:

• Clears the layer's parent scene reference
• Unsubscribes from all layer events
• Invalidates the visible layer cache
• Raises the SceneLayerRemoved event

Derived classes can override this method to add custom cleanup behavior when layers are removed, but should call the base implementation to ensure proper cleanup.

RemoveAllLayers()

void Gondwana.Scenes.Scene.RemoveAllLayers

(

)

Removes all layers from this scene.

This method removes every SceneLayer from the scene, raising the SceneLayerRemoved event for each layer. The scene is marked for full refresh and the layer collection is cleared.

Use this method when you need to completely reset the scene's content, such as when loading a new level or returning to a main menu.

RemoveLayer()

void Gondwana.Scenes.Scene.RemoveLayer

(

SceneLayer

sceneLayer

)

Removes the specified layer from this scene.

Parameters

sceneLayer

The SceneLayer to remove from the scene.

This method removes the specified layer from the scene's layer collection and raises the SceneLayerRemoved event. The scene is marked for full refresh to ensure the visual representation is updated.

If the specified layer is not in this scene, the method has no effect.

Property Documentation

CollisionWorld

CollisionWorld Gondwana.Scenes.Scene.CollisionWorld = new()

get

Gets the collision world associated with this scene, used for physics and collision detection.

A Gondwana.Collision.CollisionWorld instance managing collision data for this scene.

The collision world maintains collision geometry, spatial partitioning structures, and collision detection state for all collidable entities within the scene. It is automatically created when the scene is initialized and is used by the engine's collision resolution system.

Count

int Gondwana.Scenes.Scene.Count

get

Gets the total number of layers in this scene, including hidden layers.

The count of all SceneLayer instances in the scene.

This property returns the total number of layers regardless of their visibility state. To get only visible layers, use VisibleSceneLayers or CountOfVisibleLayers.

CountOfVisibleLayers

int Gondwana.Scenes.Scene.CountOfVisibleLayers

get

Gets the number of currently visible layers in this scene.

The count of layers with SceneLayer.Visible set to true.

This property provides a quick way to determine how many layers will be rendered without iterating through the full layer collection. It reflects the count of layers in VisibleSceneLayers.

Empty

Scene Gondwana.Scenes.Scene.Empty = new EmptyScene()

staticget

Gets the singleton empty scene instance.

A Scene instance that contains only the empty layer and cannot be modified.

The empty scene is a special singleton instance that serves as a null object pattern implementation. It contains only SceneLayer.Empty and does not allow adding or removing layers.

This scene is useful as a default value or placeholder when a valid scene is not available, avoiding null reference checks throughout the codebase. Attempting to add layers to this scene will throw an InvalidOperationException.

The empty scene is not included in the global scene collection and cannot be disposed.

FullRefreshNeeded

bool Gondwana.Scenes.Scene.FullRefreshNeeded

getset

Gets or sets a value indicating whether the entire scene needs to be refreshed on the next render.

true if all layers and content should be re-rendered from scratch; otherwise, false.

This flag is set to true when structural changes occur that affect the entire scene, such as adding/removing layers, changing layer properties (z-order, parallax, wrapping, etc.), or other global scene modifications.

When true, the rendering system will perform a full redraw rather than incremental updates, ensuring all visual changes are properly reflected. The flag should be reset after the full refresh is completed.

ID

string Gondwana.Scenes.Scene.ID = Guid.NewGuid().ToString()

getset

Gets or sets the unique identifier for this scene.

A string representing the scene's unique ID, typically a GUID.

The ID is automatically generated when a scene is created and is used to identify the scene in the global scene collection. It is also used during serialization and deserialization to maintain scene references across save/load operations.

SceneLayers

ReadOnlyCollection<SceneLayer> Gondwana.Scenes.Scene.SceneLayers

get

Gets a read-only collection of all layers in this scene, in their current order.

A ReadOnlyCollection<T> containing all SceneLayer instances, including hidden layers.

This collection includes all layers regardless of visibility and preserves the order in which they were added. For rendering purposes, use VisibleSceneLayers which returns only visible layers sorted by z-order.

this[int i]

SceneLayer? Gondwana.Scenes.Scene.this[int i]

get

Gets the SceneLayer at the specified index in the layer collection.

Parameters

i	The zero-based index of the layer to retrieve.

Returns

The SceneLayer at the specified index, or null if the index is out of range.

This indexer provides direct access to layers by their position in the collection. The order reflects the order in which layers were added, not their z-order for rendering. For rendering order, use VisibleSceneLayers which is sorted by z-order.

this[string id]

SceneLayer? Gondwana.Scenes.Scene.this[string id]

get

Gets the SceneLayer with the specified unique identifier.

Parameters

id	The unique ID of the layer to retrieve.

Returns

The SceneLayer with the matching ID, or null if no layer with that ID exists in this scene.

This indexer provides convenient access to layers by their ID and internally calls GetSceneLayerByID. For example: var layer = scene["myLayerId"];

ValueBag

TypedValueBag Gondwana.Scenes.Scene.ValueBag = new()

get

Gets the extensible value bag for storing arbitrary scene-specific metadata.

A TypedValueBag instance for storing custom key-value data.

The value bag allows games or engine extensions to attach arbitrary structured data to scenes (such as level metadata, objectives, ambient settings, or custom properties) without modifying the core Scene class. Values are accessed using strongly-typed ValueKey<T> instances and are included in scene serialization.

VisibleSceneLayers

ReadOnlyCollection<SceneLayer> Gondwana.Scenes.Scene.VisibleSceneLayers

get

Gets a read-only collection of visible layers sorted by z-order for rendering.

A ReadOnlyCollection<T> containing only visible SceneLayer instances, sorted by their SceneLayer.ZOrder property in ascending order.

This property returns a cached, sorted collection that is automatically updated when layer visibility or z-order changes. The cache improves performance by avoiding repeated sorting operations during rendering.

Layers are sorted in ascending z-order, meaning layers with lower z-order values are rendered first (appear behind) and layers with higher z-order values are rendered last (appear in front).

Event Documentation

SceneDisposing

Action<Scene>? Gondwana.Scenes.Scene.SceneDisposing

Occurs when this scene is being disposed.

This event is raised at the beginning of the Dispose method, before any layers are removed or resources are released. Subscribers can use this event to perform cleanup operations or save state before the scene is destroyed.

SceneLayerAdded

Action<SceneLayer>? Gondwana.Scenes.Scene.SceneLayerAdded

Occurs when a SceneLayer is added to this scene.

This event is raised after a layer has been added to the scene and all internal setup has completed, including event subscription and scene reference assignment. Subscribers can use this event to respond to scene composition changes.

SceneLayerRemoved

Action<SceneLayer>? Gondwana.Scenes.Scene.SceneLayerRemoved

Occurs when a SceneLayer is removed from this scene.

This event is raised after a layer has been removed from the scene and all internal cleanup has completed, including event unsubscription and scene reference clearing. Subscribers can use this event to respond to scene composition changes or perform cleanup.