Creating a 2‑D Navigation Mesh in Godot 4.0 with NavigationServer2D: A Practical Guide

Desired Outcome

By the end of this guide you will have a fully functional 2‑D navigation mesh that allows NavigationAgent2D nodes to path‑find around both static and moving obstacles in a Godot 4.0 project. The mesh will be visible in the editor’s debug overlay, and agents will automatically recalculate paths when obstacles appear or move.

Prerequisites

• Godot Engine 4.0 or newer.
• Basic familiarity with the Godot editor and GDScript.
• A 2‑D scene with at least one NavigationAgent2D node.
• Understanding that NavigationPolygon is the core data structure for 2‑D navigation in Godot 4.

Step 1: Build the Navigation Polygon

Navigate to the editor’s Navigation panel and create a new NavigationPolygon resource. You can do this via the Polygon2D node or directly in code. Below is a script that creates a simple rectangular polygon and assigns it to a NavigationRegion2D node:

# res://NavigationSetup.gd
extends Node2D

func _ready():
    var poly = NavigationPolygon.new()
    # Define four corners of a rectangle
    var points = [Vector2(-200, -100), Vector2(200, -100), Vector2(200, 100), Vector2(-200, 100)]
    poly.add_outline(points)
    poly.make_polygons_from_outlines()

    var region = NavigationRegion2D.new()
    region.navigation_polygon = poly
    add_child(region)

Place this script on a node that is a child of the main scene root. The polygon will automatically be registered with NavigationServer2D when the region is added to the scene tree.

Step 2: Register with NavigationServer2D

When a NavigationRegion2D node is added to the scene, Godot internally calls NavigationServer2D.map_add_region() to make the polygon visible to agents. No manual API call is necessary unless you need to update the polygon at runtime. To modify the polygon after the game starts, use:

var server = NavigationServer2D
var region_id = server.map_get_region_id(region)
server.region_set_navigation_polygon(region_id, new_polygon)

Step 3: Configure the NavigationAgent2D

Attach a NavigationAgent2D to your AI character. Configure its radius, height, and max_speed to match the character’s physical dimensions. The following table summarizes typical values:

Parameter	Description	Typical Value
radius	Half the width of the agent’s collision shape.	16
height	Not used in 2‑D but required by the API; set to 0.	0
max_speed	Maximum movement speed in pixels per second.	200
target_desired_distance	How close to the target before stopping.	8
avoidance_enabled	Turn on local avoidance between agents.	true

In GDScript, set these values in _ready():

var agent = $NavigationAgent2D
agent.radius = 16
agent.max_speed = 200
agent.target_desired_distance = 8
agent.avoidance_enabled = true

Step 4: Adding Dynamic Obstacles

For moving obstacles, use NavigationObstacle2D. These nodes temporarily block the navigation mesh. Create one in the editor or via script:

var obstacle = NavigationObstacle2D.new()
obstacle.radius = 32
obstacle.height = 0
obstacle.collision_layer = 1
obstacle.collision_mask = 1
add_child(obstacle)

When the obstacle moves, the navigation server automatically updates the mesh. If you need to add or remove obstacles at runtime, simply add or free the node.

Step 5: Debugging and Runtime Checks

Enable the navigation debug overlay in the editor: Debug > Navigation > Show Navigation Polygons. This displays the mesh and the paths calculated by agents.

• Verify the mesh: Each region should be highlighted in a distinct color. If no polygons appear, check that the NavigationRegion2D is correctly parented and that the polygon is not empty.
• Agent path: Run the game, set a target position for the agent with agent.set_target_position(target), and observe the drawn path. It should bend around static obstacles and adapt when a NavigationObstacle2D moves.
• Console warnings: Look for NavigationServer2D warnings such as “no path found” or “invalid target”. These indicate that the target lies outside the navigable area.
• Performance: Monitor FPS. If you notice a drop, consider splitting large polygons or reducing the number of dynamic obstacles.

Step 6: Fallback and Recovery

Agents that cannot find a path should fall back to a simple behavior: stop moving or wander randomly. In GDScript, handle the path_found signal:

func _ready():
    agent.connect("path_changed", self, "_on_path_changed")

func _on_path_changed():
    if agent.get_current_path().size() == 0:
        # No path – perform fallback
        agent.set_velocity(Vector2.ZERO)
        # Optional: trigger a random walk
        _start_random_wander()

To recover from a missing navigation region, you can rebuild the polygon in _process() or reload the scene. Avoid frequent rebuilds to maintain performance.

Limitations & Best Practices

• Mixing Godot 3.x navigation nodes with Godot 4.0’s NavigationServer2D causes runtime errors. Use only the 4.x API.
• Large convex polygons inflate memory usage. Split complex shapes into multiple smaller polygons.
• Agents with a radius smaller than the obstacle clearance may still intersect obstacles. Adjust the radius to match the collider size.
• Dynamic obstacles only affect the mesh if they are added to the scene tree. Removing them without freeing the node will leave stale data.

By following these steps, you can create a robust 2‑D navigation system that scales from simple static maps to complex, obstacle‑rich environments.