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:
- The velocity vector along the path.
- The velocity vector of avoidance from nearest agents.
- 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
Debug
| Use Log | UseLog | bool | Whether it is necessary to log agent work processes. | true, false |
|---|---|---|---|---|
|
Log records count |
LogSize |
int |
Agent log size. |
>0 |
English 
Russian