Struct SpatialGridAccessor

Namespace

Typhon.Engine

Assembly

Typhon.Engine.dll

Game-facing read/write accessor for the engine's Typhon.Engine.Internals.SpatialGrid (issue #232). Exposed on SpatialGrid so system callbacks can assign cell tiers, query cell coordinates, and use multi-observer helpers (SetCellTierMin(int, int, int, SimTier), ResetAllTiers(SimTier), SetTierInAABB(double, double, double, double, double, double, SimTier)).

public readonly struct SpatialGridAccessor

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Remarks

8-byte readonly struct (one managed reference). The design doc specifies ref struct but TickContext is a regular struct — ref structs cannot be fields of non-ref structs. Using readonly struct with a single reference field achieves the same zero-allocation, thin-wrapper semantics without the composability constraint.

All methods delegate to the internal Typhon.Engine.Internals.SpatialGrid. No logic duplication.

Properties

CellCount

Number of cells that actually exist — the grid is sparse, so this counts occupied cells rather than the whole world.

public int CellCount { get; }

Property Value

int

CellSize

Cell size in world units.

public double CellSize { get; }

Property Value

double

Remarks

f64 since #914, with the world frame it belongs to — an f64 world may configure a cell size no f32 can hold exactly.

GridDepth

Grid depth in cells. 1 for a flat world — see Flat(Vector2, Vector2, double, float, float, float, float, float, float, int, float, float, int, float, bool, bool, float, int, int, int, float).

public int GridDepth { get; }

Property Value

int

GridHeight

Grid height in cells.

public int GridHeight { get; }

Property Value

int

GridWidth

Grid width in cells.

public int GridWidth { get; }

Property Value

int

IsValid

True when the engine has a configured spatial grid. False when no grid was set up (non-spatial game) or during shutdown.

public bool IsValid { get; }

Property Value

bool

Methods

ComputeCellKey(int, int, int)

The cell key for the given cell coordinates, or -1 when no cell exists there. Cell keys are pool slots handed out when a cell is first occupied (#872 step 8), so an empty region has no key — game code reading grid state must handle -1.

public int ComputeCellKey(int cellX, int cellY, int cellZ)

Parameters

cellX int

cellY int

cellZ int

Returns

int

GetCellCoords(int)

Convert a cell key back to grid coordinates (x, y, z). Throws for a key that names no live cell — including the -1 that ComputeCellKey(int, int, int) and WorldToCell(double, double, double) return for an empty region, which is the easiest one to forward here by accident.

public (int x, int y, int z) GetCellCoords(int cellKey)

Parameters

cellKey int

Returns

(int UncompressedBytes, int CompressedBytes, int RecordCount)

ResetAllTiers(SimTier)

Bulk-set all cells to the specified tier. Typically called at the start of TierAssignment.

public void ResetAllTiers(SimTier tier)

Parameters

tier SimTier

SetCellTier(int, int, int, SimTier)

Set a cell's tier by grid coordinates. Requires a single-bit SimTier flag. A coordinate with no cell is a no-op, not an error: tier assignment sweeps whole regions, most of which are empty, and a tier on a clusterless cell is inert anyway — TierClusterIndex reads only the cells clusters are actually attached to. Creating one per swept coordinate would rebuild the dense grid a tier call at a time.

public void SetCellTier(int cellX, int cellY, int cellZ, SimTier tier)

Parameters

cellX int

cellY int

cellZ int

tier SimTier

SetCellTierMin(int, int, int, SimTier)

Set a cell's tier using min (promote-only) semantics (Q7). If the cell already has a higher-priority tier (lower flag value), the call is a no-op. Enables multi-observer union: ResetAllTiers(Tier3) then SetCellTierMin per observer.

public void SetCellTierMin(int cellX, int cellY, int cellZ, SimTier tier)

Parameters

cellX int

cellY int

cellZ int

tier SimTier

SetTierInAABB(double, double, double, double, double, double, SimTier)

Set tiers for all cells overlapping a world-space AABB, using min (promote-only) semantics.

public void SetTierInAABB(double minX, double minY, double minZ, double maxX, double maxY, double maxZ, SimTier tier)

Parameters

minX double

minY double

minZ double

maxX double

maxY double

maxZ double

tier SimTier

Remarks

f64 since #914, with the world frame it addresses. An f32 call site is unchanged — widening is exact — but an observer box in a world past ~1.7 × 10⁷ could not have been expressed at all before.

WorldToCell(double, double, double)

Convert a world-space point to a grid cell key, or -1 when no cell exists there. Points outside bounds are clamped.

public int WorldToCell(double worldX, double worldY, double worldZ)

Parameters

worldX double

worldY double

worldZ double

Returns

int

Remarks

f64 since #914 — see SetTierInAABB(double, double, double, double, double, double, SimTier).