NavMeshAgent Movement

Export

NavMeshAgent Movement converts a Unity NavMeshAgent path into input and rotation for Ultimate Character Locomotion. Use it for AI, point-and-click movement, or any character that should follow a baked NavMesh while retaining UCC collision, animation, abilities, and root motion.

The NavMeshAgent calculates the path, but Ultimate Character Locomotion moves the character. The ability keeps the agent synchronized with the character rather than allowing the agent to update the Transform directly.

Before you begin

  • Build an active NavMesh that includes the character’s starting position and intended destination.
  • Place the character on that NavMesh.
  • Ensure the character already has an Ultimate Character Locomotion component.
  • Add Jump and Fall if the agent should traverse jump links.

Add NavMeshAgent Movement

  1. Select the character GameObject.
  2. In the Ultimate Character Locomotion component, expand Abilities.
  3. Select the plus button and add NavMeshAgent Movement. Its required NavMeshAgent component is added when needed.
  4. Select the ability and keep Enabled selected, Start Type set to Automatic, and Stop Type set to Manual.
  5. If the character also uses Speed Change, drag Speed Change above NavMeshAgent Movement. Pathfinding Movement already applies the active multiplier when it writes the character input; placing Speed Change below it would multiply that input again.
  6. Configure Auto Enable, Rotation Override, Arrived Distance, airborne movement, and off-mesh link settings.
  7. Set a destination through gameplay code or another controlling system, then verify the path in Play Mode.

Choose destination and enable behavior

Auto Enable controls what happens when SetDestination is called on a disabled ability.

  • Keep it enabled when assigning a destination should enable the ability and NavMeshAgent automatically.
  • Disable it when another AI state or gameplay system owns ability activation. In this mode, a destination request fails while the ability is disabled.

SetDestination updates the destination of an active agent. If the ability is inactive, it enables the agent when allowed, verifies that the agent is on a NavMesh, sets the path, and starts the ability. The call returns whether the destination was accepted.

Arrived Distance is the remaining-distance threshold used by HasArrived and the stop check. The default is 0.2.

  • Increase it when the character only needs to approach the target or oscillates while trying to reach an exact point.
  • Decrease it when interactions require tighter placement, while leaving enough tolerance for the character collider and path resolution.

Choose rotation control

Rotation Override determines which system supplies facing while following the path:

  • No Override: use the NavMeshAgent’s updateRotation setting.
  • NavMesh: face along the NavMesh path even when agent rotation would otherwise be disabled.
  • Character: preserve the character’s own rotation so another movement type, look source, or ability can control facing.

Use SetDestinationRotation when the character should adopt a specific rotation after arriving. The ability continues to use path-facing behavior while it is still traveling.

Choose speed and airborne behavior

Pathfinding Movement reads an active Speed Change multiplier and applies it when writing the input vector. Keep Speed Change above this ability in the list so Speed Change does not process the generated input a second time.

For a root-motion character, the NavMeshAgent’s speed does not directly determine visible displacement. Use Speed Change and matching movement animations so the Animator selects the intended walking, running, or sneaking motion.

Allow Movement In Air is inherited from Pathfinding Movement:

  • Keep it enabled when the agent should continue supplying planar input while airborne.
  • Disable it when airborne abilities should own movement and rotation until the character lands.

NavMeshAgent Movement disables the agent’s automatic link traversal and coordinates supported links with UCC:

  • Manual Off Mesh Link Name identifies the NavMesh area used for a manually authored jump link. The default is Jump.
  • Enable Jump Across Manual Off Mesh Link when a manual link in that area should start the character’s Jump ability.
  • Built-in jump-across links can also start Jump. The ability waits when Fall is already active instead of starting another jump.
  • Drop-down links complete after the character becomes grounded.

Confirm the NavMesh link type, area name, and landing surface match the ability settings.

How NavMeshAgent Movement runs

The ability can start while its NavMeshAgent is on a NavMesh. Setting a destination supplies or updates the path, then the ability translates the agent’s desired velocity into the character’s two-dimensional input. Input larger than a magnitude of one is normalized, while smaller values are preserved so the character can slow near the destination.

Each update also computes the requested rotation. Ultimate Character Locomotion applies movement and collision, and the ability synchronizes NavMeshAgent.nextPosition to the resulting character position during Late Update. Near the destination, it limits final movement so the character does not repeatedly overshoot the target.

HasArrived becomes true when the path is no longer pending and the remaining distance is at or below Arrived Distance. The default stop type is manual, so reaching the destination does not by itself require the ability to disappear from the active list; the controlling AI can query arrival, assign another destination, stop the ability, or disable it.

Teleport, landing, death, and respawn events keep the NavMeshAgent position, links, and rotation state synchronized with the character.

Verify in Play Mode

  1. Confirm the character begins on the baked NavMesh and the NavMeshAgent is enabled.
  2. Keep the Ultimate Character Locomotion Inspector visible, assign a reachable destination, and confirm (Active) appears beside NavMeshAgent Movement.
  3. Confirm a path is created and the character follows it without the NavMeshAgent moving the Transform independently.
  4. Observe the character slowing or stopping within Arrived Distance, then confirm HasArrived reports true.
  5. Test each Rotation Override option used by the game and confirm the character faces from the intended source.
  6. Activate Speed Change with Speed Change above this ability and confirm the path input is scaled once.
  7. Traverse a configured jump or drop link and confirm Jump, Fall, landing, and path continuation occur in order.
  8. Teleport or respawn the character and confirm the NavMeshAgent resumes from the new position rather than the previous path position.

Troubleshoot NavMeshAgent Movement

  • SetDestination returns false: confirm the character and destination are on the baked NavMesh. If the ability is disabled, enable Auto Enable or enable the ability before the call.
  • The character has a destination but does not move: check that the NavMeshAgent has a valid, non-pending path, is not stopped, and is farther than Arrived Distance from the destination.
  • The character moves too fast when Speed Change is active: place Speed Change above NavMeshAgent Movement. The pathfinding base already applies its active multiplier.
  • Changing NavMeshAgent speed does not affect root-motion movement: configure Speed Change and movement animations with the required root-motion speed.
  • The character faces the wrong direction: choose the appropriate Rotation Override and check the NavMeshAgent’s updateRotation value when using No Override.
  • The agent will not cross a jump link: confirm Jump and Fall exist, Jump Across Manual Off Mesh Link is enabled when required, and Manual Off Mesh Link Name matches the link area.
  • Airborne input stops unexpectedly: enable Allow Movement In Air, or confirm that the intended airborne ability supplies its own movement.
  • The agent jitters near the target: increase Arrived Distance and confirm the destination is reachable at the character collider’s scale.
  • The agent returns to an old location after teleport or respawn: confirm the immediate-transform and respawn events reach the character’s UCC components.
  • Speed Change configures the active pathfinding speed multiplier and must remain above this ability.
  • Jump and Fall handle supported airborne link traversal.
  • Abilities explains list update order, automatic and manual activation, and runtime state.
  • Animator Controller explains movement blend trees and root-motion animation setup.

Developer reference

Retrieve the ability from UltimateCharacterLocomotion and call SetDestination. The method returns false when the disabled ability cannot auto-enable, the agent is not on a NavMesh, or the agent rejects the destination.

using UnityEngine;
using Opsive.UltimateCharacterController.Character;
using Opsive.UltimateCharacterController.Character.Abilities.AI;

public class MyObject : MonoBehaviour
{
    [Tooltip("The character whose NavMeshAgent Movement ability should receive the destination.")]
    [SerializeField] protected GameObject m_Character;
    [Tooltip("The NavMeshAgent destination.")]
    [SerializeField] protected Vector3 m_Destination;

    /// <summary>
    /// Sets the NavMeshAgentMovement destination.
    /// </summary>
    private void Start()
    {
        var characterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        var navMeshAgentMovement = characterLocomotion.GetAbility<NavMeshAgentMovement>();
        navMeshAgentMovement.SetDestination(m_Destination);
    }
}

The current runtime surface includes:

  • SetDestination(Vector3): sets or updates the path and returns whether it was accepted.
  • GetDestination(): returns the current destination.
  • HasArrived: reports a completed path inside Arrived Distance.
  • SetDestinationRotation(Quaternion): sets the desired facing at the destination.
  • Teleport(Vector3): warps the NavMeshAgent to a new position.
  • InputVector and DeltaRotation: expose the pathfinding output consumed by Ultimate Character Locomotion.
  • OnCharacterAbilityActive: tracks the active Speed Change multiplier.
  • OnCharacterImmediateTransformChange: warps the agent after a character teleport.
  • OnCharacterGrounded, OnDeath, and OnRespawn: synchronize links, agent rotation, and agent position with character state.