Represents a single layer within a Scene, containing a grid of tiles and supporting various coordinate systems, parallax scrolling, and rendering properties. Scene layers provide the fundamental structure for organizing and rendering tile-based game content. More...

Inheritance diagram for Gondwana.Scenes.SceneLayer:

Public Member Functions
void	SetTileSize (int newWidth, int newHeight)
	Sets both the width and height of tiles in this layer atomically, raising only a single SceneLayerTileSizeChanged event.
PointF	GridToWorldPx (PointF grid)
	Converts a grid coordinate (col,row) into the world-space pixel anchor where that tile begins. This returns the tile's top-left anchor in world pixels, not the tile center.
PointF	WorldPxToGrid (PointF worldPx)
	Converts a world-space pixel position into this layer's grid coordinates. This uses the layer's active coordinate system (square, iso, hex, etc.) and returns fractional grid values when the point lies between tiles.
SceneLayerTile?	GetAdjacentTile (SceneLayerTile tile, CardinalDirections direction)
	Returns the neighboring tile in the given direction, or null if the direction would move off the layer and wrapping is not enabled. The meaning of N,S,E,W depends on the active coordinate system.
PointF	WrapGrid (PointF grid)
	Wraps a grid coordinate around the layer's valid grid bounds using toroidal wrapping (0..max). Used by movement and map designs that loop at edges.
virtual RectangleF	GetLayerBoundsPx ()
	Computes the world-space pixel bounding rectangle for this SceneLayer. This uses the coordinate system to evaluate the pixel extents of the extreme grid tiles. Works for square, iso, hex, and any other supported projection.
IEnumerator	GetEnumerator ()
	Returns an enumerator that iterates through the layer's tiles.
virtual void	Dispose ()
	Releases all resources used by the SceneLayer and disposes all tiles.

Properties
TypedValueBag	ValueBag = new() `[get]`
	Gets the extensible value bag for storing arbitrary layer-specific metadata.
CoordinateSystemTypes	CoordinateSystemType `[get, set]`
	Gets or sets the coordinate system type used by this layer for transforming between grid coordinates and pixel positions.
string	ID = Guid.NewGuid().ToString() `[get, set]`
	Gets or sets the unique identifier for this layer.
Scene	Scene `[get, set]`
	Gets or sets the parent scene that contains this layer.
int	ZOrder `[get, set]`
	Gets or sets the z-order (rendering depth) of this layer within its parent scene.
float	Parallax `[get, set]`
	Gets or sets the parallax scrolling factor for this layer.
int	SceneLayerTileHeight `[get, set]`
	Gets or sets the height of each tile in this layer, measured in pixels.
int	SceneLayerTileWidth `[get, set]`
	Gets or sets the width of each tile in this layer, measured in pixels.
bool	Visible `[get, set]`
	Gets or sets a value indicating whether this layer should be rendered.
SceneLayerTile[,]	SceneLayerTileArray `[get]`
	Gets the two-dimensional array of tiles that comprise this layer's grid.
int	GridColumnCount `[get]`
	Gets the number of columns (tiles wide) in this layer's grid.
int	GridRowCount `[get]`
	Gets the number of rows (tiles high) in this layer's grid.
bool	WrapHorizontally `[get, set]`
	Gets or sets a value indicating whether this layer wraps horizontally at the grid boundaries.
bool	WrapVertically `[get, set]`
	Gets or sets a value indicating whether this layer wraps vertically at the grid boundaries.
bool	ShowGridLines `[get, set]`
	Gets or sets a value indicating whether grid lines should be rendered over this layer for debugging.
bool	ShowCollisionBoxes `[get, set]`
	Gets or sets a value indicating whether collision boxes should be rendered over this layer for debugging.
Point	OriginPx `[get, set]`
	Gets or sets the world-space pixel origin of this layer's (0,0) tile position.
SceneLayerTile?	this[int x, int y] `[get]`
	Gets the tile at the specified grid coordinates.
SceneLayerTile?	this[Point pt] `[get]`
	Gets the tile at the specified grid coordinates.
SceneLayerTile?	this[PointF ptF] `[get]`
	Gets the tile at the specified grid coordinates, truncating fractional values.
static SceneLayer	Empty = new EmptySceneLayer() `[get]`
	Gets the singleton empty scene layer instance.

Events
Action< SceneLayer >?	SceneLayerTileSizeChanged
	Occurs when the tile dimensions of this layer change.
Action< SceneLayer >?	VisibleChanged
	Occurs when the visibility state of this layer changes.
Action< SceneLayer >?	WrappingChanged
	Occurs when the wrapping configuration of this layer changes.
Action< SceneLayer >?	ShowGridLinesChanged
	Occurs when the grid line display setting changes.
Action< SceneLayer >?	ShowCollisionBoxesChanged
	Occurs when the collision box display setting changes.
Action< SceneLayer >?	ZOrderChanged
	Occurs when the z-order (rendering depth) of this layer changes.
Action< SceneLayer >?	ParallaxChanged
	Occurs when the parallax scrolling factor of this layer changes.
Action< SceneLayer >?	OriginPxChanged
	Occurs when the world-space origin point of this layer changes.
Action< SceneLayer >?	Disposing
	Occurs when this layer is being disposed.

Detailed Description

Represents a single layer within a Scene, containing a grid of tiles and supporting various coordinate systems, parallax scrolling, and rendering properties. Scene layers provide the fundamental structure for organizing and rendering tile-based game content.

A SceneLayer is a 2D grid of SceneLayerTile instances that can be rendered with different coordinate systems (orthogonal, isometric, hexagonal), z-ordering for depth sorting, and parallax effects for multi-plane scrolling backgrounds.

Layers support both tile-based content and sprite rendering, with automatic management of dirty regions for efficient incremental rendering. They can also contain direct drawing instances for custom graphics overlays.

Each layer maintains its own coordinate system transformation, allowing mixing of different projection types within the same scene. Layers can be configured to wrap horizontally or vertically for seamless tiling effects.

Member Function Documentation

◆ Dispose()

virtual void Gondwana.Scenes.SceneLayer.Dispose ( )

virtual

Releases all resources used by the SceneLayer and disposes all tiles.

This method performs orderly cleanup of the layer, including:

Raising the Disposing event
Disposing all SceneLayerTile instances in the grid
Clearing all event subscriptions

After disposal, the layer 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.

◆ GetAdjacentTile()

SceneLayerTile? Gondwana.Scenes.SceneLayer.GetAdjacentTile	(	SceneLayerTile	tile,
		CardinalDirections	direction )

Returns the neighboring tile in the given direction, or null if the direction would move off the layer and wrapping is not enabled. The meaning of N,S,E,W depends on the active coordinate system.

◆ GetEnumerator()

IEnumerator Gondwana.Scenes.SceneLayer.GetEnumerator ( )

Returns an enumerator that iterates through the layer's tiles.

Returns: An IEnumerator for iterating through SceneLayerTile instances.

This method enables enumeration of layer tiles using non-generic enumerator interfaces. Tiles are enumerated in column-major order (all rows in column 0, then all rows in column 1, etc.). For type-safe enumeration, the generic IEnumerable<T>.GetEnumerator is preferred.

◆ GetLayerBoundsPx()

virtual RectangleF Gondwana.Scenes.SceneLayer.GetLayerBoundsPx ( )

virtual

Computes the world-space pixel bounding rectangle for this SceneLayer. This uses the coordinate system to evaluate the pixel extents of the extreme grid tiles. Works for square, iso, hex, and any other supported projection.

◆ GridToWorldPx()

PointF Gondwana.Scenes.SceneLayer.GridToWorldPx ( PointF grid )

Converts a grid coordinate (col,row) into the world-space pixel anchor where that tile begins. This returns the tile's top-left anchor in world pixels, not the tile center.

◆ SetTileSize()

void Gondwana.Scenes.SceneLayer.SetTileSize	(	int	newWidth,
		int	newHeight )

Sets both the width and height of tiles in this layer atomically, raising only a single SceneLayerTileSizeChanged event.

Parameters

newWidth	The new tile width in pixels.
newHeight	The new tile height in pixels.

This method is preferred over setting SceneLayerTileWidth and SceneLayerTileHeight separately, as it avoids triggering two change events and two scene refreshes.

The method raises the SceneLayerTileSizeChanged event after updating both dimensions.

◆ WorldPxToGrid()

PointF Gondwana.Scenes.SceneLayer.WorldPxToGrid ( PointF worldPx )

Converts a world-space pixel position into this layer's grid coordinates. This uses the layer's active coordinate system (square, iso, hex, etc.) and returns fractional grid values when the point lies between tiles.

◆ WrapGrid()

PointF Gondwana.Scenes.SceneLayer.WrapGrid ( PointF grid )

Wraps a grid coordinate around the layer's valid grid bounds using toroidal wrapping (0..max). Used by movement and map designs that loop at edges.

Property Documentation

◆ CoordinateSystemType

CoordinateSystemTypes Gondwana.Scenes.SceneLayer.CoordinateSystemType

getset

Gets or sets the coordinate system type used by this layer for transforming between grid coordinates and pixel positions.

A CoordinateSystemTypes value specifying the projection type.

The coordinate system determines how grid positions are mapped to screen pixels and affects rendering, collision detection, and movement calculations. Common types include:

CoordinateSystemTypes.Orthogonal - Standard square grid
CoordinateSystemTypes.IsometricRhombic - Diamond-shaped isometric projection
CoordinateSystemTypes.IsometricAxial - Axial isometric projection
CoordinateSystemTypes.HexAxialFlatTop - Hexagonal grid with flat-top orientation
CoordinateSystemTypes.HexAxialPointedTop - Hexagonal grid with pointed-top orientation

Changing the coordinate system after layer creation is supported but may produce unexpected visual results if tile content was designed for a different projection.

◆ Empty

SceneLayer Gondwana.Scenes.SceneLayer.Empty = new EmptySceneLayer()

staticget

Gets the singleton empty scene layer instance.

A SceneLayer instance with zero dimensions that serves as a null object pattern.

The empty scene layer is a special singleton instance that contains no tiles (0x0 grid), is invisible, has minimum z-order, and serves as a placeholder when a valid layer is not available. It is used internally by Scene.Empty and helps avoid null reference checks.

This layer has the following characteristics:

Grid dimensions: 0 columns × 0 rows
Tile size: 1×1 pixels
Visible: false
ZOrder: int.MinValue
Parallax: 1.0

◆ GridColumnCount

int Gondwana.Scenes.SceneLayer.GridColumnCount

get

Gets the number of columns (tiles wide) in this layer's grid.

The width of the tile grid in tiles.

This value is determined at layer creation time and represents the horizontal extent of the tile array. Valid column indices range from 0 to GridColumnCount - 1.

◆ GridRowCount

int Gondwana.Scenes.SceneLayer.GridRowCount

get

Gets the number of rows (tiles high) in this layer's grid.

The height of the tile grid in tiles.

This value is determined at layer creation time and represents the vertical extent of the tile array. Valid row indices range from 0 to GridRowCount - 1.

◆ ID

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

getset

Gets or sets the unique identifier for this layer.

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

The ID is automatically generated when a layer is created and is used to identify the layer within its parent scene. It can also be used to look up layers via Scene.GetSceneLayerByID or the scene's string indexer.

◆ OriginPx

Point Gondwana.Scenes.SceneLayer.OriginPx

getset

Gets or sets the world-space pixel origin of this layer's (0,0) tile position.

A Point specifying the pixel offset in world space. Default is (0, 0).

The origin point allows shifting the entire layer as a block within world space, which is useful for creating offset parallax effects, layered UI elements, or special positioning requirements. Normally this is (0, 0), meaning the layer's grid coordinate (0, 0) maps to world pixel (0, 0).

Setting this property raises the OriginPxChanged event and triggers a full scene refresh.

◆ Parallax

float Gondwana.Scenes.SceneLayer.Parallax

getset

Gets or sets the parallax scrolling factor for this layer.

A floating-point value controlling the layer's scroll rate relative to the camera. Default is 1.0 (no parallax effect).

Parallax scrolling creates depth illusion by moving layers at different rates:

Values less than 1.0 (e.g., 0.5) create a background effect, moving slower than the camera
Value of 1.0 moves with the camera (standard layer movement)
Values greater than 1.0 (e.g., 1.5) create a foreground effect, moving faster than the camera

Setting this property raises the ParallaxChanged event and triggers a full scene refresh.

◆ Scene

Scene Gondwana.Scenes.SceneLayer.Scene

getset

Gets or sets the parent scene that contains this layer.

The Gondwana.Scenes.Scene that owns this layer, or null if the layer is not attached to a scene.

This property is set automatically when the layer is added to a scene via Scene.AddLayer and cleared when the layer is removed. The scene reference provides access to scene-level resources such as the collision world.

◆ SceneLayerTileArray

SceneLayerTile [,] Gondwana.Scenes.SceneLayer.SceneLayerTileArray

get

Gets the two-dimensional array of tiles that comprise this layer's grid.

A 2D array of SceneLayerTile instances indexed by [column, row].

This property provides direct access to the underlying tile array. The array is indexed by [x, y] or [column, row], where [0, 0] represents the top-left tile.

For safer access with bounds checking and wrapping support, prefer using the layer's indexer properties (layer[x, y], layer[point], or layer[pointf]).

◆ SceneLayerTileHeight

int Gondwana.Scenes.SceneLayer.SceneLayerTileHeight

getset

Gets or sets the height of each tile in this layer, measured in pixels.

The tile height in pixels. Default is typically 32.

This property defines the rendered height of tiles in this layer. Changes to tile height affect how tiles are positioned and rendered within the layer's coordinate system.

Setting this property raises the SceneLayerTileSizeChanged event and triggers a full scene refresh. Consider using SetTileSize to update both width and height atomically with a single event.

◆ SceneLayerTileWidth

int Gondwana.Scenes.SceneLayer.SceneLayerTileWidth

getset

Gets or sets the width of each tile in this layer, measured in pixels.

The tile width in pixels. Default is typically 32.

This property defines the rendered width of tiles in this layer. Changes to tile width affect how tiles are positioned and rendered within the layer's coordinate system.

Setting this property raises the SceneLayerTileSizeChanged event and triggers a full scene refresh. Consider using SetTileSize to update both width and height atomically with a single event.

◆ ShowCollisionBoxes

bool Gondwana.Scenes.SceneLayer.ShowCollisionBoxes

getset

Gets or sets a value indicating whether collision boxes should be rendered over this layer for debugging.

true if collision boxes should be displayed; otherwise, false.

Collision boxes provide a visual overlay showing the collision geometry of tiles and sprites, which is useful during development for debugging physics interactions, verifying collision boundaries, and tuning collision detection.

Setting this property raises the ShowCollisionBoxesChanged event and triggers a full scene refresh.

◆ ShowGridLines

bool Gondwana.Scenes.SceneLayer.ShowGridLines

getset

Gets or sets a value indicating whether grid lines should be rendered over this layer for debugging.

true if grid lines should be displayed; otherwise, false.

Grid lines provide a visual overlay showing tile boundaries, which is useful during development for aligning content, debugging tile positions, and verifying coordinate system behavior.

Setting this property raises the ShowGridLinesChanged event and triggers a full scene refresh.

◆ this[int x, int y]

SceneLayerTile? Gondwana.Scenes.SceneLayer.this[int x, int y]

get

Gets the tile at the specified grid coordinates.

Parameters

x	The zero-based column index (X coordinate).
y	The zero-based row index (Y coordinate).

Returns: The SceneLayerTile at the specified position, or null if the coordinates are out of bounds.

This indexer provides bounds-checked access to tiles in the layer's grid. Coordinates outside the valid range (0 to GridColumnCount-1, 0 to GridRowCount-1) return null. Wrapping is not applied; use WrapGrid first if wrapping behavior is desired.

◆ this[Point pt]

SceneLayerTile? Gondwana.Scenes.SceneLayer.this[Point pt]

get

Gets the tile at the specified grid coordinates.

Parameters

pt	A Point specifying the grid coordinates (X = column, Y = row).

Returns: The SceneLayerTile at the specified position, or null if the coordinates are out of bounds.

This indexer provides convenient point-based access to tiles and internally uses the [x, y] indexer. Coordinates outside the valid range return null.

◆ this[PointF ptF]

SceneLayerTile? Gondwana.Scenes.SceneLayer.this[PointF ptF]

get

Gets the tile at the specified grid coordinates, truncating fractional values.

Parameters

ptF	A PointF specifying the grid coordinates (X = column, Y = row). Fractional values are truncated to integers.

Returns: The SceneLayerTile at the truncated position, or null if the coordinates are out of bounds.

This indexer provides convenient access when working with floating-point grid coordinates, such as results from WorldPxToGrid. The coordinates are cast to integers, truncating toward zero. Coordinates outside the valid range return null.

◆ ValueBag

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

get

Gets the extensible value bag for storing arbitrary layer-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 layers (such as layer-specific properties, AI navigation data, weather effects, or custom attributes) without modifying the core SceneLayer class. Values are accessed using strongly-typed ValueKey<T> instances and are included in layer serialization.

◆ Visible

bool Gondwana.Scenes.SceneLayer.Visible

getset

Gets or sets a value indicating whether this layer should be rendered.

true if the layer is visible and should be rendered; otherwise, false.

Invisible layers are excluded from rendering but remain part of the scene structure. This is useful for temporarily hiding layers (such as background layers in cutscenes) without removing them from the scene.

Setting this property raises the VisibleChanged event, invalidates the parent scene's visible layer cache, and triggers a full scene refresh.

◆ WrapHorizontally

bool Gondwana.Scenes.SceneLayer.WrapHorizontally

getset

Gets or sets a value indicating whether this layer wraps horizontally at the grid boundaries.

true if horizontal wrapping is enabled; otherwise, false.

When enabled, horizontal coordinates that exceed the grid boundaries wrap around to the opposite side, creating a seamless toroidal topology. This is useful for scrolling backgrounds, wrap-around game worlds, and continuous map designs.

Setting this property raises the WrappingChanged event and triggers a full scene refresh.

◆ WrapVertically

bool Gondwana.Scenes.SceneLayer.WrapVertically

getset

Gets or sets a value indicating whether this layer wraps vertically at the grid boundaries.

true if vertical wrapping is enabled; otherwise, false.

When enabled, vertical coordinates that exceed the grid boundaries wrap around to the opposite side, creating a seamless toroidal topology. This is useful for scrolling backgrounds, wrap-around game worlds, and continuous map designs.

Setting this property raises the WrappingChanged event and triggers a full scene refresh.

◆ ZOrder

int Gondwana.Scenes.SceneLayer.ZOrder

getset

Gets or sets the z-order (rendering depth) of this layer within its parent scene.

An integer representing the layer's rendering priority. Lower values render first (behind), higher values render last (in front).

Z-order determines the rendering order of layers when multiple layers are present in a scene. Layers with lower z-order values are rendered first and appear behind layers with higher values.

Setting this property raises the ZOrderChanged event and typically triggers a full scene refresh to ensure correct layer ordering.

Event Documentation

◆ Disposing

Action<SceneLayer>? Gondwana.Scenes.SceneLayer.Disposing

Occurs when this layer is being disposed.

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

◆ OriginPxChanged

Action<SceneLayer>? Gondwana.Scenes.SceneLayer.OriginPxChanged

Occurs when the world-space origin point of this layer changes.

This event is raised when the OriginPx property is modified. Origin changes shift the entire layer as a block within world space and require a full scene refresh to ensure all tiles and sprites are positioned correctly.

◆ ParallaxChanged

Action<SceneLayer>? Gondwana.Scenes.SceneLayer.ParallaxChanged

Occurs when the parallax scrolling factor of this layer changes.

This event is raised when the Parallax property is modified. Parallax changes affect how the layer scrolls relative to the camera and require a full scene refresh to ensure correct positioning of all layer content.

◆ SceneLayerTileSizeChanged

Action<SceneLayer>? Gondwana.Scenes.SceneLayer.SceneLayerTileSizeChanged

Occurs when the tile dimensions of this layer change.

This event is raised when either SceneLayerTileWidth or SceneLayerTileHeight is modified, or when SetTileSize is called. Changes to tile size typically require a full scene refresh to ensure correct rendering of all tiles and sprites.

◆ ShowCollisionBoxesChanged

Action<SceneLayer>? Gondwana.Scenes.SceneLayer.ShowCollisionBoxesChanged

Occurs when the collision box display setting changes.

This event is raised when the ShowCollisionBoxes property is modified. Collision box visibility changes require a full scene refresh to add or remove collision box overlays from the rendering output, useful for debugging collision detection.

◆ ShowGridLinesChanged

Action<SceneLayer>? Gondwana.Scenes.SceneLayer.ShowGridLinesChanged

Occurs when the grid line display setting changes.

This event is raised when the ShowGridLines property is modified. Grid line visibility changes require a full scene refresh to add or remove grid line overlays from the rendering output.

◆ VisibleChanged

Action<SceneLayer>? Gondwana.Scenes.SceneLayer.VisibleChanged

Occurs when the visibility state of this layer changes.

This event is raised when the Visible property is modified. Visibility changes affect which layers are included in rendering and may trigger cache invalidation for visible layer collections in the parent scene.

◆ WrappingChanged

Action<SceneLayer>? Gondwana.Scenes.SceneLayer.WrappingChanged

Occurs when the wrapping configuration of this layer changes.

This event is raised when either WrapHorizontally or WrapVertically is modified. Wrapping changes affect how the layer handles tile coordinates at boundaries and typically require a full scene refresh.

◆ ZOrderChanged

Action<SceneLayer>? Gondwana.Scenes.SceneLayer.ZOrderChanged

Occurs when the z-order (rendering depth) of this layer changes.

This event is raised when the ZOrder property is modified. Z-order changes affect the rendering order of layers within the parent scene and typically require re-sorting the visible layer collection and a full scene refresh.

Public Member Functions

Properties

Events

Detailed Description

Member Function Documentation

◆ Dispose()

◆ GetAdjacentTile()

◆ GetEnumerator()

◆ GetLayerBoundsPx()

◆ GridToWorldPx()

◆ SetTileSize()

◆ WorldPxToGrid()

◆ WrapGrid()

Property Documentation

◆ CoordinateSystemType

◆ Empty

◆ GridColumnCount

◆ GridRowCount

◆ ID

◆ OriginPx

◆ Parallax

◆ Scene

◆ SceneLayerTileArray

◆ SceneLayerTileHeight

◆ SceneLayerTileWidth

◆ ShowCollisionBoxes

◆ ShowGridLines

◆ this[int x, int y]

◆ this[Point pt]

◆ this[PointF ptF]

◆ ValueBag

◆ Visible

◆ WrapHorizontally

◆ WrapVertically

◆ ZOrder

Event Documentation

◆ Disposing

◆ OriginPxChanged

◆ ParallaxChanged

◆ SceneLayerTileSizeChanged

◆ ShowCollisionBoxesChanged

◆ ShowGridLinesChanged

◆ VisibleChanged

◆ WrappingChanged

◆ ZOrderChanged