Unreal Engine 4.26 Documentation

Unreal Engine 4.27 Documentation

Unreal Engine 5.0 Documentation

Unreal Engine 5.1 Documentation

Unreal Engine 5.2 Documentation

Unreal Engine 5.3 Documentation

> Making Interactive Experiences > Artificial Intelligence > MassEntity > Mass Avoidance > Mass Avoidance Overview

Light Theme

Dark Theme

You can try out this Experimental feature, but we do not recommend shipping projects with it.

Features are sometimes made available in an Experimental state so you can try them out, provide feedback, and see what we are planning. We do not recommend shipping projects with Experimental features. Please keep in mind that we do not guarantee backward compatibility for assets created at the experimental stage, the APIs for these features are subject to change, and we may remove entire Experimental features or specific functionality at our discretion.

Mass Avoidance Overview

Overview of the Mass Avoidance system in Unreal Engine 5.

On this page

Overview
System Inputs
System Outputs
System Execution
Debugging Mass Avoidance
- Visual Logger
  - Enabling the Visual Logger
- Gameplay Debugger
  - Enabling the Gameplay Debugger

Overview

Mass Avoidance is a force-based avoidance system integrated with MassEntity. The system provides high performance avoidance for any Entity using the MassEntity system.

The system uses the UMassMovingAvoidanceProcessor to process various inputs and outputs a steering force into the FMassForceFragment. This output force is used to steer the Entity away from other entities in the environment.

System Inputs


Input	Description
FMassForceFragment	Represents the force applied to the Entity to steer it away from other Entities.
FMassNavigationEdgesFragment	Provides a list of edges (walls) used for avoidance by the Entity.
FMassMoveTargetFragment	Represents the target destination for the Entity. It also contains additional information, such as forward direction and current status (standing still, moving, etc)
FDataFragment_Transform	Represents the Entity's transform.
FMassVelocityFragment	Represents the Entity's velocity.
FDataFragment_AgentRadius	Represents the Entity's radius.

System Outputs


Output	Description
FMassForceFragment	The final steering force applied to the Entity.

System Execution

UMassMovingAvoidanceProcessor

The UMassMovingAvoidanceProcessor computes the sum of the separation forces and avoidance forces for each Entity. These forces originate from nearby Entities and obstacles.

Other Entities are represented as colliders (see FMassAvoidanceColliderFragment) and can have a capsule or pill shape, used for humans and vehicles respectively. You can adjust several settings to balance the effect of these forces.

Nearby Entities are gathered by using FNavigationObstacleHashGrid2D (owned by the UMassNavigationSubsystem) and only the closest Entities are considered. Obstacles are represented as edges and originate from FMassNavigationEdgesFragment. Avoidance forces are predictive, meaning that their directions are computed from future impact positions. Separation forces are perpendicular forces aiming to keep a loose distance from the environment.

UMassStandingAvoidanceProcessor

The UMassStandingAvoidanceProcessor is a similar version of the processor used when Entities are standing in place.

UMassNavigationObstacleGridProcessor

The UMassNavigationObstacleGridProcessor is used to update the grid position of obstacles into the FNavigationObstacleHashGrid2D.

UMassZoneGraphLaneCacheBoundaryProcessor

The UMassZoneGraphLaneCacheBoundaryProcessor is used in conjunction with ZoneGraph and it builds edges from the current cached lane segments being followed (see the FMassZoneGraphCachedLaneFragment and FMassZoneGraphPathFollowTask).

These edges are added to the FMassNavigationEdgesFragment.

System Settings

The Mass Avoidance settings are stored in FMassMovingAvoidanceParameters and FMassStandingAvoidanceParameters. To see a detailed description of all the settings available, refer to MassAvoidanceFragments.h in your project files.

Debugging Mass Avoidance

You can debug the Mass Avoidance system by using the Visual Logger and the Gameplay Debugger.

Visual Logger

You can use the Visual Logger to display the following categories in the editor:


Category	Description
LogAvoidance	Displays basic information, such as initial and final steering force and current Entity.
LogAvoidanceVelocity	Displays the current velocity and the desired velocity for the Entity.
LogAvoidanceAgents	Displays the obstacle edges, predicted collisions, and the forces associated with the Entities.

Enabling the Visual Logger

Click Tools > Debug > Visual Logger to open the Visual Logger window.
Select the MassSimulationSubsystem track from the list.
Go to Edit > Editor Preferences to open the Editor Preferences window. Click the Visual Logger category and enable the Stick to Recent Data checkbox to display real-time data.
Press the ~ key to open the command line and enter ai.debug.mass.DebugEntity or ai.debug.mass.SetDebugEntityRange to set the Entities that will be displayed while debugging.
Press the Play Settings menu button and click Simulate to see the debug visualizations in the editor.

To learn more about using the Visual Logger, refer to the Visual Logger documentation.

Gameplay Debugger

You can use the Gameplay Debugger to display information such as MoveTarget, Steering, and Colliders for the Entities in the editor.

Enabling the Gameplay Debugger

During gameplay, press the ` key to activate the Gameplay Debugger. Then, press Shift+O to see the Entity Overview, or Shift+V to display avoidance.

Open the GameplayDebuggerCategory_Mass.cpp source file for further information about how to use the Gameplay Debugger with Mass Avoidance.