aa09b6601d
# Objective While directional navigation is helpful for UI in general for accessibility reasons, it is *especially* valuable for a game engine, where menus may be navigated primarily or exclusively through the use of a game controller. Thumb-stick powered cursor-based navigation can work as a fallback, but is generally a pretty poor user experience. We can do better! ## Prior art Within Bevy, https://github.com/nicopap/ui-navigation and https://github.com/rparrett/bevy-alt-ui-navigation-lite exist to solve this same problem. This isn't yet a complete replacement for that ecosystem, but hopefully we'll be there for 0.16. ## Solution UI navigation is complicated, and the right tradeoffs will vary based on the project and even the individual scene. We're starting with something simple and flexible, hooking into the existing `InputFocus` resource, and storing a manually constructed graph of entities to explore in a `DirectionalNavigationMap` resource. The developer experience won't be great (so much wiring to do!), but the tools are all there for a great user experience. We could have chosen to represent these linkages via component-flavored not-quite-relations. This would be useful for inspectors, and would give us automatic cleanup when the entities were despawned, but seriously complicates the developer experience when building and checking this API. For now, we're doing a dumb "entity graph in a resource" thing and `remove` helpers. Once relations are added, we can re-evaluate. I've decided to use a `CompassOctant` as our key for the possible paths. This should give users a reasonable amount of precise control without being fiddly, and playing reasonably nicely with arrow-key navigation. This design lets us store the set of entities that we're connected to as a 8-byte array (yay Entity-niching). In theory, this is maybe nicer than the double indirection of two hashmaps. but if this ends up being slow we should create benchmarks. To make this work more pleasant, I've added a few utilities to the `CompassOctant` type: converting to and from usize, and adding a helper to find the 180 degrees opposite direction. These have been mirrored onto `CompassQuadrant` for consistency: they should be generally useful for game logic. ## Future work This is a relatively complex initiative! In the hopes of easing review and avoiding merge conflicts, I've opted to split this work into bite-sized chunks. Before 0.16, I'd like to have: - An example demonstrating gamepad and tab-based navigation in a realistic game menu - Helpers to convert axis-based inputs into compass quadrants / octants - Tools to check the listed graph desiderata - A helper to build a graph from a grid of entities - A tool to automatically build a graph given a supplied UI layout One day, it would be sweet if: - We had an example demonstrating how to use focus navigation in a non-UI scene to cycle between game objects - Standard actions for tab-style and directional navigation with a first-party bevy_actions integration - We had a visual debugging tool to display these navigation graphs for QC purposes - There was a built-in way to go "up a level" by cancelling the current action - The navigation graph is built completely out of relations ## Testing - tests for the new `CompassQuadrant` / `CompassOctant` methods - tests for the new directional navigation module --------- Co-authored-by: Rob Parrett <robparrett@gmail.com>
34 lines
1.1 KiB
TOML
34 lines
1.1 KiB
TOML
[package]
|
|
name = "bevy_input_focus"
|
|
version = "0.16.0-dev"
|
|
edition = "2021"
|
|
description = "Keyboard focus management"
|
|
homepage = "https://bevyengine.org"
|
|
repository = "https://github.com/bevyengine/bevy"
|
|
license = "MIT OR Apache-2.0"
|
|
keywords = ["bevy"]
|
|
rust-version = "1.83.0"
|
|
|
|
[dependencies]
|
|
# bevy
|
|
bevy_app = { path = "../bevy_app", version = "0.16.0-dev", default-features = false }
|
|
bevy_ecs = { path = "../bevy_ecs", version = "0.16.0-dev", default-features = false }
|
|
bevy_input = { path = "../bevy_input", version = "0.16.0-dev", default-features = false }
|
|
bevy_hierarchy = { path = "../bevy_hierarchy", version = "0.16.0-dev", default-features = false }
|
|
bevy_math = { path = "../bevy_math", version = "0.16.0-dev", default-features = false }
|
|
bevy_window = { path = "../bevy_window", version = "0.16.0-dev", default-features = false }
|
|
|
|
# other
|
|
thiserror = { version = "2", default-features = false }
|
|
tracing = { version = "0.1", default-features = false, features = ["std"] }
|
|
|
|
[dev-dependencies]
|
|
smol_str = "0.2"
|
|
|
|
[lints]
|
|
workspace = true
|
|
|
|
[package.metadata.docs.rs]
|
|
rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
|
|
all-features = true
|