Advanced Hands on Rust: B3 Parts I & II errata list

@herbert

Loving the book so far! I have the habit of marking any errata or concerns I have with a book as I read, and since this one is in beta, it may actually be helpful this time. The notes on chapter 1 are mainly Bevy 0.12 vs 0.15 comments, which may not be relevant. Chapter 2+ are mostly errata or typos. I’m also following along with Bevy 0.15, I’ll release the 0.15 repo after the book is launched if anyone is interested.

Part 1

Chapter 1

• Does not mention adding [workspace.dependencies] with Bevy prior to trying to add Bevy as a member dependency and compile.
• A specific version of Bevy doesn’t seem to be mentioned until page 30, but in passing Bevy 0.12 is shown in a box on page 10. Given that Bevy has a rapid release cycle and is known for releasing breaking changes regularly, and we’re already on
  0.15 before the book is released, it seems like it would be prudent to either explicitly tell readers to use Bevy 0.12
  so that they don’t run into confusing incompatibility, or consider upgrading the book’s code to 0.15. (As you’re likely
  already aware, 0.15 released one of the largest changes yet in that it switched from “bundles” to “required components”
  as the way to use groups of components together)
• Bullet point 4 on page 12 mentions bundles like SpriteBundle and Camera2dBundle, but these are deprecated as of
  Bevy 0.15 in favor of “required components.”
• Minor nitpick: Bullet point 8 on page 12 mentioned using .insert to attach your own components, but Bevy treats any tuple of components as a bundle, so when spawning an entity you can pass all components you want as a tuple and do not need to use .insert() at all.
• The movement system on pages 13-14 use Res<Input> and KeyCode::Left, but the latest Bevy uses
  Res<ButtonInput> and KeyCode::ArrowLeft (etc) to accomplish this. I believe they’re the exact same,
  but at some time between Bevy 0.12 and Bevy 0.15, Res<Input<>> was removed and the KeyCode variants got name changes.
• Typo on page 14 bullet point 4: “… passing the values of references components into the included function.”

Part 2

Chapter 2

• Page 20, paragraph one contains the type “…responding to Operating Sytem…”
• Page 21, paragraph one contains the typo “…Rust has created your library and has a detected…”
• Page 28, bullet point 2 uses the word “guaranty” as a verb. I believe guarantee/guaranty is a US/UK English variation
  for the noun sense (a legal guaranty) only, not the verb. I believe the verb should be “guarantee.”
• page 28, after the bullet points contains “(it’s an exclusive range)—”, should probably choose either parentheses or
  dash.
• Page 29, bullet point 3, “guaranty” again.
• Page 30, is it intentional that Pig depends on its own version of Bevy, “bevy = 0.12”, while hello_bevy relies on the
  workspace bevy, “bevy = {workspace = true}”?
• Page 32, add_state is now called init_state as of Bevy 0.13.
• Page 34 & 36, as of Bevy 0.13, TextureAtlas and TextureAtlasLayout are two separate structs, and TextureAtlasSprite has been removed. Required components are now preferred over bundles in Bevy 0.15.
• Page 39, bullet point 5, for whatever reason, when Bevy reworked colors, they eliminated all color constants except for WHITE and BLACK.
  As such, there is no Color::BLUE, and it needs to be explicitly defined.
• Page 39, bullet point 6, typo “…their total score nad…”

Chapter 3

• Page 50, bullet point 2 contains the typo “Random number generation algoritms…”

• Page 54 contains the typo “There are two interesting figures in thes benchmark results:”

• Page 56 contains the typo “There’s’ a very long…”

• Page 56 contains the grammatical error “Changing random core will…” (unless intended to be read with a heavy
  Slavic accent)

• Page 57, rand is shown here as being a workspace dependency, but on page 23 we were instructed to add rand as a dependency directly to my_library/cargo.toml, not to the workspace.

• Page 57-58, On page 57, we search crates.io and find the "pcg_rand = “0.13.0” crate, but on page 58 we use “rand_pcg”.
  This is very confusing, as there are two different packages on crates.io called pcg_rand and rand_pcg.
  They have different versioning and appear to have been developed independently. Without referencing the book’s Git
  repo, it is not possible to see at this point which crate the book’s project intended to be used.

• Page 58, the book says to add rand_pcg and rand_xorshift as workspace dependencies in the my_library manifest, but it
  does not add them to the workspace, so this won’t compile. (The reader should be able to figure this out without being
  spoon-fed, but it becomes more confusing due to the rand_pcg vs pcg_rand confusion. There is no version mentioned on page 58, so should I add pcg_rand = 0.13.0 or rand_pcg = 0.3.0 to my workspace? I assumed that since rand_pcg has the same version number and same owner as rand_xorshift, this is the correct crate.)

• Page 58, one of the [features] is default = [ “pcg” ], but there is also pcg = [ “rand_pcg” ]. I understand that
  the latter means the pcg feature flag is mapped to the rand_pcg crate, but I don’t see any “pcg” crate that default is
  mapped to. Reading an excerpt from the Cargo Book made it clear that default maps to which feature flags should be
  included by default, but since that behavior is different from all other flags under [features] (the default pattern
  is “default” => list_of_flags, everything else is flag => list_of_crates), it may be worth explaining here.

• Pages 61, we read “PCG is slightly faster, so let’s make it the default”, but there is no accompanying code to set
  PCG to be the default here. I think it was set as default on page 58, but I didn’t notice this until I got confused
  several pages later and re-read it. The timing makes it a little confusing, “let’s set it to default” feels like we
  are here on page 61-62 going to do so, but it’s already been done silently on page 58.

• Page 62, When we test the feature flags, I believe that there is a conflict between what the book’s text says we are
  doing and what the cargo commands actually do. When I read the snippet on features from the Cargo Book, it says that
  –no-default-features DISABLES the default set. On page 58, we set “pcg” to be the default set. If I’m thinking about
  this correctly:

  • The book first says “Let’s start by testing your new default feature set”, but the cargo command uses --no-default-features. This will disable the default “pcg” and we didn’t request xorshift, so this is still testing StdRng from rand.
  • The book then says we will test xorshift, and the cargo command matches that.
  • The book then says we’ll finally “test that StdRng still works”, but the cargo command specifies “–no-default-features --features pcg”. These flags are contradictory (disable pcg, enable pcg). If Cargo resolves them in order, it’ll test pcg.
  • I think the intended behavior for 1-3 would be “cargo test”, “cargo test --no-default-features --features xorshift”, and “cargo test --no-default-features”

• Small note: running Pig at the end of this section initially didn’t work for me, because when I read how to use features
  at the bottom of page 58, I immediately put features=[“xorshift”] in the Pig manifest.
  By the end of the section this wouldn’t compile, because I also needed to include default-features=false. This is
  likely covered elsewhere, but for people who tried to use the features immediately, they’ll hit an error here.

• Page 63 contains invalid sentence “In your pig program, manually creating a RandomNumberGenerator, and storing it
  as a resource.”

• Page 63, is Bevy intended to be a dependency in my_library now instead of making it a workspace dependency?

• Page 63, “Declare that Random implements…” should be “Declare that RandomPlugin implements…”, I think.

• Page 64, Resource is derived twice for RandomNumberGenerator, once using bevy::prelude::Resource and once just
  using Resource (which won’t compile since random.rs doesn’t import the Bevy prelude).

• Page 64, point 1 in the code shows explicitly importing RandomNumberGenerator and RandomPlugin from my_library, but
  point 1 in the explanatory text says to use the wildcard to import all public entries.

• Page 65, the line that we’re removing is commands.insert_resource(Random(RandomNumberGenerator::new())). Note the Random() wrapper. We originally created a tuple struct in the Pig file called “Random” which derived resource and wrapped RandomNumberGenerator. Due to this, our systems also still contain ResMut<Random> and the game will crash on startup when it fails to find that resource.
  So we need to remove the suggested line, refactor the systems to use ResMut<RandomNumberGenerator>, and then refactor the two uses of rng.0.range(1…=6) to rng.range(1…=6) (then delete the Random wrapper I suppose since it is unused).

• Page 68, typo after the code: “Once lock is obtained, it has represents exclusive access…”

• Page 70, the paragraph after the code says “The as random part renames the random_locking module to random.” I don’t see “as random” anywhere, was this edited out?

Chapter 4

• Page 76, a path is mentioned as “my_library/src/lib/.rs” with an extra slash at the end there before .rs.