< Summary

Information
Class: GridForge.Grids.Topology.GridNavigationCorridorValidationCursor
Assembly: GridForge
File(s): /home/runner/work/GridForge/GridForge/src/GridForge/Grids/Topology/GridNavigationCorridorValidationCursor.cs
Line coverage
100%
Covered lines: 128
Uncovered lines: 0
Coverable lines: 128
Total lines: 288
Line coverage: 100%
Branch coverage
100%
Covered branches: 58
Total branches: 58
Branch coverage: 100%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
get_Status()100%11100%
get_PortalWaypointCount()100%11100%
get_GeometricCost()100%11100%
TryGetCurrentPortal(...)100%22100%
.ctor(...)100%44100%
Advance(...)100%1212100%
PerformNext(...)100%1414100%
ValidateNextPortal(...)100%2020100%
ValidateExitAnchor(...)100%44100%
Fail(...)100%11100%
TryAccumulateDistance(...)100%22100%

File(s)

/home/runner/work/GridForge/GridForge/src/GridForge/Grids/Topology/GridNavigationCorridorValidationCursor.cs

#LineLine coverage
 1//=======================================================================
 2// GridNavigationCorridorValidationCursor.cs
 3//=======================================================================
 4// MIT License, Copyright (c) 2024-present David Oravsky (mrdav30)
 5// See LICENSE file in the project root for full license information.
 6//=======================================================================
 7
 8using System;
 9using FixedMathSharp;
 10
 11namespace GridForge.Grids.Topology;
 12
 13
 14
 15/// <summary>
 16/// Resumably validates one deterministic navigation corridor into caller-owned storage.
 17/// </summary>
 18/// <remarks>
 19/// The ordered cell and waypoint spans are not retained. Their lengths and contents must remain
 20/// stable between calls. A successful corridor of N cells consumes exactly 2N+1 work units.
 21/// Advance one work unit at a time and call <see cref="TryGetCurrentPortal"/> after each call to
 22/// consume every portal certificate in order.
 23/// </remarks>
 24public struct GridNavigationCorridorValidationCursor
 25{
 26    private enum ValidationStage : byte
 27    {
 28        Cells,
 29        EntryAnchor,
 30        Portals,
 31        ExitAnchor
 32    }
 33
 34    private readonly int _cellCount;
 35    private readonly Vector3d _entryAnchor;
 36    private readonly Vector3d _exitAnchor;
 37    private readonly Fixed64 _radiusClearance;
 38    private readonly Fixed64 _heightClearance;
 39    private GridNavigationCorridorValidationStatus _status;
 40    private ValidationStage _stage;
 41    private bool _hasCurrentPortal;
 42    private int _cellIndex;
 43    private int _portalIndex;
 44    private int _portalWaypointCount;
 45    private Vector3d _previousPoint;
 46    private Fixed64 _geometricCost;
 47    private GridNavigationPortal _selectedPortal;
 48
 49    /// <summary>The current validation state.</summary>
 910550    public readonly GridNavigationCorridorValidationStatus Status => _status;
 51
 52    /// <summary>The number of canonical waypoints written, or zero after failure.</summary>
 2453    public readonly int PortalWaypointCount => _portalWaypointCount;
 54
 55    /// <summary>The checked canonical polyline length accumulated so far.</summary>
 2456    public readonly Fixed64 GeometricCost => _geometricCost;
 57
 58    /// <summary>
 59    /// Attempts to get the portal certificate produced by the last completed work unit.
 60    /// </summary>
 61    /// <remarks>
 62    /// The value is available only when the final work unit completed by the most recent advance
 63    /// was successful portal work. Use a one-unit budget to consume every certificate in order.
 64    /// </remarks>
 65    /// <param name="portal">The produced portal, or <see langword="default"/> when unavailable.</param>
 66    /// <returns><see langword="true"/> when a portal certificate is available.</returns>
 67    public readonly bool TryGetCurrentPortal(out GridNavigationPortal portal)
 68    {
 705869        portal = _hasCurrentPortal ? _selectedPortal : default;
 705870        return _hasCurrentPortal;
 71    }
 72
 73    /// <summary>
 74    /// Creates a cursor for one ordered source, witness, and destination cell chain.
 75    /// </summary>
 76    /// <param name="cellCount">The stable number of ordered cells supplied to every advance.</param>
 77    /// <param name="entryAnchor">The source-cell foot anchor.</param>
 78    /// <param name="exitAnchor">The destination-cell foot anchor.</param>
 79    /// <param name="radiusClearance">The required nonnegative horizontal body radius.</param>
 80    /// <param name="heightClearance">The required positive body height.</param>
 81    public GridNavigationCorridorValidationCursor(
 82        int cellCount,
 83        Vector3d entryAnchor,
 84        Vector3d exitAnchor,
 85        Fixed64 radiusClearance,
 86        Fixed64 heightClearance)
 87    {
 105788        _cellCount = cellCount;
 105789        _entryAnchor = entryAnchor;
 105790        _exitAnchor = exitAnchor;
 105791        _radiusClearance = radiusClearance;
 105792        _heightClearance = heightClearance;
 105793        _status = cellCount >= 2
 105794            && radiusClearance >= Fixed64.Zero
 105795            && heightClearance > Fixed64.Zero
 105796                ? GridNavigationCorridorValidationStatus.InProgress
 105797                : GridNavigationCorridorValidationStatus.Invalid;
 105798        _stage = ValidationStage.Cells;
 105799        _cellIndex = 0;
 1057100        _portalIndex = 0;
 1057101        _portalWaypointCount = 0;
 1057102        _previousPoint = entryAnchor;
 1057103        _geometricCost = default;
 1057104        _selectedPortal = default;
 1057105        _hasCurrentPortal = false;
 1057106    }
 107
 108    /// <summary>
 109    /// Performs at most <paramref name="maxWork"/> bounded validation units.
 110    /// </summary>
 111    /// <param name="orderedCells">The unchanged ordered cells supplied for this cursor.</param>
 112    /// <param name="portalWaypoints">Caller-owned storage for twice the portal count.</param>
 113    /// <param name="maxWork">The nonnegative maximum number of work units to perform.</param>
 114    /// <returns>The resulting validation state.</returns>
 115    public GridNavigationCorridorValidationStatus Advance(
 116        ReadOnlySpan<GridCellPrism> orderedCells,
 117        Span<Vector3d> portalWaypoints,
 118        int maxWork)
 119    {
 7113120        if (maxWork < 0)
 1121            throw new ArgumentOutOfRangeException(nameof(maxWork));
 122
 7112123        _hasCurrentPortal = false;
 7112124        if (_status != GridNavigationCorridorValidationStatus.InProgress)
 2125            return _status;
 126
 7110127        if (orderedCells.Length != _cellCount
 7110128            || _cellCount - 1 > portalWaypoints.Length / 2)
 129        {
 1130            return Fail(GridNavigationCorridorValidationStatus.Invalid);
 131        }
 132
 14364133        while (maxWork-- > 0 && _status == GridNavigationCorridorValidationStatus.InProgress)
 7255134            PerformNext(orderedCells, portalWaypoints);
 135
 7109136        return _status;
 137    }
 138
 139    private void PerformNext(
 140        ReadOnlySpan<GridCellPrism> orderedCells,
 141        Span<Vector3d> portalWaypoints)
 142    {
 7255143        _hasCurrentPortal = false;
 7255144        switch (_stage)
 145        {
 146            case ValidationStage.Cells:
 3122147                GridCellPrism cell = orderedCells[_cellIndex++];
 3122148                if (cell.FootprintVertexCount is not 4 and not 6
 3122149                    || cell.VerticalMax < cell.VerticalMin)
 150                {
 2151                    Fail(GridNavigationCorridorValidationStatus.Invalid);
 2152                    return;
 153                }
 154
 3120155                if (_cellIndex == _cellCount)
 1049156                    _stage = ValidationStage.EntryAnchor;
 3120157                return;
 158
 159            case ValidationStage.EntryAnchor:
 1049160                GridCellGeometry.TryCreateNavigationPortal(
 1049161                    orderedCells[0],
 1049162                    orderedCells[1],
 1049163                    out _selectedPortal);
 1049164                if (!GridCellGeometry.IsNavigationBodyAnchorValid(
 1049165                        orderedCells[0],
 1049166                        _entryAnchor,
 1049167                        _radiusClearance,
 1049168                        _heightClearance,
 1049169                        _selectedPortal))
 170                {
 10171                    Fail(GridNavigationCorridorValidationStatus.Invalid);
 10172                    return;
 173                }
 174
 1039175                _stage = ValidationStage.Portals;
 1039176                return;
 177
 178            case ValidationStage.Portals:
 2054179                ValidateNextPortal(orderedCells, portalWaypoints);
 2054180                return;
 181
 182            default:
 1030183                ValidateExitAnchor(orderedCells);
 1030184                return;
 185        }
 186    }
 187
 188    private void ValidateNextPortal(
 189        ReadOnlySpan<GridCellPrism> orderedCells,
 190        Span<Vector3d> portalWaypoints)
 191    {
 2054192        GridCellPrism source = orderedCells[_portalIndex];
 2054193        GridCellPrism target = orderedCells[_portalIndex + 1];
 2054194        GridNavigationPortal incomingPortal = _portalIndex == 0
 2054195            ? default
 2054196            : _selectedPortal;
 2054197        GridNavigationPortal outgoingPortal = _selectedPortal;
 2054198        if ((_portalIndex > 0
 2054199                && !GridCellGeometry.TryCreateNavigationPortal(source, target, out outgoingPortal))
 2054200            || !outgoingPortal.IsValid
 2054201            || !outgoingPortal.TryResolveProfile(
 2054202                _radiusClearance,
 2054203                _heightClearance,
 2054204                out Vector3d sourcePoint,
 2054205                out Vector3d targetPoint)
 2054206            || !GridCellGeometry.IsNavigationBodySegmentValid(
 2054207                source,
 2054208                _previousPoint,
 2054209                sourcePoint,
 2054210                _radiusClearance,
 2054211                _heightClearance,
 2054212                incomingPortal,
 2054213                outgoingPortal,
 2054214                GridNavigationBodySegmentEndpointAllowance.None))
 215        {
 7216            Fail(GridNavigationCorridorValidationStatus.Invalid);
 7217            return;
 218        }
 219
 2047220        portalWaypoints[_portalWaypointCount++] = sourcePoint;
 2047221        if (!TryAccumulateDistance(_previousPoint, sourcePoint))
 222        {
 1223            Fail(GridNavigationCorridorValidationStatus.CostOverflow);
 1224            return;
 225        }
 226
 2046227        _previousPoint = sourcePoint;
 2046228        if (outgoingPortal.FaceKind == VoxelContactFaceKind.Horizontal)
 229        {
 4230            portalWaypoints[_portalWaypointCount++] = targetPoint;
 4231            if (!TryAccumulateDistance(_previousPoint, targetPoint))
 232            {
 1233                Fail(GridNavigationCorridorValidationStatus.CostOverflow);
 1234                return;
 235            }
 236
 3237            _previousPoint = targetPoint;
 238        }
 239
 2045240        _selectedPortal = outgoingPortal;
 2045241        _hasCurrentPortal = true;
 2045242        _portalIndex++;
 2045243        if (_portalIndex == _cellCount - 1)
 1030244            _stage = ValidationStage.ExitAnchor;
 2045245    }
 246
 247    private void ValidateExitAnchor(ReadOnlySpan<GridCellPrism> orderedCells)
 248    {
 1030249        if (!TryAccumulateDistance(_previousPoint, _exitAnchor))
 250        {
 1251            Fail(GridNavigationCorridorValidationStatus.CostOverflow);
 1252            return;
 253        }
 254
 1029255        if (!GridCellGeometry.IsNavigationBodySegmentValid(
 1029256                orderedCells[_cellCount - 1],
 1029257                _previousPoint,
 1029258                _exitAnchor,
 1029259                _radiusClearance,
 1029260                _heightClearance,
 1029261                _selectedPortal,
 1029262                default,
 1029263                GridNavigationBodySegmentEndpointAllowance.None))
 264        {
 3265            Fail(GridNavigationCorridorValidationStatus.Invalid);
 3266            return;
 267        }
 268
 1026269        _status = GridNavigationCorridorValidationStatus.Complete;
 1026270    }
 271
 272    private GridNavigationCorridorValidationStatus Fail(
 273        GridNavigationCorridorValidationStatus status)
 274    {
 26275        _portalWaypointCount = 0;
 26276        _geometricCost = default;
 26277        _hasCurrentPortal = false;
 26278        _status = status;
 26279        return status;
 280    }
 281
 282    private bool TryAccumulateDistance(Vector3d start, Vector3d end)
 283    {
 3081284        return Vector3d.TryGetDistance(start, end, out Fixed64 distance)
 3081285            && Fixed64.TryAdd(_geometricCost, distance, out _geometricCost);
 286    }
 287
 288}