New Welcome Section #187
New Welcome Section #187
Conversation
|
Should I update every reference to bevy import from 0.5 to 0.6 |
|
Have you seen #176? I think we may have duplicated work 😅 Good to have a second set of eyes; we can review both and compare / merge content. |
|
Oh, sorry, I just saw yours, let's compare work. |
|
|
||
| We highly recommend reading some form of Rust documentation. The best resource to choose is probably [The Rust Book](https://docs.rust-lang.org/book), as it provides projects and examples. | ||
|
|
||
| However, if you like to get your hands dirty quick, you can try [Rust by Example](https://docs.rust-lang.org/stable/rust-by-example) or [Rustlings](https://github.com/rust-lang/rustlings/). |
There was a problem hiding this comment.
I like these additional resources a lot; I think we should aim to add these to #176.
|
|
||
| ## Third-Party Crates | ||
|
|
||
| Bevy has a lot of third-party crates associated with it, such as [bevy_retrograde](https://github.com/katharostech/bevy_retrograde), [bevy_spicy_networking](https://github.com/CabbitStudios/bevy_spicy_networking) and [heron](https://github.com/jcornaz/heron). |
There was a problem hiding this comment.
We should be careful not to link to Katharos stuff without very clear license disclaimers. They seem like nice folks, but the license is a deal-breaker for almost every potential user.
|
|
||
| These are often published to [crates.io](https://crates.io) and use Bevy's plugin system, meaning technically, at this point, you can make your own thrid-party crates (although, they may not be entirely useful). | ||
|
|
||
| There is a whole GitHub repository dedicated to showing awesome bevy assets, aptly named [bevy-assets](https://github.com/bevyengine/bevy-assets). Be sure to check it out! |
There was a problem hiding this comment.
When talking about bevy-assets, we need to be clear that it includes plugins / crates as well as classical "assets" (sounds, models, sprites). As someone without a background in Unity etc. this was confusing to me at first.
|
|
||
| Bevy programs, which include games, tools and more, are conventially named 'Apps' and currently our Bevy program doesn't really follow the app structure or how bevy apps work. | ||
|
|
||
| Below is a basic outline of how your Bevy Apps should look. |
There was a problem hiding this comment.
This is an interesting idea to show the structural elements and code organization. Hmm....
| Bear in mind, the order of everything beyond modules is completely up to you. | ||
|
|
||
| In detail: | ||
| - First, you should import your modules. In order for a bevy program to work properly, it is **ESSENTIAL** that you import the bevy prelude, as this contains the App struct and other things required for bevy to work. |
There was a problem hiding this comment.
This is a bit confusing: you can also manually import each needed element, and will definitely trip up advanced programmers.
| In detail: | ||
| - First, you should import your modules. In order for a bevy program to work properly, it is **ESSENTIAL** that you import the bevy prelude, as this contains the App struct and other things required for bevy to work. | ||
|
|
||
| - Secondly, you should define your components and implementations. As displayed, a component can **optionally have values and implementations** which can be used when creating an entity |
There was a problem hiding this comment.
When writing docs like this, it's important to try and explain what terms mean when you get a good chance, rather than just repeating jargon.
In this case, "implementations" are something of a specialized term for Rust: mentioning that they're "methods" (if you're targeting other programmers) or "functions that belong to a specific type" (if you're targeting complete novices) goes a long way to unobtrusively clarify a concept.
|
|
||
| ## Making A Bevy App | ||
|
|
||
| That was a lot of information to take in, but don't worry. Let's start off simple with a basic Bevy App! |
There was a problem hiding this comment.
That information overload is a sign that the structure is inverted IMO :)
|
|
||
| A lot of this, you don't need to wory about right now. Just remember that: | ||
| - You add systems to your app in the main function and | ||
| - You define systems that can act on components |
There was a problem hiding this comment.
| - You define systems that can act on components | |
| - You define systems that can act on the component data of entities |
The interplay with entities is important here: you're not just operating on columns of data at once, and talking about how entities have components ties the mental model together a bit better.
| } | ||
| ``` | ||
|
|
||
| We just ran a **trait extension method** which allows us to convert our simple function to a powerful system. |
There was a problem hiding this comment.
Oh that's a wonderful term of art that we should throw into the ECS chapter.
|
|
||
| ## `MinimalPlugins` | ||
|
|
||
| One of the aformentioned plugin groups is the `MinimalPlugins` group. This plugin is for the most bare-bones of games or tools. It only includes bevy-core and bevy-app. If you are making a text-based game, this is the option for you. |
There was a problem hiding this comment.
Adding links to the documentation (on docs.rs usually) helps curious readers dig into the details of the topic without distracting from the main flow.
| .run() | ||
| ``` | ||
|
|
||
| **NOTE: The Bevy Prelude must be included in `main.rs`** |
There was a problem hiding this comment.
We should ensure that examples are compileable / runnable when possible: this helps beginners and allows us to automatically check for staleness.
The bit of repeated boilerplate is worth it.
|
|
||
| Bevy has been designed to use a flexible data system in order to provide a smart, usable workflow. The engine uses an **Entity Component System** (ECS) to acheive this goal. In traditional game engines, a singular object (entity) contains its logic and components in one system. This is known as an object-oriented entity system. | ||
|
|
||
| This has its benifits, however, in general, it is being phased out by ECSs. Instead of containing all the systems and components in a singular entity, in ECS, all of this is abstracted into structs (in Rust) and functions. Entities are defined as unique integers. |
There was a problem hiding this comment.
it is being phased out by ECSs
I personally think this is likely to be true, but is probably a bit inflammatory :p
Entities are defined as unique integers
This is mostly an implementation detail: you could use strings or chars or PNG files as entities just fine if you really wanted. The critical bit is that they're unique identifiers that you can use to organize and quickly look up the data attached to a particular "unit", whether that's a tangible game object or something more abstract.
|
|
||
| Components are structs that contain values for said components. Systems are Rust functions that are parsed into the main function and can specify components that an entity must have to be affected by the system. | ||
|
|
||
| **This can allow for a great amount of abstraction that help with S.O.L.I.D principles.** |
There was a problem hiding this comment.
This sentence doesn't add a ton of concrete value, and many readers won't know what S.O.L.I.D. is.
The overall idea of summarizing the section is good though.
|
|
||
| **LR:** | ||
|
|
||
| The Bevy Game Engine uses a **scene system** that allows for **hot reloading**. In very short, not technological terms, you have the ability to instantly change certain files (meshes, textures, scenes) and view the changes without recompiling. |
There was a problem hiding this comment.
Non-technical readers won't know what recompiling is ;)
| There is much more Bevy is unique for, including, | ||
| - Fast Compile Times | ||
| - Modular, parallel render graph | ||
| - Flex Box Inspired UI system |
There was a problem hiding this comment.
I'm not sure this feature is ready enough to be advertised (nor is flex-box UI very unique, even among game engines).
|
|
||
| Bevy is a relatively new engine, going public as early as August 2020, meaning that there is a **VERY** high chance vital parts of the engine can change almost every month (if not every week), especially if you are using the master branch of the source. This is why we recommend holding onto a specific hash when working on a project (we'll get into that later). | ||
|
|
||
| Using the engine for major projects as of right now is **HIGHLY DISCOURAGED** (at least until version 1.0 comes out). Trust us when we say the engine changes every update. |
There was a problem hiding this comment.
I expect we'll hit practical, useful stability well before 1.0 :)
|
|
||
| **LR:** | ||
|
|
||
| This links back to the first point. The engine is so early in development that there is no editor and no mobile support, along with other things. So if that is a necessity in your project, we are currently a no-go. |
There was a problem hiding this comment.
We have some mobile support! Audio, UI and animations are the biggest practical blockers right now IMO.
|
Thanks for doing this <3 The duplication was unfortunate, but this was good to read through and I very much appreciate the way you took the initiative to tackle this. Hopefully the feedback I left is helpful; writing docs is something of an art! Things I definitely think we should incorporate:
Are you okay to work off my branch @asleeponmykeyboard? It's a fair bit further along. Also come say hi on the Discord server if you're able (I'm Alice on there) and we can coordinate a bit more casually. |
Thanks to @alice-i-cecile for the help! Co-authored-by: Alice Cecile <[email protected]>
|
@alice-i-cecile of course, i'll leave this open for now, but tell me if i need to close it |
|
Closing because it's duplicate work. Check out #176 if you wanna contribute to welcome chapter. |
Filled in all the pages in the welcome section to the best of my ability
If I spelt anything incorrectly or was too wordy with my explanations, let me know