Thoroughly document the current state of observers #19590
Conversation
alice-i-cecile
added
C-Docs
| //! By contrast, [`EventReader`] and [`EventWriter`] ("buffered events"), are pull-based. | ||
| //! They require periodically polling the world to check for new events, typically in a system that runs as part of a schedule. | ||
| //! | ||
| //! This imposes a small overhead, making observers a better choice for extremely rare events, |
There was a problem hiding this comment.
would be nice to quantify "extremely rare" rather than leaving it up to the user's interpretation. Many users will think of "extremely rare" as a user-driven button click seconds or minutes apart, while others will think of "once every N frames".
There was a problem hiding this comment.
Indeed! But I don't have any benches to provide guidance here right now.
| //! ## Observer timing | ||
| //! | ||
| //! Observers are triggered via [`Commands`], which imply that they are evaluated at the next sync point in the ECS schedule. | ||
| //! Accordingly, they have full access to the world, and are evaluated sequentially, in the order that the commands were sent. |
There was a problem hiding this comment.
Fun anecdote: During the game jam, I had a case where I was using Commands (let's call this C1) to trigger an observer in a system that also had a custom SystemParam that had its own Commands (C2). Not thinking about it too much, I used C1, then called a method that internally used C2, and then afterwards used C1 again. But because these were separate command queues, the execution order was actually either C1 C1 C2 or C2 C2 C1, which in this scenario caused a logic bug that gave me infinite recursion! This one was fun to track down :P
Co-authored-by: Chris Biscardi <chris@christopherbiscardi.com>
Co-authored-by: Joona Aalto <jondolf.dev@gmail.com> Co-authored-by: Chris Biscardi <chris@christopherbiscardi.com>
Jondolf
added
S-Ready-For-Final-Review
Objective
The documentation for observers is not very good. This poses a problem to users, but also causes serious problems for engine devs, as they attempt to improve assorted issues surrounding observers.
This PR:
Trigger#14726.To keep this PR at all reviewable, I've opted to simply note the various limitations (some may call them bugs!) in place, rather than attempting to fix them. There is a huge amount of cleanup work to be done here: see Alice's Work Planning.
Solution