Major Overhaul for the Bevy 0.5 Release

[inodentry]

Creating this PR as a place for any feedback and review, if anyone from the community has any comments about the new version of the book that I am working on for the new Bevy 0.5 release.

Click here to read the rendered version of the new book.

The new version has major changes and significant reorganization. Many pages have been partly or entirely rewritten. I have tried my best to address any confusion that I noticed people in Discord running into, and to generally make the book a better introductory experience for people new to bevy.

If you have the time, I would really appreciate it if you could try to put yourself in the shoes of a bevy beginner and try to "learn from the book" (by reading the chapters/pages on introductory topics, etc.), and provide feedback on what that feels like.

---

New chapter structure:

• "Bevy Basics" has been replaced with "Bevy Programming" and "Bevy Features".
  • "Bevy Programming" teaches how to program with bevy. (features of bevy as a framework and its mental model) It is further split into "Basics" and "Advanced".
  • "Bevy Features" covers how to use core game engine features of bevy.
• "Advanced Patterns" is more explicit about covering more controversial techniques for advanced users.
• "Bevy on Different Platforms": new chapter to address non-desktop platforms; the WASM content from WASM chapter #23 will eventually be incorporated under here.

Introductory pages on the basics of ECS have been expanded with extra text, to help teach users unfamiliar with the ECS paradigm. Most other things have also been expanded with more detail to help teach new users.

"Bevy Programming" pages have been revised to make explanations clearer and to better recommend good practices. I've tried to limit such recommendations to common confusions about the ECS paradigm, because I believe that these introductory chapters should be as unopinionated as possible.

Entirely new pages:

• Bevy Programming > Intro to ECS
• Bevy Programming > System Ordering
• Bevy Programming > System Sets
• Bevy Programming > Run Criteria
• Bevy Programming > Labels
• Bevy Features > Transforms and Coordinates
• Common Pitfalls > UI is not displaying
• Bevy on Different Platforms

Pages with major rewrites or new content:

• Bevy Programming > Resources > Usage Advice
• Bevy Programming > Plugins
• Bevy Programming > Local Resources
• Bevy Programming > Hierarchical Entities
• Bevy Programming > States
• Bevy Programming > Stages
• Bevy Features > Assets

Addressed Issues:

• Closes ECS v2: system param limit is now 12 #28
• Closes Common pitfall: querying for bundles #20
• Closes Order of execution (both v0.4 and v0.5); system labels and dependencies (v0.5) #5
• Closes Discuss relationship between Rust module/file structure and Bevy Plugins #37
• Closes Page about Transforms #31
• Closes Asset paths and labels #4
• Closes Run Criteria #3
• not Page about working with GLTF in Bevy #2
• Closes Events page should mention add_event::<LevelUpEvent>() #40
• Closes Common Pitfall: using add_system instead of add_startup_system? #41
• Closes Improve change detection chapter clarity #45

Meta organizational changes:

• The main book will no longer contain any info specific to bevy's git main branch. Instead, the next branch is the place for any work to cover new developments, in preparation for the next bevy release. It will stay published at the URL above.

[TheRawMeatball]

Alright, I read through the ECS section, and here's my review (if some of this stuff is just not done yet, then just ignore it :) )

1. Expand the bundle description

• Show #[bundle] for nesting them
• Highlight querying them as a common pitfall

2. Maybe reword the resources part a bit? they don't need to be monolithic, and if a piece of data isn't clearly associated with a particular entity, and there aren't duplicate copies, it should probably be stored as lots of small resources.
3. Query sets are nice, but often times they aren't the correct fix for a beginner mistake. An alternative pattern is to pull the conflicting access into it's own query and use .get
4. For Local<T>, explain how they can be configured using the .config() syntax

[inodentry]

Show #[bundle] for nesting them

I wasn't aware that this problem was already solved! Could you point me to an example or help me write one?

Highlight querying them as a common pitfall

WIP

resources

Yeah, the wording can be better. I will address your comments. :)

query sets

I should probably move them into their own separate page under the "Advanced" section, rather than introducing them on the same page alongside basic queries.

Local

Will do. Never personally seen that syntax, so I'm gonna have to go find it / look it up.

[inodentry]

Also, could someone help me with Run Criteria Labels? After searching through bevy api docs, I could not figure out how they are meant to be defined and used. I am not sure i understand them.

I presume they are for the use case of reusing the same run criteria in multiple system sets?

I know that a run criteria can be added to a system set, by adding it as a system.

If using labels, where would they be defined, and how would they be used?

Where can I find out more about this stuff?

[TheRawMeatball]

I wasn't aware that this problem was already solved! Could you point me to an example or help me write one?

bevyengine/bevy#1588

Local

I used them to implement states, you should be able to find examples there. Using them to emulate closures should probably be under advanced patterns

[TheRawMeatball]

As a heads-up, you should probably update the page on generic systems to explain how they don't out-of-the-box with labels (see bevyengine/bevy#1497)

[MinerSebas]

When talking about which Types are allowed in a System I would make two additions:

• Directly mention that the type needs to implement SystemParam
• Structs that derive SystemParam and are only made of such Types are also valid.

[inodentry]

I will merge this tonight (say, in ~6 hrs). Please provide any additional feedback you may have, until then.

If there is any wrong or misleading information, please let me know. This is the most important type of feedback.

If it is something with the wording or specific content, I'd prefer if you use the github review functionality to leave comments on the diff.

If it is a missing feature / something left un-addressed, I'd prefer if you file a separate github issue, so that I can decide whether to address it here in this PR, or leave it for later.

[alice-i-cecile]

In really advanced scenarios, if you insist on all affected systems becoming settled during the same frame, you might be able to do it using Looping Run Criteria.

This can also be done very nicely with states. They are, of course, built out of Looping Run Criteria, but that's likely not obvious.

[alice-i-cecile]

Added: detect adding new components to existing entities
Changed: detect when a component is modified

This is not a great explanation. Added also triggers when you create a new entity with those components. Changed is also triggered whenever Added is.

[alice-i-cecile]

Stages are also the only way to apply Commands.

Outside of exclusive systems.

[inodentry]

(circular deps)

This can also be done very nicely with states. They are, of course, built out of Looping Run Criteria, but that's likely not obvious.

I actually struggle to imagine how the problem would be solved using states. I can easily imagine how to solve it using looping run criteria directly. That's why I wrote that statement like that.

For now, I simply noted it, but if you could file an issue with some example or something to show me how it would actually be done, I'd consider expanding that section in the future.

(change detection)

This is not a great explanation. ...

OK, I agree, I expanded that part to clarify. Also explicitly clarified the reliable nature of the new change detection 😄 (as you suggested in #45 )

(applying commands)

Outside of exclusive systems.

But exclusive systems are tied to stages anyway (afaik they have to run at the start or end of a stage), so it is effectively the same thing in practice (as in, you still need to understand and work with stages to control commands application).

I think I'm gonna leave that as it is right now. This could be addressed in the future when I make the page about exclusive systems and direct world access.