Make Documentation or Behavior for `SystemState` More Straightforward
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 171
Description
This is a very simple Issue – it just serves to bring some attention to, and clear up, a snag in the documentation.
So, I am making an arcade-style video game with a simple UI, with buttons that have callbacks. In [a thread I started on the Bevy community Discord](https://discord.com/channels/691052431525675048/1541102972812140584), I was confused why `Command`s from my UI elements' callbacks weren't being applied when I structured my code using `SystemState`, instead ov rawdogging everything with `World` directly — at first I thought this was a bug; however, after some chatter, someone recommended using `.apply(world)`, something I was previously unaware ov.
Now, to be fair, the documentation for `SystemState` does mention that using `World::run_system` is simpler because it *“ensures that change detection and command flushing work as expected”*; **however**, there is only a cursory mention ov the method in a comment, in a codeblock, as an example.
Maybe this incident could be chalked up to an oversight on my part, but I feel like for being something so important, enough emphasis does not seem to have been placed upon it. — I am an avid believer that the documentation should be straightforward, and it should always guide you to the thing(s) you need, rather than you actively needing to seek out the things you need. (Obviously, this wouldn't apply for "miscellaneous" things. But this is not a miscellaneous thing, your code may not function as intended if you overlook this.)
Additionally, I feel like the comment that mentions `.apply(world)` is contradictory and/or misleading to some degree. On the first line, it says "you can choose when to apply them to the world" – which makes it sound like this action could, if desired, be automatic – but on the next says you must manually apply them, which doesn't make sense, unless something else is meant by "when" (in "choose when to apply them") than what I am thinking.
I feel like the comment could be shortened and more accurately summarized as "When using \`Commands\`, you must manually call \`.apply(world)\` on the \`SystemState\` to apply them.".
I solution to this issue is fairly obvious: tweak the documentation to place more emphasis that things, such as (but maybe not exclusively) `Command`s, don't have any effect until you invoke the proper method(s) — I am making a companion PR, #25558, to go along with this Issue, illustrating what the adjustment could look like.
Contributor guide
Research direction
Start by reading the SystemState documentation and the comment and example covering World::run_system and .apply(world). Clarify when Commands take effect and make the wording about manually applying them consistent with the documented behavior; compare the proposed adjustment in companion PR #25558.】【。
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 75/100