Navigation servers

Purpose

NavigationServer2D and NavigationServer3D provide pathfinding over navigation meshes and 2D polygon-based navigation regions. The servers own the navigation maps, regions, links, agents, and obstacles; the scene tree side (NavigationAgent*, NavigationRegion*, NavigationLink*, NavigationObstacle*) is a thin wrapper that talks to the servers.

Directory layout

servers/navigation_2d/                 NavigationServer2D + impls
servers/navigation_3d/                 NavigationServer3D + impls
servers/nav_heap.h                     Shared min-heap used by A* expansion
modules/navigation_2d/                 The active 2D backend
modules/navigation_3d/                 The active 3D backend (Recast-based for navmesh baking)
scene/2d/navigation/                   NavigationAgent2D, NavigationRegion2D, NavigationLink2D, NavigationObstacle2D
scene/3d/navigation/                   NavigationAgent3D, NavigationRegion3D, NavigationLink3D, NavigationObstacle3D

The 2D and 3D APIs look the same; the 3D side adds navmesh baking via Recast (thirdparty/recastnavigation/).

Core concepts

Concept	Owns	Notes
Map	A complete navigation world	Each World2D and World3D has its own map RID. Multiple maps can coexist for split-screen or layered worlds.
Region	A polygon mesh contributing navigation polygons	Created from a NavigationPolygon (2D) or NavigationMesh (3D) resource. Regions are merged into the map when their bounds touch.
Link	A directed edge between two points on the map	Used for jumps, ladders, teleporters — anything that bridges regions without polygons.
Agent	A moving navigation client	Owns a position, velocity, radius, height. The server computes velocity adjustments via RVO (reciprocal velocity obstacles) and reports back per-agent target velocities.
Obstacle	A dynamic navigation blocker	Used for movable obstacles that should not be baked into a region (e.g., other characters).

Pathfinding

Pathfinding is A* on the polygon graph induced by region edges. The min-heap shared by 2D and 3D lives in servers/nav_heap.h. Path queries are serviced through NavigationServer*::map_get_pathandNavigationPathQueryParameters* resources (scene/resources/navigation_path_query*).

graph LR
    Region1[NavigationRegion3D<br/>baked from MeshInstance3D] --> Map[Navigation Map]
    Region2[NavigationRegion3D] --> Map
    Link[NavigationLink3D] --> Map
    Map --> A[A* graph]
    Agent[NavigationAgent3D] -->|map_get_path| A
    A -->|sequence of polygons| Agent
    Map -->|RVO| Agent

Avoidance (RVO)

The 3D server integrates RVO2 (vendored under thirdparty/recastnavigation/RVO2) for local avoidance. Each agent registers its preferred velocity via NavigationAgent3D::set_velocity; the server runs RVO to compute a "safe" velocity for the next tick that avoids other agents and obstacles. The corrected velocity is reported back through the agent's velocity_computed signal.

The 2D server has its own RVO2-based implementation under modules/navigation_2d/.

Baking

For 3D, navmesh baking happens via Recast. The bake pipeline:

1. Collect source geometry from the scene (MeshInstance3D nodes inside a NavigationRegion3D or via the editor's bake tool).
2. Voxelize into a heightfield with the configured cell size and step height.
3. Run region segmentation, contour tracing, polygon decomposition.
4. Output a NavigationMesh resource that the region uses at runtime.

Source code: modules/navigation_3d/navigation_mesh_generator.cpp. The editor exposes the bake button on NavigationRegion3D selection.

For 2D, polygons are authored directly (drawing with the NavigationPolygon editor tool or assigned from TileSet navigation layers) and baked via simpler boolean polygon ops.

Key abstractions

Abstraction	File	Role
NavigationServer3D / NavigationServer2D	servers/navigation_server_*.h	Public API
NavigationMesh (3D) / NavigationPolygon (2D)	scene/resources/navigation_mesh*.cpp	Serializable mesh resources
NavigationPathQueryParameters3D/2D	scene/resources/	Path query input
NavigationPathQueryResult3D/2D	scene/resources/	Path query output
NavigationAgent3D/2D	scene/3d/navigation/, scene/2d/navigation/	Per-character path follower with RVO
NavigationRegion3D/2D	scene tree nodes	Wraps a region RID + a mesh resource
NavigationLink3D/2D	scene tree nodes	Wraps a link RID with start/end transforms
NavigationObstacle3D/2D	scene tree nodes	Wraps an obstacle RID for dynamic avoidance

Integration points

• Each Viewport's World*D has its own map RID; Viewport::get_world_2d/3d()->get_navigation_map() returns it.
• NavigationAgent3D integrates with CharacterBody3D by computing desired_velocity → safe_velocity and feeding that into move_and_slide.
• The editor displays navmesh debug visuals via DebugNavigationMeshSettings and the navigation panel in the 3D viewport.

Entry points for modification

• Tuning bake parameters → see NavigationMesh::set_cell_size, set_agent_height, set_agent_max_climb etc.; these map to Recast's parameters.
• Custom path post-processing → NavigationServer3D::map_set_use_edge_connections plus a custom NavigationPathQueryParameters3D::path_postprocessing hook (smoothing options).
• New navigation client primitives → subclass the relevant scene-side node and register a new server-side helper. The server itself is largely a thin wrapper around the backend (modules/navigation_*).