Nav3DAgentDescription

Nav3DAgentDescription

Nav3DAgentDescription

serves as a description of the agent and allows you to customize its behavior and all necessary parameters.
This class inherits from ScriptableObject, so you can create an instance of it through the context menu of the Project tab.


After creating a description, in its inspector you will see the following list of parameter groups:

The “Set default parameters” button will speed up the configuration of all parameters by setting their default values.

Here is an explanation of the purpose of the parameters and their allowable values.


Behavior


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Behavior TypeBehavior Typeenum BehaviorTypeDEFAULT, YIELDING, INDIFFERENT

Describes the type of agent behavior:

  • The agent can behave in a standard way (DEFAULT), i.e. search for a path, then follow it, or follow any other user instructions. The agent’s behavior will be completely determined by its description.
  • The agent may have yielding behavior (YIELDING). It will not be able to execute user commands and will not have its own tasks.
    (An exception will be thrown if you try to call methods to go to the target.) His only concern will be to make way for agents nearby. It will interact with them using a local evasion mechanism, according to its speed and radius parameters in the description.

The agent can also be INDIFFERENT.
The agent won’t do anything, he’ll just be there. Other agents will be able to bypass it when performing a local crawl. An attempt to call methods to follow a target with this type of behavior will result in an exception similar to receiving.

OptionProperty name in Nav3DAgentDescriptionTypeValue range
Motion Navigation TypeMotionNavigationTypeenum MotionNavigationTypeGLOBAL, GLOBAL_AND_LOCAL, LOCAL

The main purpose of all agents is to move towards some goal, be it another agent or a point in space. Agents can move using three ways of orientation in space:

  • Using the global path (GLOBAL). In this case, the agent will search for a path and will move along it, regardless of external conditions (other agents or edges of obstacles that are too close).
  • Using only local avoidance (LOCAL). The agent will not use pathfinding for movement, but will move towards the target in a straight line, dodging other agents and obstacles along the way when they meet on the course of movement. Of course, not every obstacle can be overcome in this way.
  • Finally, the agent can move towards the target using pathfinding and local avoidance at the same time

Radius


OptionProperty name in Nav3DAgentDescriptionTypeValue range
RadiusRadiusfloat>0

The range of the agent is used to perform local evasion maneuvers. Establishing the correct radius is important for effective local traversal by both the agent itself and other agents nearby. We advise you to adjust the radius so that all the visual content of the game unit, which is the agent, is inside the sphere of the specified radius.


Speed


OptionProperty name in Nav3DAgentDescriptionTypeValue range
SpeedSpeedfloat>0

The agent’s speed. You can change it at any time if needed.


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Max SpeedMax Speedfloat>Speed

The maximum speed of the agent. This parameter is required to perform a local crawl. In some situations, the agent may need to speed up to avoid a collision. If the value is set too high, the agent may sometimes move jerkily when performing a local crawl. Therefore, we advise you to set the maximum speed a little more than Speed (less than one and a half times more).

For your convenience, there are two ways to set this value in the inspector. With a certain value. Or using a multiplier to increase the speed. We recommend using a multiplier so that the maximum speed depends on the agent’s speed. Then the maximum speed will change following the speed change at any time.


Local avoidance


OptionProperty name in Nav3DAgentDescriptionTypeValue range
ORCA TauORCATaufloat>0

The time range for calculating the velocity obstacle (VO). We do not recommend changing this parameter.

To better understand its meaning, the original article about ORCA: Reciprocal n-body Collision Avoidance. Jur van den Berg, Stephen J. Guy, Ming Lin, and Dinesh Manocha


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Agents considered number limitAgents considered number limitbooltrue, false

Allows you to limit the number of nearby agents considered for local crawling.
Enabling this option makes sense if you use a large number of agents in a limited space. In such a situation, each agent may have many neighbors, and performance may not be sufficient to ensure high fps if all nearby agents are taken into account in the calculations.


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Agents numberConsideredAgentsNumberLimitint>=1

The number of agents that are taken into account from all nearby agents.


Pathfinding


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Pathfinding timeout (ms)PathfindingTimeoutint>0

Maximum path search time. If the path search takes longer, the Action _OnFail callback will be executed if it was passed to UpdatePath().


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Smooth the pathSmoothPathbooltrue, false

Whether it is necessary to smooth the found path.


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Samples per min bucket volumeSmoothRatioint>0

The number of path segments per minimum octree cell size resulting from smoothing the original path. You should not excessively increase this parameter, as this increases the total pathfinding time..

OptionProperty name in Nav3DAgentDescriptionTypeValue range
Auto-update path on stagnant behaviorAutoUpdatePathbooltrue, false

When using the local avoidance mechanism in combination with global pathfinding, a situation may arise when the path passes through an area of space where many other agents are present. Then our agent can deviate from the path found, trying to avoid collisions with other agents. This process can continue indefinitely, because, trying to return to the original trajectory, the agent will always deviate from it again, meeting with other agents.

Enable this option to automatically replace the path. Then, if the agent has moved away from its path far enough and is at a sufficiently large distance, the path will be found again from the agent’s current position.


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Auto-update cooldown (ms)PathAutoUpdateCooldownint>=1

Minimum path auto-update period. If the area of space is too full of other agents, then path recalculation may be too frequent, which will negatively affect performance in case of a large number of agents in the scene. We recommend limiting the frequency of auto correction to a few seconds.


Motion


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Target reach distanceTargetReachDistancefloat>=0

The distance required to reach the goal. When you order an agent to reach a goal, the goal will be considered reached when the agent’s pivot point coincides with the goal coordinate (the distance between them will be 0). This can be inconvenient if the target is a hooked object, say, a planet in space. In this case, set this parameter equal to the sum of the radius of the visible part of the agent and the radius of the planet. Then the agent will stop when it reaches the surface of the planet.


OptionProperty name in Nav3DAgentDescriptionTypeValue range
Max rotation in degrees per fixed update tickMaxAgentDegreesRotationPerTickfloat>=0

The maximum number of degrees that the agent can rotate when performing a rotation in the direction of movement.
During the movement, the agent turns towards the velocity vector. If the velocity vector changes dramatically during movement, then the agent’s turn may look sharp. To make it smoother, set this parameter not too high.


Velocity blending


When using global pathfinding and local avoidance, the agent moves using three velocity vectors:

  1. The velocity vector along the path.
  2. The velocity vector of avoidance from nearest agents.
  3. Obstacle avoidance velocity vector.

The agent blends these three velocities in different proportions and uses the resulting vector for movement. In order to tell the agent in what proportion to mix the speeds, we have introduced weights, the values ​​of which you can adjust.

Not all three velocities can be blended in all situations. For example, there may be no obstacles near the agent, then only the velocity of following the path and the velocity of the nearest agents avoidance will be mixed.

This way you can tell the agent how significant each rate should be when getting the resulting one. If it is preferable to follow the path, then the first weight can be made much larger than the last two. If it is imperative to perform local evasion maneuvers, then the weight of the velocity along the trajectory should be made much smaller than the weight of the evasion speeds.

Below are explanations of the weight parameters. Note that separate parameters are used for each situation.

All weights are floating and must be greater than 0.

The corresponding property names in Nav3DAgentDescription are:

  • PathVelocityWeight
  • PathVelocityWeight1
  • PathVelocityWeight2
  • AgentsAvoidanceVelocityWeight
  • AgentsAvoidanceVelocityWeight1
  • AgentsAvoidanceVelocityWeight2
  • ObstacleAvoidanceVelocityWeight
  • ObstacleAvoidanceVelocityWeight1
  • ObstacleAvoidanceVelocityWeight2