First round of feedback

[iolivia]

Thanks a lot everyone who offered to be an early beta tester!

Here are some questions to help structure your feedback:

1. Structure - did the structure make sense? Anything you would change, add, remove?
2. Form - was the text useful? was the formatting OK, etc? was the text clear and was it easy to understand?
3. Rust level - some of your are just getting started in Rust and some of you are more experienced, did the book make sense at your level, could you follow?
4. Something to add - if you could add one thing, what would it be?
5. Something to remove - if you could remove one thing, what would it be?
6. Learning - do you feel like you learned enough about making a simple 2D game in Rust? is there anything you would've hoped to learn with this that wasn't covered?
7. Graphics - would it help having nicer game graphics or would it distract from the content?

I'll edit this issue if I can think of more stuff, but it would be awesome once you've gone through the book if you could write a sentence or two on each of the topics above. You can reply here on the issue or if you are not comfortable with that please DM me on Twitter 😄

---

EDIT: feedback summary

👍positives

1. ECS + ggez is a good intro!
2. section on splitting into modules

🤔to work on/think about

1. delay on input queue Investigate input queue delay #22 (2)
2. deep dive into ECS and storage
3. derive macros Explain derive macros #23 (2)
4. title screens and transitions Title screens and transitions #25
5. lifetimes Explain lifetimes #24 (2)
6. use tree for printing directories
7. use prettier for the md files
8. more intuitive code sampler folder naming
9. procedurally generated maps
10. audio
11. better explanation of &mut stuff
12. &'static syntax explanation
13. where to put the input function

❓questions/more vague

1. jumping into ECS to start with?
2. more complex graphics
3. resolution independence
4. had to look up #[storage(VecStorage)]

[wbprice]

Some of my initial thoughts:

Overall

• Teaching ECS with ggez seems gentler than using a game engine that has it included from the get-go e.g. amethyst. My impression is that the game seems a great deal less complicated than a similar game written with Amethyst (or at least, any of my attempts so far). I'm sure there are performance / complexity tradeoffs to consider.
• The delay between a keypress and the player character making a movement seems very long. I'm curious about how other ggez games implement an input queue and how the performance compares.
• I'm glad that you cover splitting the codebase into modules. This was something that I struggled with a lot when starting to learn Rust. I didn't find the Rust Book's description of this very clear at the time.

Ch 1.2
It would be helpful to spend time on what storage is and how it relates to components and entities. A big aha for me when working with specs was understanding that storages contain components and the entity acts like a key to grab the position of "player 1", the velocity of "player 1", etc.

Ch 1.3
I think it would be good to spend some time on attributes and what they're doing as they relates to ECS (especially as someone coming from JavaScript, where annotations are relatively new). That way, when reading a code sample like this...

#[derive(Debug, Component, Clone, Copy)]
#[storage(VecStorage)]
pub struct Position {
    x: u8,
    y: u8,
    z: u8,
}

the reader is better equipped to understand it.

[GuilhermoReadonly]

On my side, on my journey to game dev with GGEZ I'm currently trying to implement different screen (a start screen, a game screen, a game-over screen et perhaps a settings screen).

It may be nice to explain how to do it (at the moment I have no clue, I'm learning ; if I find an elegant solution i could share). GGEZ don't have any built-in for this but we could probably implement it ourself and I think having different screen/stage could be a nice addition to your book too ! :)

[zubivan]

@GuilhermoReadonly when I was playing around with ggez and structuring my solution I approached different screens as State. The overall idea is that your game is represented as a state diagram, via current state (read screens) and transitions (player actions).
I have an example here you can take a look at: https://github.com/zubivan/games50-rust/tree/master/pong/src (this repo is still very much work in progress that I started, but never finished).

[GuilhermoReadonly]

I like your solution with traits for State and Transition !

That is definitively what I had in mind when I talked about elegant solution. :)

I think it could be a nice addition to the book (and to my own project too :P ) !

[zubivan]

Some of my initial impressions:

• Do you think it's essential to jump into ECS for the overall story? Seems like we can also get by introducing couple of traits to describe game objects and maybe, for simplicity, implement everything first using Rust built-ins. Transition to ECS could be a separate chapter of the book, also would show why it is valuable to move to that pattern once game setup becomes more complicated. Maybe it even would be an idea to build your own simple ECS framework before using one off-the-shelf.
• In Ch 1.4 we are using lifetimes, but also never talk about them. Since it's such an essential feature of rust, maybe it's worse spending a bit of time explaining it.

Overall, I really like where it can be going! Great work so far, wish I ever had patience to work on such detailed tutorials! Let me know what you think!

[iolivia]

thank you so much @wbprice @GuilhermoReadonly @zubivan for you feedback and for the awesome contributions so far, you folks are really helping me make this better! I've edited the initial comment on this issue to reflect all your points and created a bunch of issues for tracking.

I think these are all super valid points, the thing that I am trying to balance is keeping the book interesting and not too difficult for beginners, which is why I haven't covered some of the more advanced stuff. My strategy is to keep the reader engaged in the fun task, while dropping Rust knowledge along the way. As the reader gets more comfortable, I'll start explaining some of the more advanced concepts that were kind of hand waved before, otherwise I fear no one would stick with it. So to summarize, definitely planning to cover more advanced ECS, UI, lifetimes, macros, etc. but slowly 😄

@zubivan for your question on whether we should be jumping into ECS to start with, I am basing this on my personal experience of having tried the traits/somewhat traditional OOP approach for my first game and it was super difficult to do anything because of the borrow checker. also I think it's kind of nice to have a "best practice" approach as the starting point of a big series of "lessons", but maybe this would be a good idea to do for a blog post.

@GuilhermoReadonly good idea about the title screens and transitions, definitely a pain point for me as well. I have solved it in my game somewhat but it's really not very clean, need to have a look at @zubivan's solution.

@wbprice really glad to hear about the ggez choice, I haven't done much with amethyst but I did get the sense it was much more complicated, so I'm really glad this bet paid off.

[ChristianIsaacRoy]

I'm still working through the book. I haven't had much free time yet, but wanted to get something posted for now.

In 1.1 Project Setup, the &mut self explanation could be a bit clearer. Why is mut necessary? I don't have to do that in other languages? If I was a self taught programmer I might not recognize that mut is short for mutable or what that even means. Maybe explain that other languages default to having mutable variables, but rust defaults to having non mutable variables.

In 1.3 Components and entities - Assets section. We are told to add the Resources folder but not the images folder shown in the hierarchy, just a minor inconsistency.

#[derive(Debug, Component, Clone, Copy)]
#[storage(VecStorage)]
What are these? I'm unfamiliar with this syntax. We mentioned traits but a brief explanation would be nice.

2.1 Map Loading
What is going on with &'static syntax?

2.2 Moving the player - Input Events
You give us a function, and tell us to run it, but not where to put it, I had to look at the final implementation at the end of the section to know where.
Maybe going into logging somewhere would be useful as well, I'm unfamiliar with the {:?} syntax in the prinln! function.

That about as far as I am in right now. But these are mostly nit picky things. I didn't just want to say "yeah its great!" haha

[iolivia]

thanks @ChristianIsaacRoy, made a note of all the points in the original issue! this is good stuff, I think it's really easy as someone who knows that &mut means or whatever to skip past explaining this stuff, so this is great feedback!

[ghost]

My semester has finally reached its end so I could finally sit down and read through the book.

As a first impression; it's great - lightweight, fun and a swift introduction to Rust & game dev. However there are a couple things that nudged me the wrong way (but keep in mind that I had to be pretty nit-picky with these 😅).

Chapter 1.2

Based on the requirements we've established...

Perhaps being explicit about the requirements would make it easier on the reader.

Chapter 1.3 & Chapter 1.4

Among some other stuff we silently introduce macros and lifetimes in these chapters. Now as far as I can tell we're trying to avoid diving into the details of advanced topics such as macros and lifetimes. I wonder though if it would be nice with a sentence or so explaining that it is for example a macro, what it does and where it's defined. We do this for the match operator but not for the previous two.

General

Annotating code sections with their corresponding file path would be really nice.

[iolivia]

hey everyone! just wanted to give y'all a quick update, I am aiming to write up a final section in chapter 3 around testing since I think that is a pretty big unknown, and do some final text edits and tiny fixes, but after that we should be pretty much ready to ship this 🚀

[iolivia]

hey everyone! another quick update, managed to get through most of the updates I wanted to make before releasing (unfortunately not the testing chapter yet), and deployed the book at sokoban.iolivia.me, check it out at let me know if you have any trouble accessing it. Please don't share the link around yet, I'll start posting on twitter/etc later this week. Oh also I've changed the name of the repository so you might have to re-fork or sync your forks, sorry for the trouble!

[iolivia]

FYI I ported a lot of the tiny fixes to #40 hence closing this. I think most of the other feedback has been addressed in other issues, thanks again everyone! 🚀