[Merged by Bors] - Introduction for ECS chapter

[alice-i-cecile]

Extracted from #182.

Status

• Simplify example
• Avoid database analogy
• Edit and revise for clarity and quality
• Fix dead links
• Refactor Breakout example on Bevy repo
• Update text to sync closely with Breakout example

[MrGVSV]

I like the change to cut back on the code, I think it makes things more conceptual and less Rust/Bevy-specific.

Are you planning on adding images as well?

[doup]

After reading the intro I've sketched this chart (ignore spacing/style; its not meant to be pretty), I suppose it's not accurate as it misses stages and probably other stuff I don't even know about… buuuut, could be useful as an entry level birds-eye representation:

Somewhat related, this raises the question on how to create charts that are maintainable, consistent and pretty. Maybe using something like Figma is a good option here (as it allows to create components, has layout features [e.g. autolayout]…). Has anyone thought about this?

[doup]

I've done this on Figma, much better looking than before:

[MrGVSV]

I've done this on Figma, much better looking than before:

I actually really like the colors and design— it's simple and effective! If we decide to include an image, I think something like this would be great!

It's also nice that it emphasizes the fact that entities are just "numbers" (i.e. Entity 1 is conceptually a paddle).

Some small notes:

• The arrows are a bit difficult to see on dark mode. Maybe add an outline or choose a more middle gray color?
• This is more preference, but I think all components should share the same corner radii. Or if you want to keep the caps, maybe make their end corners a little less round?
• Would it make sense to show the components/resources listed under systems (similar to entities)? To visualize to what extent they interact with the world.

[alice-i-cecile]

@doup that's great! What's the best way to share and document a Figma file like that?

I definitely want an image, and I'm quite happy with what you've come up with.

[alice-i-cecile]

Would it make sense to show the components/resources listed under systems (similar to entities)? To visualize to what extent they interact with the world.

Definitely agree with this: the function signatures of systems are always super informative.

[doup]

Hi! I've added the system dependencies as suggested, it looks good, what do you think? Although I've skipped any mention to queries, mutability, etc. I'm not sure if it'll be too bloated otherwise… it already has lot's of information. I've also tweaked some colors so that it works both in light and dark backgrounds. I don't like a lot how much height it takes though…

Anyway, here is the SVG (you can download this):

And a PNG screenshot on dark-mode (just for reference, don't use this one):

It would be nice if it's somewhat synced with the breakout tutorial components/systems. But it can be changed later on.

I'll check tomorrow how to share the Figma file.

[doup]

Haha! I just noticed I forgot to change handle_collisions & destroy_bricks "signature". -_-

[james7132]

Two nits with the graphic:

• Lots of negative space in the Resources column, could we move that to the bottom or top as a row instead?
• apply_velocity should probably have a Time resource in it.

[MrGVSV]

Although I've skipped any mention to queries, mutability, etc. I'm not sure if it'll be too bloated otherwise…

I think that's a good choice. I’d even remove mention of Commands as well since they're not really a resource, entity, or component.

[doup]

Thanks for the suggestions! I've reduced the white-space so now it's more compact, fixed the apply_velocity signature and skipped the signature for the rest of the systems. I prefer to leave the signatures as they are until the breakout tutorial is ready.

---

Downloadable SVG:

---

Dark-mode PNG (⚠️ don't use this)

[alice-i-cecile]

I'm currently working on refactoring the Breakout example over on the main repo. Once that's done, I'll revise this text to match.

[doup]

I've updated the chart following the changes in: bevyengine/bevy#4261

---

Downloadable SVG

---

Dark-mode PNG (⚠️ don't use this)

[alice-i-cecile]

Wow, I really love the use of color-coding for resource vs component, and the way it makes it clear what the systems are using. I'm really keen to include this, and now I also want an automated tool to make these diagrams 😂

[alice-i-cecile]

bors r+

[bors]

Pull request successfully merged into new-book.

Build succeeded:

• build
• markdownlint
• test-code