Advanced Hands-on Rust: B3 Chapter 5 Errata List

@herbert

More notes as I continue through the book, this time for chapter 5.

Chapter 5

• Page 86, point 2 says to copy my_library INTO the code/FirstLibraryDocs/my_library/ directory. I think it means to
  copy my_library FROM code/FirstLibraryDocs/my_library.

• Page 86, the sentence before the code to add dependencies to cargo.toml contains the typo “add the my_libary and
  bevy to the [dependencies] section”. Typo is spelling of my_library and article mismatch (add the my_library and bevy
  packages, or add my_library and bevy).

• Page 86, I found this section to be confusing.

  • Are we supposed to be building Flappy Dragon in the same workspace as what we were using in part 1-2, or should we
    build a different one?
  • If the same, then why does the [workspace] section on page 86 only have flappy_dragon and my_library? Where are
    pig et al?
  • If the same, then why are we adding Bevy as a dependency to flappy_dragon instead of using the workspace’s Bevy?
  • If we’re supposed to make a new workspace, why is that? We already have the library set up in the existing
    workspace, and presumably readers have been following along. Why are we downloading a second copy of the library
    that we just built?
  • The source has flappy_dragon/Cargo.toml with [package] name = “flappy_dragon”, but the book shows [package]
    name = “flappy_dragon_base” after saying to open flappy_dragon/Cargo.toml.
  • I ultimately chose to continue using the same workspace as before. I didn’t download the copy of my_library,
    relying instead on the one we built in part 2, and I used the top-level workspace’s Bevy for flappy_dragon_base
    instead of adding an independent version to flappy_dragon/Cargo.toml. This worked, and I hope it doesn’t doom me
    later in the book.

• Page 89, paragraph in Modeling Game State starts with “Your building a framework…”, should be “You’re building a
  framework…”

• OPINION: On page 90, there is a box about historical nested states that existed in a previous Bevy version. I don’t
  think it’s useful to mention deprecated features, as Bevy is big enough without thinking about the changes it has
  gone through. Also, at this point in the book, we haven’t even implemented state management yet, so it’s hard to
  appreciate the differences in implementation of state management features anyway at this point.

• Page 92, we will need to use the Bevy prelude in mod.rs for the code introduced in 92 to run.

• Page 92, we add a bit of code to flappy_dragon_base/src/main.rs, but the text refers to the folder as "
  flappy_basics/src/main/rs".

• Page 92, GamePhase needs to #[derive(Copy)] in addition to its other traits, because the trait bound for impl
  Plugin for GameStatePlugin is, by the time we add the menus, T: States + Copy. We’re going to be using GamePhase as
  the concrete type for T. This is correctly shown on page 90 when contrasting what game states may look like for Flappy
  Dragon versus Pig, but when it’s actually added to the code on page 92, it doesn’t implement Copy and is not updated
  later. I failed to notice this initially and had a rough time figuring out the problem, because it triggered an unrelated esoteric error message from deep in the bowels of Bevy.

• There are several Bevy 0.12 to 0.15 changes needed for pages 92 - 95 to run. The most notable:

  • A query is not an iterator, so query.for_each() must become query.iter().for_each()
  • Implementing the generic plugin required T: States + FreelyMutableState + Default, not just T: States.
    Copy, at least, may not be a Bevy 0.15 change, this may be required for 0.12 too since the contents of the plugin
    would try to move the fields of GameStatePlugin if they do not implement Copy.
  • I think I mentioned the other kinds of changes previously.

• page 95, toward the bottom mentions the “flappy_basics” folder again, we’re working out of “flappy_dragon_base”

• page 96 after the code snippet says “Notice that MainMenu and setup_main_menu are not public and won’t be exported
  from your library for public use.” I don’t see either “MainMenu” or “setup_main_menu” here, though.

• Page 98, bullet point 3, I think it should start with “Now that the system…”

• Page 98, bullet point 4 contains the typo “panicing”, should be “panicking”.

• Page 98/99, the code snippet says
  else if current_state == menu_state.game_end_state { if keyboard.just_pressed(KeyCode::M) { state.set(menu_state.game_end_state.clone()) } ...
  but we can’t restart from here. This logic says “if game over and player presses M, go to game over.” It should be
  if keyboard.just_pressed(KeyCode::M) { state.set(menu_state.menu_state.clone()) }...

• Page 100, the book ends the section with “you have a working main and game over screen”, but the code was never
  updated to start on the main menu, and the IO was not implemented to be able to leave the game over screen, so there is no way to reach the main menu or leave the game over screen at this point in the project. The minor change in the above point fixes this, but if I try to make the main menu the default state instead of “Flapping” being the default,
  I get the runtime error upon startup
  my_library::bevy_framework::game_menus::setup<flappy_dragon_base::GamePhase> could not access system parameter Res<MenuAssets>.
  The same problem occurs with Pig’s menus later. It may be an issue with one of the more recent Bevy versions and how its
  ordering things under-the-hood.

• Note at this point: I found it a little odd that we’re spawning multiple cameras–one in flappy’s setup system and
  another in the menu setup–but it makes sense since it’s explained on page 98. Moreover, I believe the marker components and cleanup function ensure that cameras are removed when their associated phase is exited. However, it seems like Bevy isn’t doing what is expected. After playing through a round, Bevy starts screaming at us every frame,
  WARN bevy_render::camera::camera: Camera order ambiguities detected for <it rambles for a paragraph about how terrible a person you are for having conflicting cameras>
  Whenever we transition to a different state the previous camera should be cleaned up. I looked over the code for a
  good while trying to figure out why this doesn’t seem to be happening, and I wasn’t able to figure it out. It’s
  possible that it’s a Bevy error, or maybe the cameras are indeed being cleaned up correctly, but there’s some
  linger data that makes Bevy think there are multiple conflicting cameras? Either way, there isn’t a noticeable impact on the
  game, just a bunch of warnings.

• Page 100 toward the bottom has the typo “…a macro provides a convenient short-hand to the length code wrapped
  inside.” I believe it should be “shorthand” and “lengthy”.

• Page 102, bottom has the typo “…the command is part of the pattern to match.” I think this should be “comma”.

• Suggestion: On page 104, my understanding is that $start and $exit are stand-ins for individual startup and exit
  systems that we’re going to pass in to the macro. Maybe calling them $startup_sys and $exit_sys would be better to
  make it more explicit that these are placeholders for systems, not one-shot start or exit variables/functions.

• Page 109, we need to import add_phase, cleanup, and GameStatePlugin from my_library for Pig’s shiny new main function to run.

• Page 109, just as with Flappy Dragon, if the GamePhase enum defaults to MainMenu, the game immediately crashes at
  runtime when it tries to set up, throwing the error
  my_library::bevy_framework::game_menus::setup<pig::GamePhase> could not access system parameter Res<MenuAssets>.
  It appears to have something to do with the order in which resources and systems are added, but after poking around a
  good bit, I was unable to resolve the issue, and moved on by having the games not start on the MainMenu. If this error
  doesn’t exist on the author’s machine, it’s possible that it’s a funky bug introduced in a later Bevy version since I’m using
  0.15.