Sync with the latest develop branch

README.md

@@ -63,7 +63,7 @@ Read the [online book][bk] for a comprehensive tutorial to using Amethyst. There
 is also an online crate-level [API reference][ar].
 
 [bk]: https://www.amethyst.rs/book/
-[ar]: https://www.amethyst.rs/doc/amethyst/
+[ar]: https://www.amethyst.rs/doc/
 
 ## Quick Example
 

book/src/getting_started.md

@@ -19,8 +19,11 @@ Rust compiler. Here are the system requirements (they're pretty modest):
 ## Setting Up
 
 > Note: This guide assumes you have nightly Rust and Cargo installed, and also
-> have a working Internet connection. Please take care of these prerequisites
-> first before proceeding.
+> have a working Internet connection.
+> Please take care of these prerequisites first before proceeding.
+> See [rustup][ru] for handling multiple rust toolchains.
+
+[ru]: https://www.rustup.rs/
 
 There are two ways to get started working with Amethyst:
 

book/src/getting_started/hello_world.md

@@ -7,33 +7,37 @@ copy and paste the following code:
 ```rust
 extern crate amethyst;
 
-use amethyst::engine::{Application, Duration, State, Trans};
+use amethyst::engine::{Application, State, Trans};
+use amethyst::context::{Context, Config};
+use amethyst::ecs::World;
 
 struct HelloWorld;
 
 impl State for HelloWorld {
-    fn on_start(&mut self) {
+    fn on_start(&mut self, _: &mut Context, _: &mut World) {
         println!("Game started!");
     }
 
-    fn update(&mut self, _delta: Duration) -> Trans {
+    fn update(&mut self, _: &mut Context, _: &mut World) -> Trans {
         println!("Hello from Amethyst!");
         Trans::Quit
     }
 
-    fn on_stop(&mut self) {
+    fn on_stop(&mut self, _: &mut Context, _: &mut World) {
         println!("Game stopped!");
     }
 }
 
 fn main() {
-    let mut game = Application::new(HelloWorld);
+    let config = Config::default();
+    let context = Context::new(config);
+    let mut game = Application::build(HelloWorld, context).done();
     game.run();
 }
 ```
 
-Then, compile and run the code with `cargo run`, or `amethyst run` if you
-have the [CLI tool installed][ct].
+Then, compile and run the code inside "**src/**" with `cargo run`,
+or `amethyst run` if you have the [CLI tool installed][ct].
 
 [ct]: ./getting_started/automatic_setup.html
 
@@ -46,11 +50,11 @@ Game stopped!
 ```
 
 If instead you see `error: use of unstable library feature` then make sure
-you're using the [nightly release][nr] of Rust. You can use [multirust][mr] to
+you're using the [nightly release][nr] of Rust. You can use [rustup][ru] to
 install stable and nightly Rust side-by-side. 
 
 [nr]: https://doc.rust-lang.org/book/release-channels.html
-[mr]: https://github.com/brson/multirust
+[ru]: https://www.rustup.rs
 
 Congratulations! You have successfully written your first Amethyst application.
 

book/src/getting_started/manual_cargo_setup.md

@@ -16,15 +16,27 @@ the following lines to your "Cargo.toml":
 [dependencies]
 amethyst = "*"
 ```
+### From Git via cargo
 
-### From Git
+If you don't want to get Amethyst from Crates.io but directly from the
+Git repository, you can add the following lines to your "Cargo.toml":
 
-If you don't want to get Amethyst from Crates.io, you can clone the entire SDK
-from the Git repository. Once you're done, create a new Cargo project and `cd`
-into it.
+```toml
+[dependencies]
+amethyst = { git = "https://github.com/amethyst/amethyst.git" }
+```
+
+See the [crates guide][crg] for more information on the Cargo manifest file.
+
+[crg]: http://doc.crates.io/specifying-dependencies.html#specifying-dependencies-from-git-repositories
+
+### From Git via clone
+
+Instead of using the above, you can also clone the entire SDK from the
+Git repository. Once you're done, create a new Cargo project and `cd` into it.
 
 ```
-$ git clone https://github.com/ebkalderon/amethyst.git
+$ git clone https://github.com/amethyst/amethyst.git
 $ cargo new --bin hello_world
 $ cd hello_world
 ```

examples/pong.rs

@@ -362,7 +362,10 @@ impl State for Pong {
 
 fn main() {
     use amethyst::engine::Config;
-    let config = Config::from_file("../config/pong_example_config.yml").unwrap();
+    let config = Config::from_file(
+        format!("{}/config/pong_example_config.yml",
+                env!("CARGO_MANIFEST_DIR"))
+        ).unwrap();
     let mut context = Context::new(config.context_config);
     let rendering_processor = RenderingProcessor::new(config.renderer_config, &mut context);
     let mut game = Application::build(Pong, context)

examples/renderable.rs

@@ -113,14 +113,19 @@ impl State for Example {
 
 fn main() {
     use amethyst::engine::Config;
-    let config = Config::from_file("../config/renderable_example_config.yml").unwrap();
+    let config = Config::from_file(
+        format!("{}/config/renderable_example_config.yml",
+                env!("CARGO_MANIFEST_DIR"))
+        ).unwrap();
     let mut context = Context::new(config.context_config);
     let rendering_processor = RenderingProcessor::new(config.renderer_config, &mut context);
     let mut game = Application::build(Example::new(), context)
                    .with::<RenderingProcessor>(rendering_processor, "rendering_processor", 0)
+
                    .register::<Renderable>()
                    .register::<Light>()
                    .register::<Camera>()
+
                    .done();
     game.run();
 }

examples/sphere.rs

@@ -75,7 +75,10 @@ impl State for Example {
 
 fn main() {
     use amethyst::context::ContextConfig;
-    let config = ContextConfig::from_file("../config/window_example_config.yml").unwrap();
+    let config = ContextConfig::from_file(
+        format!("{}/config/window_example_config.yml",
+                env!("CARGO_MANIFEST_DIR"))
+        ).unwrap();
     let context = Context::new(config);
     let mut game = Application::build(Example, context).done();
     game.run();

examples/window.rs

@@ -37,7 +37,10 @@ impl State for Example {
 
 fn main() {
     use amethyst::context::ContextConfig;
-    let config = ContextConfig::from_file("../config/window_example_config.yml").unwrap();
+	  let config = ContextConfig::from_file(
+        format!("{}/config/window_example_config.yml",
+                env!("CARGO_MANIFEST_DIR"))
+        ).unwrap();
     let context = Context::new(config);
     let mut game = Application::build(Example, context).done();
     game.run();

src/ecs/Cargo.toml

@@ -14,3 +14,8 @@ license = "MIT"
 [dependencies]
 time = "^0.1"
 specs = "^0.7.0"
+
+[[example]]
+name = "usage"
+path = "examples/usage.rs"
+

src/ecs/examples/usage.rs

@@ -1,4 +1,4 @@
-///! Example of a basic entity-component system with 3 types of components.
+///! Example of a basic entity-component system with 3 types of generic components.
 extern crate time;
 
 extern crate amethyst_ecs as ecs;
@@ -7,28 +7,29 @@ use time::Duration;
 
 use ecs::{World, Simulation, Processor, RunArg, Component, VecStorage, JoinIter};
 
-// Define our components.
+// First we define our components.
 
+// Position in 3d of the Entity
 #[derive(Debug)]
 struct Position {
     x: f32,
     y: f32,
     z: f32,
 }
-impl Component for Position {
-    type Storage = VecStorage<Position>;
-}
 
-#[derive(Debug)]
-struct Light {
-    x: f32,
-    y: f32,
-    z: f32,
+impl Position {
+    fn add_speed(&mut self, speed: &Speed) {
+        self.x += speed.dx;
+        self.y += speed.dy;
+        self.z += speed.dz;
+    }
 }
-impl Component for Light {
-    type Storage = VecStorage<Light>;
+
+impl Component for Position {
+    type Storage = VecStorage<Position>;
 }
 
+// Example of a mesh component
 #[derive(Debug)]
 struct Mesh {
     handle: u64,
@@ -37,16 +38,38 @@ struct Mesh {
 impl Component for Mesh {
     type Storage = VecStorage<Mesh>;
 }
+// Example of a speed component
+#[derive(Debug)]
+struct Speed {
+    dx: f32,
+    dy: f32,
+    dz: f32,
+}
+impl Component for Speed {
+    type Storage = VecStorage<Speed>;
+}
 
 // Define our processors.
 
+struct Update;
+impl Processor<Duration> for Update {
+    fn run(&mut self, arg: RunArg, _: Duration) {
+        let (mut p, s) = arg.fetch(|w| (w.write::<Position>(), w.read::<Speed>())); // Make p writable.
+        for (p, s) in JoinIter::new((&mut p, &s)) {
+            // We want to only update entities with position and speed.
+            p.add_speed(&s);
+        }
+    }
+}
+
 struct Render {
     frame_count: u32,
 }
 impl Processor<Duration> for Render {
     fn run(&mut self, arg: RunArg, _: Duration) {
-        let (p, m) = arg.fetch(|w| (w.read::<Position>(), w.read::<Mesh>()));
+        let (p, m) = arg.fetch(|w| (w.read::<Position>(), w.read::<Mesh>())); // Make p writable.
         for (p, _) in JoinIter::new((&p, &m)) {
+            // We want to only render entities with position and mesh.
             println!("Render {:?}", p);
         }
         self.frame_count += 1;
@@ -55,24 +78,24 @@ impl Processor<Duration> for Render {
 }
 
 fn main() {
+    // Replace this with your favorite rng.
+    fn pfrand(i: u32) -> f32 {
+        (i as f32) * 1.21912
+    }
     let mut world = World::new();
     world.register::<Position>();
-    world.register::<Light>();
+    world.register::<Speed>();
     world.register::<Mesh>();
 
     let mut simulation = Simulation::build(world, 4)
-                             .with(Render { frame_count: 0 }, "Renderer", 1000)
+                             .with(Update, "Updater", 1000) // High priority
+                             .with(Render { frame_count: 0 }, "Renderer", 500) // Low priority
                              .done();
 
     for i in 0..180 {
         simulation.mut_world()
                   .create_now()
                   .with(Position {
-                      x: i as f32 * 0.1,
-                      y: 0.0,
-                      z: 0.0,
-                  })
-                  .with(Light {
                       x: 0.0,
                       y: 0.0,
                       z: 0.0,
@@ -81,6 +104,11 @@ fn main() {
                       handle: 1234567890,
                       y: 12,
                   })
+                  .with(Speed {
+                      dx: pfrand(i),
+                      dy: pfrand(i),
+                      dz: pfrand(i),
+                  })
                   .build();
     }
 

src/engine/app.rs

@@ -16,7 +16,7 @@ pub struct Application {
 }
 
 impl Application {
-    /// Creates a new Application with the given initial game state, planner, and config.
+    /// Creates a new Application with the given initial game state, planner, and context.
     pub fn new<T>(initial_state: T, planner: Planner<Arc<Mutex<Context>>>, context: Context) -> Application
         where T: State + 'static
     {