 |
Recast Navigation
Navigation-mesh Toolset for Games
|
|
Recast Navigation
Navigation-mesh Toolset for Games
|
Specifies a configuration to use when performing Recast builds. More...
#include <Recast.h>
Public Attributes | |
| int | width |
| The width of the field along the x-axis. [Limit: >= 0] [Units: vx]. More... | |
| int | height |
| The height of the field along the z-axis. [Limit: >= 0] [Units: vx]. More... | |
| int | tileSize |
| The width/height size of tile's on the xz-plane. [Limit: >= 0] [Units: vx]. More... | |
| int | borderSize |
| The size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx]. More... | |
| float | cs |
| The xz-plane cell size to use for fields. [Limit: > 0] [Units: wu]. More... | |
| float | ch |
| The y-axis cell size to use for fields. [Limit: > 0] [Units: wu]. More... | |
| float | bmin [3] |
| The minimum bounds of the field's AABB. [(x, y, z)] [Units: wu]. More... | |
| float | bmax [3] |
| The maximum bounds of the field's AABB. [(x, y, z)] [Units: wu]. More... | |
| float | walkableSlopeAngle |
| The maximum slope that is considered walkable. [Limits: 0 <= value < 90] [Units: Degrees]. More... | |
| int | walkableHeight |
| Minimum floor to 'ceiling' height that will still allow the floor area to be considered walkable. More... | |
| int | walkableClimb |
| Maximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx]. More... | |
| int | walkableRadius |
| The distance to erode/shrink the walkable area of the heightfield away from obstructions. More... | |
| int | maxEdgeLen |
| The maximum allowed length for contour edges along the border of the mesh. [Limit: >=0] [Units: vx]. More... | |
| float | maxSimplificationError |
| The maximum distance a simplified contour's border edges should deviate the original raw contour. More... | |
| int | minRegionArea |
| The minimum number of cells allowed to form isolated island areas. [Limit: >=0] [Units: vx]. More... | |
| int | mergeRegionArea |
| Any regions with a span count smaller than this value will, if possible, be merged with larger regions. More... | |
| int | maxVertsPerPoly |
| The maximum number of vertices allowed for polygons generated during the contour to polygon conversion process. More... | |
| float | detailSampleDist |
| Sets the sampling distance to use when generating the detail mesh. More... | |
| float | detailSampleMaxError |
| The maximum distance the detail mesh surface should deviate from heightfield data. More... | |
Specifies a configuration to use when performing Recast builds.
The is a convenience structure that represents an aggregation of parameters used at different stages in the Recast build process. Some values are derived during the build process. Not all parameters are used for all build processes.
Units are usually in voxels (vx) or world units (wu). The units for voxels, grid size, and cell size are all based on the values of cs and ch.
In this documentation, the term 'field' refers to heightfield and contour data structures that define spacial information using an integer grid.
The upper and lower limits for the various parameters often depend on the platform's floating point accuraccy as well as interdependencies between the values of multiple parameters. See the individual parameter documentation for details.
0.4 and a height of 2.0. | float rcConfig::bmax[3] |
The maximum bounds of the field's AABB. [(x, y, z)] [Units: wu].
| float rcConfig::bmin[3] |
The minimum bounds of the field's AABB. [(x, y, z)] [Units: wu].
| rcConfig::borderSize |
The size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx].
This value represents the the closest the walkable area of the heightfield should come to the xz-plane AABB of the field. It does not have any impact on the borders around internal obstructions.
| rcConfig::ch |
The y-axis cell size to use for fields. [Limit: > 0] [Units: wu].
The voxelization cell height ch is defined separately in order to allow for greater precision in height tests. A good starting point for ch is half the cs value. Smaller ch values ensure that the navmesh properly connects areas that are only separated by a small curb or ditch. If small holes are generated in your navmesh around where there are discontinuities in height (for example, stairs or curbs), you may want to decrease the cell height value to increase the vertical rasterization precision of Recast.
cs and ch define voxel/grid/cell size. So their values have significant side effects on all parameters defined in voxel units.
The minimum value for this parameter depends on the platform's floating point accuracy, with the practical minimum usually around 0.05.
| rcConfig::cs |
The xz-plane cell size to use for fields. [Limit: > 0] [Units: wu].
The voxelization cell size cs defines the voxel size along both axes of the ground plane: x and z in Recast. This value is usually derived from the character radius r. A recommended starting value for cs is either r/2 or r/3. Smaller values of cs will increase rasterization resolution and navmesh detail, but total generation time will increase exponentially. In outdoor environments, r/2 is often good enough. For indoor scenes with tight spaces you might want the extra precision, so a value of r/3 or smaller may give better results.
The initial instinct is to reduce this value to something very close to zero to maximize the detail of the generated navmesh. This quickly becomes a case of diminishing returns, however. Beyond a certain point there's usually not much perceptable difference in the generated navmesh, but huge increases in generation time. This hinders your ability to quickly iterate on level designs and provides little benefit. The general recommendation here is to use as large a value for cs as you can get away with.
cs and ch define voxel/grid/cell size. So their values have significant side effects on all parameters defined in voxel units.
The minimum value for this parameter depends on the platform's floating point accuracy, with the practical minimum usually around 0.05.
| float rcConfig::detailSampleDist |
Sets the sampling distance to use when generating the detail mesh.
(For height detail only.) [Limits: 0 or >= 0.9] [Units: wu]
| float rcConfig::detailSampleMaxError |
The maximum distance the detail mesh surface should deviate from heightfield data.
(For height detail only.) [Limit: >=0] [Units: wu]
| int rcConfig::height |
The height of the field along the z-axis. [Limit: >= 0] [Units: vx].
| rcConfig::maxEdgeLen |
The maximum allowed length for contour edges along the border of the mesh. [Limit: >=0] [Units: vx].
In certain cases, long outer edges may decrease the quality of the resulting triangulation, creating very long thin triangles. This can sometimes be remedied by limiting the maximum edge length, causing the problematic long edges to be broken up into smaller segments.
The parameter maxEdgeLen defines the maximum edge length and is defined in terms of voxels. A good value for maxEdgeLen is something like walkableRadius * 8. A good way to adjust this value is to first set it really high and see if your data creates long edges. If it does, decrease maxEdgeLen until you find the largest value which improves the resulting tesselation.
Extra vertices will be inserted as needed to keep contour edges below this length. A value of zero effectively disables this feature.
| rcConfig::maxSimplificationError |
The maximum distance a simplified contour's border edges should deviate the original raw contour.
[Limit: >=0] [Units: vx]
When the rasterized areas are converted back to a vectorized representation, the maxSimplificationError describes how loosely the simplification is done. The simplification process uses the Ramer–Douglas-Peucker algorithm, and this value describes the max deviation in voxels.
Good values for maxSimplificationError are in the range [1.1, 1.5].
A value of 1.3 is a good starting point and usually yields good results. If the value is less than 1.1, some sawtoothing starts to appear at the generated edges. If the value is more than 1.5, the mesh simplification starts to cut some corners it shouldn't.
The effect of this parameter only applies to the xz-plane.
| rcConfig::maxVertsPerPoly |
The maximum number of vertices allowed for polygons generated during the contour to polygon conversion process.
[Limit: >= 3]
If the mesh data is to be used to construct a Detour navigation mesh, then the upper limit is limited to <= DT_VERTS_PER_POLYGON.
| rcConfig::mergeRegionArea |
Any regions with a span count smaller than this value will, if possible, be merged with larger regions.
[Limit: >=0] [Units: vx]
The triangulation process works best with small, localized voxel regions. The parameter mergeRegionArea controls the maximum voxel area of a region that is allowed to be merged with another region. If you see small patches missing here and there, you could lower the minRegionArea value.
| rcConfig::minRegionArea |
The minimum number of cells allowed to form isolated island areas. [Limit: >=0] [Units: vx].
Watershed partitioning is really prone to noise in the input distance field. In order to get nicer areas, the areas are merged and small disconnected areas are removed after the water shed partitioning. The parameter minRegionArea describes the minimum isolated region size that is still kept. A region is removed if the number of voxels in the region is less than the square of minRegionArea.
Any regions that are smaller than this area will be marked as unwalkable. This is useful in removing useless regions that can sometimes form on geometry such as table tops, box tops, etc.
| rcConfig::tileSize |
The width/height size of tile's on the xz-plane. [Limit: >= 0] [Units: vx].
This field is only used when building multi-tile meshes.
| rcConfig::walkableClimb |
Maximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx].
The walkableClimb value defines the maximum height of ledges and steps that the agent can walk up. Given a designer-defined maxClimb distance in world units, the value of walkableClimb should be calculated as ceil(maxClimb / ch).
Note that this is using ch not cs because it's a height-based value.
Allows the mesh to flow over low lying obstructions such as curbs and up/down stairways. The value is usually set to how far up/down an agent can step.
| rcConfig::walkableHeight |
Minimum floor to 'ceiling' height that will still allow the floor area to be considered walkable.
[Limit: >= 3] [Units: vx]
This value defines the worldspace height h of the agent in voxels. Th value of walkableHeight should be calculated as ceil(h / ch). Note this is based on ch not cs since it's a height value.
Permits detection of overhangs in the source geometry that make the geometry below un-walkable. The value is usually set to the maximum agent height.
| rcConfig::walkableRadius |
The distance to erode/shrink the walkable area of the heightfield away from obstructions.
[Limit: >=0] [Units: vx]
The parameter walkableRadius defines the worldspace agent radius r in voxels.
Most often, this value of walkableRadius should be calculated as ceil(r / cs). Note this is based on cs since the agent radius is always parallel to the ground plane.
If the walkableRadius value is greater than zero, the edges of the navmesh will be pushed away from all obstacles by this amount.
A non-zero walkableRadius allows for much simpler runtime navmesh collision checks. The game only needs to check that the center point of the agent is contained within a navmesh polygon. Without this erosion, runtime navigation checks need to collide the geometric projection of the agent's logical cylinder onto the navmesh with the boundary edges of the navmesh polygons.
In general, this is the closest any part of the final mesh should get to an obstruction in the source geometry. It is usually set to the maximum agent radius.
If you want to have tight-fitting navmesh, or want to reuse the same navmesh for multiple agents with differing radii, you can use a walkableRadius value of zero. Be advised though that you will need to perform your own collisions with the navmesh edges, and odd edge cases issues in the mesh generation can potentially occur. For these reasons, specifying a radius of zero is allowed but is not recommended.
| rcConfig::walkableSlopeAngle |
The maximum slope that is considered walkable. [Limits: 0 <= value < 90] [Units: Degrees].
The parameter walkableSlopeAngle is to filter out areas of the world where the ground slope would be too steep for an agent to traverse. This value is defined as a maximum angle in degrees that the surface normal of a polgyon can differ from the world's up vector. This value must be within the range [0, 90].
The practical upper limit for this parameter is usually around 85 degrees.
| int rcConfig::width |
The width of the field along the x-axis. [Limit: >= 0] [Units: vx].