Module directional_navigation

A navigation framework for moving between focusable elements based on directional input.

While virtual cursors are a common way to navigate UIs with a gamepad (or arrow keys!), they are generally both slow and frustrating to use. Instead, directional inputs should provide a direct way to snap between focusable elements.

Like the rest of this crate, the InputFocus resource is manipulated to track the current focus.

Navigating between focusable entities (commonly UI nodes) is done by passing a CompassOctant into the navigate method from the DirectionalNavigation system parameter. Under the hood, an entity is found automatically via brute force search in the desired CompassOctant direction.

If some manual navigation is desired, a DirectionalNavigationMap will override the brute force search in a direction for a given entity. The DirectionalNavigationMap stores a directed graph of focusable entities. Each entity can have up to 8 neighbors, one for each CompassOctant, balancing flexibility and required precision.

Setting up Directional Navigation

Automatic Navigation (Recommended)

The easiest way to set up navigation is to add the AutoDirectionalNavigation component to your UI entities. This component is available in the bevy_ui crate. If you choose to include automatic navigation, you should also use the AutoDirectionalNavigator system parameter in that crate instead of DirectionalNavigation.

Manual Navigation

You can also manually define navigation connections using methods like add_edge and add_looping_edges.

Combining Automatic and Manual

Following manual edges always take precedence, allowing you to use automatic navigation for most UI elements while overriding specific connections for special cases like wrapping menus or cross-layer navigation.

When to Use Manual Navigation

While automatic navigation is recommended for most use cases, manual navigation provides:

• Precise control: Define exact navigation flow, including non-obvious connections like looping edges
• Cross-layer navigation: Connect elements across different UI layers or z-index levels
• Custom behavior: Implement domain-specific navigation patterns (e.g., spreadsheet-style wrapping)

Structs

AutoNavigationConfig

Configuration resource for automatic directional navigation and for generating manual navigation edges via auto_generate_navigation_edges

DirectionalNavigation

A system parameter for navigating between focusable entities in a directional way.

DirectionalNavigationMap

A resource that stores the manually specified traversable graph of focusable entities.

DirectionalNavigationPlugin

A plugin that sets up the directional navigation resources.

FocusableArea

A focusable area with position and size information.

NavNeighbors

The up-to-eight neighbors of a focusable entity, one for each CompassOctant.

Enums

DirectionalNavigationError

An error that can occur when navigating between focusable entities using directional navigation.

Traits

Navigable

Trait for extracting position and size from navigable UI components.

Functions

auto_generate_navigation_edges

Automatically generates directional navigation edges for a collection of nodes.