Skip to main content

Mass - Debugging

Debugging problems in Mass.

Background​

This is part of a series of articles about the Mass system, these articles include:

Mass - Debugging
Mass - Concepts
Mass - Cache Concepts and Optimization

Problem​

If we follow the tutorial Large Numbers of Entities with Mass in UE5 | Feature Highlight | State of Unreal 2022, we

  • create a mass configuration object which has a vizualizer component
  • set a static mesh as a property of the vizualizer component
  • add a Mass Spawner object to the world which is supposed to create 100 entities
  • position the Mass Spawner object in front of the player character
  • press play
  • nothing appears!
  • press pause and the 100 cones do appear.

This would seem to be a bug. If we replace the old Debug Visualiser with the more modern Mass Movable Visualization Trait we can configure the trait like this:

  • under Static Mesh Instance Desc add an entry to Meshes
  • for that entry set Mesh to Cone

Now press the ValidateEntityConfig button. This generates errors in the message window which can be fixed by:

  • adding a new trait and setting it to LODCollector
  • adding a new trait and setting it to Assorted Fragments
    • adding a fragment to Assorted Fragment and setting it to Mass Actor Fragment
    • adding a fragment to Assorted Fragment and setting it to Transform Fragment
    • adding a fragment to Assorted Fragment and setting it to Mass Viewer Info Fragment

Now it should pass validation and look like this:

The Params/LODRepresentation should be set like this so that for all LOD values the static mesh is displayed:

But still no entities are displayed, even when pause is pressed.

This shows some techniques for debugging mass to find out what is wrong.

Gameplay Debugger​

Press play, and while the game is running type this console command

enablegdt

This displays the gameplay debugger over the top of the running game:

The third line down lists areas which can be debugged. If "Mass" is not listed you need to enable the Mass AI plugin.

These areas a toggle by pressing the corresponding keys on the numeric keypad, for example click on the game window and press 1 2 8 to disable everything except Mass:

We can see from this screen it says:

[CATEGORY: Mass] Entities count active/all: 100/100

This tells us the 100 entities have been created by the Mass Spawner but for some reason we cannot see them.

Type this console command to select the first entity:

mass.debug.DebugEntity 1

As shown in this image we can see the location of the selected entity highlighted in purple:

Now press Shift-G to show the tags and fragments the entity has:

After than press Shift-D to show the values of the fragments:

We can see the Translation is 1570, 1550, 90 which is the position of the entity

The debug output now shows the Entity selected and which tags and fragments it has:

Now press Shift-D to display the values of the fragments for the selected entity:

We can see the entity is at -130, 2010, 1170

There are a number of things which might be wrong here:

  • on the MassRepresentationLODFragment the LOD=Max
  • on the MassRepresentationFragment the StaticMeshDescHandle=() which is presumably null
  • why does it have a MassVisibilityCulledByDistanceTag tag

Using Breakpoints​

By browsing through the code you can set breakpoints in places you think should be getting hit, like the first line in this function:

void UMassVisualizationProcessor::UpdateVisualization(FMassExecutionContext& Context)
{
	FMassVisualizationChunkFragment& ChunkData = UpdateChunkVisibility(Context);
	if (!ChunkData.ShouldUpdateVisualization())
	{
		return;
	}

In our case this line is never hit, suggesting the visualization processor is not running.

When the game is running typing the mass.debug console command brings up the Mass Debugger window, like so:

width80

Where it says "Pick Environment" select the option which has "PIE" in it, for the editor process:

width100

Click on the Archetypes tab, you should see the name of the mass config data asset we are running listed together with the number of entities which exist. Again this confirms the entities are being created:

width80

Click on archetype name to display more details:

width80

Click on the Processing Graph tab and click on the "Pre Physics Group" entry. This is the stage at which processors run by default:

width80

Looking at this we don't see a visualization processor, again suggesting the the visualization processor is not running.

MassDefaults.ini​

To fix this make sure these lines are in the file Config\MassDefaults.ini:

[/Script/MassRepresentation.MassRepresentationProcessor]
bAutoRegisterWithProcessingPhases=True

[/Script/MassRepresentation.MassVisualizationLODProcessor]
bAutoRegisterWithProcessingPhases=True

[/Script/MassLOD.MassLODCollectorProcessor]
bAutoRegisterWithProcessingPhases=True

If they are missing, update the file and restart the editor.

  • Run the level again
  • use the console command "mass.debug"
  • where it says "Pick Environment" select the option which has "PIE" in it
  • look at the "Pre Physics Group" entry, you should now see the a visualization processor like this:

Having fixed this you should now see a bunch of cones like this:

If you use the console command

enablegdt

Then:

  • press Shift-P to select a random entity
  • press Shift-G to display the tags and fragments

You see something like this:

Because we enabled to LOD processor by adding it to the MassDefaults.ini file at the same time as we fixed the missing visualizer process, the tag MassVisibilityCulledByDistanceTag is no longer on the entity.

If we press Shift-D to show the entity details we see:

Note that the LOD on the MassRepresentationLODFragment is Medium and not Max.

References​