NavLocation

Description

A world position that is guaranteed to be on the navigation data, either on a NavMesh surface or on a link.

The NavLocation stores that position together with the NavNode of the node containing it, which is either a polygon of a NavMesh surface or a link. Using NavLocations with NavWorld operations removes the need to project the desired world position onto the NavMesh at the beginning of each operation.

A NavLocation can be invalid in the following scenarios:

1. When it has been created empty, instead of being the result of a NavWorld operation.
2. When a NavWorld.MapLocation call finds no polygon that matches the requested position, extents, agent type, or area mask.
3. When the NavMesh has been removed or modified at the indicated position or in its close vicinity.

If a NavMeshObstacle carving the NavMesh in its vicinity makes a NavLocation invalid, the NavLocation returns to a valid state once all NavMeshObstacle objects stop carving the NavMesh tile where the NavLocation is. This is because removing all NavMeshObstacle objects restores the NavMesh to its original form without regenerating it.

Additional resources: NavWorld.MapLocation, NavWorld.IsValid, NavNode, NavNodeType

using UnityEngine;
using UnityEngine.AI;
using Unity.AI.Navigation.LowLevel;

public class NavLocationExample : MonoBehaviour
{
    public Transform target;

    void Update()
    {
        using NavWorld world = NavWorld.GetDefaultWorld();

        // Obtain a NavLocation by projecting a world position onto the NavMesh.
        NavLocation here = world.MapLocation(transform.position, Vector3.one, 0);
        if (!world.IsValid(here))
            return;

        // The location pairs a snapped world position with the node that owns it.
        Debug.DrawLine(transform.position, here.position, Color.green);

        // Pass the same NavLocation to other NavWorld operations without re-projecting.
        NavLocation reached = world.MoveLocation(here, target.position, NavMesh.AllAreas);
        Debug.DrawLine(here.position, reached.position, Color.cyan);
    }
}

Properties

Public Methods

Operators