Class GridTracer
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
-
GridTracer
- Inherited Members
Methods
ArePlanarCoverageNeighborsOrCoincident(in NormalizedGridConfiguration, VoxelIndex, in NormalizedGridConfiguration, VoxelIndex)
Tests whether two cell footprints are coincident or exact planar coverage neighbors.
public static bool ArePlanarCoverageNeighborsOrCoincident(in NormalizedGridConfiguration sourceGrid, VoxelIndex source, in NormalizedGridConfiguration targetGrid, VoxelIndex target)
Parameters
sourceGridNormalizedGridConfigurationsourceVoxelIndextargetGridNormalizedGridConfigurationtargetVoxelIndex
Returns
Remarks
Uses the source grid's quantized forward topology. Vertical layers and physical voxel presence are ignored.
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
worldGridWorldThe world whose grids should be queried.
areaFixedBoundAreaThe 2D area whose X component maps to world X and Y component maps to world Z.
layerYFixed64The world Y layer to cover. Defaults to zero.
paddingFixed64?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
worldGridWorldThe world whose grids should be queried.
boundsMinVector2dThe 2D minimum corner whose X component maps to world X and Y component maps to world Z.
boundsMaxVector2dThe 2D maximum corner whose X component maps to world X and Y component maps to world Z.
layerYFixed64The world Y layer to cover. Defaults to zero.
paddingFixed64?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
worldGridWorldThe world whose grids should be queried.
boundsMinVector3dThe minimum corner of the bounding area.
boundsMaxVector3dThe maximum corner of the bounding area.
paddingFixed64?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
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
worldGridWorldareaFixedBoundArearesultsSwiftList<ScanCell>scratchGridScanScratchlayerYFixed64paddingFixed64?
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
worldGridWorldboundsMinVector2dboundsMaxVector2dresultsSwiftList<ScanCell>layerYFixed64paddingFixed64?
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
worldGridWorldboundsMinVector2dboundsMaxVector2dresultsSwiftList<ScanCell>scratchGridScanScratchlayerYFixed64paddingFixed64?
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
worldGridWorldboundsMinVector3dboundsMaxVector3dresultsSwiftList<ScanCell>scratchGridScanScratchpaddingFixed64?
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
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
worldGridWorldThe world whose grids should be queried.
areaFixedBoundAreaThe 2D area whose X component maps to world X and Y component maps to world Z.
layerYFixed64The world Y layer to cover. Defaults to zero.
paddingFixed64?Value applied to the min/max bounds before snapping.
Returns
- IEnumerable<GridVoxelSet>
Grouped results whose voxel lists are lent until enumeration completes or is disposed.
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
worldGridWorldThe world whose grids should be queried.
boundsMinVector2dThe 2D minimum corner whose X component maps to world X and Y component maps to world Z.
boundsMaxVector2dThe 2D maximum corner whose X component maps to world X and Y component maps to world Z.
layerYFixed64The world Y layer to cover. Defaults to zero.
paddingFixed64?Value applied to the min/max bounds before snapping.
Returns
- IEnumerable<GridVoxelSet>
Grouped results whose voxel lists are lent until enumeration completes or is disposed.
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
worldGridWorldboundsMinVector3dboundsMaxVector3dpaddingFixed64?
Returns
Remarks
Each result lends a pooled voxel list until enumeration completes or is
disposed. Copy contents before retaining them, or use GetCoveredVoxelsInto.
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
worldGridWorldThe world whose grids should be queried.
areaFixedBoundAreaThe 2D area whose X component maps to world X and Y component maps to world Z.
resultsSwiftList<Voxel>Caller-owned storage that receives covered voxels.
layerYFixed64The world Y layer to cover. Defaults to zero.
paddingFixed64?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
worldGridWorldThe world whose grids should be queried.
areaFixedBoundAreaThe 2D area whose X component maps to world X and Y component maps to world Z.
resultsSwiftList<Voxel>Caller-owned storage that receives covered voxels.
scratchGridTraceScratchReusable scratch storage for grid candidates and duplicate-voxel guards.
layerYFixed64The world Y layer to cover. Defaults to zero.
paddingFixed64?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
worldGridWorldThe world whose grids should be queried.
boundsMinVector2dThe 2D minimum corner whose X component maps to world X and Y component maps to world Z.
boundsMaxVector2dThe 2D maximum corner whose X component maps to world X and Y component maps to world Z.
resultsSwiftList<Voxel>Caller-owned storage that receives covered voxels.
layerYFixed64The world Y layer to cover. Defaults to zero.
paddingFixed64?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
worldGridWorldThe world whose grids should be queried.
boundsMinVector2dThe 2D minimum corner whose X component maps to world X and Y component maps to world Z.
boundsMaxVector2dThe 2D maximum corner whose X component maps to world X and Y component maps to world Z.
resultsSwiftList<Voxel>Caller-owned storage that receives covered voxels.
scratchGridTraceScratchReusable scratch storage for grid candidates and duplicate-voxel guards.
layerYFixed64The world Y layer to cover. Defaults to zero.
paddingFixed64?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
worldGridWorldThe world whose grids should be queried.
boundsMinVector3dThe minimum corner of the bounding area.
boundsMaxVector3dThe maximum corner of the bounding area.
resultsSwiftList<Voxel>Caller-owned storage that receives covered voxels.
scratchGridTraceScratchReusable scratch storage for grid candidates and duplicate-voxel guards.
paddingFixed64?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
worldGridWorldThe world whose grids should be queried.
boundsMinVector3dThe minimum corner of the bounding area.
boundsMaxVector3dThe maximum corner of the bounding area.
resultsSwiftList<Voxel>Caller-owned storage that receives covered voxels.
paddingFixed64?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
worldGridWorldstartVector3dendVector3dresultsSwiftList<GridTraceInterval>scratchGridTraceIntervalScratchgridCandidateLimitintaddressCandidateLimitintoutputLimitintcandidateWorkLimitlong
Returns
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. The supplied scratch must not already be active in another trace; reentrant use throws before clearing results.
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
worldGridWorldThe world whose grids should be traced.
startVector2dStarting XZ-plane position in world space.
endVector2dEnding XZ-plane position in world space.
paddingFixed64?Value applied to the start/end positions before snapping.
includeEndboolWhether to include the end voxel in the traced line.
layerYFixed64The world Y layer to trace. Defaults to zero.
Returns
- IEnumerable<GridVoxelSet>
Grouped results whose voxel lists are lent until enumeration completes or is disposed.
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
worldGridWorldThe world whose grids should be traced.
startVector3dStarting position in world space.
endVector3dEnding position in world space.
paddingFixed64?Value applied to the start/end positions before snapping.
includeEndboolWhether to include the end voxel in the traced line.
Returns
- IEnumerable<GridVoxelSet>
Grouped results whose voxel lists are lent until enumeration completes or is disposed.
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.
Consume each pooled voxel list inside the enumeration or copy its contents
to caller-owned storage. Retained results should use TraceLineInto.
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
worldGridWorldThe world whose grids should be traced.
startVector2dStarting XZ-plane position in world space.
endVector2dEnding XZ-plane position in world space.
resultsSwiftList<Voxel>Caller-owned storage that receives traced voxels.
scratchGridTraceScratchReusable scratch storage for grid candidates and duplicate-voxel guards.
paddingFixed64?Value applied to the start/end positions before snapping.
includeEndboolWhether to include the end voxel in the traced line.
layerYFixed64The 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
worldGridWorldThe world whose grids should be traced.
startVector2dStarting XZ-plane position in world space.
endVector2dEnding XZ-plane position in world space.
resultsSwiftList<Voxel>Caller-owned storage that receives traced voxels.
paddingFixed64?Value applied to the start/end positions before snapping.
includeEndboolWhether to include the end voxel in the traced line.
layerYFixed64The 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
worldGridWorldThe world whose grids should be traced.
startVector3dStarting position in world space.
endVector3dEnding position in world space.
resultsSwiftList<Voxel>Caller-owned storage that receives traced voxels.
scratchGridTraceScratchReusable scratch storage for grid candidates and duplicate-voxel guards.
paddingFixed64?Value applied to the start/end positions before snapping.
includeEndboolWhether 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
worldGridWorldThe world whose grids should be traced.
startVector3dStarting position in world space.
endVector3dEnding position in world space.
resultsSwiftList<Voxel>Caller-owned storage that receives traced voxels.
paddingFixed64?Value applied to the start/end positions before snapping.
includeEndboolWhether 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
worldGridWorldsourceWorldVoxelIndextargetWorldVoxelIndexstartFootVector3dendFootVector3dhorizontalRadiusFixed64bodyHeightFixed64resultsSwiftList<GridNavigationBodyTraceCell>scratchGridNavigationBodyTraceScratchgridCandidateLimitintaddressCandidateLimitintoutputLimitintcandidateWorkLimitlong
Returns
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.
TraceNavigationBodyInto(GridWorld, WorldVoxelIndex, WorldVoxelIndex, Vector3d, Vector3d, Fixed64, Fixed64, SwiftList<GridNavigationBodyTraceCell>, GridNavigationBodyTraceScratch, int, int, int, long, SwiftPackedSet<long>?, SwiftList<GridConfigurationKey>?)
Writes upright-body coverage while excluding the supplied exact grid generations.
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, SwiftPackedSet<long>? excludedGridSpawnTokens, SwiftList<GridConfigurationKey>? excludedGridCandidates = null)
Parameters
worldGridWorldsourceWorldVoxelIndextargetWorldVoxelIndexstartFootVector3dendFootVector3dhorizontalRadiusFixed64bodyHeightFixed64resultsSwiftList<GridNavigationBodyTraceCell>scratchGridNavigationBodyTraceScratchgridCandidateLimitintaddressCandidateLimitintoutputLimitintcandidateWorkLimitlongexcludedGridSpawnTokensSwiftPackedSet<long>excludedGridCandidatesSwiftList<GridConfigurationKey>
Returns
Remarks
Supply SpawnToken values from the given world and keep the set unchanged until the trace returns.
An excluded generation cannot provide prism coverage or cell dependency evidence. Its broad-phase
candidate still counts toward the grid and combined limits, with no address work charged.
An excluded source or target invalidates the trace. An old token never excludes a replacement grid.
The optional excludedGridCandidates list is cleared first and receives the configuration keys
of excluded grids encountered during candidate traversal. An aborted trace can leave only a prefix.
TracePlanarNavigationBodyInto(GridWorld, ReadOnlySpan<GridPlanarLayer>, Fixed64, WorldVoxelIndex, WorldVoxelIndex, Vector2d, Vector2d, Fixed64, Fixed64, SwiftList<GridNavigationBodyTraceCell>, GridNavigationBodyTraceScratch, int, int, int, long)
Writes bounded native planar upright-capsule coverage for one immediate neighbor leg.
public static GridNavigationBodyTraceReport TracePlanarNavigationBodyInto(GridWorld world, ReadOnlySpan<GridPlanarLayer> eligibleLayers, Fixed64 embeddingY, WorldVoxelIndex source, WorldVoxelIndex target, Vector2d startCenter, Vector2d endCenter, Fixed64 axisLength, Fixed64 radius, SwiftList<GridNavigationBodyTraceCell> results, GridNavigationBodyTraceScratch scratch, int gridCandidateLimit, int addressCandidateLimit, int outputLimit, long candidateWorkLimit)
Parameters
worldGridWorldThe explicit world owning every selected generation.
eligibleLayersReadOnlySpan<GridPlanarLayer>Exact generations and one selected layer each, in strict configuration order.
embeddingYFixed64World Y contained by every selected layer.
sourceWorldVoxelIndexPinned source identity in an eligible generation/layer.
targetWorldVoxelIndexPinned target identity on the same footprint or an immediate planar neighbor.
startCenterVector2dCapsule center at the start of the planar sweep.
endCenterVector2dCapsule center at the end of the planar sweep.
axisLengthFixed64Nonnegative upright core segment length; zero represents a circle.
radiusFixed64Strictly positive capsule radius.
resultsSwiftList<GridNavigationBodyTraceCell>Pre-sized caller-owned evidence storage, cleared before writing.
scratchGridNavigationBodyTraceScratchPre-sized caller-owned temporary storage, cleared on return.
gridCandidateLimitintMaximum charged generation inspections.
addressCandidateLimitintMaximum charged address inspections.
outputLimitintMaximum complete required and dependency-evidence cells.
candidateWorkLimitlongMaximum combined generation and address inspections.
Returns
- GridNavigationBodyTraceReport
The completion status, exact candidate counts, and coherent evidence stamp.
Remarks
Eligible generations must be strictly configuration-ordered, with one selected layer per generation.
The positive-radius capsule has an upright Forward axis of axisLength;
total height is axis length plus twice the radius. World Y selects layers, not gameplay height.
Closed endpoint contact admits identity; only strict swept interior overlap claims other cells.
Existing scratch/output capacities are hard ceilings. Candidate work counts admitted generation
and address inspections, not every geometry operation. Per selected grid, candidate range math
uses at most four 31-step forward-lattice bounds. With N retained candidates, union closure
visits at most eight planar neighbors per member; sorting and lookup are O(N log N), with
duplicate-alternative scans bounded by O(N squared). No world-registry scan or storage growth occurs.
The world read lock precedes the committed-change lock for the whole bounded proof.
TryTraceRectangularSlabsInto(GridWorld, Vector3d, Vector3d, in GridCoveredAddressGeneration, SwiftList<GridTraceInterval>, GridTraceIntervalScratch, Span<int>, Func<GridTraceSlab, bool>, int, int, int, long, out GridTraceIntervalReport)
Attempts a bounded trace observed after each complete rectangular X slab.
public static bool TryTraceRectangularSlabsInto(GridWorld world, Vector3d start, Vector3d end, in GridCoveredAddressGeneration expectedGeneration, SwiftList<GridTraceInterval> results, GridTraceIntervalScratch scratch, Span<int> intervalSourceOrdinals, Func<GridTraceSlab, bool> continueTrace, int gridCandidateLimit, int addressCandidateLimit, int outputLimit, long candidateWorkLimit, out GridTraceIntervalReport report)
Parameters
worldGridWorldstartVector3dendVector3dexpectedGenerationGridCoveredAddressGenerationresultsSwiftList<GridTraceInterval>scratchGridTraceIntervalScratchintervalSourceOrdinalsSpan<int>continueTraceFunc<GridTraceSlab, bool>gridCandidateLimitintaddressCandidateLimitintoutputLimitintcandidateWorkLimitlongreportGridTraceIntervalReport
Returns
Remarks
Returns false only before chargeable discovery when the original segment or expected single-layer rectangular generation is unsupported. Results are then empty and the observer is not invoked. All qualified terminal outcomes return true, including ceilings. The observer runs under the world read lock and must not reenter world/grid operations or mutate results or scratch. Reading world identity/change-stamp properties for freshness fences is allowed. Scratch is not thread-safe. Returning false from the observer retains emission-order intervals, not a canonical ray prefix; ties and coverage remain unassigned. Continuation sorts canonically and source ordinals follow every move. The ordinal span must fit outputLimit. Failure or exception clears results and used ordinals; exceptions propagate after cleanup. World stamps are captured before qualification, not refreshed by callbacks; concurrent obstacle changes remain possible and consumers own their final freshness fence.