A generic UI navigation algorithm meant to be adaptable to any UI library, but currently limiting itself to targeting the Bevy engine default UI library.
toml
[dependencies]
bevy-ui-navigation = "0.10.0"
The in-depth design specification is available here.
Check out the examples directory for bevy examples.
Ultimate navigation example demo
This crate exposes the bevy-ui feature. It is enabled by default. Toggling
off this feature let you compile this crate without requiring the bevy render
feature. But you won't be able to use FocusableButtonBundle, and you'll have
to use generic_default_mouse_input for mouse input and define special spacial
components to get it working.
See this example for a quick start guide.
You just have a collection of buttons displayed on screen and you want the
player to be able to select between them with their controller? Simply use the
bevy_ui_navigation::components::FocusableButtonBundle instead of
ButtonBundle. The navigation system is capable of switching focus based on
the 2D position of each focusable element.
This won't work out of the box though, you must wire the UI to the control
scheme, by sending requests to the NavRequest event queue. We do not provide
out of the box a way to do this, but we provide default input handling systems.
Try this:
rust
use bevy_ui_navigation::systems::{default_gamepad_input, default_keyboard_input, InputMapping};
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugin(NavigationPlugin)
.init_resource::<InputMapping>()
.add_system(default_keyboard_input)
.add_system(default_gamepad_input)
.run();
}
The default button mapping may not be what you want, or you may want to change it
in-game (for example when the user is in an input mapping menu) The controls
are modifiable with the InputMapping resource. Check out the doc for it for
more details.
Check the examples directory for more example code.
To respond to relevant user input, for example when the player pressed the
"Action" button when focusing start_game_button, you should read the
NavEvent event queue:
rust
fn handle_nav_events(mut events: EventReader<NavEvent>, game: Res<Gameui>) {
use bevy_ui_navigation::{NavEvent::NoChanges, NavRequest::Action};
for event in events.iter() {
match event {
NoChanges { from, request: Action } if from.first() == game.start_game_button => {
// Start the game on "A" or "ENTER" button press
}
_ => {}
}
}
}
The focus navigation works across the whole UI tree, regardless of how or where
you've put your focusable entities. You just move in the direction you want to
go, and you get there.
In truth, FocusableButtonBundle is just a ButtonBundle with an extra
Focusable component field.
Any Entity can be converted into a focusable entity by adding the Focusable
component to it. To do so, just:
rust
commands.entity(my_entity).insert(Focusable::default());
That's it! Now my_entity is part of the navigation tree. The player can
select it with their controller the same way as any other Focusable element.
You probably want to render the focused button differently than other buttons,
this can be done with the Changed<Focusable> query parameter as follow:
rust
fn button_system(
materials: Res<Materials>,
mut focusables: Query<(&Focusable, &mut Handle<ColorMaterial>), Changed<Focusable>>,
) {
for (focus_state, mut material) in focusables.iter_mut() {
if focus_state.is_focused() {
*material = materials.focused.clone();
} else {
*material = materials.inert.clone();
}
}
}
NavMenusSuppose you have a more complex game with menus sub-menus and sub-sub-menus etc.
For example, in your everyday 2021 AAA game, to change the antialiasing you
would go through a few menus:
game menu → options menu → graphics menu → custom graphics menu → AA
In this case, you need to be capable of specifying which button in the previous
menu leads to the next menu (for example, you would press the "Options" button
in the game menu to access the options menu).
For that, you need to use the NavMenu component.
1. First you need a "root" NavMenu. This is a limit of the navigation
algorithm (which may be fixed in the future)
2. You also need the Entity value of your "Options" button
3. You then add a NavMenu::reachable_from(options_button) to the
NodeBundle containing all the options menu Focusable entities.
This may look like this:
```rust
let menu = NodeBundle {
style: Style { flexdirection: Column, ..Default::default()},
..Default::default()
};
let button = FocusableButtonBundle::from(ButtonBundle {
material: Color::rgb(1.0, 0.3, 1.0).into(),
..Default::default()
});
let mut spawnbutton = |bundle: &FocusableButtonBundle| {
commands.spawnbundle(bundle.clone()).id()
};
let optionsbutton = spawn(&button);
// Spawn the game menu !!vvvvvv!! let gamemenu = commands.spawn(menu).insert(NavMenu::root()).id(); commads.entity(optionsbutton).insert(Parent(gamemenu)); commads.entity(gamebutton).insert(Parent(gamemenu)); commads.entity(quitbutton).insert(Parent(gamemenu)); commads.entity(loadbutton).insert(Parent(game_menu));
// Spawn the options menu let optionsmenu = commands .spawn(menu) // !!vvvvvvvvvvvvvvvvvvvvvvvvvvvvvv!! .insert(NavMenu::reachablefrom(optionsbutton)) .id(); commads.entity(graphicsoptionbutton).insert(Parent(optionsmenu)); commads.entity(audiooptionsbutton).insert(Parent(optionsmenu)); commads.entity(inputoptionsbutton).insert(Parent(optionsmenu)); commads.entity(gameplayoptionsbutton).insert(Parent(options_menu)); ```
With this, your game menu will be isolated from your options menu, you can only
access it by sending the NavRequest::Action when options_button is focused,
or by sending a NavRequest::FocusOn(input_options_button).
Specifically, navigation between Focusable entities will be constrained to
other Focusable that are children of the same NavMenu. It creates a
self-contained menu.
NavRequest::FocusOnYou can't directly manipulate which entity is focused, because we need to keep
track of a lot of thing on the backend to make the navigation work as expected.
But you can set the focused element to any arbitrary entity with the
NavRequest::FocusOn request.
NavMenu settingsA NavMenu doesn't only define menu-to-menu navigation, but it also gives you
finner-grained control on how navigation is handled within a menu.
NavMenu::{cycle, closed} controls whether or not going left from the
leftmost element goes to the rightmost and vis-versa. NavMenu::scope
sets the menu as a sort of global control menu. It catches NavRequest::ScopeMove
requests even when the focused entity is in another sub-menu reachable from this
menu. This behaves like you would expect a tabbed menu to behave. See the
"ultimate" menu navigation
example
for a demonstration.
0.8.2: Fix offsetting of mouse focus with UiCameras with a transform set
to anything else than zero.0.9.0: Add Focusable::cancel (see documentation for details); Add warning
message rather than do dumb things when there is more than a single NavRequest
per frame0.9.1: Fix #8, Panic on diagonal gamepad input0.10.0: Add the bevy-ui feature, technically this includes breaking
changes, but it is very unlikely you need to change your code to get it
working
default_mouse_input, it now has
additional parametersui_focusable_at and NodePosQuery now have type parametersCopyright © 2021 Nicola Papale
This software is licensed under either MIT or Apache 2.0 at your leisure. See LICENSE file for details.