Struct SpatialGridConfig

Namespace

Typhon.Engine

Assembly

Typhon.Engine.dll

Immutable configuration for the engine-wide spatial grid. Set once via ConfigureSpatialGrid(SpatialGridConfig) before archetypes are initialized.

public readonly struct SpatialGridConfig

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Remarks

All spatial archetypes share a single coarse grid with one cell size (Decision Q1 in claude/design/Spatial/SpatialTiers/01-spatial-clusters.md). Per-archetype differences are expressed at the system level via tier filters, not at the grid level.

Grid dimensions are derived from (WorldMax - WorldMin) / CellSize and rounded up to the nearest power of two when Morton cell keys are enabled — this keeps the Morton decode well-defined without needing a per-axis width.

Constructors

SpatialGridConfig(Vector2, Vector2, float, float)

Build a grid configuration and precompute the derived cell dimensions. World bounds are half-open: worldMin is inclusive, worldMax is exclusive.

public SpatialGridConfig(Vector2 worldMin, Vector2 worldMax, float cellSize, float migrationHysteresisRatio = 0.05)

Parameters

worldMin Vector2

World-space minimum corner (inclusive).

worldMax Vector2

World-space maximum corner (exclusive); must be strictly greater than worldMin on both axes.

cellSize float

Cell size in world units; must be > 0.

migrationHysteresisRatio float

Per-axis dead zone as a fraction of cell size (default 0.05). Reserved for the Phase 3 migration path.

Exceptions

ArgumentOutOfRangeException

cellSize is not positive, or the derived per-axis key-space dimension exceeds the 32 768 limit of the 32-bit Morton encoding.

ArgumentException

worldMax is not strictly greater than worldMin on both axes.

Fields

CellCount

Total number of descriptor slots. Equals KeySpaceDim² for Morton keys.

public readonly int CellCount

Field Value

int

CellSize

Size of a single grid cell, in world units. Must be > 0.

public readonly float CellSize

Field Value

float

GridHeight

Number of real cells along the Y axis.

public readonly int GridHeight

Field Value

int

GridWidth

Number of real cells along the X axis — derived from (WorldMax.X - WorldMin.X) / CellSize, rounded up. This is the count of cells entities can actually occupy.

public readonly int GridWidth

Field Value

int

InverseCellSize

Precomputed 1 / CellSize.

public readonly float InverseCellSize

Field Value

float

KeySpaceDim

Cell key space size per axis. Equal to GridWidth/GridHeight for row-major, or padded to the next power of two (matching the larger of the two) for Morton. Used only for descriptor array sizing — not for world-to-cell clamping.

public readonly int KeySpaceDim

Field Value

int

MigrationHysteresisRatio

Fractional dead zone applied per axis during entity migration, as a fraction of cell size. Default 0.05 (5 % of cell size). Unused in Phase 1+2 — reserved for the Phase 3 migration path.

public readonly float MigrationHysteresisRatio

Field Value

float

WorldMax

World-space maximum corner (exclusive — the grid excludes the max edge).

public readonly Vector2 WorldMax

Field Value

Vector2

WorldMin

World-space minimum corner (inclusive).

public readonly Vector2 WorldMin

Field Value

Vector2