Docy Child

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

Option Property name in Nav3DAgentDescription Type Value range
Behavior Type
Behavior Type
enum BehaviorType
DEFAULT, 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 move to the target.) His only concern will be to give way to agents nearby. It will interact with them using the Local avoidance mechanism, in accordance with its speed and radius parameters in description.
  • Also, the agent can be indifferent (INDIFFERENT).
    The agent will not do anything, it will just be there. Other agents will be able to bypass it when performing local avoidance. An attempt to call methods to follow to a target with this type of behavior will result in an exception being thrown, similar to YIELDING.
Option Property name in Nav3DAgentDescription Type Value range
Motion Navigation Type
MotionNavigationType
enum MotionNavigationType
GLOBAL, 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

Option Property name in Nav3DAgentDescription Type Value range
Radius
Radius
float
>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

Option Property name in Nav3DAgentDescription Type Value range
Speed
Speed
float
>0

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

Option Property name in Nav3DAgentDescription Type Value range
Max Speed
Max Speed
float
>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

Option Property name in Nav3DAgentDescription Type Value range
ORCA Tau
ORCATau
float
>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

Option Property name in Nav3DAgentDescription Type Value range
Agents considered number limit
Agents considered number limit
bool
true, 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.

Option Property name in Nav3DAgentDescription Type Value range
Agents number
ConsideredAgentsNumberLimit
int
>=1

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

Pathfinding

Option Property name in Nav3DAgentDescription Type Value range
Pathfinding timeout (ms)
PathfindingTimeout
int
>0

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

Option Property name in Nav3DAgentDescription Type Value range
Smooth the path
SmoothPath
bool
true, false

Whether it is necessary to smooth the found path.

Option Property name in Nav3DAgentDescription Type Value range
Samples per min bucket volume
SmoothRatio
int
>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..

Option Property name in Nav3DAgentDescription Type Value range
Auto-update path on stagnant behavior
AutoUpdatePath
bool
true, 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.

Option Property name in Nav3DAgentDescription Type Value range
Auto-update cooldown (ms)
PathAutoUpdateCooldown
int
>=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

Option Property name in Nav3DAgentDescription Type Value range
Target reach distance
TargetReachDistance
float
>=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.

Option Property name in Nav3DAgentDescription Type Value range
Max rotation in degrees per fixed update tick
MaxAgentDegreesRotationPerTick
float
>=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
en_USEnglish