Navigation regions: resources, transforms and disabling
Place navigation geometry and update retained routes correctly.
NavigationRegion2D places a NavigationPolygon resource on a map; NavigationRegion3D uses NavigationMesh. Adding a region Entity alone does not create traversable geometry: its resource needs actual polygons. A visual floor model or physics collider does not replace that data.
Prepare a region
- Add a region of the correct dimension to the level.
- Assign a
NavigationPolygonorNavigationMeshwith prepared data. Use navigation baking to build it from source geometry. - Check the region map through
GetNavigationMap(), its layers andEnabled. - After publication, query a path within the surface, then test a transition to a neighboring region.
Direct server usage follows the same order: RegionCreate, resource assignment with RegionSetNavigationPolygon or RegionSetNavigationMesh, then RegionSetMap. Your code releases directly created RIDs. An ordinary region Entity manages its own RID; obtain it with GetRid() but do not free it separately.
Map, placement and layers
A region belongs to one map. See the complete map helper for migration and explicit procedural-region ownership.
The region transform places its navigation vertices in map space. In the executed fixture, translating by (10, 0) shifted bounds and broke the connection; restoring the identity transform restored the route. Scaling X by 2 doubled server-geometry width. A blanket claim that scale is ignored is therefore incorrect for the checked 2D server.
Transforming prepared geometry does not recalculate baked character clearance. Revisit parameters and rebake after changing source-level dimensions. Updating navigation transforms also does not carry a physical passenger on a moving platform: movement and attachment remain game responsibilities.
NavigationLayers is a query-access mask rather than physics layers. See navigation layers for masks and numbering.
Disabling and old routes
RegionSetEnabled(region, false) or Enabled = false excludes the region from new searches after the map updates. An existing path array remains unchanged. In the fixture, the old array still ended in the disabled region while a new search no longer found a complete route.
After disabling a door, platform or level section, decide which characters must request a new route. A region change does not stop existing movement or rewrite retained point arrays.
Diagnose problems
- A region exists but no path does: check polygon count, map, layers and data publication.
- Paths work within regions but not between them: inspect edge connections.
- A character follows an old route after disabling: query again and handle an unreachable result.
- Geometry is offset: distinguish resource-local vertices from the region transform.
Executed 2D server checks cover disabling/enabling, retained path arrays, translation, scale and restored connections. A baked resource was checked in 3D. Editor placement, platform physics and 3D scale were not tested by this suite.