Class GridTracer

Namespace

GridForge.Utility

Assembly

GridForge.dll

Provides utilities for tracing lines or bounding areas in a grid, aligning them to grid voxels. Uses fixed-point calculations to ensure deterministic and accurate grid traversal.

public static class GridTracer

Inheritance

object

GridTracer

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

GetCoveredScanCells(GridWorld, FixedBoundArea, Fixed64, Fixed64?)

Retrieves all scan cells within the given XZ-plane area on the supplied world Y layer.

public static IEnumerable<ScanCell> GetCoveredScanCells(GridWorld world, FixedBoundArea area, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

area FixedBoundArea

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

layerY Fixed64

The world Y layer to cover. Defaults to zero.

padding Fixed64?

Value applied to the min/max bounds before snapping.

Returns

IEnumerable<ScanCell>

An enumerable of covered scan cells grouped by grid.

GetCoveredScanCells(GridWorld, Vector2d, Vector2d, Fixed64, Fixed64?)

Retrieves all scan cells within the given XZ-plane bounding area on the supplied world Y layer.

public static IEnumerable<ScanCell> GetCoveredScanCells(GridWorld world, Vector2d boundsMin, Vector2d boundsMax, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

boundsMin Vector2d

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

boundsMax Vector2d

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

layerY Fixed64

The world Y layer to cover. Defaults to zero.

padding Fixed64?

Value applied to the min/max bounds before snapping.

Returns

IEnumerable<ScanCell>

An enumerable of covered scan cells grouped by grid.

GetCoveredScanCells(GridWorld, Vector3d, Vector3d, Fixed64?)

Retrieves all scan cells within the given bounding area across relevant grids in the supplied world.

public static IEnumerable<ScanCell> GetCoveredScanCells(GridWorld world, Vector3d boundsMin, Vector3d boundsMax, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

boundsMin Vector3d

The minimum corner of the bounding area.

boundsMax Vector3d

The maximum corner of the bounding area.

padding Fixed64?

Value applied to the min/max bounds before snapping.

Returns

IEnumerable<ScanCell>

An enumerable of covered scan cells grouped by grid.

GetCoveredScanCellsInto(GridWorld, FixedBoundArea, SwiftList<ScanCell>, Fixed64, Fixed64?)

Clears and fills caller-owned storage with scan cells covered by the supplied XZ-plane area.

public static void GetCoveredScanCellsInto(GridWorld world, FixedBoundArea area, SwiftList<ScanCell> results, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

area FixedBoundArea

results SwiftList<ScanCell>

layerY Fixed64

padding Fixed64?

GetCoveredScanCellsInto(GridWorld, FixedBoundArea, SwiftList<ScanCell>, GridScanScratch, Fixed64, Fixed64?)

Clears and fills caller-owned storage using caller-owned scratch collections for an XZ-plane area.

public static void GetCoveredScanCellsInto(GridWorld world, FixedBoundArea area, SwiftList<ScanCell> results, GridScanScratch scratch, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

area FixedBoundArea

results SwiftList<ScanCell>

scratch GridScanScratch

layerY Fixed64

padding Fixed64?

GetCoveredScanCellsInto(GridWorld, Vector2d, Vector2d, SwiftList<ScanCell>, Fixed64, Fixed64?)

Clears and fills caller-owned storage with scan cells covered by the supplied XZ-plane bounding area.

public static void GetCoveredScanCellsInto(GridWorld world, Vector2d boundsMin, Vector2d boundsMax, SwiftList<ScanCell> results, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

boundsMin Vector2d

boundsMax Vector2d

results SwiftList<ScanCell>

layerY Fixed64

padding Fixed64?

GetCoveredScanCellsInto(GridWorld, Vector2d, Vector2d, SwiftList<ScanCell>, GridScanScratch, Fixed64, Fixed64?)

Clears and fills caller-owned storage using caller-owned scratch collections for an XZ-plane bounding area.

public static void GetCoveredScanCellsInto(GridWorld world, Vector2d boundsMin, Vector2d boundsMax, SwiftList<ScanCell> results, GridScanScratch scratch, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

boundsMin Vector2d

boundsMax Vector2d

results SwiftList<ScanCell>

scratch GridScanScratch

layerY Fixed64

padding Fixed64?

GetCoveredScanCellsInto(GridWorld, Vector3d, Vector3d, SwiftList<ScanCell>, GridScanScratch, Fixed64?)

Clears and fills caller-owned storage using caller-owned scratch collections.

public static void GetCoveredScanCellsInto(GridWorld world, Vector3d boundsMin, Vector3d boundsMax, SwiftList<ScanCell> results, GridScanScratch scratch, Fixed64? padding = null)

Parameters

world GridWorld

boundsMin Vector3d

boundsMax Vector3d

results SwiftList<ScanCell>

scratch GridScanScratch

padding Fixed64?

GetCoveredScanCellsInto(GridWorld, Vector3d, Vector3d, SwiftList<ScanCell>, Fixed64?)

Clears and fills caller-owned storage with scan cells covered by the supplied bounding area.

public static void GetCoveredScanCellsInto(GridWorld world, Vector3d boundsMin, Vector3d boundsMax, SwiftList<ScanCell> results, Fixed64? padding = null)

Parameters

world GridWorld

boundsMin Vector3d

boundsMax Vector3d

results SwiftList<ScanCell>

padding Fixed64?

GetCoveredVoxels(GridWorld, FixedBoundArea, Fixed64, Fixed64?)

Retrieves all grid voxels covered by the given XZ-plane area on the supplied world Y layer.

public static IEnumerable<GridVoxelSet> GetCoveredVoxels(GridWorld world, FixedBoundArea area, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

area FixedBoundArea

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

layerY Fixed64

The world Y layer to cover. Defaults to zero.

padding Fixed64?

Value applied to the min/max bounds before snapping.

Returns

IEnumerable<GridVoxelSet>

A collection of GridVoxelSet objects representing the covered voxels.

GetCoveredVoxels(GridWorld, Vector2d, Vector2d, Fixed64, Fixed64?)

Retrieves all grid voxels covered by the given XZ-plane bounding area on the supplied world Y layer.

public static IEnumerable<GridVoxelSet> GetCoveredVoxels(GridWorld world, Vector2d boundsMin, Vector2d boundsMax, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

boundsMin Vector2d

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

boundsMax Vector2d

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

layerY Fixed64

The world Y layer to cover. Defaults to zero.

padding Fixed64?

Value applied to the min/max bounds before snapping.

Returns

IEnumerable<GridVoxelSet>

A collection of GridVoxelSet objects representing the covered voxels.

GetCoveredVoxels(GridWorld, Vector3d, Vector3d, Fixed64?)

Retrieves all grid voxels covered by the given bounding area in the supplied world.

public static IEnumerable<GridVoxelSet> GetCoveredVoxels(GridWorld world, Vector3d boundsMin, Vector3d boundsMax, Fixed64? padding = null)

Parameters

world GridWorld

boundsMin Vector3d

boundsMax Vector3d

padding Fixed64?

Returns

IEnumerable<GridVoxelSet>

GetCoveredVoxelsInto(GridWorld, FixedBoundArea, SwiftList<Voxel>, Fixed64, Fixed64?)

Clears and fills caller-owned storage with voxels covered by the supplied XZ-plane area.

public static void GetCoveredVoxelsInto(GridWorld world, FixedBoundArea area, SwiftList<Voxel> results, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

area FixedBoundArea

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

results SwiftList<Voxel>

Caller-owned storage that receives covered voxels.

layerY Fixed64

The world Y layer to cover. Defaults to zero.

padding Fixed64?

Value applied to the min/max bounds before normalization.

GetCoveredVoxelsInto(GridWorld, FixedBoundArea, SwiftList<Voxel>, GridTraceScratch, Fixed64, Fixed64?)

Clears and fills caller-owned storage using caller-owned scratch collections for an XZ-plane area.

public static void GetCoveredVoxelsInto(GridWorld world, FixedBoundArea area, SwiftList<Voxel> results, GridTraceScratch scratch, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

area FixedBoundArea

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

results SwiftList<Voxel>

Caller-owned storage that receives covered voxels.

scratch GridTraceScratch

Reusable scratch storage for grid candidates and duplicate-voxel guards.

layerY Fixed64

The world Y layer to cover. Defaults to zero.

padding Fixed64?

Value applied to the min/max bounds before normalization.

GetCoveredVoxelsInto(GridWorld, Vector2d, Vector2d, SwiftList<Voxel>, Fixed64, Fixed64?)

Clears and fills caller-owned storage with voxels covered by the supplied XZ-plane bounding area.

public static void GetCoveredVoxelsInto(GridWorld world, Vector2d boundsMin, Vector2d boundsMax, SwiftList<Voxel> results, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

boundsMin Vector2d

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

boundsMax Vector2d

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

results SwiftList<Voxel>

Caller-owned storage that receives covered voxels.

layerY Fixed64

The world Y layer to cover. Defaults to zero.

padding Fixed64?

Value applied to the min/max bounds before normalization.

GetCoveredVoxelsInto(GridWorld, Vector2d, Vector2d, SwiftList<Voxel>, GridTraceScratch, Fixed64, Fixed64?)

Clears and fills caller-owned storage using caller-owned scratch collections for an XZ-plane bounding area.

public static void GetCoveredVoxelsInto(GridWorld world, Vector2d boundsMin, Vector2d boundsMax, SwiftList<Voxel> results, GridTraceScratch scratch, Fixed64 layerY = default, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

boundsMin Vector2d

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

boundsMax Vector2d

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

results SwiftList<Voxel>

Caller-owned storage that receives covered voxels.

scratch GridTraceScratch

Reusable scratch storage for grid candidates and duplicate-voxel guards.

layerY Fixed64

The world Y layer to cover. Defaults to zero.

padding Fixed64?

Value applied to the min/max bounds before normalization.

GetCoveredVoxelsInto(GridWorld, Vector3d, Vector3d, SwiftList<Voxel>, GridTraceScratch, Fixed64?)

Clears and fills caller-owned storage using caller-owned scratch collections.

public static void GetCoveredVoxelsInto(GridWorld world, Vector3d boundsMin, Vector3d boundsMax, SwiftList<Voxel> results, GridTraceScratch scratch, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

boundsMin Vector3d

The minimum corner of the bounding area.

boundsMax Vector3d

The maximum corner of the bounding area.

results SwiftList<Voxel>

Caller-owned storage that receives covered voxels.

scratch GridTraceScratch

Reusable scratch storage for grid candidates and duplicate-voxel guards.

padding Fixed64?

Value applied to the min/max bounds before normalization.

GetCoveredVoxelsInto(GridWorld, Vector3d, Vector3d, SwiftList<Voxel>, Fixed64?)

Clears and fills caller-owned storage with voxels covered by the supplied bounding area.

public static void GetCoveredVoxelsInto(GridWorld world, Vector3d boundsMin, Vector3d boundsMax, SwiftList<Voxel> results, Fixed64? padding = null)

Parameters

world GridWorld

The world whose grids should be queried.

boundsMin Vector3d

The minimum corner of the bounding area.

boundsMax Vector3d

The maximum corner of the bounding area.

results SwiftList<Voxel>

Caller-owned storage that receives covered voxels.

padding Fixed64?

Value applied to the min/max bounds before normalization.

TraceIntervalsInto(GridWorld, Vector3d, Vector3d, SwiftList<GridTraceInterval>, GridTraceIntervalScratch, int, int, int, long)

Traces an arbitrary world-space segment into exact, canonically ordered grid-cell intervals.

public static GridTraceIntervalReport TraceIntervalsInto(GridWorld world, Vector3d start, Vector3d end, SwiftList<GridTraceInterval> results, GridTraceIntervalScratch scratch, int gridCandidateLimit, int addressCandidateLimit, int outputLimit, long candidateWorkLimit)

Parameters

world GridWorld

start Vector3d

end Vector3d

results SwiftList<GridTraceInterval>

scratch GridTraceIntervalScratch

gridCandidateLimit int

addressCandidateLimit int

outputLimit int

candidateWorkLimit long

Returns

GridTraceIntervalReport

Remarks

Results are cleared on entry and on any ceiling or representability failure. Candidate grids are discovered through the world spatial index. Candidate addresses are bounded around the segment, then exact rectangular or hexagonal prisms reject all broad-phase false positives.

TraceLine(GridWorld, Vector2d, Vector2d, Fixed64?, bool, Fixed64)

Traces a 2D XZ-plane line between two points in the supplied world, snapping them to grid coordinates.

public static IEnumerable<GridVoxelSet> TraceLine(GridWorld world, Vector2d start, Vector2d end, Fixed64? padding = null, bool includeEnd = true, Fixed64 layerY = default)

Parameters

world GridWorld

The world whose grids should be traced.

start Vector2d

Starting XZ-plane position in world space.

end Vector2d

Ending XZ-plane position in world space.

padding Fixed64?

Value applied to the start/end positions before snapping.

includeEnd bool

Whether to include the end voxel in the traced line.

layerY Fixed64

The world Y layer to trace. Defaults to zero.

Returns

IEnumerable<GridVoxelSet>

A collection of GridVoxelSet objects representing the traced path.

Remarks

This method maps FixedMathSharp.Vector2d.X to world X, FixedMathSharp.Vector2d.Y to world Z, and layerY to world Y. The default layer is world Y = 0.

TraceLine(GridWorld, Vector3d, Vector3d, Fixed64?, bool)

Traces a 3D line between two points in the supplied world. The traced points are returned as grid voxels.

public static IEnumerable<GridVoxelSet> TraceLine(GridWorld world, Vector3d start, Vector3d end, Fixed64? padding = null, bool includeEnd = true)

Parameters

world GridWorld

The world whose grids should be traced.

start Vector3d

Starting position in world space.

end Vector3d

Ending position in world space.

padding Fixed64?

Value applied to the start/end positions before snapping.

includeEnd bool

Whether to include the end voxel in the traced line.

Returns

IEnumerable<GridVoxelSet>

A collection of GridVoxelSet objects representing the traced path.

Remarks

Uses a fractional step algorithm inspired by Bresenham’s line algorithm. This implementation leverages fixed-point math to maintain precision across a deterministic grid.

TraceLineInto(GridWorld, Vector2d, Vector2d, SwiftList<Voxel>, GridTraceScratch, Fixed64?, bool, Fixed64)

Clears and fills caller-owned storage with voxels traced by a 2D XZ-plane line using caller-owned scratch collections.

public static void TraceLineInto(GridWorld world, Vector2d start, Vector2d end, SwiftList<Voxel> results, GridTraceScratch scratch, Fixed64? padding = null, bool includeEnd = true, Fixed64 layerY = default)

Parameters

world GridWorld

The world whose grids should be traced.

start Vector2d

Starting XZ-plane position in world space.

end Vector2d

Ending XZ-plane position in world space.

results SwiftList<Voxel>

Caller-owned storage that receives traced voxels.

scratch GridTraceScratch

Reusable scratch storage for grid candidates and duplicate-voxel guards.

padding Fixed64?

Value applied to the start/end positions before snapping.

includeEnd bool

Whether to include the end voxel in the traced line.

layerY Fixed64

The world Y layer to trace. Defaults to zero.

TraceLineInto(GridWorld, Vector2d, Vector2d, SwiftList<Voxel>, Fixed64?, bool, Fixed64)

Clears and fills caller-owned storage with voxels traced by a 2D XZ-plane line.

public static void TraceLineInto(GridWorld world, Vector2d start, Vector2d end, SwiftList<Voxel> results, Fixed64? padding = null, bool includeEnd = true, Fixed64 layerY = default)

Parameters

world GridWorld

The world whose grids should be traced.

start Vector2d

Starting XZ-plane position in world space.

end Vector2d

Ending XZ-plane position in world space.

results SwiftList<Voxel>

Caller-owned storage that receives traced voxels.

padding Fixed64?

Value applied to the start/end positions before snapping.

includeEnd bool

Whether to include the end voxel in the traced line.

layerY Fixed64

The world Y layer to trace. Defaults to zero.

TraceLineInto(GridWorld, Vector3d, Vector3d, SwiftList<Voxel>, GridTraceScratch, Fixed64?, bool)

Clears and fills caller-owned storage with voxels traced by a 3D line using caller-owned scratch collections.

public static void TraceLineInto(GridWorld world, Vector3d start, Vector3d end, SwiftList<Voxel> results, GridTraceScratch scratch, Fixed64? padding = null, bool includeEnd = true)

Parameters

world GridWorld

The world whose grids should be traced.

start Vector3d

Starting position in world space.

end Vector3d

Ending position in world space.

results SwiftList<Voxel>

Caller-owned storage that receives traced voxels.

scratch GridTraceScratch

Reusable scratch storage for grid candidates and duplicate-voxel guards.

padding Fixed64?

Value applied to the start/end positions before snapping.

includeEnd bool

Whether to include the end voxel in the traced line.

TraceLineInto(GridWorld, Vector3d, Vector3d, SwiftList<Voxel>, Fixed64?, bool)

Clears and fills caller-owned storage with voxels traced by a 3D line.

public static void TraceLineInto(GridWorld world, Vector3d start, Vector3d end, SwiftList<Voxel> results, Fixed64? padding = null, bool includeEnd = true)

Parameters

world GridWorld

The world whose grids should be traced.

start Vector3d

Starting position in world space.

end Vector3d

Ending position in world space.

results SwiftList<Voxel>

Caller-owned storage that receives traced voxels.

padding Fixed64?

Value applied to the start/end positions before snapping.

includeEnd bool

Whether to include the end voxel in the traced line.

TraceNavigationBodyInto(GridWorld, WorldVoxelIndex, WorldVoxelIndex, Vector3d, Vector3d, Fixed64, Fixed64, SwiftList<GridNavigationBodyTraceCell>, GridNavigationBodyTraceScratch, int, int, int, long)

Writes the canonical cells required by one direct upright-body sweep.

public static GridNavigationBodyTraceReport TraceNavigationBodyInto(GridWorld world, WorldVoxelIndex source, WorldVoxelIndex target, Vector3d startFoot, Vector3d endFoot, Fixed64 horizontalRadius, Fixed64 bodyHeight, SwiftList<GridNavigationBodyTraceCell> results, GridNavigationBodyTraceScratch scratch, int gridCandidateLimit, int addressCandidateLimit, int outputLimit, long candidateWorkLimit)

Parameters

world GridWorld

source WorldVoxelIndex

target WorldVoxelIndex

startFoot Vector3d

endFoot Vector3d

horizontalRadius Fixed64

bodyHeight Fixed64

results SwiftList<GridNavigationBodyTraceCell>

scratch GridNavigationBodyTraceScratch

gridCandidateLimit int

addressCandidateLimit int

outputLimit int

candidateWorkLimit long

Returns

GridNavigationBodyTraceReport

Remarks

The start and end bodies must have closed-set contact with the declared source and target prisms respectively; exact endpoint tangency is admitted for that identity check. A prism is claimed only when its planar and vertical interiors overlap the swept body at one shared continuous parameter. Boundary-only coincidence and tangency are excluded. Grid, address, output, and combined candidate-work ceilings are independent.