So far, learning bevy is limited to short explanations in the book, the incomplete docs, and the examples. I think it would be great if we could include a tutorial for creating the breakout example in the book.

Currently, since the project is moving really fast I've seen a few issues that are fixed by using the git version of bevy instead of using cargo. I assume this will stabilize and won't be an issue, but for now I think it would be good to at least add a note to mention this in the installation guide.

We should be consistent with the bevy and rfcs repositories and switch from master to main.

When debugging actual Bevy games, you almost always want to use info! instead of println in order to reduce blocking behavior.

This is not at all obvious to Rust beginners, and showing them how to use println misleads them into thinking it's a good pattern to replicate.

This was a simple find-and-replace change for me, and resulted in much faster looping.

See https://github.com/bevyengine/rfcs

In the current state, API documentation is left to be auto-generated and hosted by docs.rs when we cargo publish a new version. This requires no effort, but the results are not excellent, especially for a library with many crates like Bevy. By hosting the docs on our own, we can have better control over the generated output.

Benefits

• cross-crate navigation: This is the main concern. docs.rs generates the docs once for each crate, but it doesn't include dependencies. Thus, if we are in the bevy_app crate and we click a link that bring us to a struct defined in bevy_ecs, we lose some perks, like the src links.
• styling: with cargo doc it's possible to style with CSS the generated docs to give them a unique look.
• main branch docs: API docs for the main branch can be generated. This is of minor concern though since it can easily be generated locally.

Strategy

• Change the various Cargo.toml files to include the URL for documentation
• (optional, but would save a lot of labor) Set up a GitHub action for deployment. When run, this will cargo publish the next Bevy version and run a command like cargo doc --workspace --exclude ci --no-deps, storing the output into a subdomain of the website, like api.bevyengine.org
• change the docs on the website to the new location.

As I write many more chapters for the book, the sidebar is getting very long. I think being able to fold the chapters down is the best solution to improve the UX here.

In the spirit of accessibility we should be careful to not use difficult to read color formats/palettes on the website.

I noticed that the greet_people systems (both the foreach and the later query variation) compile and run just fine without the Person reference.

So: fn greet_people(name: &Name) fn greet_people(time: Res<Time>, mut timer: ResMut<GreetTimer>, mut query: Query<&Name>) work just like fn greet_people(person: &Person, name: &Name) and fn greet_people(time: Res<Time>, mut timer: ResMut<GreetTimer>, mut query: Query<(&Person, &Name)>).

Is there a specific reason the author included the Person references here? It seems confusing to me.

I like that the Bevy Guide provides directions for a better linker in the setup guide.

However as the documentation stands, $YOUR_WORKSPACE is unclear across platforms and there is no way to verify if the config is working or not.

Tested on:

• Edge for Android
• Firefox for Android

Would appreciate:

• People confirming they are experiencing the issue on other platforms/browsers
• Someone fixing it :)

Following the setup guide for fast builds on windows leads to errors when using dynamic linking. There seem to be two issues, which both have the solution of turning off "share-generics" for windows builds (bevyengine/bevy#1126, bevyengine/bevy#1110).

Maybe it would be good to offer a solution in the setup guide, or perhaps even temporarily turn off shared generics in the cargo config template.

Users (especially on linux) often don't have the required dependencies to build bevy. It would significantly reduce friction to provide the list for them.

This should extend the existing Setup page with something like:

## Install OS Dependencies
* [Linux](https://github.com/bevyengine/bevy/docs/linux_dependencies.md)
* Windows: You should be good to go!
* MacOS: No dependencies here!

Then the bevy repo would contain linux_dependencies.md with one section for each linux variant.

Is Bevy "data-driven"? It says so on the website, but that's in reference to the engine's cache-optimised design / ECS, I think. If that's the case, I think that "data-oriented" is a better fit.

There is a semantic mess of confusion about what "data-driven" means. Ultimately, I don't think it's very meaningful. I think some use it to refer to game engines having the game implemented as scripts/assets, separated from the engine. In this sense, Bevy is less data-driven than other engines, considering the game code and engine code are built into one executable.

Followup from bevyengine/bevy#2509

"Free and open-source" on the homepage might deserve a call-out.

This could probably go in the book too, but I'm not sure it's important enough / on topic. Those who care can and will check the repo.

This also needs to work for broken short-codes, which are particularly easy to screw up / hard to verify and will break whenever we refactor a referenced item with a rename / module move.

Hello!

I started playing around with bevy (super cool) and it was quite exasperating to be unable to make for-each system with mutable components. Most of the frustration comes from the compiler giving useless feedback about not being able to build a system from the function. Also, most of the examples used query systems for these cases, so it was hard to find.

After converting everything to a query, I stumbled upon this in the Bevy-Cheatsheet:

You must use Mut instead of &mut T.

It would be cool if you could mention it in the book. I tried to look for it but I could not find it or, maybe, this pattern is discouraged, but it would also be worth mentioning it.

The main page screen shot of the syntax is now obsolete, as for-each systems have been deprecated.

The replacement code is:

struct Component;

fn system(query: Query<Entity, Component>){
}

But that doesn't demonstrate how to actually use a Query object smoothly.

Something like:

struct Component;

fn system(query: Query<Entity, Component>){
  for (e, c) in query.iter(){
  }
}

Is probably the most representative of actual use now.

In the final section of the Bevy Book, the example for setting up a timer resource doesn't work. The "greet_people" system produces the following error:

no method named tick found for struct bevy::prelude::ResMut<'_, GreetTimer> in the current scope
items from traits can only be used if the trait is implemented and in scope

HelloPlugin also still uses the add_resource function, which was renamed to insert_resource in 0.5.

I think the example described in https://bevyengine.org/learn/book/getting-started/ecs/ should be updated, now you'll need
to provide a plugin with a SchedulerRunnerPlugin mode, otherwise the app.initialize() is not called and I only see one line in the output instead of the list of people.

Here is a possible modification:

// update use
use bevy::{app::ScheduleRunnerPlugin, prelude::*};

fn main() {
    App::build()
        .add_startup_system(add_people.system())
>>>>        .add_plugin(ScheduleRunnerPlugin::run_once())
        .add_system(hello_world.system())
        .add_system(greet_people.system())
        .run();
}

The same arguments for "strongly typed, semantic" content that apply to API docs apply here too :)

Here it is, the first draft of the monthly update for Bevy.
Any feedback is highly appreciated and very much encouraged.

Here a few points we should make clear/discuss prior to the first publication.

• A catchy name for the updates (I've come up with The Bevy Brief, but the more suggestions the better

• Any section that doesn't have any new updates does not need to be included.

• I've added some examples for some of the sections, the final template should have either a description about what to put or removed any examples/text beside the text of the sections entirely. Other suggestions is very welcome.

Template based on The Bevy Brief PoC:

The Bevy Brief - 001 - Hello World!

Introduction

Community

Pride Month Discord Logo

François now have merge rights! Woohoo!

Bevy Development

Engine-related development progress, the same categories as in the Discord channel.
Keeping up to date on what aspects of the engine is undergoing development.
In the case of a recent release, the new changes/addition should also be mentioned first for each subsection or reference to the bevy news like with 0.5. Arrange in order of major changes or else alphabetical.

Rendering

🎉 Introducing the new Render Pipeline! 🎉

UI

AI

Animation

Assets

Audio

Documentation

ECS

Editor

Input

Modding

Networking

GGOP for bevy is now in the works!

Physics

Rapier has gotten a major update!

...

Scenes

Website

Bevy Awesome is now Bevy Assets, get your plugin or game featured!

XR

Asset Highlight

Newly added assets to Bevy Assets or things that undergoing new major/minor updates that are worth mentioning.

Learning

Unofficial Bevy Cheat Book update!

Assets / Plugins

bevy_transform_gizmo

bevy_editor_pls

bevy_ecs_tilemap

bevy_pixels

bevy_mod_raycast performance improvements!

Apps & Games

Tools

Showcases

Display what people have shown off since the last update.

TheRawMeatball's fruit ninja clone on Android:

Maybe some useful backstory etc... with videos, gifs, or images, everyone loves seeing progress visually.

On small screen sizes or mobile devices the navigation (selector "nav.book-nav") is hidden by CSS. This way it isn't really possible to read the book on mobile devices.

I would expect, that the navigation is either still visible on mobile devices, or an alternative way to navigate the book is provided.

The documentation links for Rust types from the Getting Started guide are broken - for example on the ECS page the link for System points to https://docs.rs/bevy_ecs/std/bevy_ecs/trait.System.html, which doesn't exist on docs.rs.

The link works if std is replaced with 0.4.0 or latest (e.g. https://docs.rs/bevy_ecs/0.4.0/bevy_ecs/trait.System.html)

Currently on the 0.4 news page it says the following:

on_enter: Runs once when first entering a state

What is the first supposed to signify here?
It will run everytime it enters the state. I think it is clearer if you get rid of 'first', so on_enter and on_exit look the same.

There have been a number of cases where the Bevy book falls out of sync from the most recent release and stays that way for a while, confusing new users that come on board right after an exciting new release.

To that end, this code should be fully compiled with Bevy as a dependency, and then its examples checked against the release candidate before the release goes live. Copy-pasting the code into test scripts is tedious, so it would be nice if this occurred more automatically.

I know mdbook supports this smoothly (because I support in Understanding Bevy); I'm not sure that you can do the same in Zola. As an added bonus, swapping to mdbook (#47) lets end users run the example code directly if they clone this repo.

Currently, the setup guide tells Windows users to:

Windows: Make sure to install VS2019 build tools

But following the link and downloading the executable presents them with a baffling (to novice programmers) array of tools to consider. I believe the C++ bundle is what's needed, but that's not at all intuitive, considering we're writing in Rust ;)

Rather than having to specify weight in the file header, extract the relevant information (or maybe just sort alphabetically?) from the file name.

Its trying to deploy the website during validation and (very very fortunately) failing because it doesnt have permission.

We should add another configuration specifically for PR validation.

I was wondering why mdBook wasn't being used for documentation and found @cart commented about this on Discord. I'll quote what he said for anyone else wondering and maybe we can discuss the idea.

Quote of @cart's message on Discord:

I've been playing around with that idea for awhile. It's clearly the more feature complete solution, but I don't want to lose the "integrated feel" of the current implementation. I also think using the same codebase for all website contributions keeps things nice and simple.

It's worth opening an issue to capture this

For myself the "integrated feel" doesn't matter with the documentation. Many awesome open source projects have a separate docs website which I don't mind at all. Bevy could have a docs.bevyengine.org where the documentation would reside at or maybe book.bevyengine.org which seems to be the style for rust projects.

All of the pages in the Bevy Book display well on mobile with the exception of the Resources page where the Time resource is introduced.

Using OnePlus 5T Chrome

All of the book files derive from the same template, so this is a bit curious.

Thanks for this great learning resource, I am really enjoying the docs so far.
In https://bevyengine.org/learn/book/getting-started/resources/ you add:
struct GreetTimer(Timer);
And I was a bit confused why we need a struct there instead of using direclty Timer.
By using Timer:

fn greet_people(time: Res<Time>, mut timer: ResMut<Timer>, _person: &Person, name: &Name) {
    timer.tick(time.delta_seconds);

    if timer.finished {
        println!("Hello {}!", name.0)
    }
}

impl Plugin for HelloPlugin {
    fn build(&self, app: &mut AppBuilder) {
        app.add_resource(Timer::from_seconds(2.0, true))
            .add_startup_system(add_people.system())
            .add_system(greet_people.system());
    }
}

You have a little bit less code, and no need to do the .0..
I was wondering if there is a specific reason to adding a new struct here.

Just as in the main Bevy repo, this would be helpful functionality.

It's particularly nice when combined with /latest/ links to docs.rs, which will let us know if something has been moved and prompt a refresh of that section of the book.

On this page:
https://github.com/bevyengine/bevy-website/blob/master/content/learn/book/getting-started/plugins/_index.md

This no longer compiles in 0.3:

impl Plugin for HelloPlugin {
    fn build(&self, app: &mut AppBuilder) {
        app.add_startup_system(add_people.system())
            .add_system(hello_world.system())
            .add_system(greet_people.system());
    }
}

fn main() {
    App::build()
        .add_plugins(DefaultPlugins)
        .add_plugin(HelloPlugin)
        .run();
}

I still haven't grokked how to do PluginGroups

EDIT:
The compiler error

the trait bound `HelloPlugin: bevy::prelude::PluginGroup` is not satisfied

the trait `bevy::prelude::PluginGroup` is not implemented for `HelloPlugin`rustc(E0277)

Following-up on bevyengine/rfcs#23, here are the steps that I see we need to get this implemented:

• review and merge bevyengine/bevy#2094 for a shiny new breakout game example
• create a skeleton for the new book structure (#154).
• reorganize the Learn section into Quick Starts / Book
• write each chapter of the book
• write the quick start guide for the Breakout game

If you want a chapter, claim it here :) Otherwise I'll slowly write them up and come to the community for help as needed once #154 is merged.

Very useful for 10k word blog posts like 0.5. Try to use standard tools for this to make sure screen-readers play nice.

Hi!

Just noticed the 0.4 update, congrats on the milestone!

I had finished the book recently and was about to do a recap of what I had learned, when I noticed that my code no longer matched the code in the book. This led me to a moment of confusion and I had to dig a little here in the repo to fully understand what happened. In order to avoid this sort of confusion I think 2 things could be done.

1. Display the number of the version of bevvy (used in the book) next to the logo.
   Why?
   This would make it easier for people following the book to know if they should update their crate and expect changes. This is specially true if a new version introduces breaking changes.

2. Version the documentation
   Why?
   By having versioned documentation (with specific urls), you guarantee to your users that the doc will not change as they are going through it. This will become more and more relevant as this doc grows, and finding a solution for this problem is probably easier now than later.

Let me know what you think of this and if you' d like some help.

Cheers

Book navigation has stopped working on all pages except the Getting Started page. This is true in Edge (Chromium) as well as Firefox. The flip-page link/gesture is non-existent except on the Getting Started page.

Hey there,
I did not see a license file in the repo so I wanted to ask if it was okay to fork this website to create my own?

Rather than using page-title/_index.md, it would be very convenient to just be able to use page-title.md.

Unfortunately, I couldn't figure out how to get Zola to do this.

Getting the wrong signature for a function leads to a complex error message like

error[E0599]: no method named `system` found for fn item `for<'r, 's, 't0, 't1, 't2, 't3> fn(&'r mut bevy::prelude::Commands, &'s mut bevy::prelude::ResMut<'t0, GameState>, bevy::prelude::Query<'t1, (&'t2 PieceIndex, &'t3 mut Position), bevy::prelude::With<CurrentPiece>>) {place_current_piece}` in the current scope
   --> src/main.rs:168:41
    |
168 |         .add_system(place_current_piece.system())
    |                                         ^^^^^^ method not found in `for<'r, 's, 't0, 't1, 't2, 't3> fn(&'r mut bevy::prelude::Commands, &'s mut bevy::prelude::ResMut<'t0, GameState>, bevy::prelude::Query<'t1, (&'t2 PieceIndex, &'t3 mut Position), bevy::prelude::With<CurrentPiece>>) {place_current_piece}`
    |
    = note: `place_current_piece` is a function, perhaps you wish to call it

I managed to solve my issue thanks to this reddit comment (specifically I had the arg state: &mut ResMut<GameState> where bevy wanted mut state: ResMut<GameState>), but that was literally the only helpful documentation I could find.

The error and a set of guidelines for what an acceptable fn signature is should be documented somewhere in the bevy book, perhaps in the Troubleshooting section to begin with.

https://bevyengine.org/assets/ is very useful, but "Assets" does not reflect its contents. I would expect "asset pack", rather than "general Bevy resources". This makes it hard to link to coherently and hinders discoverability.

What problem does this solve or what need does it fill?

This would be a nice easy to use tracker for the big game engine areas assets, ui, editor, rendering stuff.

What solution would you like?

We could buy the website arewebevyyet.org and make that similar to arewegameyet.rs

What alternative(s) have you considered?

I guess this could also just be a section on the bevy website.

Additional context

The main reason I thought this was a good issue is that not every wants to dig into a github page to learn stuff about a project. Most people who get into bevy will probably look at its website, not at the github issues/discussions.

Project board and issues tends to be updated with development, this should be updated for released versions.

Some examples: https://arewegameyet.rs/
https://www.arewewebyet.org/

A particular emphasis on open source games would be particularly useful to newcomers who want further examples of how to use the engine.

Most code-based projects I've used have a link to github. I've seen it fairly often in the header, but it's also sometimes in the frontpage and/or the footer. The only link is currently in the Community tab which wasn't obvious to me.

Examples:

• https://deno.land
• https://reactjs.org
• https://rocket.rs
• https://actix.rs
• https://yew.rs
• https://www.getzola.org
• https://tauri.studio/en/
• https://www.meilisearch.com

After trying to find examples it's not as common as I thought outside of the js ecosystem.

Bevy Website repo

• Generate Zola pages from Bevy Assets repo
  • First pass with minimal fields - #156
  • Crate can generate the website - #156
  • Setup CI - #156
  • Crate can validate the input - #163
• Remove other references to Awesome Bevy - #165
• Metadata of assets
  • Image support - #163
  • Agree on complete format and additional fields we want
  • Enrich with crates.io data (license, Bevy version, ...) - https://github.com/alyti/populate-crate-metadata
  • Enrich with github data (stars? not sure it's possible without hitting GitHub api limits)
  • Enrich with other potential sources (gitlab? our own database for ❤️?)
• Website views
  • Basic list view - #156
  • Add a text explanation on what it is and how to add your own stuff, and link to Bevy Assets repo
  • Add a page view per asset - Figma design ideas
  • Asset search
  • Prettier small cards in list view
  • Assets can have one primary tag and several secondary tags, can filter on tag

Bevy Assets repo

• Updated the readme to help with automatic migration:
  • Changed headers - bevyengine/bevy-assets#102
  • Remove markdown links - bevyengine/bevy-assets#102
  • Script for automatic migration - #156
  • Automatic migration - bevyengine/bevy-assets#102
• Repo setup for new Bevy Assets:
  • Setup order for some items - bevyengine/bevy-assets#102
  • Setup CI to validate new files added in a PR - bevyengine/bevy-assets#105
  • Setup CI to trigger bevy-website publish - bevyengine/bevy-assets#105
  • Update the readme (specify new way, describe format, link to Bevy Assets) - bevyengine/bevy-assets#105
  • Update migrations with Assets added since branch creation - bevyengine/bevy-assets#108
  • Switch branch
  • Rename the repo - #165
• Enrich initial repo
  • Fix assets for new constraints (description without markdown and 100 chars limit) - bevyengine/bevy-assets#105
  • Ask for contributors to add pictures, new metadata, ...

Website would be made of several parts:

• Current landing page, blog, community wouldn't change
• Learn section
  • docs and examples unchanged
  • book on mdbook #47 #83
  • Awesome Bevy linking to Awesome Bevy v2 learning section

Awesome Bevy part would pull from another repo files describing all the community contributions and display them integrated in the website (bevyengine/bevy-assets#71)

Work needed for that:

• theming mdbook to the website theme
• setting up new Awesome Bevy
• setting up CI

Downsides:

• CI to deploy will be quite more complex
• Different tools to build different part of the website, making it harder to contribute / maintain

Other options:

• Completely custom site - example https://tokio.rs https://github.com/tokio-rs/website - significantly more work
• Everything under Zola - code examples may have unnoticed errors
• Everything under mdbook - theme & navigation won't be great

What do you think?

Once rust-lang/cargo#9133 stabilizes we can remove the "branch = main" added in #170.

As previously discussed, this is critical information, and important to quickly show to users who are browsing (and eventually filter by).

In the setup page (getting-started/setup) the only dependency specified to run with the config_fast_builds is lld, but clang is also required...

Maybe it should be sudo pacman -S lld clang? (I can open a PR to add that)

I'm also not sure if this affects Ubuntu and other distros (unless they install clang with lld, I'd be inclined to believe so)

And thanks a lot for this awesome crate 😄