Navigator

The NavigatorSystem provides a mechanism for navigating an entity on a 3D NavMesh. The Navigator component encapsulates the navigation behavior usually found in navigation components. The Navigator moves on a separate _navigation entity and uses its Transform3D component to calculate the position and movement. The _origin entity's Transform3D needs to be synchronized with the _navigation entity's Transform3D.

In other words the NavigatorSystem requires two entities:

• an origin entity which holds all the components, including the Navigator component, as well as the entity's logic; and,
• a navigation entity which is created by the Navigator component, holds the navigation related components and generates the input necessary for the MovementSystem to move the origin entity.

The Navigator component is primarily used in scenarios where the movement on the NavMesh plays a supportive role. For example for an AI, it generates input based on NavMesh pathfinding, but the actual movement is processed by MovementSystem.

The following diagram presents the components setup for an __origin entity (spider) and __navigation entity:

When using the Navigator component, there are few points to keep in mind:

• Only add the Navigator component to the origin entity.
• Do not use the NavMeshPathfinder, NavMeshSteeringAgent and NavMeshAvoidanceAgent components directly.
• To access the NavMesh related components and Transform3D, use the methods declared on the Navigator component.
  • GetNavMeshPathfinder()
  • GetNavMeshSteeringAgent()
  • GetNavMeshAvoidanceAgent()
  • GetTransform3D()
• Synchronization of the origin entity's position with navigation entity's Transform3D can be done automatically at start of the frame or manually.
• Synchronization of the navigation entity's position with the origin entity Transform3D is never done automatically.

The Navigator component contains these properties:

• NavMeshAgentConfig: reference to the NavMeshAgentConfig asset used to initialize the NavMeshPathfinder component.
• ManualTransformSynchronization: indicates whether to use automatic or manual Transform3D synchronization.
• MaxDistance: maximum distance between the navigation entity and the origin entity before the former is snapped back to the SnapBackDistance.
• SnapBackDistance: distance for snapping the navigation entity back.

Snapping the navigation entity back to the origin entity's position is necessary for correct navigation behavior. There might be situations where the navigation entity follows a path on the NavMesh but the origin entity cannot for some reason and remains stuck in a place.