It would be great if there were tips on measuring performance, to see where most time is spent.

• Something like a flamegraph?
• Measuring individual systems?
• GPU vs CPU, where is the bottleneck?

Thanks for the great book!

It would be nice to have some introductory section / tutorial on how to make UIs with bevy.

If anyone has any suggestions for what it should include or how it might be structured, please leave comments in this issue.

Stub page already in book; need to write content. Expands on #3.

Recommend some sort of solution for typical debug rendering use cases: wireframe, lines, gizmos.

I recall there were people showcasing this kind of stuff in the Discord. TODO: track that down and figure out if it can be recommended.

Resizing, renaming, etc are all common questions that come up.

Add a section to cover Run Criteria.

It would be great to have a list of things that will wreck your performance, such that users can know patterns to avoid.

• Example(s) of bad ordering of systems s.t. they depend on each other?
• Systems all needing to use a single ResMut<T> (I haven't tried this but I guess it must be bad)

A section on things to avoid and perhaps things to do instead would be really great.

Show how to save/load settings (such as keybindings or graphics/window settings) to persist them across multiple runs of the game.

Currently, there is an implementation of something like this in Sotora. It uses a RON file, without any special I/O abstraction (which would be needed for WASM support, etc.).

There was some ongoing discussion about making a better i/o abstraction for save/load, to be integrated into bevy, but the cookbook should contain an example of something that works now in current Bevy.

Expand the assets page in Bevy Basics, to talk about AssetPath and labels, giving the background needed to understand how to work with GLTF files (and other similar scenarios).

See my explanation in bevy discord for reference: https://discord.com/channels/691052431525675048/742884593551802431/813356658004328458

Commonly requested. See this Reddit thread for a prototype solution.

Clarify that bevy's 2d camera bundle constructor creates a Transform that positions the camera at Z=999 (or something like that, close to the clipping plane). For 2d to behave as expected (Y axis up, looking towards -Z, background at Z=0, higher sprite layers at positive Z coorditnates), this must be preserved.

If users try to create their own transform for their 2d camera, and don't put it at this far-away Z coordinate, they might wonder why they can't see their sprites, or why sprites appear flipped, or why they need to use negative Z coordinates, etc...

Add a cookbook page to show how to manage window parameters.

It should show both how to initialize them using the WindowDescriptor resource, as well as how to change them at runtime (for an existing window).

Very useful, easy to explain. Stick it in the Query chapter

https://discord.com/channels/691052431525675048/742884593551802431/817711420073705482

Using With<(Ball, Collider)> ends up checking for components with that tuple type, which obviously doesn't exist. You need <With<Ball>, With<Collider>> instead.

Example in the wild.

Useful to have a quick lookup of the incantation.

Obviously needs caveats on when to care, and how to interpret.

This would probably really help learners, by directly pointing them to relevant official examples as they read the book.

Bevy Cheatbook should refer enthusiasts seeking to make procedural meshes to the mesh module in the bevy source code here:
https://github.com/bevyengine/bevy/blob/89a41bc62843be5f92b4b978f6d801af4de14a2d/crates/bevy_render/src/mesh/shape/mod.rs

I think an example usage of the world_to_screenspace function to show text on 3D objects would fit nicely in the Bevy cookbook section. Here's an example from aevyrie:

https://github.com/aevyrie/bevy_world_to_screenspace

It's really useful for debugging or showing messages to players

Mixing up add_system and add_startup_system can cause bugs or performance issues that might not be easy to track down for beginners. This might be a good thing to point out in the system function common pitfall page?

I got slightly tripped up on events until I realized I was missing

App::build().add_event::<LevelUpEvent>()

The events page doesn't mention this, although it is mentioned on the App Builder page (the next page in the cheatbook). For comparison, the resources page mentions needing to add the resource to the app builder. Additionally, the systems page does not.

Expand on #3.

I'm currently using this for extremely complex combat events in Fonts of Power.

The core idea here is that rather than emitting an event, you spawn an entity with a marker component, and then look for that in your "event-handling" systems. This has a few nice advantages:

1. You can make lists of various "events" in a heterogenous fashion without needing to resort to trait objects. This is what forced me to switch in the first place.
2. The "events" can be incredibly heterogenous, letting you add only the relevant fields to the specific event emitted.
3. You can change the fields present on each event on the fly.
4. You can perform complex operations with overlapping systems, touching only the events that have the right fields (in this case, components on your event-entity).
5. No need for complex generics.

It also has a few critical disadvantages:

1. Unlike true events, event-entities aren't spawned immediately.
2. Ditto for adding and removing components.
3. Much higher conceptual overhead in simple cases.
4. Cleanup must be handled manually.

Change detection should note that it checks if X has occurred since the last time the system ran, no matter how long it's been since then*.

• for any sane use case at all.

Talk about other uses of Generic Systems.

In combination with Traits?

In combination with Const Generics?

Please share information you know about use cases we should cover, if you are knowledgeable about this.

Stopgap solution for: bevyengine/bevy#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.

Or, use a field name for auto-deref behavior.

Example in the wild

Especially when it comes to making multiple levels.

Cover the fixed timestep runcriteria / how to make systems run on a fixed timestep.

Very common: using Query<SpriteBundle>, rather than asking for the component within it.

Add a page to show how to extend Commands with custom commands for your game.

See this discord post for reference: https://discord.com/channels/691052431525675048/730525730601041940/813570672110469190

Chapter on Bevy Rendering and graphics.

Cover Render Graph, Pipelines, Shaders (and their inputs: vertex attributes, uniforms, etc.), etc.

including usage examples, caveats / implications

Make a page that addresses the common beginner questions about bevy's transforms, such as the orientation of the coordinate system for 2D and 3D, global/local transforms, and the math apis.

EDIT: closing this. Now is not the time for it. I will do this again later in the 0.5->0.6 bevy development cycle, when people have some experience with the new cheatbook revision #33

The Cheatsheet is a page that takes considerable effort to maintain. I am happy to continue maintaining it, if I know that people actually find it useful. Otherwise, I would like to remove it from the book.

The information on that page is redundant; everything on it is also covered elsewhere in the book, with prose and explanations. The goal of the cheatsheet was to be a convenience -- an ultra-concise single-page index, for people who already understand the concepts.

I need community feedback to decide on this. Please vote (using reacts) on this issue:

• 👍 if you would like it to be kept in the book
• 👎 if you wouldn't mind it being removed from the book

This poll is active until it is time to update the book for Bevy 0.6 / the next release of Bevy. I will then make a judgement whether to update the Cheatsheet for the new version or remove it. It will stay in the book until then.

1. Expand the Systems page in Bevy Basics to talk about parallelism/performance and order of execution.

If we do this before the 0.5 release, it should contain two sections, one for 0.4 and one for bevy git.

2. Show the new .before()/.after() and .label() syntax.

This should be done in both the Cheatsheet and in the Systems page in Bevy Basics.

The cheatbook should contain advice on how to set up debugging for various common IDEs, and highlight some common pitfalls when using a debugger on a game.

Here's a template that works for bevy development in VSCode

{
    "type": "lldb",
    "request": "launch",
    "name": "Debug example 'breakout'",
    "cargo": {
        "args": [
            "build",
            "--example=breakout",
            "--package=bevy"
        ],
        "filter": {
            "name": "breakout",
            "kind": "example"
        }
    },
    "args": [],
    "cwd": "${workspaceFolder}",
    "env": {
        "CARGO_MANIFEST_DIR": "${workspaceFolder}",
    }
}

Add a cookbook page for handling multiple buttons across a complex UI.

The pattern to showcase should probably be based on a button identifier with system chains, as used in Sotora.

https://github.com/jakobhellermann/bevycheck

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).

Add a page to talk about how to avoid introducing 1-frame delays into your game / how to handle things with minimal latency.

Talk about why you might want to add systems to bevy's PreUpdate and PostUpdate stages.

1. Spawning entities in PreUpdate, so Commands can be processed before the user's main update systems run, allowing them to work on the new entities.
2. Cleanup in PostUpdate? (is this a good idea? discuss?)
3. For 0.5: Bevy labels to be aware of (if you add a system to PostUpdate, maybe you want it to be before/after the transform propagate system? other important systems?)
4. Input->Update->Output pipeline; read things in during PreUpdate (such as reading a network socket), process things in Update, write things out during PostUpdate (such as writing a network socket). With a network socket, this allows multiplayer updates to be handled in a single frame.
5. Others??

Motivating Example

(from Discord
I have a crit_system that processes crits, causing them to deal double damage. If my actor has the TripleCrits component, instead their crits do triple damage instead. This is handled in triple_crit_system. There are many possible ways in which the crit logic could be varied (e.g. a Keen component), and I'd like people to be able to add their own without needing to touch already written code.

The three obvious ways to do this are:

1. Expand the crit_system to handle every case.
2. Use Without<TripleCrits> in crit_system
3. Overwrite the damage calculation performed in crit_system in triple_crit_system

There are two less obvious ways to do this:
4. Use With<DefaultCrits> in crit_system
5. Use With<{CritType::Default}> in crit_system

4 and 5 (if it works?) are the best choices here, but it seems a bit tricky to remember to always add the DefaultX components

When to Use This Pattern

1. You want to override the behavior of a system for some entities.
2. You need to override it in complex and varied ways, especially if this isn't known in advance (e.g. in mods).
3. You don't want to bloat the behavior or complexity of your default system.
4. The default behavior is expensive or has annoying side effects, making overwriting its final results painful.

When Not to Use This Pattern

1. Your behavior variants are simple or few. Use an enum component instead.
2. You always want to perform some of the default behavior. Split your systems, and use the intermediate result.

How to Use This Pattern

1. Add the DefaultX component to every entity that should be processed by your default system.
2. Add With<DefaultX> to your query in your default system.
3. Add the DifferentX component to every entity whose behavior should be overridden in this way.
4. Add With<DifferentX> component to your query in the overriding system.

Notes

Once archetype invariants land, they will be extremely useful to ensure correctness.

short page on hot reloading? There's a mention of the feature on the main bevy page and an example on the 0.1 release news post, and two examples in the official bevy examples (assets and shaders) but a couple people on the discord were surprised the feature existed

Probably to the chapter on change detection?

Example

bevyengine/bevy#1582

use derive_more::{Deref, DerefMut};
#[derive(Deref, DerefMut)]
struct Score(u32);

let mut my_score = Score(42);
*my_score = 43;

This is much prettier than let my_score.0 = 43 all over the place, and much clearer.