Obstacles: avoidance, baking and carve

A navigation obstacle has two independent roles: avoidance participation and baking input. It is not a physics collider. Adding NavigationObstacle2D to a running level does not automatically cut a hole into prepared navigation.

Choose a mechanism

AffectNavigationMesh allows the obstacle Entity to contribute when source geometry is parsed for baking. CarveNavigationMesh chooses its cutting behavior during that bake. Changing these flags does not itself parse geometry or update an assigned resource.

AvoidanceEnabled independently enables avoidance participation. Radius defines a dynamic obstacle circle; vertices define a static outline. Moving a static outline requires its data to be updated; do not treat it as a physics wall or a guarantee of passing a dense crowd. Avoidance layers and navigation layers are different masks.

Checked 2D obstacle bake

Save ObstacleBake2D.cs in a Reckfell 1.0.0 C# project:

using Reckfell;
using System;

public static class ObstacleBake2D
{
    public static NavigationPolygon Bake(bool carve)
    {
        using var source = new NavigationMeshSourceGeometryData2D();
        source.AddTraversableOutline(new[]
        {
            new Vector2(0, 0), new Vector2(20, 0),
            new Vector2(20, 10), new Vector2(0, 10)
        });
        source.AddProjectedObstruction(new[]
        {
            new Vector2(8, 3), new Vector2(12, 3),
            new Vector2(12, 7), new Vector2(8, 7)
        }, carve);
        var polygon = new NavigationPolygon { AgentRadius = 1, CellSize = 1 };
        NavigationServer2D.BakeFromSourceGeometryData(polygon, source);
        if (polygon.GetPolygonCount() > 0) return polygon;
        polygon.Dispose();
        throw new InvalidOperationException("Obstacle bake produced no polygons.");
    }
}

The traversable area is 20×10; the rectangular obstruction occupies x=8–12, y=3–7. Call Bake(true) or Bake(false), assign the returned resource to a region and wait for map publication. This source-data helper needs no obstacle Entity in the tree. The caller owns its returned resource.

With carve = true, cutting occurs after the AgentRadius offset: the cut outline itself receives no additional radius clearance. With false, the obstruction participates in normal offsetting, increasing the forbidden area. Carve is not an automatic way to provide physical-body clearance near a cut edge.

In the executed check, a route from (2, 5) to (18, 5) went around the cut after explicit baking. The obstruction center (10, 5) was outside navigation. The non-carved version with agent radius 1 had a greater center-to-nearest-surface distance.

What does not change the route

The check first added a NavigationObstacle2D Entity with AffectNavigationMesh = true and avoidance enabled. MapGetPath on the old resource stayed straight. The route changed only after explicit baking and assignment of the new resource.

Continual rebaking may be inappropriate for a moving object. Use avoidance for velocity adjustments, and consider a navigation link for doors or special transitions. Either choice still requires stuck-character and unreachability handling.

Diagnose problems

• An obstacle does not change paths: check that it was parsed and rebaked; one flag does not update a resource.
• An agent ignores it: check map, AvoidanceEnabled, layers/masks and use of VelocityComputed in the agent example.
• A body clips the cut edge: check carve mode, baking radius and physics shape.
• A route exists around it but the character walks straight: refresh the retained route after new geometry publication.

Executed checks cover no automatic rebake, the exact source-data helper, the detour and carve true/false differences in 2D. Obstacle Entity parsing was checked against source; static avoidance, dense crowds, 3D obstacles and performance were not executed.