Navigation3D programmatic API

Most gameplay should use components and EBuses (see Querying). This page covers when to call the L1 core directly, with a minimal example.

When to use L1 directly

Good fits:

Headless tools, offline processing, custom pipelines;
Unit tests that must not depend on EBuses / assets / PhysX;
Frame-sliced Step pathfinding outside the component layer.

L1 (SvoBuilder / SvoVolume / SvoPathfinder) depends only on AzCore. Volumes are immutable after build and safe for concurrent reads. Coordinates are volume-local single precision (see Core concepts).

Minimal build + pathfind

#include <Navigation3D/SvoBuilder.h>
#include <Navigation3D/SvoVolume.h>
// SvoPathfinder lives under Source/Core (linked on the component path)

Navigation3D::SvoBuildInput input;
// input.m_vertices / m_indices = triangle soup

Navigation3D::SvoBuildConfig config;
config.m_leafVoxelSize = 0.5f;
config.m_agentRadius = 0.5f;

AZ::Aabb localBounds = /* . */;
Navigation3D::SvoVolume volume =
 Navigation3D::SvoBuilder::Build(input, localBounds, config);

if (volume.IsValid())
{
 bool free = volume.IsFree(localPos);
 bool los = volume.RaycastFree(a, b);
 // FindNearestFreeCell / CapsuleFree / SampleRandomFreeCell .
}

For multiple tiers sharing one occupancy field: Voxelize once, then BuildFromOccupancy per radius.

Validation

AZStd::string error;
if (!Navigation3D::ValidateVolumeInvariants(volume, &error))
{
 // error describes which invariant failed
}

Same source as console nav3d_validateVolume.

Runtime facade (optional)

Components usually use INavigation3DRuntime automatically. Custom systems can:

if (auto* runtime = AZ::Interface<Navigation3D::INavigation3DRuntime>::Get())
{
 AZ::EntityId vol = runtime->FindVolumeContaining(worldPos);
 // domain-link registry, enqueue / cancel async flight queries, etc.
}

Tests and deeper docs

Gems/Navigation3D/Code/Tests/ covers voxelization, pathfinding, cross-chunk, Hybrid, follow, Climb, HTN, and more. Determinism contract: Core concepts.

Back to the handbook: Overview · Getting started · Debugging.