Added a detailed tutorial for the breakout game to the Bevy book. #102

rhulha · 2021-02-28T07:44:21Z

I went ahead and added a very detailed tutorial for the breakout game to the Bevy book.
I double checked every link and that it works as advertised. ;-)
I hope it is useful to the community.

rhulha · 2021-03-11T11:43:08Z

Any update on this?

cart · 2021-03-11T18:34:15Z

I'll give it a run through soon. Long-form tutorials require more scrutiny and I want to give this the time it deserves, but we're also trying to get the 0.5 release ready. I'll try to get to this asap.

content/learn/book/your-first-game/_index.md

MinerSebas · 2021-03-11T23:21:59Z

content/learn/book/your-first-game/_index.md

+Why is that necessary?  
+Well two fold: It is usually good practice to give every object in a game its own material. Otherwise it can happen, that you change the color on one object and suddenly you
+have changed the color on all objects that share the same material. This is usually not what you want. Secondly, of course Rust would like to have a single material owner per SpriteBundle instance.
+So in this case we can solve both requirements with a simple call to ```wall_material.clone()```.


Does it really handle the shared material?
I thought you are just cloning the handle itself, not the ColorMaterial it is pointing to.

Agreed. Handles are ref counted though, which may be worth mentioning?

rhulha · 2021-03-16T15:32:01Z

Thanks for the review @MinerSebas
I like your suggestions very much.
Do I have to do anything?
Resolve them all? Commit something?
Or is that cart's job?

MinerSebas · 2021-03-18T11:22:14Z

You should apply the suggestions which you agree with.
If you made the change, you can mark those comments as resolved.

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

This PR fixes #1240, where the ball is escaping the playing field at low framerates. I did this by moving the movement and physics system into a Fixed Timestep system set and changing the movement steps to a constant. So we lose the example use of delta_time for changing position, but gain a use of FixedTimestep. If this is accepted bevyengine/bevy-website#102 will need to be updated to match. Co-authored-by: Carter Anderson <mcanders1@gmail.com>

rhulha · 2021-04-16T15:21:06Z

I compared the tutorial code to the 0.5 release code. It is very similar.
Would it be an option to accept this pull request and then fix the few differences?

cart · 2021-04-16T20:36:36Z

Now that 0.5 is released, we'll want to make sure the tutorial matches the 0.5 release prior to merging. I'm starting my review now.

This PR fixes bevyengine#1240, where the ball is escaping the playing field at low framerates. I did this by moving the movement and physics system into a Fixed Timestep system set and changing the movement steps to a constant. So we lose the example use of delta_time for changing position, but gain a use of FixedTimestep. If this is accepted bevyengine/bevy-website#102 will need to be updated to match. Co-authored-by: Carter Anderson <mcanders1@gmail.com>

rhulha · 2021-04-23T20:13:50Z

Thanks Carter. Much appreciated!

rhulha · 2021-04-29T07:15:00Z

Now that bevy 0.5 is out, I believe that it is a good moment to turn some attention to the learn section of the bevy book.
Currently there are only the very basics explained.
Barely more than a hello_world plugin.
I am not trying to disparage the current page, it is a great start and I used it to great success myself.
But I truly believe now is the time to add a page that goes into detail on a real world example:
The truly inspiring breakout example.

cart · 2021-04-30T02:21:42Z

First, I apologize for not doing a full review yet. I got distracted by the renderer rework and reviewing other things that definitely take precedence (like bugs / safety issues).

We definitely need to start expanding the book. I've been overly protective of the content we add to it for a long time because I have specific goals for the tone + voice of the writing. But I also haven't had the time (or inclination) to write content myself, so its a bit unfair for me to hold the book hostage indefinitely (and tone / "voice" can be addressed in code reviews).

My biggest concern about the Breakout example (and why I haven't just quality checked the content and merged it) is that it isn't necessarily the best way to introduce Bevy concepts. I want the Bevy Book to intentionally layer on concepts piece by piece. Starting from the idea to "write a tutorial on how to write Breakout" isn't necessarily the best way to teach people what they need to know. As a general rule we should come up with a list of things to teach first, define an order that they should be taught, and then try to write a set of tutorials that cover that content (and maybe generate a complete game ... but that isn't even necessarily a requirement).

Again, this isn't a comment on the quality of the breakout tutorial (which I haven't worked through fully yet), just a general comment on book methodology and how I assign priorities to things.

A "how to write X in Bevy" style of tutorial is at the very least still extremely useful and would be a good blog post. Once I work through it I'll hopefully have an opinion on if it is a good fit for the bevy book.

cart · 2021-04-30T02:23:54Z

I'll also link to this in the Bevy discord so we can get more eyes on it / opinions on Bevy Book direction.

alice-i-cecile · 2021-04-30T02:43:14Z

This is great work! If we decide not to merge this, please, please contribute this to awesome-bevy @rhulha so others can benefit from it :)

My biggest concern about the Breakout example (and why I haven't just quality checked the content and merged it) is that it isn't necessarily the best way to introduce Bevy concepts.

I agree with this. Progressively growing tutorials can be a great approach, but I don't think this Breakout game is a great choice for that. The code quality isn't optimal (it prioritizes simplicity over good architecture) and doesn't hit all the points we might want.

We definitely need to start expanding the book.

Agreed. I think we should design on a high-level vision for what it should be, write up some style guides and then open it up to contributions. IMO those details are best finalized in an RFC, and then added to this repo's CONTRIBUTING.md.

As a general rule we should come up with a list of things to teach first, define an order that they should be taught, and then try to write a set of tutorials that cover that content (and maybe generate a complete game ... but that isn't even necessarily a requirement).

I agree with this philosophy; this is a great place to start from. A concept map might be a nice place to start planning that?

cart · 2021-04-30T03:20:37Z

IMO those details are best finalized in an RFC, and then added to this repo's CONTRIBUTING.md

Yeah I agree with this. I'm cool with using the RFC rfc repo for documentation stuff, as I consider the Bevy Book to be a part of the "Bevy product' as a whole.

rhulha · 2021-04-30T07:35:56Z

Thank you all for your great feedback. I have two comments:

Regarding the statement: "I've been overly protective of the content we add to it for a long time because I have specific goals for the tone + voice of the writing."

I completely understand with the voice and tone goals. Please feel free to change any of my jokes or quips if there are any. Or to change anything else. But I also agree with the statement of being overly protective.
I would like to argue that the tutorial I wrote adds more utility to the bevy book and the community than the tutorial not being
there. Could there be a better tutorial coming in the future? Sure. But until then, let's just add this for now.
Please also consider that the bevy book currently points to exactly the breakout game as a next step to look-at here:
https://bevyengine.org/learn/book/next-steps/

So it is hard for me to understand that the breakout code is deemed not great on the one hand, therefor we should not have a tutorial on it, but on the other hand it is fine to have a direct link to the source code without the explaining words from my tutorial.

Unless you believe that my tutorial will misleads users and move them in the wrong direction. I still believe that adding
the tutorial adds more value than not having it there. And I promise if a better tutorial comes along and you delete mine,
I will not have any hard feelings.

Regarding the statement: "My biggest concern about the Breakout example (and why I haven't just quality checked the content and merged it) is that it isn't necessarily the best way to introduce Bevy concepts. I want the Bevy Book to intentionally layer on concepts piece by piece. "

I believe I had and have the exact same sentiments and you might be happy to learn, that I did exactly that: Introduce the concepts piece by piece. I did not simply go through the breakout source code and just explain every line of code, no, instead I created 5 new projects all based on the breakout source code.

In each of those new projects I introduce a new concept.

First I start with a breakout example that only has the paddle:
https://gist.github.com/rhulha/0d41043539b979b1da450ee0c745490d
This is a complete self-contained example.

Then if readers want to go on and learn more, in the next step I show how to add the walls:
https://gist.github.com/rhulha/1697c629433896608b9485b6fe112321
Again a complete self-contained example.

Then if readers want to go on and learn more, in the next step I show how to add the ball and the collision system:
Again a complete self-contained example.

Then if readers want to go on and learn more, in the next step I show how to add the bricks:
Again a complete self-contained example.

Finally if readers want to go on and learn more, in the final step I show how to add the Scoreboard using a TextBundle.
This of course then represents the original source code.

I really tried my best to be careful and considerate with a beginners time and expectations of learning, exactly as you said, piece by piece.

This tutorial represents, to the best of my knowledge and experience, the dream tutorial I would be happy to read on any game engine anywhere.

My best whishes,
Ray.

alice-i-cecile · 2021-05-03T21:45:27Z

I would like to argue that the tutorial I wrote adds more utility to the bevy book and the community than the tutorial not being there. Could there be a better tutorial coming in the future? Sure. But until then, let's just add this for now.

I can very much see the value in this, especially if we can't get an alternate solution in place for the 0.6 launch. Fundamentally, I'm not sure that much of the existing content will exist after a full revamp, which means that removing more won't make the situation there worse (especially since this content can be migrated).

I'm going to do a full review of this today, let's see if we can get something better up. The return on investment in terms of Bevy's success of better highly-visible tutorial content is extremely high.

P.S. I would very much like to see #83 fixed as we extend the book out more; the maintenance burden of manually testing this code and perils of releasing broken tutorial code are both too high for my comfort.

content/learn/book/your-first-game/_index.md

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

alice-i-cecile · 2021-05-03T22:48:37Z

Alright, review is finished. There's a bunch of small nits that will be easy to address, so I'll focus on the larger stuff here.

The code quality of the Breakout game is... not great. Sorry Cart! Things like monolithic setup systems, the unidiomatic way we access the text, the awkwardness around setting the max time step. Those should be cleaned up before we integrate this into the book and further encourage bad habits.
The Breakout example is missing some pretty critical patterns that are essential to Bevy games. Namely: code organization practices (modules and plugins and states), events, change detection, audio and asset loading. We could expand the example in the future to get around this, or work to build a new one.
I don't love the practice of commenting out lines as we go. IMO this example should be split into three separate pages: paddle and walls only, adding ball + bricks, adding the scoring system. This will also help with length. Don't include dead code, just modify functions later as its needed. At the top of each of those pages, link to a gist or use some sort of code folding to have the complete code for that step shown.
Like I mentioned above, we're really going to need to fix Bevy book code should be compiled against new releases #83 and automatically compile and test this code somehow for this to be maintainable in the future. I'm not entirely sure how to best do that. @mockersf, what's your perspective on this question?

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

rhulha · 2021-05-03T23:00:13Z

Wow, thank you alice-i-cecile,
this was a thorough review..
Your changes and ideas are great!

My only feedback at this moment is, that using git to work on the webpage/tutorial doesn't seem very agile.
I personally would suggest to have something more like a wiki with named write access only.
So you and everyone who is allowed can do direct changes.
I think having to accept and click two buttons for every backtick change is a bit overkill.
But hey, if it works for you guys I am happy as well.

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

rhulha · 2021-05-03T23:03:33Z

Also, I have to click on "66 hidden items" "load more" wait 3 seconds. Click on two buttons to accept a change request.
And then the whole page reloads and I have to click on "67 hidden items" "load more" again... rinse and repeat.

I am probably too uneducated in the ways of the Github, but this is super annoying.

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

alice-i-cecile · 2021-05-03T23:08:15Z

My apologies @rhulha; I should have just made a PR to your branch. It started off as a quick review, but then it ended up being a comprehensive edit. If you'd prefer, you can just mark my comments as resolved and implement them manually.

The other workflow that can work well if you're collaborating intensively with a few people is to make them collaborators on your fork, which then lets them make commits directly.

rhulha · 2021-05-03T23:09:50Z

Oh no, it's not your fault that Github reloads the page every time I accept a change...

68 bottles of beer on the wall, 68 bottles of beer.
Take one down, pass it around, 69 bottles of beer on the wall...

mockersf · 2021-05-03T23:11:29Z

I'll just comment on @alice-i-cecile points, you're the one who pinged me 👍

The goal of the game examples are not "great code quality". In my opinion, it's "good enough quality given the constraints": small number of systems, only one file, nothing too complex.
Related to first point. The Breakout example is not meant to be complete. We should do some, there is More complex game examples bevy#1248. Just a complete breakout would be great for that, and would be ton more complex than the existing example
I agree. More on that below
I'll reply there

I wanted to mention two tutorials for other game engine that I followed:

Amethyst Pong Tutorial: https://book.amethyst.rs/book/stable/pong-tutorial
- + At the beginning of Amethyst docs
- + Nice step by step
- - Never worked for me when I tried to do it (two different times)
Godot Your first game: https://docs.godotengine.org/en/stable/getting_started/step_by_step/your_first_game.html
- - Late in the doc, I actually just skimmed over it after reading everything before
- - All in one page, not split at all
- + Doc before that was top, and after reading the first chapters of the step by step (before the game tutorial) I was actually able to pick what I wanted from the doc without reading everything

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

alice-i-cecile · 2021-05-03T23:24:52Z

The goal of the game examples are not "great code quality". In my opinion, it's "good enough quality given the constraints": small number of systems, only one file, nothing too complex.

I think we can improve this significantly within the constraints there still. While they may not be complete, they should be exemplary: worth emulating and learning from in addition to serving as tests. I'll try to get a PR to the main repo for that in though; it's been bugging me for a while.

Related to first point. The Breakout example is not meant to be complete. We should do some, there is bevyengine/bevy#1248. Just a complete breakout would be great for that, and would be ton more complex than the existing example

I agree. This is mostly a mark against taking the approach of adapting one of our existing simple examples to serve as a tutorial. I like the idea of having both a simple and complex breakout a lot!

rhulha · 2021-05-03T23:37:47Z

If it might be useful to hear from an actual beginning Bevy user, I found the breakout example extremely helpful.
I loved that it

was a real game that was actual fun and engaging to play.
was using text elements to show the score.
had collision detection and fun bouncy physics.
was easy to read and understand even for a Rust and Bevy newbie like me.
showed and handled different things like graphics, positioning, physics, text and input.

Of course I can't judge if it would be possible to make the breakout source code even better, since I don't know enough about Bevy. But for my personal taste, the example was awesome and gave me a really good first impression of Bevy as an engine, while also showing what was different about it to other engines that I had used in the past. (The Rust things and the cool query syntax come to mind). I liked it so much in fact, that I felt bad, that there was no tutorial using it as its foundation.... And well, the rest is history. :-D

Cheers! I love you all!

B-Reif · 2021-05-05T05:38:17Z

I think we can improve this significantly within the constraints there still. While they may not be complete, they should be exemplary: worth emulating and learning from in addition to serving as tests. I'll try to get a PR to the main repo for that in though; it's been bugging me for a while.

It's also helpful to explain why some bit of code is exemplary. For instance, the Rust book has a nice section on some basic refactoring techniques. A tutorial can teach more by starting with something quick/sloppy, and then include refactoring in the tutorial's content.

Some of the changes in bevyengine/bevy#2094 might also make sense as steps in the tutorial!

alice-i-cecile · 2021-05-05T05:47:40Z

I like the idea of refining code a lot, and showing the refactoring process. It's very educational, but almost never formally taught.

alice-i-cecile · 2021-05-13T03:12:21Z

I've written up an RFC on how to revamp the book now!

Of note, I propose splitting the learning material into two paths: Quick Start and the Bevy Book. A condensed and updated version of a Breakout tutorial would fit well as one of our Quick Start games.

alice-i-cecile · 2021-05-25T02:29:05Z

We'll be looking for a refreshed version of something very similar to this as part of a Quickstart Game. See bevyengine/rfcs#23. Thanks for the awesome inspiration!

That will need to be a new effort, basically from scratch to compensate for changes to both the website structure and Breakout code changes though, so I'm going to close this PR out <3

This PR fixes bevyengine#1240, where the ball is escaping the playing field at low framerates. I did this by moving the movement and physics system into a Fixed Timestep system set and changing the movement steps to a constant. So we lose the example use of delta_time for changing position, but gain a use of FixedTimestep. If this is accepted bevyengine/bevy-website#102 will need to be updated to match. Co-authored-by: Carter Anderson <mcanders1@gmail.com>

Added a detailed tutorial for the breakout game to the Bevy book.

02001b4

hymm mentioned this pull request Mar 3, 2021

[Merged by Bors] - Change breakout to use fixed timestamp bevyengine/bevy#1541

Closed

MinerSebas reviewed Mar 11, 2021

View reviewed changes

rhulha and others added 10 commits March 20, 2021 03:18

Update content/learn/book/your-first-game/_index.md

314b83f

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

Update content/learn/book/your-first-game/_index.md

b691c02

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

Update content/learn/book/your-first-game/_index.md

14e6512

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

Update content/learn/book/your-first-game/_index.md

7e6b40b

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

Update content/learn/book/your-first-game/_index.md

ee6b0bf

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

Update content/learn/book/your-first-game/_index.md

4237d79

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

Update content/learn/book/your-first-game/_index.md

183b477

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

Update content/learn/book/your-first-game/_index.md

f1d46b0

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

Update content/learn/book/your-first-game/_index.md

06713e3

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

Update content/learn/book/your-first-game/_index.md

ec68014

Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com>

alice-i-cecile reviewed May 3, 2021

View reviewed changes

content/learn/book/your-first-game/_index.md Outdated Show resolved Hide resolved

rhulha and others added 2 commits May 4, 2021 00:44

Update content/learn/book/your-first-game/_index.md

915b34d

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Update content/learn/book/your-first-game/_index.md

0c3ae0f

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

rhulha and others added 2 commits May 4, 2021 00:50

Update content/learn/book/your-first-game/_index.md

0ee045b

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Update content/learn/book/your-first-game/_index.md

9dbe419

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Update content/learn/book/your-first-game/_index.md

af44d55

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

rhulha and others added 2 commits May 4, 2021 01:05

Update content/learn/book/your-first-game/_index.md

4437f3a

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Update content/learn/book/your-first-game/_index.md

5771407

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

rhulha and others added 6 commits May 4, 2021 01:16

Update content/learn/book/your-first-game/_index.md

2fff522

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Update content/learn/book/your-first-game/_index.md

5a70b25

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Update content/learn/book/your-first-game/_index.md

f32aa9c

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Update content/learn/book/your-first-game/_index.md

9a2d9cd

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Update content/learn/book/your-first-game/_index.md

1df51a0

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Update content/learn/book/your-first-game/_index.md

68339c4

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

alice-i-cecile mentioned this pull request May 4, 2021

Improve code quality of Breakout game example bevyengine/bevy#2094

Closed

alice-i-cecile mentioned this pull request May 5, 2021

First-time user experience friction bevyengine/bevy#2109

Closed

mockersf mentioned this pull request May 9, 2021

skeptic setup #148

Closed

alice-i-cecile closed this May 25, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added a detailed tutorial for the breakout game to the Bevy book. #102

Added a detailed tutorial for the breakout game to the Bevy book. #102

rhulha commented Feb 28, 2021

rhulha commented Mar 11, 2021

cart commented Mar 11, 2021

MinerSebas Mar 11, 2021 •

edited

Loading

alice-i-cecile May 3, 2021

rhulha commented Mar 16, 2021

MinerSebas commented Mar 18, 2021

rhulha commented Apr 16, 2021

cart commented Apr 16, 2021

rhulha commented Apr 23, 2021

rhulha commented Apr 29, 2021

cart commented Apr 30, 2021

cart commented Apr 30, 2021

alice-i-cecile commented Apr 30, 2021

cart commented Apr 30, 2021

rhulha commented Apr 30, 2021

alice-i-cecile commented May 3, 2021

alice-i-cecile commented May 3, 2021

rhulha commented May 3, 2021

rhulha commented May 3, 2021

alice-i-cecile commented May 3, 2021 •

edited

Loading

rhulha commented May 3, 2021 •

edited

Loading

mockersf commented May 3, 2021 •

edited

Loading

alice-i-cecile commented May 3, 2021

rhulha commented May 3, 2021 •

edited

Loading

B-Reif commented May 5, 2021 •

edited

Loading

alice-i-cecile commented May 5, 2021

alice-i-cecile commented May 13, 2021

alice-i-cecile commented May 25, 2021

Added a detailed tutorial for the breakout game to the Bevy book. #102

Added a detailed tutorial for the breakout game to the Bevy book. #102

Conversation

rhulha commented Feb 28, 2021

rhulha commented Mar 11, 2021

cart commented Mar 11, 2021

MinerSebas Mar 11, 2021 • edited Loading

Choose a reason for hiding this comment

alice-i-cecile May 3, 2021

Choose a reason for hiding this comment

rhulha commented Mar 16, 2021

MinerSebas commented Mar 18, 2021

rhulha commented Apr 16, 2021

cart commented Apr 16, 2021

rhulha commented Apr 23, 2021

rhulha commented Apr 29, 2021

cart commented Apr 30, 2021

cart commented Apr 30, 2021

alice-i-cecile commented Apr 30, 2021

cart commented Apr 30, 2021

rhulha commented Apr 30, 2021

alice-i-cecile commented May 3, 2021

alice-i-cecile commented May 3, 2021

rhulha commented May 3, 2021

rhulha commented May 3, 2021

alice-i-cecile commented May 3, 2021 • edited Loading

rhulha commented May 3, 2021 • edited Loading

mockersf commented May 3, 2021 • edited Loading

alice-i-cecile commented May 3, 2021

rhulha commented May 3, 2021 • edited Loading

B-Reif commented May 5, 2021 • edited Loading

alice-i-cecile commented May 5, 2021

alice-i-cecile commented May 13, 2021

alice-i-cecile commented May 25, 2021

MinerSebas Mar 11, 2021 •

edited

Loading

alice-i-cecile commented May 3, 2021 •

edited

Loading

rhulha commented May 3, 2021 •

edited

Loading

mockersf commented May 3, 2021 •

edited

Loading

rhulha commented May 3, 2021 •

edited

Loading

B-Reif commented May 5, 2021 •

edited

Loading