diff --git a/Readme.md b/Readme.md index ae7eb2f..72fcf5e 100644 --- a/Readme.md +++ b/Readme.md @@ -1,8 +1,8 @@ # Bevy UI navigation -[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking) +[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://bevyengine.org/learn/quick-start/plugin-development/#main-branch-tracking) [![Latest version](https://img.shields.io/crates/v/bevy_ui_navigation.svg)](https://crates.io/crates/bevy_ui_navigation) -[![MIT/Apache 2.0](https://img.shields.io/badge/license-MIT%2FApache-blue.svg)](./LICENSE) +[![MIT/Apache 2.0](https://img.shields.io/badge/license-MIT%2FApache-blue.svg)](./licenses) [![Documentation](https://docs.rs/bevy-ui-navigation/badge.svg)](https://docs.rs/bevy-ui-navigation/) A generic UI navigation algorithm for the @@ -15,13 +15,12 @@ bevy-ui-navigation = "0.33.1" The in-depth design specification is [available here][rfc41]. -### Examples +## Examples Check out the [`examples`][examples] directory for bevy examples. ![Demonstration of "Ultimate navigation" example](https://user-images.githubusercontent.com/26321040/141612751-ba0e62b2-23d6-429a-b5d1-48b09c10d526.gif) - ## Cargo Features This crate exposes the `cuicui_dsl` feature. Disabled by default. Enabling it @@ -47,7 +46,6 @@ doesn't include many examples. This page contains most of the doc examples, you should check the [examples directory][examples] for examples showcasing all features of this crate. - ### Simple case To create a simple menu with navigation between buttons, simply replace usages @@ -142,6 +140,7 @@ go, and you get there. Any [`Entity`] can be converted into a focusable entity by adding the [`Focusable`] component to it. To do so, just: + ```rust # use bevy::prelude::*; # use bevy_ui_navigation::prelude::Focusable; @@ -149,11 +148,13 @@ fn system(mut cmds: Commands, my_entity: Entity) { cmds.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`][Changed] query parameter as follow: + ```rust use bevy::prelude::*; use bevy_ui_navigation::prelude::{FocusState, Focusable}; @@ -178,6 +179,7 @@ You will want the interaction feedback to be snappy. This means the interaction feedback should run the same frame as the focus change. For this to happen every frame, you should add `button_system` to your app using the [`NavRequestSystem`] label like so: + ```rust, no_run use bevy::prelude::*; use bevy_ui_navigation::prelude::{NavRequestSystem, NavRequest, NavigationPlugin}; @@ -203,19 +205,17 @@ fn main() { fn button_system() {} ``` - ## More complex use cases ### Locking -If you need to supress the navigation algorithm temporarily, you can declare a +If you need to suppress the navigation algorithm temporarily, you can declare a [`Focusable`] as [`Focusable::lock`]. This is useful for example if you want to implement custom widget with their own controls, or if you want to disable menu navigation while in game. To resume the navigation system, you'll need to send a [`NavRequest::Free`]. - ### `NavRequest::FocusOn` You can't directly manipulate which entity is focused, because we need to keep @@ -246,9 +246,11 @@ this behavior, spawn a prioritized [`Focusable`] with [`Focusable::prioritized`] Suppose 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: + ```text 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). @@ -256,6 +258,7 @@ in the game menu to access the options menu). For that, you need to use [`MenuBuilder`]. The high level usage of [`MenuBuilder`] is as follow: + 1. First you need a "root" menu using `MenuBuilder::Root`. 2. You need to spawn into the ECS your "options" button with a [`Focusable`] component. To link the button to your options menu, you need to do one of @@ -272,6 +275,7 @@ The high level usage of [`MenuBuilder`] is as follow: if you have an [`Entity`] id. In code, This will look like this: + ```rust use bevy::prelude::*; use bevy_ui_navigation::prelude::{Focusable, MenuSetting, MenuBuilder}; @@ -348,6 +352,7 @@ menu. To define a menu, you need both the `MenuBuilder` and `MenuSetting` components. A [`MenuSetting`] gives you fine-grained control on how navigation is handled within a menu: + * `MenuSetting::new().wrapping()` enables looping navigation, where going offscreen in one direction "wraps" to the opposite screen edge. @@ -358,7 +363,6 @@ A [`MenuSetting`] gives you fine-grained control on how navigation is handled wi See the [`MenuSetting`] documentation or the ["ultimate" menu navigation example][example-ultimate] for details. - #### Marking If you need to know from which menu a [`NavEvent::FocusChanged`] originated, you @@ -366,7 +370,6 @@ can use `NavMarker` in the [`mark`][module-marking] module. A usage demo is available in [the `marking.rs` example][example-marking]. - ### Menu action with keyboard return (enter) key The default [`InputMapping`] key to trigger menu actions is the space key. @@ -393,7 +396,7 @@ fn return_trigger_action(mut requests: EventWriter, input: Res, input: Res, input: Res, input: Res -### Version matrix +## Version matrix | bevy | latest supporting version | |------|--------| @@ -443,7 +443,7 @@ See the changelog at