Nav3DPath

The Nav3DPath class performs pathfinding in scene space. Agents (Nav3DAgent) use it internally, but you can also use it directly. Working with Nav3DPath is only possible after Nav3D has been initialized.

In 2.0.0, pathfinding is performed internally by a single A* search over the unified global octree (previously each obstacle octree was searched separately). The public Nav3DPath API below is unchanged, and the existing path-update behavior — Update(), the AutoUpdatePath agent option, and the OnPathUpdated event — works exactly as in 1.x.

Nav3DPathfindingManager

Contains properties to manage pathfinding task limits:

• public static int CurrentPathfindingTasksCount — how many parallel pathfinding tasks are currently active.
• public static int MaxPathfindingTasks — the ceiling on simultaneous pathfinding tasks. Default: Environment.ProcessorCount − 1; values below 1 are clamped to 1. With Adaptive Concurrency off, this is exactly how many searches may run at once, and you may change it at any time. With it on, the adaptive limit works underneath this ceiling and owns the live number, so the ceiling is fixed while it is on: a write is refused with a warning and changes nothing. Set Max Concurrent Searches on the Nav3DWorldSettings asset before initialization, or turn Adaptive Concurrency off, to drive it yourself.

Nav3DPath: Pathfinding

To perform pathfinding:

1. Create a Nav3DPath instance: new Nav3DPath().
2. Call one of the Find(…) overloads.

Find between two points:

public Task<PathfindingResult> Find(
    Vector3 _Start,
    Vector3 _End,
    bool    _Smooth      = false,
    int     _SmoothRatio = 3,
    Action<PathfindingResult> _OnSuccess = null,
    Action<PathfindingResult> _OnFail    = null,
    float _Radius = 0f,
    VolumetricPathfindingMode _VolumetricMode = VolumetricPathfindingMode.STRICT)

• _Start / _End — start and end points.
• _Smooth — whether to smooth the path.
• _SmoothRatio — number of smoothing samples per minimum pathfinding graph volume.
• _OnSuccess / _OnFail — success and failure callbacks. _Radius — clearance radius the path must keep from obstacles (volumetric pathfinding); 0 = classic point pathfinding. _VolumetricMode — behavior when no wide-enough corridor exists (ignored when _Radius is 0). New in 3.0.0

Find through more than two points:

public Task<PathfindingResult> Find(
    Vector3[] _Targets,
    bool      _Loop,
    bool      _SkipUnpassableTargets = false,
    bool      _Smooth                = false,
    int       _SmoothRatio           = 3,
    Action<PathfindingResult> _OnSuccess = null,
    Action<PathfindingResult> _OnFail    = null,
    bool      _UpdatePathSilently        = false,
    float _Radius = 0f,
    VolumetricPathfindingMode _VolumetricMode = VolumetricPathfindingMode.STRICT)

• _Targets — points the path should pass through.
• _Loop — connect the end and start points so the path forms a loop.
• _SkipUnpassableTargets — if false, a failure between any pair of points aborts pathfinding and calls _OnFail.
• Other parameters as above. _Radius — clearance radius the path must keep from obstacles (volumetric pathfinding); 0 = classic point pathfinding. _VolumetricMode — behavior when no wide-enough corridor exists (ignored when _Radius is 0). New in 3.0.0

Find using a PathfindingRequest:

public Task<PathfindingResult> Find(
    PathfindingRequest _Request,
    Action<PathfindingResult> _OnSuccess = null,
    Action<PathfindingResult> _OnFail    = null,
    bool _UpdatePathSilently = false)

You can repeat the last pathfinding (e.g. when the scene changed and the last path is no longer relevant) by calling Update().

Nav3DPath: Properties

• bool IsValid — whether the last pathfinding was successful.
• bool IsPathfindingInProgress — whether pathfinding is currently in progress.
• Vector3[] Trajectory — the last found path trajectory (check IsValid first).
• Bounds Bounds — the volume occupied by the found path.
• PathfindingResult PathfindingResult — the result of the last successful pathfinding.
• bool IsDegraded — true when the current trajectory was delivered by the fallback mode dropping the clearance constraint. New in 3.0.0
• bool IsTimedOut — true when the current trajectory was delivered after the timeout passed: valid, its refinement cut short, so possibly longer than the optimum. New in 3.0.0
• float CertifiedRadius — the clearance radius the current trajectory is certified with: a capsule of this radius along the trajectory was free of obstacles when the search answered. 0 = no promise (point search or degraded fallback). New in 3.0.0

Nav3DPath: Events

• event Action<PathfindingResult> OnPathfindingSuccess — pathfinding finished successfully.
• event Action<PathfindingResult> OnPathfindingFail — pathfinding failed.
• event Action<PathfindingResult> OnPathfindingComplete — triggers in both cases.

Nav3DPath: Dispose

Call Dispose() when you finish working with a Nav3DPath instance. Each initialized path consumes resources to track intersections with newly added obstacles; Dispose() unsubscribes it from obstacle storage updates.

PathfindingRequest

A container for pathfinding parameters for an arbitrary number of target points:

• Vector3[] Points — target points the path should pass through.
• bool Loop — loop movement through the points (move to the first again after the last).
• bool SkipUnpassableTargets — skip any point pathfinding to which failed; if disabled, a failure aborts pathfinding and calls _OnFail.
• bool TryRepositionStartIfOccupied — try to start from the nearest free cell if the start point is occupied; otherwise the search fails.
• bool TryRepositionTargetIfOccupied — try to path to the nearest free cell if the target point is occupied; otherwise the search fails.
• int Timeout — maximum time in milliseconds for the search; what a timeout does depends on TimeoutMode.
• PathfindingTimeoutMode TimeoutMode — what to do when Timeout passes after a complete route was already found: DELIVER_FOUND_ROUTE (the default) delivers that route flagged TimedOut, FAIL fails the request with TIMEOUT. A timeout with no complete route found fails in both modes. New in 3.0.0
• bool Smooth — whether to smooth the path.
• int SmoothRatio — smoothing segments per minimum cell volume.
• string RequesterID — ID of the requesting entity (internal; may be left blank).
• float Radius — the clearance radius the path must keep from obstacles (volumetric pathfinding). 0 (default) = classic point pathfinding. New in 3.0.0
• VolumetricPathfindingMode VolumetricMode — behavior when no corridor wide enough for the radius exists (ignored when Radius is 0). New in 3.0.0
• float MaxCertifiedRadius — the clearance-certification cap: on a successful volumetric search the delivered trajectory is additionally measured for the largest radius in [Radius, MaxCertifiedRadius] it actually keeps clear, recorded in PathfindingResult.CertifiedRadius. Measurement only — the route itself is always searched at Radius, so setting this never changes which path is found. 0 (default) = certify at Radius exactly. New in 3.0.0

PathfindingRequest is a record, so you can copy an instance and override a few parameters:

PathfindingRequest request = new PathfindingRequest(
    _Points: new Vector3[] { new(-1, 1.5f, 3), new(2, 3f, 5.25f), new(1, 5, 4) },
    _Loop: true, _SkipUnpassableTargets: false,
    _TryRepositionStartIfOccupied: false, _TryRepositionTargetIfOccupied: false,
    _Timeout: 3500, _Smooth: true, _SmoothRatio: 4);

PathfindingRequest anotherRequest = request with {
    Points = new Vector3[] { new(2, 7, 5), new(2.5f, -1, 4) },
    Loop = false,
};

PathfindingResult

Contains pathfinding data and time statistics.

Time statistics:

• TimeSpan PathfindingDuration — duration of the A* execution.
• TimeSpan OptimizingDuration — duration of the optimization algorithm.
• TimeSpan SmoothingDuration — duration of the smoothing algorithm.

Pathfinding data:

• Vector3[] PathRaw — the raw path from A*.
• Vector3[] PathOptimized — the path after optimization.
• Vector3[] PathFinal — the path after smoothing (equals PathOptimized if Smooth = false).
• int[] TargetIndices — indices of the target points within PathFinal.
• PathfindingResultCode Result — result code (see below).
• bool Failed — whether pathfinding failed.
• string ErrorMessage — error info if pathfinding failed.
• bool Degraded — true when this result was delivered by the FALLBACK_TO_DEFAULT mode dropping the volumetric clearance constraint (the request had a positive Radius, the trajectory is a point path). New in 3.0.0
• bool TimedOut — true when the timeout passed after a complete route was found and TimeoutMode delivered it: the route is valid, but the refinement that was running was skipped, so it may be longer than the optimum. New in 3.0.0
• float CertifiedRadius — the clearance radius the delivered trajectory is certified with (see “Certified clearance”): equals the request Radius for a volumetric success, may exceed it up to MaxCertifiedRadius when the route runs wider, and is 0 for point searches and degraded fallbacks. New in 3.0.0

PathfindingResultCode values:

Value	Description
SUCCEEDED	Pathfinding finished successfully.
PATH_DOES_NOT_EXIST	There is no path between the points (e.g. a point is surrounded on all sides).
TIMEOUT	No complete route was found within the allowed time (or the request’s TimeoutMode is FAIL); the search was aborted.
CANCELLED	Pathfinding was cancelled by the user or by Nav3D internal logic.
START_POINT_INSIDE_OBSTACLE	Cancelled because the start point is inside an obstacle.
TARGET_POINT_INSIDE_OBSTACLE	Cancelled because the target point is inside an obstacle.
UNKNOWN	Internal error.
START_POINT_TOO_NARROW [NEW in 3.0.0]	The start point is in free space, but an agent of the requested radius does not fit there (occupied space closer than the radius). Volumetric pathfinding only.
TARGET_POINT_TOO_NARROW [NEW in 3.0.0]	The same for the target point. Volumetric pathfinding only.

Usage example

using Nav3D.API;
using System;
using System.Linq;
using UnityEngine;

class YourGameScenario : MonoBehaviour
{
    Vector3[] m_FoundPath;

    void Start()
    {
        Nav3DManager.OnNav3DInit += () =>
        {
            Vector3 a = new Vector3(-10, -10, -10);
            Vector3 b = new Vector3(10, 10, 10);
            FindPath(a, b, PrintPath);
        };
    }

    void OnDrawGizmos()
    {
        if (!Application.isPlaying || !enabled) return;
        if (m_FoundPath != null && m_FoundPath.Any())
            for (int i = 0; i < m_FoundPath.Length - 1; i++)
                Gizmos.DrawLine(m_FoundPath[i], m_FoundPath[i + 1]);
    }

    void FindPath(Vector3 _A, Vector3 _B, Action<Vector3[]> _OnPathFound)
    {
        Nav3DPath path = new Nav3DPath(gameObject.name);
        path.Find(_A, _B, _OnSuccess: () =>
        {
            Debug.Log("Path successfully found!");
            _OnPathFound(path.Trajectory);
            path.Dispose();
        });
    }

    void PrintPath(Vector3[] _Path)
    {
        m_FoundPath = _Path;
        Debug.Log($"Path points: {string.Join(", ", m_FoundPath)}");
    }
}