MergeRegionSize

MergeRegionSize

#Overview

name: MergeRegionSize

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of MergeRegionSize is to define the size limit for merging smaller regions with larger regions during the navigation mesh generation process in Unreal Engine 5’s navigation system. This variable is specifically used in the Recast navigation mesh generation algorithm.

The MergeRegionSize variable is primarily used by the NavigationSystem module, particularly within the RecastNavMesh and RecastNavMeshGenerator components. These are part of Unreal Engine’s navigation and pathfinding subsystem.

The value of this variable is typically set in the ARecastNavMesh class, which is a subclass of ANavigationData. It can be configured through the Unreal Engine editor or programmatically in C++ code.

MergeRegionSize interacts with other navigation mesh generation properties such as MinRegionArea, CellSize, and TileSizeUU. It’s used in calculations to determine the mergeRegionArea in square units of the navigation mesh’s cell size.

Developers should be aware that this variable directly affects the level of detail and complexity of the generated navigation mesh. A larger MergeRegionSize will result in a simpler, less detailed mesh with fewer, larger regions. Conversely, a smaller value will produce a more detailed mesh with more, smaller regions.

Best practices when using this variable include:

  1. Adjusting it in conjunction with other navigation mesh properties to achieve the desired balance between performance and accuracy.
  2. Testing different values to find the optimal setting for your specific game environment and AI requirements.
  3. Being mindful of performance implications when setting very small values, as this can lead to more complex navigation meshes.
  4. Considering the scale of your game world and the size of your AI agents when setting this value.

Remember that the optimal value can vary greatly depending on the specific requirements of your game and the complexity of your environment.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:2829, section: [/Script/NavigationSystem.RecastNavMesh]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/NavigationSystem/Private/NavMesh/RecastNavMesh.cpp:433

Scope (from outer to inner):

file
function     FRecastNavMeshGenerationProperties::FRecastNavMeshGenerationProperties

Source code excerpt:

	AgentMaxStepHeight = 35.f;
	MinRegionArea = 0.f;
	MergeRegionSize = 400.f;
	MaxSimplificationError = 1.3f;	// from RecastDemo
	TileNumberHardLimit = 1 << 20;
	RegionPartitioning = ERecastPartitioning::Watershed;
	LayerPartitioning = ERecastPartitioning::Watershed;
	RegionChunkSplits = 2;
	LayerChunkSplits = 2;

#Loc: <Workspace>/Engine/Source/Runtime/NavigationSystem/Private/NavMesh/RecastNavMesh.cpp:465

Scope (from outer to inner):

file
function     FRecastNavMeshGenerationProperties::FRecastNavMeshGenerationProperties

Source code excerpt:

	AgentMaxStepHeight = RecastNavMesh.GetAgentMaxStepHeight(ENavigationDataResolution::Default); //FRecastNavMeshGenerationProperties is getting deprecated 
	MinRegionArea = RecastNavMesh.MinRegionArea;
	MergeRegionSize = RecastNavMesh.MergeRegionSize;
	MaxSimplificationError = RecastNavMesh.MaxSimplificationError;
	TileNumberHardLimit = RecastNavMesh.TileNumberHardLimit;
	RegionPartitioning = RecastNavMesh.RegionPartitioning;
	LayerPartitioning = RecastNavMesh.LayerPartitioning;
	RegionChunkSplits = RecastNavMesh.RegionChunkSplits;
	LayerChunkSplits = RecastNavMesh.LayerChunkSplits;

#Loc: <Workspace>/Engine/Source/Runtime/NavigationSystem/Private/NavMesh/RecastNavMesh.cpp:3448

Scope (from outer to inner):

file
function     void ARecastNavMesh::UpdateGenerationProperties

Source code excerpt:


	MinRegionArea = GenerationProps.MinRegionArea;
	MergeRegionSize = GenerationProps.MergeRegionSize;
	MaxSimplificationError = GenerationProps.MaxSimplificationError;
	TileNumberHardLimit = GenerationProps.TileNumberHardLimit;
	RegionPartitioning = GenerationProps.RegionPartitioning;
	LayerPartitioning = GenerationProps.LayerPartitioning;
	RegionChunkSplits = GenerationProps.RegionChunkSplits;
	LayerChunkSplits = GenerationProps.LayerChunkSplits;

#Loc: <Workspace>/Engine/Source/Runtime/NavigationSystem/Private/NavMesh/RecastNavMeshGenerator.cpp:4655

Scope (from outer to inner):

file
function     void FRecastNavMeshGenerator::SetupTileConfig

Source code excerpt:


	OutConfig.minRegionArea = (int32)rcSqr(DestNavMesh->MinRegionArea / CellSize);
	OutConfig.mergeRegionArea = (int32)rcSqr(DestNavMesh->MergeRegionSize / CellSize);

	OutConfig.tileSize = FMath::Max(FMath::TruncToInt(DestNavMesh->TileSizeUU / CellSize), 1);
	UE_CLOG(OutConfig.tileSize == 1, LogNavigation, Error, TEXT("RecastNavMesh TileSize of 1 is highly discouraged. This occurence indicates an issue with RecastNavMesh\'s generation properties (specifically TileSizeUU: %f, CellSize: %f). Please ensure their correctness.")
		, DestNavMesh->TileSizeUU, CellSize);

	OutConfig.regionChunkSize = FMath::Max(1, OutConfig.tileSize / FMath::Max(1, DestNavMesh->LayerChunkSplits));

#Loc: <Workspace>/Engine/Source/Runtime/NavigationSystem/Private/NavMesh/RecastNavMeshGenerator.cpp:4737

Scope (from outer to inner):

file
function     void FRecastNavMeshGenerator::ConfigureBuildProperties

Source code excerpt:


	OutConfig.minRegionArea = (int32)rcSqr(DestNavMesh->MinRegionArea / CellSize);
	OutConfig.mergeRegionArea = (int32)rcSqr(DestNavMesh->MergeRegionSize / CellSize);
	OutConfig.maxVerticalMergeError = DestNavMesh->MaxVerticalMergeError;
	OutConfig.maxSimplificationError = DestNavMesh->MaxSimplificationError;
	OutConfig.simplificationElevationRatio = DestNavMesh->SimplificationElevationRatio;
	OutConfig.bPerformVoxelFiltering = DestNavMesh->bPerformVoxelFiltering;
	OutConfig.bMarkLowHeightAreas = DestNavMesh->bMarkLowHeightAreas;
	OutConfig.bUseExtraTopCellWhenMarkingAreas = DestNavMesh->bUseExtraTopCellWhenMarkingAreas;

#Loc: <Workspace>/Engine/Source/Runtime/NavigationSystem/Public/NavMesh/RecastNavMesh.h:370

Scope: file

Source code excerpt:

	/* The size limit of regions to be merged with bigger regions (watershed partitioning only) */
	UPROPERTY(EditAnywhere, Category = Generation, meta = (ClampMin = "0.0"))
	float MergeRegionSize;

	/** How much navigable shapes can get simplified - the higher the value the more freedom */
	UPROPERTY(EditAnywhere, Category = Generation, meta = (ClampMin = "0.0"))
	float MaxSimplificationError;

	/** Absolute hard limit to number of navmesh tiles. Be very, very careful while modifying it while

#Loc: <Workspace>/Engine/Source/Runtime/NavigationSystem/Public/NavMesh/RecastNavMesh.h:800

Scope (from outer to inner):

file
class        class ARecastNavMesh : public ANavigationData

Source code excerpt:

	/* The size limit of regions to be merged with bigger regions (watershed partitioning only) */
	UPROPERTY(EditAnywhere, Category=Generation, config, meta=(ClampMin = "0.0"))
	float MergeRegionSize;

	/** Maximum vertical deviation between raw contour points to allowing merging (in voxel).
	 * Use a low value (2-5) depending on CellHeight, AgentMaxStepHeight and AgentMaxSlope, to allow more precise contours (also see SimplificationElevationRatio).
	 * Use very high value to deactivate (Recast behavior). */
	UPROPERTY(EditAnywhere, Category = Generation, config, meta = (ClampMin = "0"))
	int MaxVerticalMergeError;