Support systems that take references as input

[ItsDoot]

Objective

• Fixes Observers get a 'static Trigger and that's unsound #14924
• Closes Allow non-static references as system Input in systems that are ran directly #9584

Solution

• We introduce a new trait, SystemInput, that serves as a type function from the 'static form of the input, to its lifetime'd version, similarly to SystemParam or WorldQuery.
• System functions now take the lifetime'd wrapped version, SystemInput::Param<'_>, which prevents the issue presented in Observers get a 'static Trigger and that's unsound #14924 (i.e. InRef<T>).
• Functions for running systems now take the lifetime'd unwrapped version, SystemInput::Inner<'_> (i.e. &T).
• Due to the above change, system piping had to be re-implemented as a standalone type, rather than CombinatorSystem as it was previously.
• Removes the Trigger<'static, E, B> transmute in observer runner code.

Testing

• All current tests pass.
• Added additional tests and doc-tests.

---

Showcase

let mut world = World::new();

let mut value = 2;

// Currently possible:
fn square(In(input): In<usize>) -> usize {
    input * input
}
value = world.run_system_once_with(value, square);

// Now possible:
fn square_mut(InMut(input): InMut<usize>) {
    *input *= *input;
}
world.run_system_once_with(&mut value, square_mut);

// Or:
fn square_ref(InRef(input): InRef<usize>) -> usize {
    *input * *input
}
value = world.run_system_once_with(&value, square_ref);

Migration Guide

• All current explicit usages of the following types must be changed in the way specified:
  • SystemId<I, O> to SystemId<In<I>, O>
  • System<In = T> to System<In = In<T>>
  • IntoSystem<I, O, M> to IntoSystem<In<I>, O, M>
  • Condition<M, T> to Condition<M, In<T>>
• In<Trigger<E, B>> is no longer a valid input parameter type. Use Trigger<E, B> directly, instead.

[JMS55]

I'd personally rather InMut<Foo> be named InRefMut<Foo> to match Rust's ref foo and ref mut foo syntax.

[ItsDoot]

I'd personally rather InMut<Foo> be named InRefMut<Foo> to match Rust's ref foo and ref mut foo syntax.

But it doesn't match how bevy names things:

• Ref/Mut
• Ptr/PtrMut
• Res/ResMut

[JMS55]

Makes sense, nvm then.

[bushrat011899]

I really like this change and I'm excited to see what we can do once this is merged. Excellent work handling the early DX regressions in type inference.

[bushrat011899]

Was there a particular reason this was added in this PR? I don't disagree with the implementation, but it feels tangential to the goal here.

[ItsDoot]

I added Deref/DerefMut impls for all SystemInputs for future generic usage of abstracting over mutable or readonly access to a type in the input: where I: SystemInput + DerefMut<Target = String>, for example. Since Trigger is now a SystemInput, I added it for equality. If it's a controversial change I'm fine with removing it, but thought I might as well since we're mucking around with observers here.

[bushrat011899]

No that seems perfectly reasonable, thanks for clarifying! Just wanted to get the reasoning written down in-case anyone else had the same thought.

[navneetankur]

Do we need SystemInput::unwrap method? It seems only wrap is needed.

[ItsDoot]

Do we need SystemInput::unwrap method? It seems only wrap is needed.

It's not currently used anywhere but might prove useful in the future.

[navneetankur]

Do we need SystemInput::unwrap method? It seems only wrap is needed.

I asked because:
Currently it creates an artificial limitation than SystemInput::Inner has to be able to converted back to SystemInput. It will prevent us from implementing SystemInput for some weird objects, which only makes sense to convert in one way but not back.
Anyway It's generally better to keep Trait methods minimal.

It's not currently used anywhere but might prove useful in the future.

Okay. Though I feel it would have been better to add it later when needed. Also thanks, for the work.
Edit: On second thought, I am not sure :). If you think it will be useful in future, having it would prevent users from implementing it on such types.

[SkiFire13]

My guess is that unwrap was needed in an earlier iteration but the code that was using it has been removed/changed.

[ItsDoot]

@alice-i-cecile Should be good to go as long as this addition is correct: c08d853 (from #15276)

[alice-i-cecile]

Yep, that validation is correct. Thanks!

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1695 if you'd like to help out.