5241e09671
12 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Zachary Harrold
|
5241e09671
|
Upgrade to Rust Edition 2024 (#17967)
# Objective - Fixes #17960 ## Solution - Followed the [edition upgrade guide](https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html) ## Testing - CI --- ## Summary of Changes ### Documentation Indentation When using lists in documentation, proper indentation is now linted for. This means subsequent lines within the same list item must start at the same indentation level as the item. ```rust /* Valid */ /// - Item 1 /// Run-on sentence. /// - Item 2 struct Foo; /* Invalid */ /// - Item 1 /// Run-on sentence. /// - Item 2 struct Foo; ``` ### Implicit `!` to `()` Conversion `!` (the never return type, returned by `panic!`, etc.) no longer implicitly converts to `()`. This is particularly painful for systems with `todo!` or `panic!` statements, as they will no longer be functions returning `()` (or `Result<()>`), making them invalid systems for functions like `add_systems`. The ideal fix would be to accept functions returning `!` (or rather, _not_ returning), but this is blocked on the [stabilisation of the `!` type itself](https://doc.rust-lang.org/std/primitive.never.html), which is not done. The "simple" fix would be to add an explicit `-> ()` to system signatures (e.g., `|| { todo!() }` becomes `|| -> () { todo!() }`). However, this is _also_ banned, as there is an existing lint which (IMO, incorrectly) marks this as an unnecessary annotation. So, the "fix" (read: workaround) is to put these kinds of `|| -> ! { ... }` closuers into variables and give the variable an explicit type (e.g., `fn()`). ```rust // Valid let system: fn() = || todo!("Not implemented yet!"); app.add_systems(..., system); // Invalid app.add_systems(..., || todo!("Not implemented yet!")); ``` ### Temporary Variable Lifetimes The order in which temporary variables are dropped has changed. The simple fix here is _usually_ to just assign temporaries to a named variable before use. ### `gen` is a keyword We can no longer use the name `gen` as it is reserved for a future generator syntax. This involved replacing uses of the name `gen` with `r#gen` (the raw-identifier syntax). ### Formatting has changed Use statements have had the order of imports changed, causing a substantial +/-3,000 diff when applied. For now, I have opted-out of this change by amending `rustfmt.toml` ```toml style_edition = "2021" ``` This preserves the original formatting for now, reducing the size of this PR. It would be a simple followup to update this to 2024 and run `cargo fmt`. ### New `use<>` Opt-Out Syntax Lifetimes are now implicitly included in RPIT types. There was a handful of instances where it needed to be added to satisfy the borrow checker, but there may be more cases where it _should_ be added to avoid breakages in user code. ### `MyUnitStruct { .. }` is an invalid pattern Previously, you could match against unit structs (and unit enum variants) with a `{ .. }` destructuring. This is no longer valid. ### Pretty much every use of `ref` and `mut` are gone Pattern binding has changed to the point where these terms are largely unused now. They still serve a purpose, but it is far more niche now. ### `iter::repeat(...).take(...)` is bad New lint recommends using the more explicit `iter::repeat_n(..., ...)` instead. ## Migration Guide The lifetimes of functions using return-position impl-trait (RPIT) are likely _more_ conservative than they had been previously. If you encounter lifetime issues with such a function, please create an issue to investigate the addition of `+ use<...>`. ## Notes - Check the individual commits for a clearer breakdown for what _actually_ changed. --------- Co-authored-by: François Mockers <francois.mockers@vleue.com> |
||
|
Zachary Harrold
|
5c43890d49
|
no_std Support for bevy_input_focus (#17490)
# Objective - Contributes to #15460 ## Solution - Switched `tracing` for `log` for the atomically challenged platforms - Setup feature flags as required - Added to `compile-check-no-std` CI task ## Testing - CI --- ## Notes - _Very_ easy one this time. Most of the changes here are just feature definitions and documentation within the `Cargo.toml` |
||
|
Carter Anderson
|
21f1e3045c
|
Relationships (non-fragmenting, one-to-many) (#17398)
This adds support for one-to-many non-fragmenting relationships (with planned paths for fragmenting and non-fragmenting many-to-many relationships). "Non-fragmenting" means that entities with the same relationship type, but different relationship targets, are not forced into separate tables (which would cause "table fragmentation"). Functionally, this fills a similar niche as the current Parent/Children system. The biggest differences are: 1. Relationships have simpler internals and significantly improved performance and UX. Commands and specialized APIs are no longer necessary to keep everything in sync. Just spawn entities with the relationship components you want and everything "just works". 2. Relationships are generalized. Bevy can provide additional built in relationships, and users can define their own. **REQUEST TO REVIEWERS**: _please don't leave top level comments and instead comment on specific lines of code. That way we can take advantage of threaded discussions. Also dont leave comments simply pointing out CI failures as I can read those just fine._ ## Built on top of what we have Relationships are implemented on top of the Bevy ECS features we already have: components, immutability, and hooks. This makes them immediately compatible with all of our existing (and future) APIs for querying, spawning, removing, scenes, reflection, etc. The fewer specialized APIs we need to build, maintain, and teach, the better. ## Why focus on one-to-many non-fragmenting first? 1. This allows us to improve Parent/Children relationships immediately, in a way that is reasonably uncontroversial. Switching our hierarchy to fragmenting relationships would have significant performance implications. ~~Flecs is heavily considering a switch to non-fragmenting relations after careful considerations of the performance tradeoffs.~~ _(Correction from @SanderMertens: Flecs is implementing non-fragmenting storage specialized for asset hierarchies, where asset hierarchies are many instances of small trees that have a well defined structure)_ 2. Adding generalized one-to-many relationships is currently a priority for the [Next Generation Scene / UI effort](https://github.com/bevyengine/bevy/discussions/14437). Specifically, we're interested in building reactions and observers on top. ## The changes This PR does the following: 1. Adds a generic one-to-many Relationship system 3. Ports the existing Parent/Children system to Relationships, which now lives in `bevy_ecs::hierarchy`. The old `bevy_hierarchy` crate has been removed. 4. Adds on_despawn component hooks 5. Relationships can opt-in to "despawn descendants" behavior, meaning that the entire relationship hierarchy is despawned when `entity.despawn()` is called. The built in Parent/Children hierarchies enable this behavior, and `entity.despawn_recursive()` has been removed. 6. `world.spawn` now applies commands after spawning. This ensures that relationship bookkeeping happens immediately and removes the need to manually flush. This is in line with the equivalent behaviors recently added to the other APIs (ex: insert). 7. Removes the ValidParentCheckPlugin (system-driven / poll based) in favor of a `validate_parent_has_component` hook. ## Using Relationships The `Relationship` trait looks like this: ```rust pub trait Relationship: Component + Sized { type RelationshipSources: RelationshipSources<Relationship = Self>; fn get(&self) -> Entity; fn from(entity: Entity) -> Self; } ``` A relationship is a component that: 1. Is a simple wrapper over a "target" Entity. 2. Has a corresponding `RelationshipSources` component, which is a simple wrapper over a collection of entities. Every "target entity" targeted by a "source entity" with a `Relationship` has a `RelationshipSources` component, which contains every "source entity" that targets it. For example, the `Parent` component (as it currently exists in Bevy) is the `Relationship` component and the entity containing the Parent is the "source entity". The entity _inside_ the `Parent(Entity)` component is the "target entity". And that target entity has a `Children` component (which implements `RelationshipSources`). In practice, the Parent/Children relationship looks like this: ```rust #[derive(Relationship)] #[relationship(relationship_sources = Children)] pub struct Parent(pub Entity); #[derive(RelationshipSources)] #[relationship_sources(relationship = Parent)] pub struct Children(Vec<Entity>); ``` The Relationship and RelationshipSources derives automatically implement Component with the relevant configuration (namely, the hooks necessary to keep everything in sync). The most direct way to add relationships is to spawn entities with relationship components: ```rust let a = world.spawn_empty().id(); let b = world.spawn(Parent(a)).id(); assert_eq!(world.entity(a).get::<Children>().unwrap(), &[b]); ``` There are also convenience APIs for spawning more than one entity with the same relationship: ```rust world.spawn_empty().with_related::<Children>(|s| { s.spawn_empty(); s.spawn_empty(); }) ``` The existing `with_children` API is now a simpler wrapper over `with_related`. This makes this change largely non-breaking for existing spawn patterns. ```rust world.spawn_empty().with_children(|s| { s.spawn_empty(); s.spawn_empty(); }) ``` There are also other relationship APIs, such as `add_related` and `despawn_related`. ## Automatic recursive despawn via the new on_despawn hook `RelationshipSources` can opt-in to "despawn descendants" behavior, which will despawn all related entities in the relationship hierarchy: ```rust #[derive(RelationshipSources)] #[relationship_sources(relationship = Parent, despawn_descendants)] pub struct Children(Vec<Entity>); ``` This means that `entity.despawn_recursive()` is no longer required. Instead, just use `entity.despawn()` and the relevant related entities will also be despawned. To despawn an entity _without_ despawning its parent/child descendants, you should remove the `Children` component first, which will also remove the related `Parent` components: ```rust entity .remove::<Children>() .despawn() ``` This builds on the on_despawn hook introduced in this PR, which is fired when an entity is despawned (before other hooks). ## Relationships are the source of truth `Relationship` is the _single_ source of truth component. `RelationshipSources` is merely a reflection of what all the `Relationship` components say. By embracing this, we are able to significantly improve the performance of the system as a whole. We can rely on component lifecycles to protect us against duplicates, rather than needing to scan at runtime to ensure entities don't already exist (which results in quadratic runtime). A single source of truth gives us constant-time inserts. This does mean that we cannot directly spawn populated `Children` components (or directly add or remove entities from those components). I personally think this is a worthwhile tradeoff, both because it makes the performance much better _and_ because it means theres exactly one way to do things (which is a philosophy we try to employ for Bevy APIs). As an aside: treating both sides of the relationship as "equivalent source of truth relations" does enable building simple and flexible many-to-many relationships. But this introduces an _inherent_ need to scan (or hash) to protect against duplicates. [`evergreen_relations`](https://github.com/EvergreenNest/evergreen_relations) has a very nice implementation of the "symmetrical many-to-many" approach. Unfortunately I think the performance issues inherent to that approach make it a poor choice for Bevy's default relationship system. ## Followup Work * Discuss renaming `Parent` to `ChildOf`. I refrained from doing that in this PR to keep the diff reasonable, but I'm personally biased toward this change (and using that naming pattern generally for relationships). * [Improved spawning ergonomics](https://github.com/bevyengine/bevy/discussions/16920) * Consider adding relationship observers/triggers for "relationship targets" whenever a source is added or removed. This would replace the current "hierarchy events" system, which is unused upstream but may have existing users downstream. I think triggers are the better fit for this than a buffered event queue, and would prefer not to add that back. * Fragmenting relations: My current idea hinges on the introduction of "value components" (aka: components whose type _and_ value determines their ComponentId, via something like Hashing / PartialEq). By labeling a Relationship component such as `ChildOf(Entity)` as a "value component", `ChildOf(e1)` and `ChildOf(e2)` would be considered "different components". This makes the transition between fragmenting and non-fragmenting a single flag, and everything else continues to work as expected. * Many-to-many support * Non-fragmenting: We can expand Relationship to be a list of entities instead of a single entity. I have largely already written the code for this. * Fragmenting: With the "value component" impl mentioned above, we get many-to-many support "for free", as it would allow inserting multiple copies of a Relationship component with different target entities. Fixes #3742 (If this PR is merged, I think we should open more targeted followup issues for the work above, with a fresh tracking issue free of the large amount of less-directed historical context) Fixes #17301 Fixes #12235 Fixes #15299 Fixes #15308 ## Migration Guide * Replace `ChildBuilder` with `ChildSpawnerCommands`. * Replace calls to `.set_parent(parent_id)` with `.insert(Parent(parent_id))`. * Replace calls to `.replace_children()` with `.remove::<Children>()` followed by `.add_children()`. Note that you'll need to manually despawn any children that are not carried over. * Replace calls to `.despawn_recursive()` with `.despawn()`. * Replace calls to `.despawn_descendants()` with `.despawn_related::<Children>()`. * If you have any calls to `.despawn()` which depend on the children being preserved, you'll need to remove the `Children` component first. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> |
||
|
Antony
|
3578f9e4d0
|
Reflect bevy_input_focus (#17212)
# Objective Fixes #17099. ## Solution Derive, register, and feature flag. ## Testing Ran CI. |
||
|
Alice Cecile
|
aa09b6601d
|
Add basic directional (gamepad) navigation for UI (and non-UI) (#17102)
# 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> |
||
|
github-actions[bot]
|
573b980685
|
Bump Version after Release (#17176)
Bump version after release This PR has been auto-generated --------- Co-authored-by: Bevy Auto Releaser <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: François Mockers <mockersf@gmail.com> |
||
|
Zachary Harrold
|
a371ee3019
|
Remove tracing re-export from bevy_utils (#17161)
# Objective - Contributes to #11478 ## Solution - Made `bevy_utils::tracing` `doc(hidden)` - Re-exported `tracing` from `bevy_log` for end-users - Added `tracing` directly to crates that need it. ## Testing - CI --- ## Migration Guide If you were importing `tracing` via `bevy::utils::tracing`, instead use `bevy::log::tracing`. Note that many items within `tracing` are also directly re-exported from `bevy::log` as well, so you may only need `bevy::log` for the most common items (e.g., `warn!`, `trace!`, etc.). This also applies to the `log_once!` family of macros. ## Notes - While this doesn't reduce the line-count in `bevy_utils`, it further decouples the internal crates from `bevy_utils`, making its eventual removal more feasible in the future. - I have just imported `tracing` as we do for all dependencies. However, a workspace dependency may be more appropriate for version management. |
||
|
Alice Cecile
|
5f1e762f19
|
Return Result from tab navigation API (#17071)
# Objective Tab navigation can fail in all manner of ways. The current API recognizes this, but merely logs a warning and returns `None`. We should supply the actual reason for failure to the caller, so they can handle it in whatever fashion they please (including logging a warning!). Swapping to a Result-oriented pattern is also a bit more idiomatic and makes the code's control flow easier to follow. ## Solution - Refactor the `tab_navigation` module to return a `Result` rather than an `Option` from its key APIs. - Move the logging to the provided prebuilt observer. This leaves the default behavior largely unchanged, but allows for better user control. - Make the case where no tab group was found for the currently focused entity an error branch, but provide enough information that we can still recover from it. ## Testing The `tab_navigation` example continues to function as intended. |
||
|
Benjamin Brienen
|
8c34f00deb
|
Fix msrvs (#17012)
# Objective The rust-versions are out of date. Fixes #17008 ## Solution Update the values Cherry-picked from #17006 in case it is controversial ## Testing Validated locally and in #17006 --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> |
||
|
Talin
|
5c67cfc8b7
|
Tab navigation framework for bevy_input_focus. (#16795)
# Objective This PR continues the work of `bevy_input_focus` by adding a pluggable tab navigation framework. As part of this work, `FocusKeyboardEvent` now propagates to the window after exhausting all ancestors. ## Testing Unit tests and manual tests. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> |
||
|
Erick Z
|
ced6159d93
|
Improve bevy_input_focus (#16749)
# Objective I was curious to use the newly created `bevy_input_focus`, but I found some issues with it - It was only implementing traits for `World`. - Lack of tests - `is_focus_within` logic was incorrect. ## Solution This PR includes some improvements to the `bevy_input_focus` crate: - Add new `IsFocusedHelper` that doesn't require access to `&World`. It implements `IsFocused` - Remove `IsFocused` impl for `DeferredWorld`. Since it already implements `Deref<Target=World>` it was just duplication of code. - impl `SetInputFocus` for `Commands`. There was no way to use `SetFocusCommand` directly. This allows it. - The `is_focus_within` logic has been fixed to check descendants. Previously it was checking if any of the ancestors had focus which is not correct according to the documentation. - Added a bunch of unit tests to verify the logic of the crate. ## Testing - Did you test these changes? If so, how? Yes, running newly added unit tests. --- |
||
|
Talin
|
ea33fc04ab
|
Add "bevy_input_focus" crate. (#15611)
# Objective Define a framework for handling keyboard focus and bubbled keyboard events, as discussed in #15374. ## Solution Introduces a new crate, `bevy_input_focus`. This crate provides: * A resource for tracking which entity has keyboard focus. * Methods for getting and setting keyboard focus. * Event definitions for triggering bubble-able keyboard input events to the focused entity. * A system for dispatching keyboard input events to the focused entity. This crate does *not* provide any integration with UI widgets, or provide functions for tab navigation or gamepad-based focus navigation, as those are typically application-specific. ## Testing Most of the code has been copied from a different project, one that has been well tested. However, most of what's in this module consists of type definitions, with relatively small amounts of executable code. That being said, I expect that there will be substantial bikeshedding on the design, and I would prefer to hold off writing tests until after things have settled. I think that an example would be appropriate, however I'm waiting on a few other pending changes to Bevy before doing so. In particular, I can see a simple example with four buttons, with focus navigation between them, and which can be triggered by the keyboard. @alice-i-cecile |