Configuration Parameters

It is important to understand the various configuration parameters that effect the final result before moving on to details for each stage of mesh generation. This page provides functional descriptions of all configuration parameters used by the NMGen classes, how they impact the final result, and how they impact each other.

cellSize

Constraints
> 0
Used By
NavmeshGenerator, SolidHeightFieldBuilder, SolidHeightField, OpenHeightField, ContourSet, PolyMeshField
Description

The width and depth resolution used when sampling the source geometry. The width and depth of the cell columns that make up voxel fields.

Cells are laid out on the width/depth plane of voxel fields. Width is associated with the x-axis of the source geometry. Depth is associated with the z-axis.

A lower value allows for the generated mesh to more closely match the source geometry, but at a higher processing and memory cost.

Example: cellSize relationship to the voxel field.

Large

Sometimes you may notice an unexpectedly wide mesh border along obstacles, or a difference in the width of the border along one side of an object when compared to its other side. This is an inherent behavior of the mesh generation process. Take a look at the above visualization of a voxel field. Vertices in the final mesh can only exist on the corner of a voxel. Vertices are snapped to the voxel grid. The larger the voxel size, the larger the potential xz-plane offset of final mesh vertices, the more pronounced border "errors" can be.

Note: traversableAreaBorderSize is set to zero in both of the below examples. Even though this turns off the border functionality, borders still appear to exist. This is due to the resolution of the voxel field. Only an infinitely high resolution can completely get rid of this effect.

Border Example #1: This mesh was generated using a lower resolution (larger cellSize).

Large

Border Example #2: This mesh was generated using a higher resolution (smaller cellSize). So the appearance of an offset isn't apparent. (Though it is technically still there.)

Large
Interactions
This is a core configuration value that interacts with almost all other parameters.

cellHeight

Constraints
> 0
Used By
NavmeshGenerator, SolidHeightFieldBuilder, SolidHeightField, OpenHeightField, ContourSet, PolyMeshField
Description

The height resolution used when sampling the source geometry. The height of the voxels in voxel fields.

Height is associated with the y-axis of the source geometry.

A smaller value allows for the final mesh to more closely match the source geometry at a potentially higher processing cost. (Unlike cellSize, using a lower value for cellHeight does not significantly increase memory use.)

Example: cellHeight relationship to the voxel field.

Large

As with cellSize, cellHeight controls where vertices can exists. The surface of the final mesh will "snap" to the top of the voxels that contain the source geometry, not to the geometry itself. This is an inherent behavior of the mesh generation process. Take a look at the above visualization of a voxel field. Vertices in the final mesh can only exist on the corner of a voxel. So vertices are snapped to the voxel grid. The larger the voxel height, the larger the potential y-offset of vertices from the actual source geometry.

Example #1: This detail mesh was generated using a lower resolution (larger cellHeight).

Large

Example #2: This detail mesh was generated using a higher resolution (smaller cellHeight). So the appearance of an offset isn't as apparent.

Large
Interactions
This is a core configuration value that impacts almost all other parameters. minTraversableHeight, maxTraversableStep, and contourMaxDeviation will need to be greater than this value in order to function correctly. maxTraversableStep is especially susceptible to impact from the value of cellHeight.

minTraversableHeight

Constraints
> 0
Used By
NavmeshGenerator, SolidHeightFieldBuilder, OpenHeightFieldBuilder
Description

Represents the minimum floor to ceiling height that will still allow the floor area to be considered traversable. It permits detection of overhangs in the geometry that make the geometry below become un-walkable. It can also be thought of as the maximum agent height.

Example #1: Setting the value correctly prevents the mesh from running under tables.

Large

Example #2: Setting the value too low allows the mesh to run under tables when it shouldn't.

Large

Example #3: Setting the value too high prevents the mesh from extending into the area under a balcony.

Large
Interactions
This value should be at least two times the value of cellHeight in order to get good results.

maxTraversableStep

Constraints
>= 0
Used By
NavmeshGenerator, SolidHeightFieldBuilder, OpenHeightFieldBuilder
Description

Represents the maximum ledge height that is considered to still be traversable.

Prevents minor deviations in height from improperly showing as obstructions. Permits detection of stair-like structures, curbs, etc.

Example #1: Setting the value correctly permits the mesh to extend up a stairway.

Large

Example #2: Setting the value too low makes the stairway look like is can't be traversed. (Agent can't step high enough to walk up the stairway.)

Large

Example #3: Setting the value too high results in the mesh flowing over tables and counters.

Large
Interactions
maxTraversableStep should be greater than two times cellHeight. (maxTraversableStep > cellHeight * 2) Otherwise the resolution of the voxel field may not be high enough to accurately detect traversable ledges. Ledges may merge, effectively doubling their step height. This is especially an issue for stairways.

maxTraversableSlope

Constraints
>= 0
Used By
NavmeshGenerator, SolidHeightFieldBuilder
Description

The maximum slope that is considered traversable. (In degrees.)

Example #1: Setting the value correctly allows the mesh to extend up a traversable ramp.

Large

Example #2: Setting the value too low prevents the mesh from extending up a ramp that should be traversable.

Large
Interactions
None.

clipLedges

Constraints
None.
Used By
NavmeshGenerator, SolidHeightFieldBuilder
Description

Indicates whether ledges should be considered un-walkable

A ledge is an otherwise traversable voxel that has one or more neighbor voxels with an un-steppable drop from voxel top to voxel top. E.g. If an agent using the mesh were to travel down from the ledge voxel to its neighbor voxel, it would result in the maximum traversable step distance being violated. The agent cannot legally "step down" from a ledge to its neighbor.

Interactions
Ledge clipping is performed early in the mesh generation process. This results in the ledge voxels being interpreted by later algorithms as obstructions. For example, if traversableAreaBorderSize is > 0, then the border near clipped ledges will be thicker than in other areas. For this reason, ledge clipping is often not needed when using the traversableAreaBorderSize feature.

traversableAreaBorderSize

Constraints
>= 0
Used By
NavmeshGenerator, OpenHeightFieldBuilder
Description

Represents the closest any part of a mesh can get to an obstruction in the source geometry.

Usually this value is set to the maximum bounding radius of agents utilizing the meshes for navigation decisions.

Example #1: Setting a border size to > 0 causes the mesh to pull away from the wall and banister of the stairs.

Large

Example #2: Setting the border size to zero results in the mesh hugging the wall and banister more closely.

Large
Interactions

This value must be greater than the cellSize to have an effect.

The actual border will be larger around ledges if ledge clipping is enabled. See the clipLedges parameter for more information.

The actual border area will be larger if smoothingTreshold is > 0. See the smoothingThreshold parameter for more information.

smoothingThreshold

Constraints
>= 0
Used By
NavmeshGenerator, OpenHeightFieldBuilder
Description

The amount of smoothing to be performed when generating the distance field used for deriving regions.

This value impacts region formation and border detection. In general, a higher value results in larger regions, fewer thin triangles, and wider border sizes.

A value of zero disables smoothing.

There is a known issue with this feature. See the issues page for details.

Example #1: There are more thin, long triangles when smoothingThreshold is set to zero. (Compared to the next example.)

Large

Example #2: The triangulation is improved by setting smoothing to 2.

Large
Interactions

As noted in the description, smoothing creates a wider border area. In fact, setting the smoothing too high can cause a border to appear around meshes even if traversableAreaBorderSize is set to zero. This also means that smoothing magnifies the effect of traversableAreaBorderSize.

Example #1: A border is defined using traversableAreaBorderSize with smoothingThreshold set to zero. Borders along the wall and banister are as expected.

Large

Example #2: The same value is used for traversableAreaBorderSize, but with smoothingThreshold set to 2. The borders along the wall and banister are larger than in the first example.

Large

useConservativeExpansion

Constraints
None.
Used By
NavmeshGenerator, OpenHeightFieldBuilder
Description

Applies extra algorithms to help prevent malformed regions from forming.

If meshes are missing sections that should be present, then enabling this feature will likely fix the problem

Enabling this feature significantly increases processing cost.

This is an experimental feature not found in Recast. It is not known whether or not the issues this feature addresses exist in Recast.

Example: Without conservative expansion enabled, a region flows around two columns. This results in the eventual formation of a non-simple polygon that the triangulation algorithms can't handle. So the region looses its mesh.

Large
Interactions
None.

minUnconnectedRegionSize

Constraints
> 0
Used By
NavmeshGenerator, FilterOutSmallRegions
Description

The minimum region size for unconnected (island) regions.

The value is in voxels.

Regions that are not connected to any other region and are smaller than this size will be culled before mesh generation. I.e. They will no longer be considered traversable.

Example #1: With minUnconnectedRegionSize set correctly, the tops of the tables are un-walkable

Large

Example #2: With minUnconnectedRegionSize set too low, the tops of tables get their own meshes.

Large
Interactions
None.

mergeRegionSize

Constraints
>= 0
Used By
NavmeshGenerator, FilterOutSmallRegions
Description

Any regions smaller than this size will, if possible, be merged with larger regions.

Value is in voxels.

Helps reduce the number of small regions. This is especially an issue in diagonal path regions where inherent faults in the region generation algorithm can result in unnecessarily small regions.

Small regions are left unchanged if they cannot be legally merged with a neighbor region. (E.g. Merging will result in a non-simple polygon.)

Example #1: mergeRegionSize is too small. Some thin long triangles are generated.

Large

Example #2: mergeRegionSize is large enough to clean-up some of the long thin triangles.

Large
Interactions
None

maxEdgeLength

Constraints
>= 0
Used By
NavmeshGenerator, NullRegionMaxEdge
Description

The maximum length of polygon edges that represent the border of meshes.

More vertices will be added to border edges if this value is exceeded for a particular edge.

In certain cases this will reduce the number of long thin triangles.

A value of zero will disable this feature.

Example #1: Mesh with maxEdgeLength set to zero. (Disabled.)

Large

Example #2: maxEdgeLength is enabled, resulting in new vertices along the mesh border.

Large
Interactions
None

edgeMaxDeviation

Constraints
>= 0
Used By
NavmeshGenerator, MatchNullRegionEdges
Description

The maximum distance the edges of meshes may deviate from the source geometry.

A lower value will result in mesh edges following the xz-plane geometry contour more accurately at the expense of an increased triangle count.

A value to zero is not recommended since it can result in a large increase in the number of polygons in the final meshes at a high processing cost.

Example #1: Edge matching is turned off completely. The generator creates the simplest edges possible with poor results.

Large

Example #2: A moderate amount of edge matching results in a mesh that better follows the source geometry edges.

Large

Example #3: The maximum edge matching results in a mesh that follows the source geometry edges very closely, but with an excessive amount of polygons.

Large
Interactions
None

maxVertsPerPoly

Constraints
>= 3
Used By
NavmeshGenerator, PolyMeshField
Description

The maximum number of vertices per polygon for polygons generated during the voxel to polygon conversion process.

Higher values increase processing cost, but can also result in better formed polygons in the final meshes. A value of around 6 is generally adequate with diminishing returns for higher values.

Interactions
None

contourSampleDistance

Constraints
>= 0
Used By
NavmeshGenerator, TriangleMeshField
Description

Sets the sampling distance to use when matching the detail mesh to the surface of the original geometry.

Impacts how well the final detail mesh conforms to the surface contour of the original geometry. Higher values result in a detail mesh that conforms more closely to the original geometry's surface at the cost of a higher final triangle count and higher processing cost.

Setting this argument to less than 0.9 disables this functionality.

Example #1: Contour matching is turned off with a moderate level of edge matching. So the edges follow the contour, but the central area of the mesh does not.

Large

Example #2: Moderate level of contour and edge matching. More triangles added to the central area of the mesh.

Large

Example #3: High level of contour matching.

Large
Interactions
The difference between this parameter and edge matching is that this parameter operates on the height rather than the xz-plane. It also matches the entire detail mesh surface to the contour of the original geometry. Edge matching only matches edges of meshes to the contour of the original geometry.

contourMaxDeviation

Constraints
>= 0
Used By
NavmeshGenerator, TriangleMeshField
Description

The maximum distance the surface of the detail mesh may deviate from the surface of the original geometry.

The accuracy is impacted by contourSampleDistance.

The value of this parameter has no meaning if contourSampleDistance is set to zero.

Setting the value to zero is not recommended since it can result in a large increase in the number of triangles in the final detail mesh at a high processing cost.

See contourSampleDistance for examples.

Interactions
This parameter has no impact if contourSampleDistance is set to zero.