Navigation3D querying

All “ask for a path” EBuses are AZ::ComponentBuss addressed by the target entity’s EntityId.

Which bus to use

Need cross ground / air / climb?
 Yes → NavigationQueryRequestBus (HybridNavigationComponent)
 No, flight only → FlightNavigationRequestBus (FlightNavigationComponent)
 No, climb only → ClimbNavigationRequestBus (ClimbNavigationComponent)

Only occupancy / clearance / snap?
 → NavigationVolumeRequestBus (SvoNavigationVolumeComponent)

Gameplay code should prefer the unified facade (double precision, multi-domain, sync + async).

NavigationQueryRequestBus (unified facade)

Implemented by HybridNavigationComponent.

Path queries

#include <Navigation3D/NavigationQueryBus.h>

Navigation3D::NavigationQueryConfig cfg;
cfg.m_agentRadius = 0.5f;
cfg.m_postProcessor = Navigation3D::FlightPostProcessorType::Hover;

Navigation3D::NavigationPath path;
Navigation3D::NavigationQueryRequestBus::EventResult(
 path, agentEntityId,
 &Navigation3D::NavigationQueryRequests::FindPath,
 Navigation3D::NavigationDomain::Air, fromD, toD, cfg);

for (const auto& wp : path.m_waypoints)
{
 // wp.m_position (Vector3d), wp.m_domain, wp.m_flag (TakeOffAt / LandAt)
}

Async: FindPathAsync returns a NavigationQueryHandle; results arrive on NavigationQueryNotificationBus::OnPathReady. Cancel with CancelPath.

Spatial primitives

Sync	Async	Purpose
`FindNearestFreePosition`	`*Async`	Snap to nearest free position in radius
`FindDistanceToObstacle`	`*Async`	Clearance to nearest obstacle
`IsReachable`	`*Async`	Whether two points are reachable
`FindRandomReachablePoint`	`*Async`	Sample a reachable point with a seed

NavigationQueryConfig highlights

Field	Default	Purpose
`m_agentRadius`	`0.5`	Pick radius tier
`m_postProcessor`	`Hover`	Motion model
`m_priority`	`Normal`	Async priority Low / Normal / High
`m_heightBandLow/High` / `m_heightPenaltyPerMeter`	`0`	Height-band preference
`m_allowFreeVerticalTransfer` / `m_transferCostScale`	`false` / `1.0`	VTOL and link cost
`m_preferredLinks` / `m_forbiddenLinks`	empty	Prefer / forbid domain-link entities
`m_detourEntity` etc.	invalid	Override per-domain backend entities

NavigationPathResult::IsSuccess() equals m_reason == FlightFailureReason::None.

FlightNavigationRequestBus (flight agent)

// Sync (single-precision world)
FindFlightPathBetweenPositions(from, to)
FindFlightPathBetweenPositionsD(fromD, toD) // double
FindFlightPathBetweenEntities(fromId, toId)

// Async
FindFlightPathAsync(FlightQueryConfig) → FlightQueryHandle
CancelFlightPath(handle)
// Result: FlightNavigationNotificationBus::OnFlightPathReady

Async example:

Navigation3D::FlightQueryConfig q;
q.m_from = fromWorld;
q.m_to = toWorld;
q.m_priority = Navigation3D::FlightQueryPriority::High;

Navigation3D::FlightQueryHandle handle;
Navigation3D::FlightNavigationRequestBus::EventResult(
 handle, agentEntityId,
 &Navigation3D::FlightNavigationRequests::FindFlightPathAsync, q);

Also: IsReachable / IsReachableD, FindRandomReachablePoint / *D.

NavigationVolumeRequestBus (volume data plane)

Build and readiness

RebuildVolume();
RebuildRegion(const AZ::AabbD& region);
bool IsVolumeReady() const;
SetActiveRegion(const AZ::AabbD& worldRegion); // streaming pages

Occupancy and spatial queries

IsPositionFree / IsPositionFreeD, FindNearestFreePosition(D), FindDistanceToObstacle(D). outDistance == maxDistance means clearance ≥ maxDistance.

Runtime cost field

AddCostModifierVolume / AddCostModifierBox / AddTimeVaryingCostModifierVolume / UpdateCostModifierMultiplier / RemoveCostModifierVolume. multiplier < 1 prefers, > 1 penalizes, ≥ ~1e9 is no-fly. Prefer declarative components—see Authoring and baking.

Notification: OnNavigationVolumeReady.

Sync vs async

	Sync	Async
When it returns	Same frame: pathfind + post-process	Immediately with a handle; advances across frames
Use when	Low frequency / small volumes	High frequency / large maps / many agents
Results	Direct return value	Notification-bus callbacks
Cancel	—	`CancelPath` / `CancelFlightPath`

Results match (determinism contract); async only changes completion time. Budgets in Debugging.

ClimbNavigationRequestBus (climb)

v1 is sync only—no async / notification bus.

RebuildSurface();
bool IsSurfaceReady() const;
bool IsPositionClimbable(D)(.);

FindClimbPathBetweenPositions(from, to); // polyline
FindClimbTrajectoryBetweenPositions(from, to); // with normal / tangent / speed
FindClimbPathBetweenPositionsD / FindClimbTrajectoryBetweenPositionsD

Trajectory kinematics in Motion and following.

Script bindings (ScriptCanvas / Lua)

Request / notification buses with notifications are reflected via BehaviorContext. Examples:

NavigationQueryNotificationBus: OnPathReady / OnSpatialQueryReady
FlightPathFollowNotificationBus: OnDesiredVelocityUpdated / OnPathCompleted / OnPathDeviated / OnPathBlocked / OnAvoidanceFailed
NavigationDomainLinkRequestBus: getters / SetEnabled (category Navigation3D)

self.queryHandler = NavigationQueryNotificationBus.Connect(self, self.entityId)
function MyAgent:OnPathReady(handle, result)
 if result:IsSuccess() then
 -- consume result.m_path / result.m_flightTrajectories
 end
end

Next steps

Authoring and baking — cost zones / corridors / links / Bake
Motion and following — turn results into motion
Programmatic API — pathfind without components