Decoupling State and Stages #1297
Replies: 5 comments 18 replies
-
Handling States with Run CriteriaBy @TheRawMeatball, this code shows a quick draft of how we could implement the From a user's perspective, the API would modify system sets or stages with run criteria, which would be set up to detect whether a State has the correct variant, and when it changes. The critical code is these three functions, designed to be inserted within a run criteria like pub fn on_update(val: T) -> impl System<In = (), Out = ShouldRun> {
let d = discriminant(&val);
Wrapper::new(move |s| discriminant(&s.current) == d)
}
pub fn on_entry(val: T) -> impl System<In = (), Out = ShouldRun> {
let d = discriminant(&val);
Wrapper::new(move |s: &State<T>| s.next().map_or(false, |s| discriminant(s) == d))
}
pub fn on_exit(val: T) -> impl System<In = (), Out = ShouldRun> {
let d = discriminant(&val);
Wrapper::new(move |s: &State<T>| s.next().is_some() && discriminant(&s.current) == d)
}This should allow us to remove the concept of Note: this approach increases the importance of run criteria significantly, making resolving #1295 a much higher priority. |
Beta Was this translation helpful? Give feedback.
-
|
Re: "how do we drive transitions"/"where do we put stage
.with_exclusive_system(
State::<MyState>::handle_transition // this is called "update" in the prototype implementation
.system()
.label("MyState_transition_handler")
.at_end()
)We don't have to make sure this system runs after all state-related systems, just after any systems that might queue up a state transition (e.g. stage
.with_system(doesnt_care_about_state.system())
.with_system(may_push_state_a.system().before("state_transition_fence"))
.with_system(may_push_state_b.system().before("state_transition_fence"))
.with_system_set(
SystemSet::default()
.with_run_criteria(Never)
.with_system(noop.system().label("state_transition_fence")),
)
.with_system(
State::<MyStateA>::handle_transition
.system()
.after("state_transition_fence"),
)
.with_system(
State::<MyStateB>::handle_transition
.system()
.after("state_transition_fence"),
)This snippet demonstrates that we don't have to make users stick the state driver systems into on-end exclusives, they can have them run in parallel with everything else if they structure the dependencies right. So, whether or not it's desirable or even possible to automagic this is unclear to me right now, but it does feel like providing building blocks of familiar shapes, rather than a heap of super-specialized abstractions, is the way to go. |
Beta Was this translation helpful? Give feedback.
-
|
Yeah I agree that this should build on top of existing concepts when possible, provided it is clear and ergonomic (which the example above clearly is not). One way to improve clarity might be to do something like: stage
.with_system(doesnt_care_about_state.system())
.with_system(may_push_state_a.system().before("state_transition_fence"))
.with_system(may_push_state_b.system().before("state_transition_fence"))
.with_system(EmptySystem.label("state_transition_fence"))
.with_system(
State::<MyStateA>::handle_transition
.system()
.after("state_transition_fence"),
)
.with_system(
State::<MyStateB>::handle_transition
.system()
.after("state_transition_fence"),
) |
Beta Was this translation helpful? Give feedback.
-
|
But that approach does still feel a bit "manual" to me (when compared to StateStage). Dataflow / running state transition systems at the right time is left as an exercise for the user. |
Beta Was this translation helpful? Give feedback.
-
|
Well, we could fully automate this, but it would likely require tigthly coupled plumbing. But, we run into a new problem: what happens if the state is used in more than one stage? Making the user add handling manually removes this potential ambiguity. Another snippet: stage
.with_system(doesnt_care_about_state.system())
.with_system(may_push_state_a.system())
.with_system(may_push_state_b.system())
.with_exclusive_system(also_may_push_state_a.system())
.with_exclusive_system(also_may_push_state_b.system().at_end().before("MyStateB_transition_handling"))
.with_exclusive_system(
State::<MyStateA>::handle_transition
.system()
.after("MyStateA_transition_handling")
.at_end(),
)
.with_exclusive_system(
State::<MyStateB>::handle_transition
.system()
.after("MyStateB_transition_handling")
.at_end(),
)It's possible to stick transition handling as exclusive systems into the end of stage and not worry about ordering, except for state-pushing exclusive systems that are also at the end of stage. |
Beta Was this translation helpful? Give feedback.
-
|
This comment captures discussion from Discord. @TheRawMeatball found that in order to implement State via To allow for multiple state changes per-frame, all systems need to be in one large SystemSet which can have looping RunCriteria. In response, @Ratysz has proposed a change, relevant to #1144, that allows for nesting systems sets. Summarized, it works as follows:
This results in the following behavior:
These sets will only appear nested in the API, avoiding performance costs. This decouples run criteria from dependencies, improving conceptual clarity. (As a reminder, we need this complex looping behavior in the first place to ensure that State changes are propagated completely in a single tick. A similar problem emerges with UI, see #254.) In order to better support these changes, we need to be able to differentiate between hard dependencies that check whether their prerequisite system ran a) at all this tick, and b) the last time it was checked. Because hard dependencies should be rare relative to soft dependencies (due to intermingling concerns about when and if a system should run), we have preliminary consensus on the following names:
|
Beta Was this translation helpful? Give feedback.
-
|
Counterproposal:
|
Beta Was this translation helpful? Give feedback.
-
|
so,alternative name proposal: if the non-looping should be the default:
if the looping should be the default:
Just something to make the "looping" aspect clear in the name. "strict" is not as clear. (i don't really understand the exact semantics of this looping stuff (my brain hurts from this 😆 ) so i don't know which of the two is the one you'd want for general purpose hard dependencies (when users don't want to have to think about looping), so pick whichever makes more sense) |
Beta Was this translation helpful? Give feedback.
-
|
I like As for which should be the default, there's no difference in the standard case. However, within a looping system set, I think that the looping variant is going to be more common. Hard dependencies are typically useful when you have some strict requirement, that isn't able to be handled (at least, not ergonomically) by system chaining. Usually, you'll only want to run these systems if you have fresh data to process, but then you should just have a run criteria that checks So my initial conclusion is that hard dependencies are bad and maybe just shouldn't exist. But if they do, then checking every loop is probably the more natural pattern. Which leads to |
Beta Was this translation helpful? Give feedback.
-
ooooh right! that was a thing that exists... somehow it slipped off my mind
I am very much starting to agree with that. The more I think about it (and read discussions) the more I see the drawbacks of supporting them. We seem to have plenty of other tools available to cover the use cases where a user might have wanted a hard dependency rather than a soft one, such as system chaining. And since the scheduling model and the API design can be simplified so much by not supporting them ... yeah ... I don't think we should to support them. |
Beta Was this translation helpful? Give feedback.
-
|
Note on system chaining: systems joined that way are effectively one system to the executor. That means their access information is combined, so, if one of the systems doesn't need most of the data the other one does, splitting the chain and using something like a hard dependency instead might lead to better utilization. |
Beta Was this translation helpful? Give feedback.
-
|
A new issue with More details can be found here. |
Beta Was this translation helpful? Give feedback.
-
|
tl;dr - When using multiple
The ProblemThe issue has to do with the order of operations when running
Now let's say you change the state in an Because the state is now updated when we return to SS1 on the next tick, we never call its The WorkaroundIn order to make this work as expected, state changes cannot be made in the The simplest way to solve this is to use a single EDIT: Oh, one more thing. |
Beta Was this translation helpful? Give feedback.
-
|
Hmm, I think that this problem happens because we're trying to use the same tool to potentially solve 2 different and conflicting use cases. In the intended use case of In usage 2, multiple There are some potential solutions, but none without compromise:
A radical alternate solution would be to fully decouple the API for these two use cases, but this comes at the cost of increased API surface and higher upfront complexity, with the benefits being that two separate use cases don't have to share the same tool that isn't well-optimized for either use case. |
Beta Was this translation helpful? Give feedback.
-
|
Some of this discussion is a bit beyond me, particularly in terms of the implementation details (so if there are technical hurdles to these ideas, I wouldn't be familiar with them), but I thought I'd contribute some ideas anyway. As Separately to transitions/events, you want some systems to only run when the global state matches a variant of that state, and this can run in any arbitrary stage, and these systems could have other dependencies. If the smallest unit of conditional execution is a Ideally you would listen to separate events to actually initiate the transitions themselves, but this could be handled in userland. For what this could look like, a contrived (and definitely incorrect) example: /// Our `State`
#[derive(Clone)]
enum TrafficLight {
Red,
Yellow,
Green,
}
/// The `Event` that drives state changes
struct TimerComplete;
/// This system updates the timer, and once the timer completes, sends a `TimerComplete` event.
/// I have assumed `EventWriter<T>` has landed.
fn update_timer_and_send_events(
time: Res<Time>,
mut timer: ResMut<Timer>,
mut timer_events: EventWriter<TimerComplete>,
) {
timer.tick(time.delta_seconds());
if timer.just_finished() {
timer_events.send(TimerComplete);
}
}
/// This system listens to `TimerComplete` events, and queues up a state change *1
/// It also emits a `StateTransitionEvent<TrafficLight>`.
fn handle_timer_events(timer_events: EventReader<TimerComplete>, mut state: ResMut<State<TrafficLight>>) {
for timer_event in timer_events.iter() {
match *state {
TrafficLight::Red => { state.set_next(TrafficLight::Green).unwrap(); }
TrafficLight::Green => { state.set_next(TrafficLight::Yellow).unwrap(); }
TrafficLight::Yellow => { state.set_next(TrafficLight::Red).unwrap(); }
}
}
}
/// *1 Alternatively, an event driven system that does the same thing might look like
fn handle_timer_event(In(_): In<TimerComplete>, mut state: ResMut<State<TrafficLight>>) {
match *state {
TrafficLight::Red => { state.set_next(TrafficLight::Green).unwrap(); }
TrafficLight::Green => { state.set_next(TrafficLight::Yellow).unwrap(); }
TrafficLight::Yellow => { state.set_next(TrafficLight::Red).unwrap(); }
}
}
/// This system runs only once, when we enter a certain state, `TrafficLight::Green`*2, and is specially registered.
fn turn_lights_green(
mut query: Query<&Handle<ColorMaterial>, With<Light>>,
mut materials: ResMut<Assets<ColorMaterial>>,
) {
for handle in query.iter_mut() {
materials.get_mut(&handle).unwrap().color = Color::GREEN;
}
}
/// *2 Alternatively, an event driven system that does the same thing might look like the below.
/// It's assumed that this only runs when the state has entered `TrafficLight::Green`.
fn turn_lights_green(
In(_): In<StateTransitionEvent<TrafficLight>>,
mut query: Query<&Handle<ColorMaterial>, With<Light>>,
mut materials: ResMut<Assets<ColorMaterial>>,
) {
for handle in query.iter_mut() {
materials.get_mut(&handle).unwrap().color = Color::GREEN;
}
}
/// *2 Alternatively, the user has to handle it themselves
fn change_traffic_light_color(
In(StateTransitionEvent { _from, to }): In<StateTransitionEvent<TrafficLight>>,
mut query: Query<&Handle<ColorMaterial>, With<Light>>,
mut materials: ResMut<Assets<ColorMaterial>>,
) {
for handle in query.iter_mut() {
let material = materials.get_mut(&handle).unwrap();
material.color = match to {
TrafficLight::Green => Color::GREEN,
TrafficLight::Yellow=> Color::YELLOW,
TrafficLight::Red => Color::RED,
};
}
}
/// This system runs only within a certain state, `TrafficLight::Green`, and is specially registered.
fn cars_move_forward(time: Res<Time>, mut query: Query<(&mut Transform, &Velocity), With<Car>>) {
let dt = time.delta_seconds();
for (mut transform, velocity) in query.iter_mut() {
transform.translation += velocity.0 * dt;
}
}
/// This system runs only within a certain state, `TrafficLight::Yellow`, and is specially registered.
/// The same system runs when it is in the `TrafficLight::Red` state, and was separately registered.
fn cars_slow_down(time: Res<Time>, mut query: Query<(&mut Transform, &mut Velocity), With<Car>>) {
let dt = time.delta_seconds();
for (mut transform, mut velocity) in query.iter_mut() {
// if it's already past the traffic light at (0,0,0), continue moving
if transform.translation.y >= 0.0 {
transform.translation += velocity.0 * dt;
} else {
// slow down / stop
velocity -= 2.0 * velocity.0.normalize() * dt;
transform.translation += velocity * dt;
}
}
}I don't necessarily believe it's a good API, and I've deliberately left out how you might actually register (order and organise) these systems, but it's an overall approach to state management I'd like us to consider. tl;dr
|
Beta Was this translation helpful? Give feedback.
-
Actually, I don't think such a system needs to be dynamically inserted. It can be inserted as normal, and you simply step through / consume an iterator. I suggest that it would be very similar to pub fn update<T>(&mut self, events: &Events<T>) -> ShouldRun {
if !self.looping {
// instead of FixedTimestep's increased accumulator, instantiate the iterator
self.event_iterator = events.iter();
}
// instead of FixedTimestep's accumulator vs step check, simply call `.next()` on the iterator
if let Some(event) = self.event_iterator.next() {
// instead of FixedTimestep's overstep, store the last event so that it can be accessed by a system
self.last_event = Some(event.clone());
self.looping = true;
ShouldRun::YesAndLoop
} else {
self.last_event = None;
self.looping = false;
ShouldRun::No
}
}Not 100% sure on the |
Beta Was this translation helpful? Give feedback.
-
It does feel natural to me, and leans on an existing Bevy concept, rather than introducing a new concept.
I like this, as it opens up more possibilities by not tying to some sort of State enum, but worth bikeshedding names. I'd also suggest an explicit app
.add_system(
on_transition_a_to_b
.system()
.run_criteria(ResChangedFrom::new(State::A))
.run_criteria(ResChangedTo::new(State::B))
);I also have a question about your example code: is it intended that a single system can be conditionally executed via run criteria? I thought that was only stages and (soon) system sets? Not to further the scope creep, but could this be dynamic, e.g.
What do you mean here? Even for |
Beta Was this translation helpful? Give feedback.
-
It's not supported in #1144 right now, but there's nothing blocking it on principle.
That's the thing: we want to support going through more than one state transition per stage run. Current idea is to have |
Beta Was this translation helpful? Give feedback.
-
Can we come up with some scenarios where more than one state transition within a single stage (or system set) could be useful e.g. Is the intended behaviour something like this?: #[derive(Clone)]
enum MyState {
A,
B,
C,
}
fn system_a(mut state: ResMut<State<MyState>>) {
state.set_next(MyState::B);
}
fn system_b(mut state: ResMut<State<MyState>>) {
state.set_next(MyState::C);
}
fn system_c(mut state: ResMut<State<MyState>>) {
state.set_next(MyState::A);
}
fn startup(mut state: ResMut<State<MyState>>) {
state.set_next(MyState::A);
}
fn main() {
App::build()
.add_resource(State::new(MyState::C))
.add_startup_system(startup.system())
// register state entry handlers (made-up API) in the UPDATE stage
.add_system(system_a.system().run_criteria(State::on_enter(MyState::A)))
.add_system(system_b.system().run_criteria(State::on_enter(MyState::B)))
.add_system(system_c.system().run_criteria(State::on_enter(MyState::C)));
// we don't know which of these three will run first, if at all
// so we'll try each of them once
// then let that transition complete
// and re-run each of these systems again, and so on
}
// Within the same stage:
// startup: MyState::C -> MyState::A
// system_a: MyState::A -> MyState::B
// system_b: MyState::B -> MyState::C
// system_c: MyState::C -> MyState::A
//
// i.e.: MyState::A -> MyState::B -> MyState::C -> MyState::A -> ... (infinite loop)
// or: MyState::A -> MyState::B -> MyState::C -> X (each of these systems has run once, so terminate)What if we then threw in: app.add_system(system_x.system().run_criteria(State::on_update(MyState::B)));
fn system_x(mut state: ResMut<State<MyState>>) {
state.set_next(MyState::A);
}Which of |
Beta Was this translation helpful? Give feedback.
-
|
Don't have to come up with a multiple transition example: running of The snippet will loop infinitely. |
Beta Was this translation helpful? Give feedback.
-
|
Since #1144 is eventually coming, I implemented a nested set abstraction on top of it which I used to make a It handles multiple state changes per tick without issue, acts mostly like the current API without the burden of an extra stage, and could further be improved by using custom label types if we add such an API for system labels. As one final note, this implementation has a stack model that also helps with #1353, and has an incomplete usage example at https://github.com/TheRawMeatball/drone_attack. |
Beta Was this translation helpful? Give feedback.
-
States in Bevy have two main purposes:
Unlike in other engines, you can have as many types of
Stateas you want, each of which gets its own enum and is handled (largely) independently. This comment is a good summary of how States currently work as of Bevy 0.4.Their current implementation has two serious issues:
StateStagewith other work that could safely be handled, prevents work from being done in more appropriate stages, and is generally confusing. This also prevents us from properly handling the intersection of states.Previous Discussion
State was introduced in #1021, and significantly cleaned up in #1059.
This topic was inspired by discussion on Discord (1, 2), with the aim of coming to a conclusion about how to best improve this feature.
Beta Was this translation helpful? Give feedback.
All reactions