Add documentation for bevy::ecs::Query::removed

[lukors]

This documentation briefly explains what the bevy::ecs::Query::removed function does and how it can be used.

Related to #941.

[cart]

While stages are currently the best way to control system ordering, I think i'd rather make it clear that separate stages aren't "required". The real requirement here is that SystemB runs before SystemA. In the near future we will have other ways to control system order (such as manual dependencies) and alternative schedule executors.

Lets first express that the requirment is system execution order, then say that stages are a good way to control order.

[lukors]

Is really the real requirement that SystemB runs before SystemA? My understanding is that Commands—for instance commands.remove_one::<MyComponent>(entity);—will run after its stage is finished, so even if the system calling Query::removed() (SystemB) runs after SystemA, the component won't be deleted and available through Query::removed() until after the stage.

Is there some other way to remove components than using Commands?

You obviously know much more than me about how the engine works, so feels a bit weird to question your message, but I want to make sure the documentation is as good and accurate as possible. :)

[cart]

Thanks for pushing back 😄. I'll admit to sort of crossing wires here with the Changed/Mutated/Added states. However the "principal" still applies. A removal in SystemB needs to be applied before SystemA runs. Ex: If SystemB is a thread-local system, we don't need to wait for the end of the stage because the remove is applied immediately.

I think it might be useful to call out mechanically why (and when) stages come in to play. Ex:

• query.removed:<T>() only returns entities whose components were removed before the current system ran
• normal systems don't apply remove Commands until the end of a stage, which means normal systems in the same stage won't pick up removals for normal systems in the same stage. you can resolve this by moving your query.removed() system to a later stage.
• thread local systems manipulate the world directly, so removes are applied immediately. systems that run after thread local systems (in the same stage) will pick up removals that happened in the thread local system.

[lukors]

Thanks for the explanation! :D

I've made changes based on this.

Let me know if anything else needs changing.

[ambeeeeee]

You could use doc links here if you wanted.

[lukors]

I considered this, but there were a few reasons for not doing it:

• Quickly glancing at other doc comments I didn't see doc links being used, so this function might be an outlier if it used doc links.
• Links to Entity and Component are already available directly above the documentation in the function definition and you're already on the doc page for Query.

Let me know if I should add them anyway. :)

[cart]

Looks good to me. Thanks!