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 #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 #28
• Closes #20
• Closes #5
• Closes #37
• Closes #31
• Closes #4
• Closes #3
• ~~not #2~~
• Closes #40
• Closes #41
• Closes #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.

I'm not sure how to debug from here, looking for ideas.

% cargo -vv run --target wasm32-unknown-unknown

error: cannot produce dylib for `bevy_dylib v0.6.0` as the target `wasm32-unknown-unknown` does not support these crate types

% cat .cargo/config.toml 
[target.wasm32-unknown-unknown]
runner = "wasm-server-runner"

Stopgap solution for: https://github.com/bevyengine/bevy/issues/1519

IMO, the correct choice here is to have a page for "I can't add my function as a system!" or something of the like. It should explain each of the options that impl SystemParam, and call out common mistakes for each. As an example, missing &mut for Commands, missing & for components etc.

Hi there ✌️

I'm a web developer landing in the Rust's and Bevy's communities.

I don't know if what I'll report is even possible to fix due to that fact that the Rusts books seem to be self-generated but I've searched for "bevy queries" on Google and found a broken link at the second place of the serp, linking to this page:

https://bevy-cheatbook.github.io/cheatsheet/release.html

I have a huge background into web development (10y+) so ask me if my skills can help :)

Add a section describing how to work with asset labels to address sub-assets in GLTF files.

It should cover how to get individual meshes, scenes, textures, etc. that were loaded from a GLTF file.

It should cover both bevy-generated labels (Scene0, Primitive0, ...) and custom labels (when a GLTF file was exported with labels included in the file).

The example doesn't initialize the AssetsLoading resource, causing:

'Requested resource does not exist: playground::AssetsLoading', /path/to/system_param.rs:394:17

This type of change should likely be added to the other examples.

The change respects the current structure of not showing the strictly necessary code (ie. no Default attribute, and no main() function).

First of all, a big thank you for providing this cheatbook. It has helped me learn Bevy faster than I otherwise would have. With this I hope to contribute back a little in a problem space that I've done a lot of digging in by myself.

I am by no means an expert regarding WebAssembly, however. Therefore, I'd really appreciate if some others could chime in here and offer corrections or additions. I did test everything and do apply the majority of practices documented here in my own projects, but mistakes can always happen.

Additionally, as per the maintainer's request, I hereby waive all copyright regarding my entire contribution.

PartialEq is a required trait for labels, and it's missing in the description. It's a minor correction, but it's a confusing to have the description not matching the examples 🙂

Thanks for your work 🙂

I followed https://bevy-cheatbook.github.io/cookbook/window-icon.html, but that seems to freeze the bevy app. Not sure if it's a bug in winit or bevy or how it's used in the example.

It's specifically the line

primary.set_window_icon(Some(icon));

That seems to make everything freeze

this currently doesn't work correctly when an orthographic scale is applied. this pr fixes it by setting the w component of the pos_wld vector to 1. / ortho_scale, undoing the scale before multiplying the input vector by the view matrix.

The immediately obvious method to build systems generic over a system param such as

fn generic_system<P: SystemParam>(param: P) {}

doesn't work. This is because system parameters need to be generic over two lifetimes so bevy can call it with the correct lifetimes, whereas directly using a given generic as a parameter locks it into a single type that doesn't match what bevy can give it. The solution is to "add back" the lifetimes by going through traits, such as

fn generic_system<P: SystemParam>(
    param: <P::Fetch as SystemParamFetch<'_, '_>>::Item,
) {}

Notes: usually a generic system can't do much with it's generic parameter and needs to hand it over to a user-provided function. If this is implemented as one function, this can require extra bounds:

fn generic_system_builder<P, F>(func: F) -> BoxedSystem
where
    F: Send + Sync + 'static,
    F: Fn(<P::Fetch as SystemParamFetch<'_, '_>>::Item),
    for<'w, 's> <P::Fetch as SystemParamFetch<'w, 's>>::Item: SystemParam<Fetch = P::Fetch>,
    P: SystemParam,
{
    let f = move |x: Res<i32>, p: <P::Fetch as SystemParamFetch<'_, '_>>::Item| {
        dbg!(x);
        func(p);
    };
    Box::new(f.system())
}

Removing any of the where bounds here will cause a compile error. As for potential issues on the callsite for such a function, the parameters need to be given to the builder and cannot be inferred from the closure parameters.

// compiles
generic_system_builder::<Res<u32>, _>(|x| {});
// doesn't compile
generic_system_builder(|x: Res<u32>| {});

Similar patterns also used in the new renderer, with traits such as RenderCommand: https://github.com/bevyengine/bevy/blob/f5039a476d48ec19bd74c94e83e10772565c68f1/crates/bevy_render/src/render_phase/draw.rs#L132

bevy::ecs::system has useful type aliases for working with this pattern, such as lifetimeless versions of Res, Query, etc. and aliases for long type paths.

In the future, when rust stabilizes GAT s, all this should become significantly simpler

Getting the warning below in Bevy 0.9

2023-01-05T22:50:16.707312Z  WARN bevy_ecs::event: Missed 213 `bevy_input::mouse::MouseMotion` events. Consider reading from the `EventReader` more often (generally the best solution) or calling Events::update() less frequently (normally this is called once per frame). This problem is most likely due to run criteria/fixed timesteps or consuming events conditionally. See the Events documentation for more information. 

Doing what is recommended

#[derive(SystemParam)]
struct CustomParam<'w, 's> {
    res: Res<'w, AssetServer>,
    query: Query<'w, 's, Read<Transform>>,
    local: Local<'s, i32>,
}

On this page, the following line is provided:

# add any 3rd-party plugins you use, and make sure to use the correct branch
# (alternatively, you could also specify a commit hash, with "rev")
bevy_thing = { git = "https://github.com/author/bevy_thing?branch=bevy_main" }

This is wrong: the ?branch part of the URL is simply ignored, and the main branch is used. Instead, you must specify `branch = "bevy_main".

If you're not using DefaultPlugins, what plugin do you need for logging to work? I think it's the LogPlugin, but I'm not sure.

I went to the bevy cheatbook page, but couldn't find any info on this.

Show all the common methods for working with angles, vecs, matrices, etc:

• convert f32 to vec*: splat
• add dimension (vec2 -> vec3): extend
• remove dimension (vec3 -> vec2): truncate
• convert degrees/radians
• ...