6250698b56
4 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Zachary Harrold
|
6250698b56
|
Added on_unimplemented Diagnostic for IntoObserverSystem (#14840)
# Objective - Fixes #14658. ## Solution - Added `on_unimplemented` Diagnostic for `IntoObserverSystem` calling out argument ordering in a `note` - Added an example to the documentation on `App::observe` to provide some explanation to users. ## Testing - Ran CI locally - Deliberately introduced a parameter order error in the `ecs/observers.rs` example as a test. --- ## Showcase <details> <summary>Error Before</summary> ``` error[E0277]: the trait bound `{closure@examples/ecs/observers.rs:19:13: 22:37}: IntoObserverSystem<_, _, _>` is not satisfied --> examples/ecs/observers.rs:19:13 | 18 | .observe( | ------- required by a bound introduced by this call 19 | / |mines: Query<&Mine>, 20 | | trigger: Trigger<ExplodeMines>, 21 | | index: Res<SpatialIndex>, 22 | | mut commands: Commands| { ... | 34 | | } 35 | | }, | |_____________^ the trait `bevy::prelude::IntoSystem<bevy::prelude::Trigger<'static, _, _>, (), _>` is not implemented for closure `{closure@examples/ecs/observers.rs:19:13: 22:37}`, which is required by `{closure@examples/ecs/observers.rs:19:13: 22:37}: IntoObserverSystem<_, _, _>` | = note: required for `{closure@examples/ecs/observers.rs:19:13: 22:37}` to implement `IntoObserverSystem<_, _, _>` note: required by a bound in `bevy::prelude::App::observe` --> C:\Users\Zac\Documents\GitHub\bevy\crates\bevy_app\src\app.rs:995:24 | 993 | pub fn observe<E: Event, B: Bundle, M>( | ------- required by a bound in this associated function 994 | &mut self, 995 | observer: impl IntoObserverSystem<E, B, M>, | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `App::observe` For more information about this error, try `rustc --explain E0277`. error: could not compile `bevy` (example "observers") due to 1 previous error ``` </details> <details> <summary>Error After</summary> ``` error[E0277]: `{closure@examples/ecs/observers.rs:19:13: 22:37}` cannot become an `ObserverSystem` --> examples/ecs/observers.rs:19:13 | 18 | .observe( | ------- required by a bound introduced by this call 19 | / |mines: Query<&Mine>, 20 | | trigger: Trigger<ExplodeMines>, 21 | | index: Res<SpatialIndex>, 22 | | mut commands: Commands| { ... | 34 | | } 35 | | }, | |_____________^ the trait `IntoObserverSystem` is not implemented | = help: the trait `bevy::prelude::IntoSystem<bevy::prelude::Trigger<'static, _, _>, (), _>` is not implemented for closure `{closure@examples/ecs/observers.rs:19:13: 22:37}`, which is required by `{closure@examples/ecs/observers.rs:19:13: 22:37}: IntoObserverSystem<_, _, _>` = note: for function `ObserverSystem`s, ensure the first argument is a `Trigger<T>` and any subsequent ones are `SystemParam` = note: required for `{closure@examples/ecs/observers.rs:19:13: 22:37}` to implement `IntoObserverSystem<_, _, _>` note: required by a bound in `bevy::prelude::App::observe` --> C:\Users\Zac\Documents\GitHub\bevy\crates\bevy_app\src\app.rs:1025:24 | 1023 | pub fn observe<E: Event, B: Bundle, M>( | ------- required by a bound in this associated function 1024 | &mut self, 1025 | observer: impl IntoObserverSystem<E, B, M>, | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `App::observe` For more information about this error, try `rustc --explain E0277`. error: could not compile `bevy` (example "observers") due to 1 previous error ``` </details> |
||
|
Periwink
|
da997dd0ea
|
Allow observer systems to have outputs (#14159)
# Objective Fixes https://github.com/bevyengine/bevy/issues/14157 ## Solution - Update the ObserverSystem traits to accept an `Out` parameter ## Testing - Added a test where an observer system has a non-empty output which is piped into another system Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> |
||
|
Giacomo Stevanato
|
d7080369a7
|
Fix intra-doc links and make CI test them (#14076)
# Objective - Bevy currently has lot of invalid intra-doc links, let's fix them! - Also make CI test them, to avoid future regressions. - Helps with #1983 (but doesn't fix it, as there could still be explicit links to docs.rs that are broken) ## Solution - Make `cargo r -p ci -- doc-check` check fail on warnings (could also be changed to just some specific lints) - Manually fix all the warnings (note that in some cases it was unclear to me what the fix should have been, I'll try to highlight them in a self-review) |
||
|
James O'Brien
|
eb3c81374a
|
Generalised ECS reactivity with Observers (#10839)
# Objective
- Provide an expressive way to register dynamic behavior in response to
ECS changes that is consistent with existing bevy types and traits as to
provide a smooth user experience.
- Provide a mechanism for immediate changes in response to events during
command application in order to facilitate improved query caching on the
path to relations.
## Solution
- A new fundamental ECS construct, the `Observer`; inspired by flec's
observers but adapted to better fit bevy's access patterns and rust's
type system.
---
## Examples
There are 3 main ways to register observers. The first is a "component
observer" that looks like this:
```rust
world.observe(|trigger: Trigger<OnAdd, Transform>, query: Query<&Transform>| {
let transform = query.get(trigger.entity()).unwrap();
});
```
The above code will spawn a new entity representing the observer that
will run it's callback whenever the `Transform` component is added to an
entity. This is a system-like function that supports dependency
injection for all the standard bevy types: `Query`, `Res`, `Commands`
etc. It also has a `Trigger` parameter that provides information about
the trigger such as the target entity, and the event being triggered.
Importantly these systems run during command application which is key
for their future use to keep ECS internals up to date. There are similar
events for `OnInsert` and `OnRemove`, and this will be expanded with
things such as `ArchetypeCreated`, `TableEmpty` etc. in follow up PRs.
Another way to register an observer is an "entity observer" that looks
like this:
```rust
world.entity_mut(entity).observe(|trigger: Trigger<Resize>| {
// ...
});
```
Entity observers run whenever an event of their type is triggered
targeting that specific entity. This type of observer will de-spawn
itself if the entity (or entities) it is observing is ever de-spawned so
as to not leave dangling observers.
Entity observers can also be spawned from deferred contexts such as
other observers, systems, or hooks using commands:
```rust
commands.entity(entity).observe(|trigger: Trigger<Resize>| {
// ...
});
```
Observers are not limited to in built event types, they can be used with
any type that implements `Event` (which has been extended to implement
Component). This means events can also carry data:
```rust
#[derive(Event)]
struct Resize { x: u32, y: u32 }
commands.entity(entity).observe(|trigger: Trigger<Resize>, query: Query<&mut Size>| {
let event = trigger.event();
// ...
});
// Will trigger the observer when commands are applied.
commands.trigger_targets(Resize { x: 10, y: 10 }, entity);
```
You can also trigger events that target more than one entity at a time:
```rust
commands.trigger_targets(Resize { x: 10, y: 10 }, [e1, e2]);
```
Additionally, Observers don't _need_ entity targets:
```rust
app.observe(|trigger: Trigger<Quit>| {
})
commands.trigger(Quit);
```
In these cases, `trigger.entity()` will be a placeholder.
Observers are actually just normal entities with an `ObserverState` and
`Observer` component! The `observe()` functions above are just shorthand
for:
```rust
world.spawn(Observer::new(|trigger: Trigger<Resize>| {});
```
This will spawn the `Observer` system and use an `on_add` hook to add
the `ObserverState` component.
Dynamic components and trigger types are also fully supported allowing
for runtime defined trigger types.
## Possible Follow-ups
1. Deprecate `RemovedComponents`, observers should fulfill all use cases
while being more flexible and performant.
2. Queries as entities: Swap queries to entities and begin using
observers listening to archetype creation triggers to keep their caches
in sync, this allows unification of `ObserverState` and `QueryState` as
well as unlocking several API improvements for `Query` and the
management of `QueryState`.
3. Trigger bubbling: For some UI use cases in particular users are
likely to want some form of bubbling for entity observers, this is
trivial to implement naively but ideally this includes an acceleration
structure to cache hierarchy traversals.
4. All kinds of other in-built trigger types.
5. Optimization; in order to not bloat the complexity of the PR I have
kept the implementation straightforward, there are several areas where
performance can be improved. The focus for this PR is to get the
behavior implemented and not incur a performance cost for users who
don't use observers.
I am leaving each of these to follow up PR's in order to keep each of
them reviewable as this already includes significant changes.
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
Co-authored-by: MiniaczQ <xnetroidpl@gmail.com>
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
|