NavigationAgent2D

public bool AvoidanceEnabled { get; set; }

Enables avoidance computation. Submit desired Velocity and apply VelocityComputed output to the body. The flag does not move it or guarantee avoiding every obstacle.

public uint AvoidanceLayers { get; set; }

A bitfield determining the avoidance layers for this NavigationAgent. Other agents with a matching bit on the NavigationAgent2D.AvoidanceMask will avoid this agent.

public uint AvoidanceMask { get; set; }

A bitfield determining what other avoidance agents and obstacles this NavigationAgent will avoid when a bit matches at least one of their NavigationAgent2D.AvoidanceLayers.

public float AvoidancePriority { get; set; }

The agent does not adjust the velocity for other agents that would match the NavigationAgent2D.AvoidanceMask but have a lower NavigationAgent2D.AvoidancePriority. This in turn makes the other agents with lower priority adjust their velocities even more to avoid collision with this agent.

public bool DebugEnabled { get; set; }

If true shows debug visuals for this agent.

public Color DebugPathCustomColor { get; set; }

If NavigationAgent2D.DebugUseCustom is true uses this color for this agent instead of global color.

public float DebugPathCustomLineWidth { get; set; }

If NavigationAgent2D.DebugUseCustom is true uses this line width for rendering paths for this agent instead of global line width.

public float DebugPathCustomPointSize { get; set; }

If NavigationAgent2D.DebugUseCustom is true uses this rasterized point size for rendering path points for this agent instead of global point size.

public bool DebugUseCustom { get; set; }

If true uses the defined NavigationAgent2D.DebugPathCustomColor for this agent instead of global color.

public int MaxNeighbors { get; set; }

The maximum number of neighbors for the agent to consider.

public float MaxSpeed { get; set; }

Avoidance-computation speed limit. Align it with the body desired speed; changing this property does not automatically move the body.

public uint NavigationLayers { get; set; }

Mask of surfaces and links for the agent route. Any shared bit admits a region; this is not an all-keys condition. Changing it with an active goal requests a new path, as checked with 1 → 0 → 1.

public float NeighborDistance { get; set; }

The distance to search for other agents.

public float PathDesiredDistance { get; set; }

Distance tolerance for approaching the next waypoint in map units. Tune for speed and physics step: too small a tolerance can cause overshooting and backtracking.

public float PathMaxDistance { get; set; }

The maximum distance the agent is allowed away from the ideal path to the final position. This can happen due to trying to avoid collisions. When the maximum distance is exceeded, it recalculates the ideal path.

public NavigationPathQueryParameters2D.PathMetadataFlags PathMetadataFlags { get; set; }

Additional information to return with the navigation path.

public NavigationPathQueryParameters2D.PathPostProcessing PathPostprocessing { get; set; }

The path postprocessing applied to the raw path corridor found by the NavigationAgent2D.PathfindingAlgorithm.

public float PathReturnMaxLength { get; set; }

The maximum allowed length of the returned path in world units. A path will be clipped when going over this length.

public float PathReturnMaxRadius { get; set; }

The maximum allowed radius in world units that the returned path can be from the path start. The path will be clipped when going over this radius. Compared to NavigationAgent2D.PathReturnMaxLength, this allows the agent to go that much further, if they need to walk around a corner. Note: This will perform a sphere clip considering only the actual navigation mesh path points with the first path position being the sphere's center.

public float PathSearchMaxDistance { get; set; }

The maximum distance a searched polygon can be away from the start polygon before the pathfinding cancels the search for a path to the (possibly unreachable or very far away) target position polygon. In this case the pathfinding resets and builds a path from the start polygon to the polygon that was found closest to the target position so far. A value of 0 or below counts as unlimited. In case of unlimited the pathfinding will search all polygons connected with the start polygon until either the target position polygon is found or all available polygon search options are exhausted.

public int PathSearchMaxPolygons { get; set; }

The maximum number of polygons that are searched before the pathfinding cancels the search for a path to the (possibly unreachable or very far away) target position polygon. In this case the pathfinding resets and builds a path from the start polygon to the polygon that was found closest to the target position so far. A value of 0 or below counts as unlimited. In case of unlimited the pathfinding will search all polygons connected with the start polygon until either the target position polygon is found or all available polygon search options are exhausted.

public NavigationPathQueryParameters2D.PathfindingAlgorithmEnum PathfindingAlgorithm { get; set; }

The pathfinding algorithm used in the path query.

public float Radius { get; set; }

Agent circle radius for avoidance. Does not change a physics collider or rebake navigation geometry for a different character size.

public float SimplifyEpsilon { get; set; }

The path simplification amount in world units.

public bool SimplifyPath { get; set; }

If true a simplified version of the path will be returned with less critical path points removed. The simplification amount is controlled by NavigationAgent2D.SimplifyEpsilon. The simplification uses a variant of Ramer-Douglas-Peucker algorithm for curve point decimation. Path simplification can be helpful to mitigate various path following issues that can arise with certain agent types and script behaviors. E.g. "steering" agents or avoidance in "open fields".

public float TargetDesiredDistance { get; set; }

Tolerance for reaching the original goal and comparing the found endpoint against it. A large value may finish a route earlier than intended.

public Vector2 TargetPosition { get; set; }

Global agent goal. Assignment requests a new route; avoid assigning the same goal every frame without a reason. The agent does not automatically move its parent.

public float TimeHorizonAgents { get; set; }

The minimal amount of time for which this agent's velocities, that are computed with the collision avoidance algorithm, are safe with respect to other agents. The larger the number, the sooner the agent will respond to other agents, but less freedom in choosing its velocities. A too high value will slow down agent movement considerably. Must be positive.

public float TimeHorizonObstacles { get; set; }

The minimal amount of time for which this agent's velocities, that are computed with the collision avoidance algorithm, are safe with respect to static avoidance obstacles. The larger the number, the sooner the agent will respond to static avoidance obstacles, but less freedom in choosing its velocities. A too high value will slow down agent movement considerably. Must be positive.

public Vector2 Velocity { get; set; }

Desired avoidance velocity in map units per second. Do not multiply it by delta when subsequently supplying it to CharacterBody2D.MoveAndSlide. Computed velocity arrives through VelocityComputed.

public float DistanceToTarget();

Returns the distance to the target position, using the agent's global position. The user must set NavigationAgent2D.TargetPosition in order for this to be accurate.

public bool GetAvoidanceLayerValue(int layerNumber);

Returns whether or not the specified layer of the NavigationAgent2D.AvoidanceLayers bitmask is enabled, given a layer_number between 1 and 32.

public bool GetAvoidanceMaskValue(int maskNumber);

Returns whether or not the specified mask of the NavigationAgent2D.AvoidanceMask bitmask is enabled, given a mask_number between 1 and 32.

public Vector2[] GetCurrentNavigationPath();

Reads the agent current path array. Does not move the body; points may end at an accessible boundary rather than the original goal.

public int GetCurrentNavigationPathIndex();

Returns which index the agent is currently on in the navigation path's Vector2[].

public NavigationPathQueryResult2D GetCurrentNavigationResult();

Returns the path query result for the path the agent is currently following.

public Vector2 GetFinalPosition();

Updates navigation and returns the current path endpoint, which may differ from the original goal.

public bool GetNavigationLayerValue(int layerNumber);

Returns whether or not the specified layer of the NavigationAgent2D.NavigationLayers bitmask is enabled, given a layer_number between 1 and 32.

public uint GetNavigationLayers();

Reads the agent query mask. Does not describe body size or avoidance radius.

public Rid GetNavigationMap();

Returns the explicitly assigned agent map or, without one, its valid parent world map. The locally assigned Entity map can change before the server queue is processed.

public Vector2 GetNextPathPosition();

Updates agent state and returns the next point. Use it in the physics loop for your own parent movement; stop following after route completion.

public float GetPathLength();

Returns the length of the currently calculated path. The returned value is 0.0, if the path is still calculating or no calculation has been requested yet.

public Rid GetRid();

Returns the Rid of this agent on the NavigationServer2D.

public bool IsNavigationFinished();

Updates navigation state and reports whether the current route finished. A partial path can finish too: check IsTargetReached separately.

public bool IsTargetReachable();

Updates navigation and compares the found endpoint with the goal using TargetDesiredDistance. Check that a current path exists; this does not guarantee physical-body traversal through the level.

public bool IsTargetReached();

Reads the stored goal-reached state using TargetDesiredDistance. Path-following logic updates it; this is not a direct physics reachability test.

public void SetAvoidanceLayerValue(int layerNumber, bool value);

Based on value, enables or disables the specified layer in the NavigationAgent2D.AvoidanceLayers bitmask, given a layer_number between 1 and 32.

public void SetAvoidanceMaskValue(int maskNumber, bool value);

Based on value, enables or disables the specified mask in the NavigationAgent2D.AvoidanceMask bitmask, given a mask_number between 1 and 32.

public void SetNavigationLayerValue(int layerNumber, bool value);

Based on value, enables or disables the specified layer in the NavigationAgent2D.NavigationLayers bitmask, given a layer_number between 1 and 32.

public void SetNavigationLayers(uint navigationLayers);

Mask of surfaces and links for the agent route. Any shared bit admits a region; this is not an all-keys condition. Changing it with an active goal requests a new path, as checked with 1 → 0 → 1.

public void SetNavigationMap(Rid navigationMap);

Assigns the agent Entity query map and submits a map change for its server agent. With an active goal, resets the current result for a new search. This is not geometry-only switching: account for map-isolated avoidance.

public void SetVelocityForced(Vector2 velocity);

Replaces the internal velocity in the collision avoidance simulation with NavigationAgent2D.Velocity. When an agent is teleported to a new position this function should be used in the same frame. If called frequently this function can get agents stuck.

public event NavigationAgent2D.LinkReachedEventHandler LinkReached;

Signals that the agent reached a navigation link. Emitted when the agent moves within NavigationAgent2D.PathDesiredDistance of the next position of the path when that position is a navigation link. The details dictionary may contain the following keys depending on the value of NavigationAgent2D.PathMetadataFlags:

• position: The start position of the link that was reached.
• type: Always NavigationPathQueryResult2D.PathSegmentType.Link.
• rid: The Rid of the link.
• owner: The object which manages the link (usually NavigationLink2D).
• link_entry_position: If owner is available and the owner is a NavigationLink2D, it will contain the global position of the link's point the agent is entering.
• link_exit_position: If owner is available and the owner is a NavigationLink2D, it will contain the global position of the link's point which the agent is exiting.

public event Action NavigationFinished;

Signals that the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. This signal is emitted only once per loaded path. This signal will be emitted just after NavigationAgent2D.TargetReached when the target is reachable.

public event Action PathChanged;

Emitted when the agent had to update the loaded path:

• because path was previously empty.
• because navigation map has changed.
• because agent pushed further away from the current path segment than the NavigationAgent2D.PathMaxDistance.

public event Action TargetReached;

Signals that the agent reached the target, i.e. the agent moved within NavigationAgent2D.TargetDesiredDistance of the NavigationAgent2D.TargetPosition. This signal is emitted only once per loaded path. This signal will be emitted just before NavigationAgent2D.NavigationFinished when the target is reachable. It may not always be possible to reach the target but it should always be possible to reach the final position. See NavigationAgent2D.GetFinalPosition.

public event NavigationAgent2D.VelocityComputedEventHandler VelocityComputed;

Notifies when the collision avoidance velocity is calculated. Emitted every update as long as NavigationAgent2D.AvoidanceEnabled is true and the agent has a navigation map.

public event NavigationAgent2D.WaypointReachedEventHandler WaypointReached;

Signals that the agent reached a waypoint. Emitted when the agent moves within NavigationAgent2D.PathDesiredDistance of the next position of the path. The details dictionary may contain the following keys depending on the value of NavigationAgent2D.PathMetadataFlags:

• position: The position of the waypoint that was reached.
• type: The type of navigation primitive (region or link) that contains this waypoint.
• rid: The Rid of the containing navigation primitive (region or link).
• owner: The object which manages the containing navigation primitive (region or link).