Class VoxelGrid

Namespace

GridForge.Grids

Assembly

GridForge.dll

Represents a 3D grid structure for spatial organization, managing voxels and scan cells. Handles initialization, neighbor relationships, and occupancy tracking.

public class VoxelGrid

Inheritance

object

VoxelGrid

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods

GridObstacleManager.ClearObstacles(VoxelGrid, Voxel)

GridObstacleManager.TryAddObstacle(VoxelGrid, Vector2d, Fixed64, ObstacleToken)

GridObstacleManager.TryAddObstacle(VoxelGrid, Vector2d, ObstacleToken)

GridObstacleManager.TryAddObstacle(VoxelGrid, Vector3d, ObstacleToken)

GridObstacleManager.TryAddObstacle(VoxelGrid, Voxel, ObstacleToken)

GridObstacleManager.TryRemoveObstacle(VoxelGrid, Vector2d, Fixed64, ObstacleToken)

GridObstacleManager.TryRemoveObstacle(VoxelGrid, Vector2d, ObstacleToken)

GridObstacleManager.TryRemoveObstacle(VoxelGrid, Vector3d, ObstacleToken)

GridObstacleManager.TryRemoveObstacle(VoxelGrid, Voxel, ObstacleToken)

GridOccupantManager.TryAddVoxelOccupant(VoxelGrid, Voxel, IVoxelOccupant)

GridOccupantManager.TryAddVoxelOccupant(VoxelGrid, IVoxelOccupant)

GridOccupantManager.TryAddVoxelOccupant(VoxelGrid, VoxelIndex, IVoxelOccupant)

GridOccupantManager.TryRemoveVoxelOccupant(VoxelGrid, Voxel, IVoxelOccupant)

GridOccupantManager.TryRemoveVoxelOccupant(VoxelGrid, IVoxelOccupant)

GridOccupantManager.TryRemoveVoxelOccupant(VoxelGrid, VoxelIndex, IVoxelOccupant)

GridScanManager.GetConditionalOccupants(VoxelGrid, Vector3d, Func<IVoxelOccupant, bool>?, Func<byte, bool>?)

GridScanManager.GetConditionalOccupants(VoxelGrid, Voxel, Func<IVoxelOccupant, bool>?, Func<byte, bool>?)

GridScanManager.GetConditionalOccupants(VoxelGrid, VoxelIndex, Func<IVoxelOccupant, bool>?, Func<byte, bool>?)

GridScanManager.GetOccupants(VoxelGrid, Vector3d)

GridScanManager.GetOccupants(VoxelGrid, Voxel)

GridScanManager.GetOccupants(VoxelGrid, VoxelIndex)

GridScanManager.GetVoxelOccupantsByType<T>(VoxelGrid, Vector3d)

GridScanManager.GetVoxelOccupantsByType<T>(VoxelGrid, Voxel)

GridScanManager.GetVoxelOccupantsByType<T>(VoxelGrid, VoxelIndex)

GridScanManager.TryGetVoxelOccupant(VoxelGrid, Vector3d, OccupantTicket, out IVoxelOccupant?)

GridScanManager.TryGetVoxelOccupant(VoxelGrid, Voxel, OccupantTicket, out IVoxelOccupant?)

GridScanManager.TryGetVoxelOccupant(VoxelGrid, VoxelIndex, OccupantTicket, out IVoxelOccupant?)

Constructors

VoxelGrid()

public VoxelGrid()

Properties

ActiveScanCells

Stores currently active (occupied) scan cells within the grid.

public SwiftHashSet<int>? ActiveScanCells { get; }

Property Value

SwiftHashSet<int>

BoundsCenter

Center position of the grid in world space.

public Vector3d BoundsCenter { get; }

Property Value

Vector3d

BoundsMax

Maximum bounds of the grid in world coordinates.

public Vector3d BoundsMax { get; }

Property Value

Vector3d

BoundsMin

Minimum bounds of the grid in world coordinates.

public Vector3d BoundsMin { get; }

Property Value

Vector3d

Configuration

Defines the configuration parameters for a grid, including boundaries, topology, storage, and scan cell size. Used to describe grid properties before a world normalizes and registers the grid.

public GridConfiguration Configuration { get; }

Property Value

GridConfiguration

Remarks

MemoryPack GenerateType: unmanaged

FixedMathSharp.Vector3d BoundsMin
FixedMathSharp.Vector3d BoundsMax
int ScanCellSize
GridForge.Grids.Topology.GridTopologyKind TopologyKind
GridForge.Grids.Topology.GridTopologyMetrics TopologyMetrics
GridForge.Grids.Storage.GridStorageKind StorageKind

ConfiguredVoxelCount

The number of physical voxels configured in the grid storage. Dense grids report Size; sparse grids report configured voxels only.

public int ConfiguredVoxelCount { get; }

Property Value

int

GridIndex

World-local index of the grid within its owning world.

public ushort GridIndex { get; }

Property Value

ushort

Height

Grid height in number of voxels.

public int Height { get; }

Property Value

int

IsActive

Indicates whether the grid is currently active.

public bool IsActive { get; }

Property Value

bool

IsConjoined

Determines whether this grid has any linked neighbors.

public bool IsConjoined { get; }

Property Value

bool

IsOccupied

Determines whether the grid is occupied (active and containing occupants).

public bool IsOccupied { get; }

Property Value

bool

Length

Grid length in number of voxels.

public int Length { get; }

Property Value

int

NeighborCount

Count of currently linked neighboring grids.

public byte NeighborCount { get; }

Property Value

byte

Neighbors

Stores topology-local neighbor slots for neighboring grids based on their relative positions.

public SwiftSparseMap<SwiftHashSet<int>>? Neighbors { get; }

Property Value

SwiftSparseMap<SwiftHashSet<int>>

Remarks

Unlike voxel adjacency (which is always 1:1), grids can share multiple neighbors in the same direction.

ObstacleCount

Tracks the number of obstacles currently registered in the grid.

public int ObstacleCount { get; }

Property Value

int

ScanCellSize

Size of a scan cell used for spatial partitioning.

public int ScanCellSize { get; }

Property Value

int

Size

Total addressable voxel count within the grid bounds.

public int Size { get; }

Property Value

int

SpawnToken

Nonzero 64-bit world-local allocation generation identifying this active grid instance. Zero indicates an inactive or unallocated grid.

public long SpawnToken { get; }

Property Value

long

StorageKind

The physical voxel storage strategy used by this grid.

public GridStorageKind StorageKind { get; }

Property Value

GridStorageKind

Version

Tracks the version of the grid, incremented when a Voxel is modified.

public uint Version { get; }

Property Value

uint

Width

Grid width in number of voxels.

public int Width { get; }

Property Value

int

World

The world that owns this grid instance.

public GridWorld? World { get; }

Property Value

GridWorld

Methods

CeilToGrid(Vector3d)

Helper function to ceil snap a FixedMathSharp.Vector3d through this grid's topology, ensuring it stays within grid bounds.

public Vector3d CeilToGrid(Vector3d position)

Parameters

position Vector3d

Returns

Vector3d

ContainsVoxel(VoxelIndex)

Checks whether a physical voxel is configured at the supplied grid-local index.

public bool ContainsVoxel(VoxelIndex voxelIndex)

Parameters

voxelIndex VoxelIndex

The grid-local voxel index to test.

Returns

bool

True when the index resolves to a configured voxel; otherwise false.

EnumerateVoxels()

Enumerates physical voxels configured in this grid in deterministic storage order.

public IEnumerable<Voxel> EnumerateVoxels()

Returns

IEnumerable<Voxel>

FloorToGrid(Vector3d)

Helper function to floor snap a FixedMathSharp.Vector3d through this grid's topology, ensuring it stays within grid bounds.

public Vector3d FloorToGrid(Vector3d position)

Parameters

position Vector3d

Returns

Vector3d

GetActiveScanCells()

Enumerates all currently active scan cells within the grid.

public IEnumerable<ScanCell> GetActiveScanCells()

Returns

IEnumerable<ScanCell>

GetAllGridNeighbors()

Retrieves all neighboring grids connected to this grid.

public IEnumerable<VoxelGrid> GetAllGridNeighbors()

Returns

IEnumerable<VoxelGrid>

An enumeration of all neighboring grids.

GetHexNeighborDirection(VoxelGrid, VoxelGrid)

Determines the hex-prism direction from grid a to neighboring grid b.

public static HexDirection GetHexNeighborDirection(VoxelGrid a, VoxelGrid b)

Parameters

a VoxelGrid

The source hex-prism grid.

b VoxelGrid

The neighboring hex-prism grid.

Returns

HexDirection

The hex direction from a to b, or None when the grids are not hex-prism neighbors.

GetRectangularNeighborDirection(VoxelGrid, VoxelGrid)

Determines the rectangular-prism direction from grid a to neighboring grid b.

public static RectangularDirection GetRectangularNeighborDirection(VoxelGrid a, VoxelGrid b)

Parameters

a VoxelGrid

The source rectangular-prism grid.

b VoxelGrid

The neighboring rectangular-prism grid.

Returns

RectangularDirection

The rectangular direction from a to b, or None when the grids are not rectangular neighbors.

GetScanCellKey(Vector3d)

Computes the scan cell key for a given world position.

public int GetScanCellKey(Vector3d position)

Parameters

position Vector3d

Returns

int

GetScanCellKey(VoxelIndex)

Calculates the spatial cell index for a given position.

public int GetScanCellKey(VoxelIndex voxelIndex)

Parameters

voxelIndex VoxelIndex

Returns

int

IsFacingBoundary(VoxelIndex, HexDirection)

Determines if a topology-local voxel index is facing the hex-prism boundary in the supplied direction.

public bool IsFacingBoundary(VoxelIndex voxelIndex, HexDirection direction)

Parameters

voxelIndex VoxelIndex

direction HexDirection

Returns

bool

IsFacingBoundary(VoxelIndex, RectangularDirection)

Determines if a topology-local voxel index is facing the rectangular-prism boundary in the supplied direction.

public bool IsFacingBoundary(VoxelIndex voxelIndex, RectangularDirection direction)

Parameters

voxelIndex VoxelIndex

direction RectangularDirection

Returns

bool

IsInBounds(Vector3d)

Checks whether a given position falls within the grid bounds.

public bool IsInBounds(Vector3d target)

Parameters

target Vector3d

Returns

bool

IsOnBoundary(VoxelIndex)

Determines if a voxel coordinate is at the boundary of the grid. Used to determine if a voxel should update when a neighboring grid is added/removed.

public bool IsOnBoundary(VoxelIndex coord)

Parameters

coord VoxelIndex

Returns

bool

IsValidVoxelIndex(int, int, int)

Determines whether the given voxel coordinates are within the valid range of the grid.

public bool IsValidVoxelIndex(int x, int y, int z)

Parameters

x int

y int

z int

Returns

bool

IsVoxelAllocated(int, int, int)

Checks if a voxel at the given topology-local coordinates is allocated within the grid.

public bool IsVoxelAllocated(int x, int y, int z)

Parameters

x int

y int

z int

Returns

bool

NormalizeBounds(Vector3d, Vector3d, Fixed64?)

Normalizes world-space bounds to this grid's topology-aligned coverage bounds.

public (Vector3d min, Vector3d max) NormalizeBounds(Vector3d min, Vector3d max, Fixed64? padding = null)

Parameters

min Vector3d

The first world-space bounds corner.

max Vector3d

The second world-space bounds corner.

padding Fixed64?

Optional non-negative padding applied before normalization.

Returns

(Vector3d min, Vector3d max)

Topology-aligned minimum and maximum bounds suitable for deterministic coverage scans.

SnapToScanCell(Vector3d)

Snaps a given position to the topology-local scan cell in the grid.

public (int x, int y, int z) SnapToScanCell(Vector3d position)

Parameters

position Vector3d

Returns

(int x, int y, int z)

TryAddVoxel(VoxelIndex, out Voxel?)

Configures a sparse voxel at runtime. Dense grids, invalid indices, and already-configured sparse voxels return false.

public bool TryAddVoxel(VoxelIndex voxelIndex, out Voxel? voxel)

Parameters

voxelIndex VoxelIndex

The grid-local voxel index to configure.

voxel Voxel

The configured voxel when the operation succeeds.

Returns

bool

True when a new sparse voxel was configured; otherwise false.

TryGetClosestVoxel(Vector2d, Fixed64, out Voxel?)

Retrieves the physical voxel whose center is nearest to a 2D XZ-plane world position on the supplied world Y layer. Sparse grids only consider configured physical voxels.

public bool TryGetClosestVoxel(Vector2d position, Fixed64 layerY, out Voxel? result)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

layerY Fixed64

The world Y layer to resolve. Defaults to zero when omitted by paired overloads.

result Voxel

The closest physical voxel, if found.

Returns

bool

True if a physical voxel was resolved; otherwise false.

TryGetClosestVoxel(Vector2d, out Voxel?)

Retrieves the physical voxel whose center is nearest to a 2D XZ-plane world position on the default world Y layer. Sparse grids only consider configured physical voxels.

public bool TryGetClosestVoxel(Vector2d position, out Voxel? result)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

result Voxel

The closest physical voxel, if found.

Returns

bool

True if a physical voxel was resolved; otherwise false.

TryGetClosestVoxel(Vector3d, out Voxel?)

Retrieves the physical voxel whose center is nearest to the supplied world position. Sparse grids only consider configured physical voxels.

public bool TryGetClosestVoxel(Vector3d position, out Voxel? result)

Parameters

position Vector3d

The world position to resolve.

result Voxel

The closest physical voxel, if found.

Returns

bool

True if a physical voxel was resolved; otherwise false.

TryGetScanCell(Vector3d, out ScanCell?)

Retrieves the scan cell corresponding to a given world position.

public bool TryGetScanCell(Vector3d position, out ScanCell? outScanCell)

Parameters

position Vector3d

outScanCell ScanCell

Returns

bool

TryGetScanCell(VoxelIndex, out ScanCell?)

Retrieves the scan cell associated with the given voxel index.

public bool TryGetScanCell(VoxelIndex voxelIndex, out ScanCell? outScanCell)

Parameters

voxelIndex VoxelIndex

outScanCell ScanCell

Returns

bool

TryGetScanCell(int, out ScanCell?)

Retrieves a scan cell from the grid using its key.

public bool TryGetScanCell(int key, out ScanCell? outScanCell)

Parameters

key int

outScanCell ScanCell

Returns

bool

TryGetVoxel(Vector2d, Fixed64, out Voxel?)

Retrieves a Voxel from a 2D XZ-plane world position on the supplied world Y layer.

public bool TryGetVoxel(Vector2d position, Fixed64 layerY, out Voxel? result)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

layerY Fixed64

The world Y layer to resolve. Defaults to zero when omitted by paired overloads.

result Voxel

The resolved voxel, if found.

Returns

bool

True if the voxel was resolved; otherwise false.

TryGetVoxel(Vector2d, out Voxel?)

Retrieves a Voxel from a 2D XZ-plane world position on the default world Y layer.

public bool TryGetVoxel(Vector2d position, out Voxel? result)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

result Voxel

The resolved voxel, if found.

Returns

bool

True if the voxel was resolved; otherwise false.

TryGetVoxel(Vector3d, out Voxel?)

Retrieve Voxel from world FixedMathSharp.Vector3d points

public bool TryGetVoxel(Vector3d position, out Voxel? result)

Parameters

position Vector3d

result Voxel

Returns

bool

Voxel at the given position or null if the position is not valid.

TryGetVoxel(VoxelIndex, out Voxel?)

Retrieves a grid voxel from a topology-local coordinate.

public bool TryGetVoxel(VoxelIndex voxelIndex, out Voxel? result)

Parameters

voxelIndex VoxelIndex

result Voxel

Returns

bool

TryGetVoxel(int, int, int, out Voxel?)

Retrieves the Voxel at the specified topology-local coordinates, if allocated.

public bool TryGetVoxel(int x, int y, int z, out Voxel? result)

Parameters

x int

y int

z int

result Voxel

Returns

bool

TryGetVoxelIndex(Vector2d, Fixed64, out VoxelIndex)

Converts a 2D XZ-plane world position on the supplied world Y layer to a voxel index within the grid.

public bool TryGetVoxelIndex(Vector2d position, Fixed64 layerY, out VoxelIndex result)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

layerY Fixed64

The world Y layer to resolve. Defaults to zero when omitted by paired overloads.

result VoxelIndex

The resolved voxel index, if found.

Returns

bool

True if the position resolved to an allocated voxel index; otherwise false.

TryGetVoxelIndex(Vector2d, out VoxelIndex)

Converts a 2D XZ-plane world position on the default world Y layer to a voxel index within the grid.

public bool TryGetVoxelIndex(Vector2d position, out VoxelIndex result)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

result VoxelIndex

The resolved voxel index, if found.

Returns

bool

True if the position resolved to an allocated voxel index; otherwise false.

TryGetVoxelIndex(Vector3d, out VoxelIndex)

Converts a world position to a topology-local voxel index within the grid. Rectangular-prism grids return X/Y/Z coordinates; hex-prism grids return axial Q, layer, and axial R in X/Y/Z fields.

public bool TryGetVoxelIndex(Vector3d position, out VoxelIndex result)

Parameters

position Vector3d

result VoxelIndex

Returns

bool

TryRemoveVoxel(VoxelIndex)

Removes a configured sparse voxel at runtime when it has no unsafe runtime state. Dense grids, missing voxels, occupied voxels, voxels with obstacle tokens, partitioned voxels, and voxels with active event subscribers return false.

public bool TryRemoveVoxel(VoxelIndex voxelIndex)

Parameters

voxelIndex VoxelIndex

The grid-local voxel index to remove.

Returns

bool

True when the sparse voxel was removed; otherwise false.