Table of Contents

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
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

sourceGrid NormalizedGridConfiguration
source VoxelIndex
targetGrid NormalizedGridConfiguration
target VoxelIndex

Returns

bool

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

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>

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

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>

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

world GridWorld
boundsMin Vector3d
boundsMax Vector3d
padding Fixed64?

Returns

IEnumerable<GridVoxelSet>

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

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. 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

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>

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

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>

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

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.

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

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
excludedGridSpawnTokens SwiftPackedSet<long>
excludedGridCandidates SwiftList<GridConfigurationKey>

Returns

GridNavigationBodyTraceReport

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

world GridWorld

The explicit world owning every selected generation.

eligibleLayers ReadOnlySpan<GridPlanarLayer>

Exact generations and one selected layer each, in strict configuration order.

embeddingY Fixed64

World Y contained by every selected layer.

source WorldVoxelIndex

Pinned source identity in an eligible generation/layer.

target WorldVoxelIndex

Pinned target identity on the same footprint or an immediate planar neighbor.

startCenter Vector2d

Capsule center at the start of the planar sweep.

endCenter Vector2d

Capsule center at the end of the planar sweep.

axisLength Fixed64

Nonnegative upright core segment length; zero represents a circle.

radius Fixed64

Strictly positive capsule radius.

results SwiftList<GridNavigationBodyTraceCell>

Pre-sized caller-owned evidence storage, cleared before writing.

scratch GridNavigationBodyTraceScratch

Pre-sized caller-owned temporary storage, cleared on return.

gridCandidateLimit int

Maximum charged generation inspections.

addressCandidateLimit int

Maximum charged address inspections.

outputLimit int

Maximum complete required and dependency-evidence cells.

candidateWorkLimit long

Maximum 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

world GridWorld
start Vector3d
end Vector3d
expectedGeneration GridCoveredAddressGeneration
results SwiftList<GridTraceInterval>
scratch GridTraceIntervalScratch
intervalSourceOrdinals Span<int>
continueTrace Func<GridTraceSlab, bool>
gridCandidateLimit int
addressCandidateLimit int
outputLimit int
candidateWorkLimit long
report GridTraceIntervalReport

Returns

bool

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.