Added missing changelog link. Made new section for next release and r…

…enamed current to 0.8.0

Update contributing to new guidelines. Updated readme to be more welcoming

Adds subtitles to readme

Updated features. Updated contributing section of the readme file

Added linebreaks to the readme file

Fixed language being a _bit_ too strong

Removed part comparing it to other engines

Writing concepts for the book

Fixed bullet points in state.md. Fixed typo

Readme changes

readme changes

Wrote a couple more concept pages. Updated readme again

Added the systems concept documentation

Fixed intro errors. Added warning in state for overriding the update method not updating world. Completed the world chapter.

Added event-channel page. Added warning in resource about fetching component as a resource using defaults

english hellooooooooo

Added forgotten stuff in system concept doc

Added section in component

Concept doc for systems (amethyst#6)

* Added the systems concept documentation

* english hellooooooooo

Massive book update! Added tutorial, fixed outdated stuff, added new guidelines.

Added dispatcher theory concept doc

join join join

no more prelude

Fixed unclear passages. Testing subtitle links

quick fixes

Added System::setup

Fixing text all around

Removed _ in book filenames

Added notice for derive default

Fixed unclear passages in event channel

Added requirement to update tutorial and examples when doing a feature PR

Fixed broken links

Moved images. Fixed old links

Fixed some things in system page

s/optionnal/optional/

Addressed reviews

Massive book update!

README.md

@@ -17,20 +17,44 @@
 [gc]: https://gitter.im/orgs/amethyst/rooms
 [di]: https://discord.gg/GnP5Whs
 
-**Warning: The engine is still in alpha, and thus it changes very fast. You may find out that some parts of the documentation can be outdated. If you find such an occurrence, feel free to open an issue and it will be fixed in no time.**
+## What is Amethyst?!
 
-## Goals
+Amethyst is a game engine aiming to be fast and as configurable as possible.
 
-* Massively parallel architecture
-* Powered by a correct [Entity Component System][ecs] model
-* Rapid prototyping with [RON] files for prefabs and an abstract scripting API
+## Principles
+
+These principles are what make amethyst unique and competitive in the world of game engines.
+
+* Massively parallel architecture.
+* Powered by a correct [Entity Component System][ecs] model.
+* Rapid prototyping with [RON] (Json-like) files for prefabs and an abstract scripting API.
+* Strong focus on encouraging reusability and clean interfaces.
 
 [ecs]: https://en.wikipedia.org/wiki/Entity–component–system
 [RON]: https://github.com/ron-rs/ron
 
+## Why Amethyst?
+
+### Extreme Multithreading
+
+Amethyst is based over a very powerful parallel [ecs] called specs.
+This allows games built with Amethyst to maximize the processing power usage to make it run as smooth and as fast as possible, without the headache of multithread programming.
+
+### Clean
+
+By design, the amethyst engine encourages you to write clean and reusable code for your behaviours and data structures, allowing engine users to easily
+share useful components, thus reducing development time and cost.
+
+Using the [ecs] architecture, the code of games can be cleanly divided between data and behaviour, making it easy to understand what is going on,
+even if the game is running on a massive 64 cores processor.
+
+### Community
+
+While we may not be feature-packed (yet!), we all strongly believe that the community-oriented side of amethyst will thrive as we move forward!
+
 ## Features
 
-Please visit the [features page][feat] for a list of features Amethyst provides and will provide.
+Please visit the [features page][feat] for a list of features Amethyst provides.
 
 [feat]: docs/FEATURES.md
 
@@ -46,7 +70,9 @@ Please visit the [features page][feat] for a list of features Amethyst provides
 
 ## Usage
 
-Please read the [online book][bk] for a comprehensive tutorial to using Amethyst.
+While the engine can be hard to use at times, we made a lot of [documentation][bk] that will teach you everything you need to use amethyst comfortably!
+
+If you don't understand a part of the documentation, please let us know. Join us on discord or gitter, or open an issue, we are always happy to help!
 
 [bk]: https://www.amethyst.rs/book/master/
 
@@ -58,6 +84,14 @@ $ cargo run --example name_of_example
 ```
 All available examples are listed under [examples][ex].
 
+Our most advanced example is currently called pong. It is a pong game, as you may have guessed it.
+```
+$ cargo run --example pong
+```
+
+There are quite a few prototype games that were made with Amethyst. A list will be available soon.
+While we create this list, feel free to join our discord and ask about which projects are currently being made with Amethyst.
+
 For a full-blown "Hello World" tutorial check out the [Getting Started][gs] chapter
 in the book.
 
@@ -104,7 +138,7 @@ We do not support anything other than the most recent Rust stable release. Use n
 
 Please check out the [FAQ][faq] before asking.
 
-If you have a question, just ask on [Gitter][gt] or [Discord][di] and we'll help you and add it to the FAQ.
+If you have a question, just ask on [Discord][di] (most active) or [Gitter][gt] and we'll help you.
 
 Other places you may want to check out are [r/rust_gamedev][rg] and [#rust-gamedev IRC][irc].
 
@@ -114,24 +148,38 @@ Other places you may want to check out are [r/rust_gamedev][rg] and [#rust-gamed
 [rg]: https://www.reddit.com/r/rust_gamedev/
 [irc]: https://botbot.me/mozilla/rust-gamedev/
 
-## License
+## Contributing
 
-Amethyst is free and open source software distributed under the terms of both
-the [MIT License][lm] and the [Apache License 2.0][la].
+We are a community project that welcomes contributions from anyone. 
 
-[lm]: docs/LICENSE-MIT
-[la]: docs/LICENSE-APACHE
+If you're interested in helping out, please read the [contribution guidelines][cm] 
+file before getting started. 
 
-## Contributing
+We have a [good first issue][gfi] category that groups all issues or feature request
+that can be made without having an extensive knowledge of rust or amethyst.
+Working on those issues is a good, if not the best way to learn.
 
-We are a community project that welcomes contribution from anyone. If you're
-interested in helping out, please read the [CONTRIBUTING.md][cm] file before
-getting started. Don't know what to hack on? Check our [active projects][pr], or search though [our issue tracker][it].
+If you think you are not ready to code yet, you can still contribute by reviewing code written by other members of the community.
+In fact, code reviews ensures that the code that gets added to amethyst is of the highest quality as possible.
+Pull requests available for reviews are [here][pr].
+
+If for some reason we don't have any open PR or good first issues (that would be a good thing),
+you can look through the [issue tracker][it].
 
 [cm]: docs/CONTRIBUTING.md
 [pr]: https://github.com/amethyst/amethyst/projects
 [it]: https://github.com/amethyst/amethyst/issues
 
+[gfi]: https://github.com/amethyst/amethyst/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+
+## License
+
+Amethyst is free and open source software distributed under the terms of both
+the [MIT License][lm] and the [Apache License 2.0][la].
+
+[lm]: docs/LICENSE-MIT
+[la]: docs/LICENSE-APACHE
+
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.

book/book.toml

@@ -1,3 +1,4 @@
 [book]
 title = "Amethyst Documentation"
-author = "Eyal Kalderon"
+author = "Eyal Kalderon, Jojolepro (Joël Lupien), Moxinilian (Théo Degioanni)"
+

book/src/SUMMARY.md

@@ -1,17 +1,26 @@
 # Summary
 
 * [Introduction](./intro.md)
-* [Getting Started](./getting_started.md)
-* [Pong Tutorial](pong_tutorial.md)
-    * [Opening (and closing!) a window](./pong_tutorial/pong_tutorial_01.md)
-    * [Drawing the paddles](./pong_tutorial/pong_tutorial_02.md)
-    * [Moving the paddles](./pong_tutorial/pong_tutorial_03.md)
+* [Getting Started](./getting-started.md)
+* [Concepts](./concepts/intro.md)
+    * [State](./concepts/state.md)
+    * [Component](./concepts/component.md)
+    * [Entity](./concepts/entity.md)
+    * [Resource](./concepts/resource.md)
+    * [World](./concepts/world.md)
+    * [System](./concepts/system.md)
+    * [Dispatcher](./concepts/dispatcher.md)
+    * [Event Channel](./concepts/event-channel.md)
+* [Pong Tutorial](pong-tutorial.md)
+    * [Opening (and closing!) a window](./pong-tutorial/pong-tutorial-01.md)
+    * [Drawing the paddles](./pong-tutorial/pong-tutorial-02.md)
+    * [Moving the paddles](./pong-tutorial/pong-tutorial-03.md)
 * [Animation](./animation.md)
     * [Interpolation](./animation/interpolation.md)
     * [Channel](./animation/channel.md)
     * [Sampler](./animation/sampler.md)
     * [Definition](./animation/definition.md)
-* [Custom `GameData`](./game_data.md)
+* [Custom `GameData`](./game-data.md)
 * [Glossary](./glossary.md)
 * [Appendix A: Config Files](./appendices/a_config_files.md)
     * [Adding an Arena Config](./appendices/a_config_files/arena_config.md)

book/src/appendices/a_config_files.md

@@ -46,9 +46,9 @@ For this project, we'll be placing a `config.ron` file in the same location as t
 * [Adding Paddle Configs][2]
 
 [pong]: https://github.com/amethyst/amethyst/tree/develop/examples/pong
-[ron]: https://docs.rs/ron/0.1.7/ron/
-[config]: https://docs.rs/amethyst_config/0.5.0/amethyst_config/trait.Config.html
-[0]: ./appendices/a_config_files/arena_config.html
-[1]: ./appendices/a_config_files/ball_config.html
-[2]: ./appendices/a_config_files/paddle_configs.html
+[ron]: https://docs.rs/ron/0.3.0/ron/
+[config]: https://docs.rs/amethyst_config/0.6.0/amethyst_config/trait.Config.html
+[0]: ./a_config_files/arena_config.html
+[1]: ./a_config_files/ball_config.html
+[2]: ./a_config_files/paddle_configs.html
 

book/src/appendices/a_config_files/arena_config.md

@@ -111,11 +111,9 @@ arena: (
 )
 ```
 
-[Click here to continue to the next chapter][1]
 
-[config]: https://docs.rs/amethyst_config/0.5.0/amethyst_config/trait.Config.html
-[ecsbundle]: https://docs.rs/amethyst_core/0.1.0/amethyst_core/bundle/trait.ECSBundle.html
-[ecsbuild]: https://docs.rs/amethyst_core/0.1.0/amethyst_core/bundle/trait.ECSBundle.html#tymethod.build
-[1]: ./appendices/a_config_files/ball_config.html
+[config]: https://docs.rs/amethyst_config/0.6.0/amethyst_config/trait.Config.html
+[ecsbundle]: https://docs.rs/amethyst_core/0.2.0/amethyst_core/bundle/trait.ECSBundle.html
+[ecsbuild]: https://docs.rs/amethyst_core/0.2.0/amethyst_core/bundle/trait.ECSBundle.html#tymethod.build
 [serde_default]: https://serde.rs/attr-default.html
 [default]: https://doc.rust-lang.org/std/default/trait.Default.html

book/src/appendices/a_config_files/ball_config.md

@@ -140,7 +140,4 @@ very easy with RON; we just add an additional level of nesting.
 This configuration sets the ball to be orange, while retaining the same size and velocity as the original 
 example.
 
-[Click here to continue to the last chapter, configuring paddles][2]
-
-[2]: ./appendices/a_config_files/paddle_configs.html
 [vec2]: https://docs.rs/cgmath/0.16.0/cgmath/struct.Vector2.html

book/src/appendices/a_config_files/paddle_configs.md

@@ -162,7 +162,7 @@ keep the left paddle blue so the final `config.ron` file will be as follows:
 ```
 
 
-[add_resource]: https://docs.rs/specs/0.10.0/specs/struct.World.html#method.add_resource
-[add_with_id]: https://docs.rs/specs/0.10.0/specs/struct.World.html#method.add_resource_with_id
+[add_resource]: https://docs.rs/specs/0.12.0/specs/struct.World.html#method.add_resource
+[add_with_id]: https://docs.rs/specs/0.12.0/specs/struct.World.html#method.add_resource_with_id
 
 

book/src/concepts/component.md

@@ -0,0 +1,59 @@
+# Component
+
+## What is a `Component`?
+
+A component is any struct that can be "attached" to an `Entity` (we will cover entity in the next chapter).
+
+## Usage
+
+The relationship between an entity and a component closely ressembles the relation between a real-life object and its properties.
+
+For example, a bottle of water has a shape, a volume, a color and is made of a material(usually plastic).
+
+In this example, the bottle is the entity, and the properties are components.
+
+## Creating a component
+
+Creating a component is easy.
+
+You declare a struct:
+
+```rust
+pub struct MyComponent{
+    some_property: String,
+}
+```
+
+and then you implement the `Component` trait for it.
+
+```rust,ignore
+use amethyst::ecs::{Component, VecStorage};
+impl Component for MyComponent {
+    type Storage = VecStorage<Self>;
+}
+```
+
+## Storages?
+
+`Component`s, in contrast with popular belief, should not be stored directly inside of a `Entity`.
+
+They are instead stored in different types of `Storage`, which all have different performance strategies.
+
+When implementing `Component` for a type, you have to specify which storage strategy it should use.
+
+Here's a comparison of the most used ones:
+* `DenseVecStorage`: Elements are stored in a contiguous array. No empty space is left between `Component`s, allowing a lowered memory usage.
+  This is less performant than `VecStorage`.
+* `VecStorage`: Elements are stored into a contiguous array. Uses more memory than `DenseVecStorage` but is more performant when you use a `Component` type a lot.
+  Only use this when you know that a LOT of your entities are going to have that `Component` type. (More than 90%, for example).
+* `FlaggedStorage`: Used to keep track of changes of a component. Useful for caching purposes.
+
+For more information, see the [specs storage reference](https://docs.rs/specs/latest/specs/storage/index.html).
+
+## Tags
+
+Components can also be used to "tag" entities.
+The usual way to do it is to create an empty struct, and implement `Component` using `NullStorage` as the `Storage` type for it.
+Null storage means that it is not going to take memory space to store those components.
+
+You will learn how to use those tag components in the system chapter.

book/src/concepts/dispatcher.md

@@ -0,0 +1,18 @@
+# Dispatcher
+
+## What is a `Dispatcher`?
+
+Dispatchers are the heart of the ECS infrastructure. They are the executors that decide when the `System`s will be executed so that they don't walk over each other.
+
+When a dispatcher is created, it is associated with the systems that it will execute. It then generates an execution plan that respects mutability rules while maximizing parallelism.
+
+## Respecting mutability rules
+
+When a system wants to access a `Storage` of a resource, they can do so either mutably or immutably. This works just like in Rust: either only one system can request something mutably and no other system can access it, or multiple systems can request something but only immutably.
+
+The dispatcher looks at all the `SystemData` in the systems and builds execution stages.
+
+If you want to have the best performance possible, you should prefer immutable over mutable whenever it is possible. (`Read` instead of `Write`, `ReadStorage` instead of `WriteStorage`).
+
+_Note: Please however keep in mind that `Write` is still preferable to interior mutability, such as `Mutex` or `RwLock` for example.
+

book/src/concepts/entity.md

@@ -0,0 +1,20 @@
+# Entity
+
+## What is an entity?
+
+An `Entity` is simply a collection of `Component`s. At least conceptually. It represents a single object in your world.
+For example, a car could be an entity, with its properties being `Component`s.
+
+## Creating an entity
+
+There are two common ways to create entities:
+* From a `World` instance. See the relevant chapter in the book.
+* From a `System` using `Entities`. See the system chapter in the book.
+
+## Getting components of an entity
+
+You can't! Well, at least not directly from an `Entity` instance.
+As mentioned in the component book page, `Component`s are not directly attached to entities; they are inserted into storages.
+
+`Storage` access and modification will be covered in the resource, world and system sections of the book.
+