NavigationAgent3D

public bool AvoidanceEnabled { get; set; }

If true the agent is registered for an RVO avoidance callback on the NavigationServer3D. When NavigationAgent3D.Velocity is set and the processing is completed a safe_velocity Vector3 is received with a signal connection to NavigationAgent3D.VelocityComputed. Avoidance processing with many registered agents has a significant performance cost and should only be enabled on agents that currently require it.

public uint AvoidanceLayers { get; set; }

A bitfield determining the avoidance layers for this NavigationAgent. Other agents with a matching bit on the NavigationAgent3D.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 NavigationAgent3D.AvoidanceLayers.

public float AvoidancePriority { get; set; }

The agent does not adjust the velocity for other agents that would match the NavigationAgent3D.AvoidanceMask but have a lower NavigationAgent3D.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 NavigationAgent3D.DebugUseCustom is true uses this color for this agent instead of global color.

public float DebugPathCustomPointSize { get; set; }

If NavigationAgent3D.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 NavigationAgent3D.DebugPathCustomColor for this agent instead of global color.

public float Height { get; set; }

The height of the avoidance agent. Agents will ignore other agents or obstacles that are above or below their current position + height in 2D avoidance. Does nothing in 3D avoidance which uses radius spheres alone.

public bool KeepYVelocity { get; set; }

If true, and the agent uses 2D avoidance, it will remember the set y-axis velocity and reapply it after the avoidance step. While 2D avoidance has no y-axis and simulates on a flat plane this setting can help to soften the most obvious clipping on uneven 3D geometry.

public int MaxNeighbors { get; set; }

The maximum number of neighbors for the agent to consider.

public float MaxSpeed { get; set; }

The maximum speed that an agent can move.

public uint NavigationLayers { get; set; }

A bitfield determining which navigation layers of navigation regions this agent will use to calculate a path. Changing it during runtime will clear the current navigation path and generate a new one, according to the new navigation layers.

public float NeighborDistance { get; set; }

The distance to search for other agents.

public float PathDesiredDistance { get; set; }

Tolerance for approaching the next point. Align scale, speed and body-origin height with the path surface; too small a value can prevent waypoint progression.

public float PathHeightOffset { get; set; }

Offset subtracted on Y from points returned by GetNextPathPosition and GetFinalPosition. Setting 1 lowered the checked endpoint by 1. Does not change a physics collider or rebake geometry.

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 NavigationPathQueryParameters3D.PathMetadataFlags PathMetadataFlags { get; set; }

Additional information to return with the navigation path.

public NavigationPathQueryParameters3D.PathPostProcessing PathPostprocessing { get; set; }

The path postprocessing applied to the raw path corridor found by the NavigationAgent3D.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 NavigationAgent3D.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 NavigationPathQueryParameters3D.PathfindingAlgorithmEnum PathfindingAlgorithm { get; set; }

The pathfinding algorithm used in the path query.

public float Radius { get; set; }

The radius of the avoidance agent. This is the "body" of the avoidance agent and not the avoidance maneuver starting radius (which is controlled by NavigationAgent3D.NeighborDistance). Does not affect normal pathfinding. To change an actor's pathfinding radius bake NavigationMesh resources with a different NavigationMesh.AgentRadius property and use different navigation maps for each actor 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 NavigationAgent3D.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. The distance check is three-dimensional: body-origin vertical offset matters too.

public Vector3 TargetPosition { get; set; }

Global 3D agent goal. Assignment requests a new path even for the same position; avoid repeating it every frame without a reason. The agent does not move the body itself.

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 bool Use3DAvoidance { get; set; }

If true, the agent calculates avoidance velocities in 3D omnidirectionally, e.g. for games that take place in air, underwater or space. Agents using 3D avoidance only avoid other agents using 3D avoidance, and react to radius-based avoidance obstacles. They ignore any vertex-based obstacles. If false, the agent calculates avoidance velocities in 2D along the x and z-axes, ignoring the y-axis. Agents using 2D avoidance only avoid other agents using 2D avoidance, and react to radius-based avoidance obstacles or vertex-based avoidance obstacles. Other agents using 2D avoidance that are below or above their current position including NavigationAgent3D.Height are ignored.

public Vector3 Velocity { get; set; }

Sets the new wanted velocity for the agent. The avoidance simulation will try to fulfill this velocity if possible but will modify it to avoid collision with other agents and obstacles. When an agent is teleported to a new position, use NavigationAgent3D.SetVelocityForced as well to reset the internal simulation velocity.

public float DistanceToTarget();

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

public bool GetAvoidanceLayerValue(int layerNumber);

Returns whether or not the specified layer of the NavigationAgent3D.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 NavigationAgent3D.AvoidanceMask bitmask is enabled, given a mask_number between 1 and 32.

public Vector3[] GetCurrentNavigationPath();

Reads current path points rather than moving the parent. A complete physics example checks map geometry and the floor separately.

public int GetCurrentNavigationPathIndex();

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

public NavigationPathQueryResult3D GetCurrentNavigationResult();

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

public Vector3 GetFinalPosition();

Updates navigation and reads the current path endpoint. An unreachable goal can leave it at an accessible boundary.

public bool GetNavigationLayerValue(int layerNumber);

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

public Rid GetNavigationMap();

Reads the assigned agent map, or its valid parent world map without an explicit assignment. Does not establish polygon readiness.

public Vector3 GetNextPathPosition();

Updates navigation and returns the next point for your movement code. Use in the physics loop while the route is unfinished; this does not command body movement.

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 NavigationServer3D.

public bool IsNavigationFinished();

Updates state and checks current-route completion. This differs from reaching the original goal: the checked partial route finished without IsTargetReached.

public bool IsTargetReachable();

Updates navigation and compares its endpoint with the goal using TargetDesiredDistance. Does not check physical passage through walls.

public bool IsTargetReached();

Reads the stored original-goal arrival state. Path-following updates set it using TargetDesiredDistance.

public void SetAvoidanceLayerValue(int layerNumber, bool value);

Based on value, enables or disables the specified layer in the NavigationAgent3D.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 NavigationAgent3D.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 NavigationAgent3D.NavigationLayers bitmask, given a layer_number between 1 and 32.

public void SetNavigationMap(Rid navigationMap);

Sets the Entity explicit query map and submits assignment for the server agent. Requests a new route with an active goal; wait for the server change to be processed.

public void SetVelocityForced(Vector3 velocity);

Replaces the internal velocity in the collision avoidance simulation with NavigationAgent3D.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 NavigationAgent3D.LinkReachedEventHandler LinkReached;

Signals that the agent reached a navigation link. Emitted when the agent moves within NavigationAgent3D.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 NavigationAgent3D.PathMetadataFlags:

• position: The start position of the link that was reached.
• type: Always NavigationPathQueryResult3D.PathSegmentType.Link.
• rid: The Rid of the link.
• owner: The object which manages the link (usually NavigationLink3D).
• link_entry_position: If owner is available and the owner is a NavigationLink3D, 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 NavigationLink3D, 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 NavigationAgent3D.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 NavigationAgent3D.PathMaxDistance.

public event Action TargetReached;

Signals that the agent reached the target, i.e. the agent moved within NavigationAgent3D.TargetDesiredDistance of the NavigationAgent3D.TargetPosition. This signal is emitted only once per loaded path. This signal will be emitted just before NavigationAgent3D.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 NavigationAgent3D.GetFinalPosition.

public event NavigationAgent3D.VelocityComputedEventHandler VelocityComputed;

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

public event NavigationAgent3D.WaypointReachedEventHandler WaypointReached;

Signals that the agent reached a waypoint. Emitted when the agent moves within NavigationAgent3D.PathDesiredDistance of the next position of the path. The details dictionary may contain the following keys depending on the value of NavigationAgent3D.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).