Tracking issue: new book

[alice-i-cecile]

As I'm sure the audience is aware, the current book is very short. Naively extending it wasn't going to lead to great outcomes, so this RFC for a new structure was approved!

So, how do we get there? So far, we've:

• created a new-book branch that we can safely work off of
• written (and reviewed!) some draft chapters

However, this process sucked, for several reasons:

1. Shortcodes are miserable to write, buggy, require authors to learn a custom DSL, have limited functionality, and make reading the raw code very hard. This is bad for both authors and reviewers.
2. Reviewing an entire chapter at a time means that the turn-around on PRs is super long, and reviewing is very hard.
3. Code samples would regularly break in dumb or subtle ways, as they weren't being compiled. This also made them a lot harder to write effectively.
4. We didn't have a proper style guide in any form.

Overall, this made the process slow, painful and inaccessible. I want to change that. On the technical / process side, I want to:

• Rebase the new-book branch.
• Replace short codes with links (Remove Rust doc shortcodes from new book #272).
• Make the doc links pretty, like our current links (Make links to Rust docs pretty #273).
  • Extend with Add syntax coloring to short code links #200?
• Add markdown linting to CI #207, for quality assurance
• Bevy book code should be compiled against new releases #83, to make sure our code actually works (and continues to work!).
• Enforce formatting of code examples in Bevy book #279, to make sure our code is pretty
• Write a basic style guide for the book, which links to the RFC.

In terms of content, I would like to:

• pick two or three games, and create high-quality tutorials to them that assume 0 Bevy knowledge
• merge the Welcome chapter, and give it final polish review
• merge and polish the ECS chapter
• finish the game logic chapter
• add a rendering chapter
• add an assets chapter
• add an input chapter

Everything else is non-essential (or, like audio and UI, too immature); if you want to work on another chapter feel free, but I don't think we should block the book release for it.

[cart]

This all sounds good to me. #272 works way better than I expected (largely because I didn't know inline code block link aliases were a thing). That also solves #273, as it already formats them as "inline code block links".

I'm in favor of a faster and looser new-book merge process, headed up by @alice-i-cecile. But before that, I'd like to do a final pass over the Welcome and ECS chapters, to ensure we're on the same page when it comes to tone / style / format. I'll try to make that happen in the next few days (yell at me if that doesn't happen!) After thats done, I think some level of autonomy on the new-book branch (with appropriate Bevy Org / community reviews) will be useful to increase development velocity. Throughout the process I'll leave feedback to ensure we're in sync, but this seems like a prime "delegation" case. @alice-i-cecile please try to engage with the community as much as possible and take reviews and feedback seriously.

Additionally, I think we should negotiate what an "mvp old Bevy Book replacement" looks like / what we should focus on there. No sense in blocking on a rendering chapter when the current book doesn't have one.

[alice-i-cecile]

Awesome, I'm on board with all of that.

Community feedback is particularly critical here: the whole point is that the learning material is enjoyable and approachable to a wide audience.

I agree on the MVP: I think welcome and ECS would be enough to be a strict improvement, but we may want to hold off to coordinate a marketing push for the jam.

[SUPERCILEX]

Reposting here for visibility:

I'm finding that I still don't understand how entities, components, or bundles work. For example I just discovered that you can write this query without having to do anything special: Query<Entity, With<SomeComponent>>. The problem is that I have no idea why it works or how I could know that it should work without needing to see it in some random examples.

It'd be amazing if there were docs that explained the following:

• An explanation of how entities, components, and bundles interact with each at the data structure level. That is, walk through an example of adding and then removing some entities, showing what the memory layout looks like (I think Bevy has two, so show both). Also, what's an archetype? IIRC, that has to do with how the entities are stored, so show what happens when some component changes archetypes (again, with some ascii/visual representation of the memory).
• Explain how queries work. I'd love to know how the compile-time stuff works and see an example of how it traverses memory to find stuff.
• Explain the algorithm that decides whether or not systems can run in parallel, i.e. if I add this param what'll happen to the system ordering.
• Other technical details that would be valuable to know

Giving devs an approachable, yet highly technical explanation to Bevy's fundamentals would make a huge difference in understanding what should be possible and having an intuition for what APIs should be available and where they would be.

If more convincing is needed, there are more reasons to do this:

• Make contributing to Bevy itself more approachable. If you know how the system works, then it's much easier to find what you're looking for.
• Attract talent/publicity: a good article would probably get featured on HN and generate more interest in Bevy.

[SUPERCILEX]

BTW, I'm happy review any new chapters from the someone-that-doesn't-know-anything perspective. :)

[SUPERCILEX]

Some more questions I've run across:

• If a system includes a top-level guard such as mouse_button_input.just_pressed(MouseButton::Left), is it faster to put that in run criteria so that the actual system doesn't get run? My guess based on this line would be yes, but I'm not sure how much overhead adding run criteria entails so maybe not.
• Can bevy optimize systems that use filtered queries? That is, does adding marker components to limit query size help when only retrieving one or two entities with query.get(my_entity). For example, is Query<&Transform, With<MyMarker>> better than Query<&Transform>.

[SUPERCILEX]

One more: if only using a query for contains, is it better to write it like this Query<(), With<MarkerComponent>> or this Query<MarkerComponent>.

[BD103]

Can this issue be pinned? I feel its important enough that it should not be lost underneath the newer issues.

[alice-i-cecile]

I'm happy to do that but not immediately sure how. Do you have a link to some docs / an explanation?

[BD103]

I'm happy to do that but not immediately sure how. Do you have a link to some docs / an explanation?

Yup, here are the docs on it. It's just a bit of text on the right sidebar that you need to click. :)

[JMS55]

I'm happy to write a rendering section when the book is accepting contributions (I haven't seen it yet - do we have a dev url?). Planned sub-pages/topics:

• Overview (common user-facing types and API, small explanation of wgpu/bevy_render/bevy_pbr/etc, rendering in general "what is a mesh, what is a material, etc"
• PBR and Lighting (StandardMaterial, direct vs indirect light and sources, screen-space effects, shadow mapping, forward vs deferred, lighting units, etc)
• Post processing
• Performance (what to do, what not to do, CPU/GPU profiling)
• Color (covers bevy_color, color gamuts/spaces, SDR vs HDR, scene-referred vs display-referred values, etc)
• Customization / innards (Material and ExtendedMaterial, shaders, how to write your own plugins, etc. This will not be a wgpu/graphics tutorial, just focused on Bevy-specific concepts) [Probably going to skip this one / leave it for last as it's the most likely to change and most difficult, and really we need to do a ton of cleanup first]

[BD103]

(I haven't seen it yet - do we have a dev url?)

There's no dev URL, the book is just hidden on the website. You can view it at https://bevyengine.org/learn/book/getting-started/why-bevy/ and by checking out the content/learn/book folder.

[SIGSTACKFAULT]

What is going to happen to pages or sections which are duplicated in the book? what should we do with them now to avoid one getting updated and one languishing?

Like https://bevyengine.org/learn/quick-start/getting-started/setup/#enable-fast-compiles-optional and https://bevyengine.org/learn/book/development-practices/fast-compiles/

I assume this was decided, but nobody seems to have written it down

[alice-i-cecile]

Good question! IMO we should remove the duplicated content in the final PR which undrafts the new book.