Event-dependent run criteria for systems

[alice-i-cecile]

What problem does this solve or what need does it fill?

Some systems should only run when there are events to be processed.

This is a common pattern, but annoying

What solution would you like?

A simple run criteria helper function that checks whether an event queue of the specified type is empty.

Because run criteria apply to multiple systems at once, I don't think you can have it automatically inspect the parameters of the systems its modifying.

What alternative(s) have you considered?

Users can write their own run criteria by hand. This is tedious and error-prone.

Event-handling systems can return early if they have no work today. This combines internal logic with scheduling logic, and forces scheduling of a system when it's not needed, possibly blocking other systems' access to archetype-components or resources.

Additional context

This functionality relates to but is distinct from triggered systems, as discussed in #1273. Something morally similar might be helpful as part of a scheduler for a dedicated UI stage.

[tigregalis]

Previous work/discussion that is in a similar vein: #1041

[alice-i-cecile]

I think that the event_system API shown here is the clearest of the available options, and captures the desired functionality well.

You'll want to configure it so then the system runs if any of its event queues are non-empty, to properly handle the case of systems that read more than one event type.

This is mostly relevant at the system level, so losing the ability to generalize it in an ultra-convenient way to a SystemSet or Stage is not very concerning to me. You can always manually write a run-criteria.

The only other caveat is that by expanding the .system() syntax for other use cases, we're limiting our ability to remove it again in the future if we can find appropriate magic to do so.

[alice-i-cecile]

A similar pattern emerges for processing component data, where you only want to run a system if a query is non-empty, typically on the basis of Changed.

This is also related to the idea of ChangedRes, discussed in #1186.

Ideally we could handle all this in a single abstraction?

[alice-i-cecile]

So to capture the idea from the comment above, what I think we actually want is a run criteria of:

RunCriteria::Processing: the system will run if and only if at least one of the change-tracked resources has been changed, its EventReader buffer has events to process, or a query that contains a Changed (or similar query filter) is non-empty.

The name could use some workshopping, but I think this is an abstraction that captures a lot of patterns. In particular, I think that this could seriously mitigate the need for hard run criteria at all (see the infamous #1144). I think this also requires some thinking about how exactly to handle ChangedRes (see #1313 as well) to really capture well.

Edit: I think this is too magical. Instead, we should have more explicit run criteria helpers based on change detecting queries and event readers.

[alice-i-cecile]

The problem is that System s are opaque, and this data isn't very accessible. The problem also gets worse once nested system sets come into play.
Detecting a query with Changed is messy - it could be interminled with Or statements, or and-ed with a diffrent Changed, or just be arbitrarily deeply nested in with tuples.
ChangedRes is on its way out, and I don't think this is enough motivation to keep it around
With all three of these, you end up special-casing for specific types in a lot of places. I don't think this is the way to go

@TheRawMeatball, Discord

[alice-i-cecile]

Blocked on a better design for run criteria in #2801.

[alice-i-cecile]

Closing this out; I don't think this is the right direction (at least for now).