Begin ECS Tutorial #27
Conversation
Move chapters down to make room for `ecs tutorial` Add mechanism for putting listing no. on code Add mechanism for putting filename above code Add link anchors to headings so they can be referenced Add bevy tutorial SVG Rough out the introduction to the tutorial Fix wrong name for `add_system()` reference - there's no `add_system` on the IntoQuerySystem trait
|
Draft: Not looking for this to be merged until the chapter is complete. I am focused on content generation at the moment. No attempt has yet been made to ensure that the grammar is correct. |
|
This is what it looks like from top to bottom.
|
Add shortcodes for - captions of code - filenames above code Add anchor to captions Add scoll to bottom when navigating to caption anchors
There was a problem hiding this comment.
This is some great work! I really appreciate the time you put into this.
I want to preface this review with a disclaimer that I take docs very seriously and I will be pretty picky when it comes to presentation and content. Please don't interpret these comments as being hostile or a "negative review". I will be employing an opinionated "heavy handed" approach for all Bevy Book PRs.
| This tutorial aims to give both an awareness and practical examples of the following: | ||
| * There is a startup scheduler and a normal scheduler ({{rust_type(type="struct", crate="bevy_ecs", name="Schedule", no_mod=true, plural=false)}}) | ||
| * Startup systems run only ONCE before normal systems | ||
| * You can ask normal systems to run once or in an infinite loop | ||
| * You can slow the infinite loop by specifying an additional `k` second sleep delay between each loop | ||
| - where `k ∈ [0, 9223372036854775807_i64]` seconds (i.e. ~292 billion years) | ||
| * A **System** results from calling the inline {{rust_type(type="trait" crate="bevy_ecs", name="IntoForEachSystem" method="system" no_struct=false)}} method on a `fn`. It is a {{rust_type(type="struct", crate="bevy_ecs", name="SystemFn", no_mod=true, plural=false)}} struct that implements the {{rust_type(type="trait", crate="bevy_ecs", name="System", no_mod=true, plural=false)}} trait and encapsulates the original function | ||
| * A **System** is always assigned a **stage** in the scheduler | ||
| - This dictates the group of systems that it runs in parallel with | ||
| - The default normal stage is `stage::UPDATE` | ||
| - The default startup stage is `startup_stage::STARTUP` | ||
| * Except when certain data constraints exist (i.e. thread local with exclusive access to {{rust_type(type="struct", crate="bevy_ecs", name="World", no_mod=true, plural=false)}} and {{rust_type(type="struct", crate="bevy_ecs", name="Resources", no_mod=true, plural=false)}}) | ||
| - Startup systems run in no particular order within their **stage** due to parallel execution | ||
| - Normal systems run in no particular order within their **stage** due to parallel execution | ||
| * Stages exist as an ordered collection | ||
| * For finer control of the order of execution within a scheduler | ||
| - You can create as many NEW stages in the scheduler as you like | ||
| - New stages are added immediately *before* or *after* an existing stage (system defined or custom) | ||
| * You can emit and consume custom events | ||
| * You can add new **Components** and **Systems** to a running {{rust_type(type="struct", crate="bevy_app", name="App", no_mod=true, plural=false)}}, i.e. after `.run()` | ||
| - with `commands:` {{rust_type(type="struct", crate="bevy_ecs", name="Commands", no_mod=true, plural=false)}} | ||
| * {{rust_type(type="struct", crate="bevy_app", name="App", no_mod=true, plural=true)}} also have a mechanism for exiting gracefully |
There was a problem hiding this comment.
Can we make this a much more concise, higher level introduction? In its current form I think it dives into the details way too early. Just listing a giant list of facts is a good way to lose people's attention. I think its better to do that piece by piece as users work through the tutorial.
I think this section should probably just be a single paragraph describing the high level goals of the tutorial and the app we will be building.
There was a problem hiding this comment.
Yes, I made the intro deliberately dense because I'm using it as a roadmap to make sure I touch on all of those points. I'll definitely make it more incoming-user friendly when I've included these points throughout the tutorial. Maybe I'll do a chapter review section at the end that looks more like this.
I actually created a little MUD battle simulation (Player vs rats) to use as the basis for this tutorial, but it very quickly got out of hand. The things that make it interesting are also the things that make it too long.
| @@ -4,6 +4,7 @@ weight = 2 | |||
| sort_by = "weight" | |||
| template = "book-section.html" | |||
| page_template = "book-section.html" | |||
| insert_anchor_links = "left" | |||
There was a problem hiding this comment.
left anchors make the heading alignment feel off.
I'd prefer something closer to this:
.bevy-link {
font-size: 1.3rem;
vertical-align: top;
margin-left: 0.2rem;
}<a class="bevy-link" href="#{{ id }}" aria-label="Anchor link for: {{ id }}">🔗</a>insert_anchor_links = "right"
There was a problem hiding this comment.
The link character 🔗 also gets handled weirdly. We can't override things like color (which I would prefer to be $default-color). I think we might want to make it an svg so we can control the format.
There was a problem hiding this comment.
I started off on the right :) I didn't like the way it looked, so I pushed it to the left for a little more prominence. Putting it back on the right is fine.
I like this style of link icon, but there's no implementation in Unicode, so if you want SVG it's the perfect opportunity for me. Which shape would you prefer? I could do both and see how it pans out at font size.
There was a problem hiding this comment.
I wish headings could just automatically be links, instead of requiring a link icon. If we can make that work, that would be my preference (but from what i can tell, zola doesnt give us that option).
The link icons above are definitely a common design, but they're a bit noisy for my taste. I like the simplicity of the "infinity" style logo. Or maybe even just a # character ... thats minimal and matches the anchor link style. The # wouldn't even require an SVG.
In general I want to reduce "noise" as much as possible and use a minimal "text first" / "content first" approach.
There was a problem hiding this comment.
I replaced the Unicode with a custom link SVG. This means it can now take the $default_color and change to gray on hover. The downside is that the svg is not dynamically scalable within Zola. However, I used three sizes that correspond to h2 a svg {}, h3 a svg {}, and h4 a svg {} repectively. I hide the sizes that shouldn't display in each case (templates/anchor-link.html) Short story, the symbol varies in size with respect to each heading type.
|
I also put a CSS |
Remove tutorial logo Replace anchor link unicode with SVG - add SVG directly in html - move anchor to the right - color with $default-color - scale with headings - remove underline text-decoration from h3 headings + interferred visually with anchor Change capitalization of title Move `cargo search bevy` to `getting_started` Add preamble before code block Fix awkward formatting of `App::resources<Resources>` Add margin hack to `fileref` shortcode
|
Check out #154, which renders this PR obsolete by greatly expanding and revamping the content of the book. |
|
I'd also like to apologize to @sunwukonga for some truly terrible levels of communication / responsiveness. You did a lot of great work here and I didn't keep you in the loop on where my thoughts were. My excuse is that this pr was created during the extremely hectic initial bevy release. I was completely overwhelmed by the influx of people / questions / prs / social media and I couldn't give Bevy Book work the priority it needed. I was also very protective of Bevy Book content at the time and wasn't quite ready to let other people change the tone and structure of the book. I should have communicated that to you and I'm really sorry for disrespecting your good intentions and quality work. |
Move chapters down to make room for
ecs tutorialAdd mechanism for putting listing no. on code
Add mechanism for putting filename above code
Add link anchors to headings so they can be referenced
Add bevy tutorial SVG
Rough out the introduction to the tutorial
Fix wrong name for
add_system()referenceadd_systemon the IntoQuerySystem trait