[This is preliminary documentation and is subject to change.]

The IncrementalBuilder implements a flexible build process that can be used at design time to create PolyMesh and PolyMeshDetail objects. INMGenProcessor's are used to customize the process for almost any need.

Note:

This builder is not suitable for use at run-time since it is designed for flexibility rather than high performance.

There are a lot of configuration settings to deal with during the build process. See the NMGenParams documentation for details, including recommendations.

Only one builder is needed if the navigation mesh will contain only a single tile. Multi-tile meshes require one builder for each tile. (Builders are single use.)

CopyC#
// Example: A simple NMGen build.

// Where 'mesh' is a TriangleMesh object containing all of the input triangles
// and 'config' is a NMGenParams object containing the configuration.

// Create an input geometry object.
byte[] areas = NMGen.CreateDefaultAreaBuffer(mesh.triCount);
InputGeometryBuilder gbuilder = InputGeometryBuilder.Create(mesh, areas, 45.5f);
gbuilder.BuildAll();
InputGeometry geom = gbuilder.Result;

// Create the incremental builder.
NMGenAssetFlag resultFlags = NMGenAssetFlag.PolyMesh | NMGenAssetFlag.DetailMesh;
IncrementalBuilder builder = IncrementalBuilder.Create(config
        , resultFlags
        , geom
        , ProcessorSet.CreateStandard(ProcessorSet.StandardOptions));

// Perform the build and check the result.
builder.BuildAll();

switch (builder.State)
{
        case NMGenState.Aborted:

                // Handle the error.
                // Check builder messages for details.

        case NMGenState.Complete:

                NMGenAssets result = builder.Result;

                // Use the poly and detail mesh data.

        case NMGenState.NoResult:

                // No result was produced.  
                // Unexpected for single-tile builds.  Not uncommon for multi-tile builds.
                // Check builder messages for details.
}

The Process

The incremental builder follows the process described by The Core Build Process topic.

Standard NMGen Build

The Polygon Mesh

The IncrementalBuilder's main output is a PolyMesh object. The polygon mesh is made up of convex polygons with between three and MaxAllowedVertsPerPoly vertices. Each polygon includes edge link, area, flag data.

Polygons may overlap, based on the value of WalkableHeight used during the build.

At the end of the build process all polygons should have at least one flag set. Usually DefaultFlag.

All polygons will have a non-zero area id. (<= MaxArea)

Poly Mesh-Basic

The Detail Mesh

An common optional output of the IncrementalBuilder is a PolyMeshDetail object.

Pathfinding only uses the PolyMesh. For storage efficiency and speed the polygon mesh doesn't have a lot of height accuracy. But some secondary navigation features require more accurate height data. The detail mesh provides the extra detail.

The detail mesh consists of sub-meshes, one for each polygon in the polygon mesh. Each sub-mesh is a triangle mesh that contains all the vertices of its associated polygon, plus additional vertices that provide the extra height detail.

The NMGen Processors

The NMGen processors provided by the ProcessorSet are what give the incremental builder its flexibility and power. Without any processors, only a very simple polygon mesh can be created.

Processors are called during the post-processor step of each stage, in ascending priority. A processor may perform processing during a single stage or multiple stages.

Any oject that implements INMGenProcessor can act as a processor. The NMGenProcessor abstract class provides a good base to start from.

Two common uses for processors include polygon area and flag assignment.

Area Assignment

Area assignment can happen via the InputGeometry object. But sometimes that isn't convenient or possible. Another choice is to mark areas into the compact heightfield. You can use the AreaBoxMarker, AreaCylinderMarker, and AreaConvexMarker processors to do this.

Because processors are prioritized, area markers can overwrite each other in useful ways. For example, lets say you have a swamp area with a dry island contained within it. The swamp area needs to be assigned one area while the island needs to be a assigned a different area. If you mark the swamp, the island will be included. This can't be helped since all markers are convex. But by marking the island with a higher priority marker, it will be assigned the proper area.

Another powerful use of area markers is applying NullArea. Sometimes the build process will create polygons in areas you don't like. For example, there may be clutter on the ground that can technically be walked across, but looks bad when it is. If you mark the area with NullArea, then the area will be excluded from the final polygon mesh.

Polygon Flag Assignment

Polygon flags can be managed entirely in the Navmesh object. But sometimes the flags are best assigned to the PolyMesh during the build process. For example, you may want to assign the 'swim' flag to all 'water' area polygons.

The ApplyPolygonFlags processor can be used to add flags to all polygons.

The AreaFlagMapper processor can be used to add flags to polygons based on the area id of each polygon.

See Also