AI Navigation Component

The AI Navigation component (plAiNavigationComponent) finds a path on a runtime navmesh and steers its owner toward a world-space destination. It supports crowd avoidance, character-controller movement, root-motion integration, and off-mesh links.

Set up a character

1. Verify the scene with a Navmesh Path Test.
2. Add AI Navigation to the character's moving game object, with its origin at the feet. Select the same NavmeshConfig and PathSearchConfig as the successful test.
3. Choose a MovementMode and configure the ground-query CollisionLayer.
4. Call SetDestination(destination, allowPartialPaths) from gameplay code or use an Ai Navigate To state.
5. Enable PrintState, VisPathLine, and VisTarget in DebugFlags while testing.

With partial paths disabled, an unreachable destination produces Failed. With them enabled, the agent may travel only as far as the available route allows. Moving includes waiting for path computation; it does not guarantee visible movement every frame.

Movement modes

Mode	Setup and behavior
DirectTransform	Writes the owner's position and rotation. Set ApplySteering to false to read the computed steering transform and apply movement yourself.
PhysicsCharacter	Sends plMsgMoveCharacterController to the owner. Add a compatible character controller and match CCWalkSpeed, CCRunSpeed, and CCRotateSpeed to its settings.
RootMotion	Writes normalized movement intent to the MoveForwards blackboard entry, applies steering rotation, and corrects positional drift. Requires a shared blackboard and animation setup that actually applies root motion.

ApplySteering controls transform application in DirectTransform mode; it is not a global disable switch for the other modes. Root-motion correction is controlled by AI.Navigation.DriftCorrection.

In direct and root-motion modes, physics queries place the feet on solid ground. FootRadius is the ground-query footprint, not the body radius used for avoidance. Keep it wide enough to span small floor gaps but narrow enough to avoid hovering beside ledges. PhysicsCharacter delegates ground contact to the character controller.

Crowd avoidance

CrowdAvoidance enables local steering around registered agents. AgentRadius defines the body footprint and AvoidanceQuality controls the cost of the avoidance calculation. Navigation components register themselves; add an AI Crowd Agent component to the player or another object that moves through input, physics, or animation. That component exposes Radius and makes the object visible to avoidance without moving it.

Crowd steering and the navmesh agent radius solve different problems: the navmesh radius determines clearance from level geometry; the component radius determines clearance between moving agents. Avoidance does not replace physical collision handling.

Component properties

Property	Purpose
NavmeshConfig, PathSearchConfig	Walkable geometry configuration and ground-type permissions/costs.
Speed	Target movement speed.
Acceleration, Deceleration	How quickly movement accelerates and brakes.
ReachedDistance	Distance at which the destination counts as reached.
FootRadius, CollisionLayer, FallHeight	Ground detection and the distance below the feet that counts as falling.
CrowdAvoidance, AgentRadius, AvoidanceQuality	Local avoidance settings.
MovementMode, ApplySteering	How computed movement is applied; see the modes above.
CCWalkSpeed, CCRunSpeed, CCRotateSpeed	Character-controller settings used to convert desired velocity into controller input.
LinkTraverseSpeed	Speed of built-in off-mesh link traversal.
DebugFlags	PrintState, VisPathCorridor, VisPathLine, and VisTarget.

Exposed functions and states

• SetDestination starts navigation; CancelNavigation cancels it. Cancellation does not cancel an ongoing fall.
• StopWalking(withinDistance) requests stopping within the supplied distance.
• TurnTowards and GetTurnAngleTowards operate on a world-space XY target.
• EnsureNavMeshSectorAvailable(center, radius) requests an area and returns whether it is ready. Retry on a later frame when false.
• FindRandomPointAroundCircle and RaycastNavMesh query the navmesh. A random point can fall outside the requested circle when a large polygon overlaps it.
• GetSteeringPosition and GetSteeringRotation expose the computed transform.
• FinishLinkTraversal resumes navigation after game code finishes a link traversal.

GetState() reports Idle, Moving, Turning, Falling, Fallen, Failed, or TraversingLink. Fallen means an airborne character has landed; it is not the destination-reached state. Failure reporting does not distinguish every cause, so use the path test and debugging tools to inspect geometry and route availability.

See also

• Runtime Navmesh
• Navigation Tools
• AI Behavior