Reactive Systems / SystemParams and Resource impl

[cart]

Objective

We increasingly would like to write "reactive systems" that can detect when their inputs have been changed. This would enable things like "reactive UI" patterns.

Relates to #19712 (but does not implement a run condition ... see Next Steps)

Solution

This is the implementation from my Reactivity Proposal (without the other tangential bits like system entity targets or controversial bits like the reactive Com SystemParam).

• This adds SystemParam::should_react and System::should_react, making it possible to detect whether a param or system has changed since the last system run in such a way that should prompt a reactive run of a system.
• It also adds an unsafe variant System::should_react_unsafe, which uses UnsafeWorldCell and can be run in parallel contexts.
• It adds reactive impls for Res and FunctionSystems

This notably does not add new traits. Reactivity is something that SystemParams and Systems opt in to by overriding default impls that return false for should_react. It is implemented this way for a number of reasons:

1. It allows all system parameters to be used in reactive contexts, preventing the need for redundant trait impls. People will want to access arbitrary (non-reactive) data in their reactions, and we should let them! Parameters are non-reactive by default.
2. This allows us to use all existing system infrastructure in a way that works with reactions (ex: piping, adapters, combinators, anything involving boxed systems, etc).
3. This keeps our code complexity in check: we don't add more traits or redundant impls to the zoo.

Note that I do not think this is necessarily the solution to the "reactive UI" problem. It might be a piece of the puzzle. This PR is about extending the system API to support reacting to input changes.

Open Questions:

• How will we enable mixing and matching reactive and non-reactive inputs to system? For example Res and ResMut are currently reactive in this PR. Would we use something like NoReact<Res<Time>>, Res<Counter> to prevent reacting to the time parameter while reacting to the Counter parameter? Should we opt parameters in to reactivity via React<Res<Time>>, Res<Counter>? Should we have reactive variants (ex: Res<Time>, ReactRes<Counter>).
• Should we use the word "react" here (ex: System::should_react)? "Reactivity" intersects with the UI space, and this feature may or may not be used for the official reactive Bevy UI solution.

Next Steps

• I made this callable from arbitrary parallel contexts (ex: to support building a run condition wrapper system). However run conditions don't have access to the state of the system they are the condition for, so there is no way for it to know whether the system has been run. We can't just use a duplicate of the system in the run condition, as the change ticks would not update. We can't update the wrapped reactive system's change ticks when should_react is true (aka the ShouldReactRunCondition returns true), because we can't be sure the system will actually run (as the run condition could be combined with other run conditions). We would need to be able to somehow access the actual target system's change ticks from within run condition systems, which I'm not sure is something we want to do. I'm not sure we even want/need a run condition, as most "reactive" scenarios I can imagine would be their own system execution orchestrators (ex: reactive UI running in an exclusive system that polls reactive systems for changes and runs reactions to completion).
• Make more params reactive by implementing should_react()
• Add "reactive queries" that track when matched entities have changed. These would likely require additional overhead and infrastructure, so it probably makes sense to make this a new system param. But thats an open question!
• Consider adding something like my Reactivity Proposal's "system entity inputs", which system params can access. This would enable writing things like:

// reactions that run for specific entities
fn reactive_entity_system(health: Com<Health>) {
  log!("new health: {}", health.0);
}
world.spawn((
  Health(10),
  reactions![reactive_entity_system]
))

// observers that can directly access entity components for the triggered entity
let e1 = world.spawn(Velocity::default())
  .observe(|trigger: On<Jump>, mut velocity: ComMut<Velocity>| {
    velocity.0 = Vec3::new(0.0, 10.0, 0.0); 
  })
  .id();

world.trigger_targets(Jump, e1);

• Consider upstreaming something like my Reactivity Proposal's reaction executor.

[alice-i-cecile]

Upon review, this isn't usable enough to warrant a release note yet :) Still a very nice, clean step forward!

[alice-i-cecile]

Would we use something like NoReact<Res>, Res to prevent reacting to the time parameter while reacting to the Counter parameter? Should we opt parameters in to reactivity via React<Res>, Res? Should we have reactive variants (ex: Res, ReactRes).

I would like this to be opt-out using a wrapper param. We recently merged When this cycle for a similar thing WRT fallible systems, and I think we should use the same pattern here.

[cart]

Upon review, this isn't usable enough to warrant a release note yet :) Still a very nice, clean step forward!

Yeah I think we need to sort out opt-in/out param UX first

[alice-i-cecile]

I think this is the right shape of solution (and much more thought out than my proposal): I'm happy to land this as an incremental step forward.

[Diddykonga]

Very nice, I like the ability to poll a System if any of its SystemParams have Updated/Changed.
If/When we get Queries as Entities, and Observers used to to keep them Updated/Changed, we can likely expand this out to push-Systems.
Archetypes Update -> ArchetypeEvent
On<ArchetypeEvent> -> Queries Update -> QueryEvent
On<QueryEvent> -> Systems Update/Run -> (??? SystemEvent, updates/runs dependent Systems)

[TimJentzsch]

Feel free to ignore this, but the Com/ComMut syntax is strange to me. I get that it's short for Component, but my first thought on seeing it was that it was some other fancy thing I didn't know about. Maybe I'm just not used to it though

Why not just have Query<&Velocity> instead like everything else?

I agree, it took me a while to figure out what Com was supposed to mean. Abbreviations are always dangerous in that aspect.

[chescock]

Cool!

• Should we use the word "react" here (ex: System::should_react)? "Reactivity" intersects with the UI space, and this feature may or may not be used for the official reactive Bevy UI solution.

A more neutral option here might be has_param_changed, in analogy to the existing is_changed terminology. (Or maybe you're planning to extend this in a way where that would no longer match?)

[chescock]

You propagated should_react through tuples and StaticSystemParam, but there are a handful of other wrapper types that we might also want to propagate through: When, Option, Result, Vec, DynSystemParam, ParamSet<(tuples)>, and ParamSet<Vec>. We'll probably want to propagate through #[derive(SystemParam)], too.

Or maybe you were already counting those under "Next Steps: Make more params reactive".

(Hmm, it might be hard to make Option<Res<T>> react to the resource being removed, so maybe that one is even trickier.)

[chescock]

This might be a bit more idiomatic using is_some_and

Suggested change

	if let Some(state) = &self.state {
	<F::Param as SystemParam>::should_react(
	&state.param,
	&self.system_meta,
	world,
	last_run,
	this_run,
	)
	} else {
	false
	}
	self.state.as_ref().is_some_and(|state| {
	F::Param::should_react(&state.param, &self.system_meta, world, last_run, this_run)
	})

[chescock]

Do we really want to allow mutable access in should_react? In contrast, validate_param only permits read access, so that it can be called with &World instead of needing &mut World.

[ElliottjPierce]

This looks like a good, uncontroversial, small step forward. IIUC, this is effectively going to turn into pull style observers. To be honest, I don't know how useful that would be over normal observers, but I've seen you're reactivity ideas, so I'm trusting that you know where this is headed.

On the subject of including "react" in the names, here's my two cents: Systems params will have either changed since the last run or not (a bool). Wether or not a system should react or not feels more like three options: ("I'm not reactive", "I'm reactive and should run", "I'm reactive but shouldn't run".) So personally, I would prefer either doing should_react() -> Option<bool>, where None would mean the system should run since it's not reactive, or you could try any_params_changed() -> bool and is_reactive() -> bool. I don't think it's a huge deal either way, but that's my thought.

For what it's worth, Com and ComMut confused me at first too. Two ideas to consider: If this really is just a component value, why not Ref and Mut. Or even &T and &mut T? Or, if it is intended to support all QueryData types, maybe This<Q: QueryData> or OfTriggeredEntity<Q> or OfWatched<Q>, etc. I don't what what we'd land on, and we don't need to decide now, but those are some ideas.

In any event, this looks good to me. It's nice to see incremental improvements like this.

[ElliottjPierce]

Is there a better way to handle this besides unwrapping? Other unwraps here give a nice error message. It seems possible that the should_react could cause a crash with an opaque error message before get_param would crash with a user friendly error message. It may also be worth providing a nice error message when getting the ticks fails. Same goes for Res as well.

[ElliottjPierce]

False is probably the correct default if we plan to make reactive runs (like those "run if any params changed" ideas) fully opt-in. It's worth mentioning that if we default this to true, we could just make every system run if any params change. That's maybe not what you're shooting for, but I figured I'd point it out.

[viridia]

I was going to suggest adapting the core_widgets example to use this as a way to validate the idea. This currently uses systems and change detection (including removal detection). However, the more I think about it, the more I realize it would be a regression.

The current code updates widgets whose state have changed, using a combination of Changed, Added, and RemovedComponents. Switching this to use should_react() means that I get less information than I did previously - it only lets me know that some widget changed, but not which one. So I end up updating every button any time a single button gets hovered.

To do this efficiently, I'd need to be able to use .should_react() as a query filter, that is, only showing me rows where something changed.

The real problem, then, is that the core_widgets systems design doesn't fit the use case that .should_react() was designed for. In the previous experiments we have done, our reactive architecture was made up of many small atomized systems, where each system concerns itself with a small number of entities, perhaps only one. It wasn't meant for the "classic" ECS system which is doing massive bulk operations on many entities.

These small-scoped systems have their own problem, which is what I think you were getting at with Com: the fact that in order to access data on a single component for a single entity, you have to cast a wide net using queries. If reactions are automatically attached to queries this means that your system is constantly going to be reacting to things that are irrelevant.

[alice-i-cecile]

I'm happy to merge this as an incremental step, but we're going to need a lot more experimentation here :)

[cart]

Haha forgive me for removing it from the queue. I'd like to respond to some of the feedback and consider some terminology stuff :)

[viridia]

I've been thinking about this a lot lately. I don't think this solution, as formulated, will be effective; however I think I know a possible variation that might.

The problem with the approach presented here is that the change detection on queries is too coarse-grained, and will likely lead to (potentially massive) overreaction: formulas getting recomputed too often because of changes to unrelated entities. As I have written elsewhere (#20821), the problem has to do with the way that we use queries in Bevy: we often cast a broad net and then pick out one or a handful of entities that we are really interested in. If we react whenever any entity in the query changes, then we end up reacting even for entities we don't care about.

The solution, I think, is a hybrid approach which combines dependency injection with tracking scopes. We start by defining tracking variants of all of the normal injectable types: Res we get ResTracked, Query we get QueryTracked, and so on. These types behave like their non-tracking, read-only counterparts, but they also remember any accesses and add them to a tracking scope.

For queries, accessing an individual entity gives us an EntityRefTracked, which behaves like a normal EntityRef but also tracks component accesses.

Internally, these objects contain a RefCell<&mut TrackingScope>, which supports interior mutability so that tracked ids can be added to the set even though the context is read-only. Note that there's no borrowing conflict with the world here because the tracking scope is only added to the World after the reaction has reacted (it uses mem::swap where needed to avoid archetype moves).

We can detect whether the reaction should be run by comparing the set of tracked ids to the set of changed resources and components. Every tracking scope has a tick count for the previous reaction; a reaction should happen whenever there are changes more recent than this.

Exactly how the list of dependent ids should be stored is a design question. In my current prototypes, I use a regular HashMap. I have thought about whether it would be possible to use a bloom filter, but I don't think that will work. This is too bad as it would allow tracking scopes to be a fixed size.

In either case, what we are attempting to calculate is whether two sets intersect: the set of tracked components and the set of changed components. Whether this is done by iterating over the tracked components and looking up the tick count for each component, or by looking up the tracking scopes directly after a mutation, will determine whether we use a forward index or a reverse index.

For queries specifically, there are three kinds of changes we care about:

• Whether any of the components accessed during the last reaction have changed.
• Whether any of the entities accessed during the last reaction no longer match the query.
• Whether any new entities which previously didn't match the query now do. Note that this is conservative; we don't know whether the newly added entity will be one that the reaction actually accesses.

A secondary advantage of this scheme is that we know when the reactions are done reacting, we can use the "run to convergence" strategy rather than depending on the order of spawning mentioned above. The problem with relying on spawn order is that there are some rare edge cases where we get an unavoidable 1-frame delay. This can happen if there's a level of indirection between the reaction and its dependency, such that the indirect reference was mutated after the reaction was created to point to a dependency that was spawned later.

This scheme does not work particularly well for mutable injections. To avoid issues around mutation in a reactive context, I have been dividing up my reactions into a "read" or "lens" (as the term is used in functional programming) phase, followed by a non-reactive "effect" phase. Mutation is strictly confined to the effect phase, which does not do any tracking.