+ {{ page.summary | safe }}
+
+
+ Read more...
+
+ ":I.tabReplace?n.replace(/\t/g,I.tabReplace):""}):e}function h(e,n,t){var r=n?L[n]:t,a=[e.trim()];return e.match(/\bhljs\b/)||a.push("hljs"),-1===e.indexOf(r)&&a.push(r),a.join(" ").trim()}function d(e){var n,t,r,o,l,s=i(e);a(s)||(I.useBR?(n=document.createElementNS("http://www.w3.org/1999/xhtml","div"),n.innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/reference/intro.html b/docs/public/reference/intro.html
new file mode 100644
index 000000000..846f57a28
--- /dev/null
+++ b/docs/public/reference/intro.html
@@ -0,0 +1,199 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Specs Parallel ECS
+This is the reference for Specs, a Rust Entity Component System library.
+If you're looking for tutorials instead, there's a book for that +here, too.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/reference/mark.min.js b/docs/public/reference/mark.min.js
new file mode 100644
index 000000000..163623188
--- /dev/null
+++ b/docs/public/reference/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Specs Parallel ECS
+This is the reference for Specs, a Rust Entity Component System library.
+If you're looking for tutorials instead, there's a book for that +here, too.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/reference/searcher.js b/docs/public/reference/searcher.js
new file mode 100644
index 000000000..7fd97d487
--- /dev/null
+++ b/docs/public/reference/searcher.js
@@ -0,0 +1,477 @@
+"use strict";
+window.search = window.search || {};
+(function search(search) {
+ // Search functionality
+ //
+ // You can use !hasFocus() to prevent keyhandling in your key
+ // event handlers while the user is typing their search.
+
+ if (!Mark || !elasticlunr) {
+ return;
+ }
+
+ //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+ if (!String.prototype.startsWith) {
+ String.prototype.startsWith = function(search, pos) {
+ return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
+ };
+ }
+
+ var search_wrap = document.getElementById('search-wrapper'),
+ searchbar = document.getElementById('searchbar'),
+ searchbar_outer = document.getElementById('searchbar-outer'),
+ searchresults = document.getElementById('searchresults'),
+ searchresults_outer = document.getElementById('searchresults-outer'),
+ searchresults_header = document.getElementById('searchresults-header'),
+ searchicon = document.getElementById('search-toggle'),
+ content = document.getElementById('content'),
+
+ searchindex = null,
+ doc_urls = [],
+ results_options = {
+ teaser_word_count: 30,
+ limit_results: 30,
+ },
+ search_options = {
+ bool: "AND",
+ expand: true,
+ fields: {
+ title: {boost: 1},
+ body: {boost: 1},
+ breadcrumbs: {boost: 0}
+ }
+ },
+ mark_exclude = [],
+ marker = new Mark(content),
+ current_searchterm = "",
+ URL_SEARCH_PARAM = 'search',
+ URL_MARK_PARAM = 'highlight',
+ teaser_count = 0,
+
+ SEARCH_HOTKEY_KEYCODE = 83,
+ ESCAPE_KEYCODE = 27,
+ DOWN_KEYCODE = 40,
+ UP_KEYCODE = 38,
+ SELECT_KEYCODE = 13;
+
+ function hasFocus() {
+ return searchbar === document.activeElement;
+ }
+
+ function removeChildren(elem) {
+ while (elem.firstChild) {
+ elem.removeChild(elem.firstChild);
+ }
+ }
+
+ // Helper to parse a url into its building blocks.
+ function parseURL(url) {
+ var a = document.createElement('a');
+ a.href = url;
+ return {
+ source: url,
+ protocol: a.protocol.replace(':',''),
+ host: a.hostname,
+ port: a.port,
+ params: (function(){
+ var ret = {};
+ var seg = a.search.replace(/^\?/,'').split('&');
+ var len = seg.length, i = 0, s;
+ for (;i
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Specs Parallel ECS
+This is the reference for Specs, a Rust Entity Component System library.
+If you're looking for tutorials instead, there's a book for that +here, too.
+System
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/02_hello_world.html b/docs/public/tutorials/02_hello_world.html
new file mode 100644
index 000000000..8f3245b9f
--- /dev/null
+++ b/docs/public/tutorials/02_hello_world.html
@@ -0,0 +1,392 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction
+Welcome to The Specs Book, an introduction to ECS and the Specs API. +This book is targeted at beginners; guiding you through all the difficulties of +setting up, building, and structuring a game with an ECS.
+Specs is an ECS library that allows parallel system execution, with both low +overhead and high flexibility, different storage types and a type-level +system data model. It is mainly used for games and simulations, where it allows +to structure code using composition over inheritance.
+Additional documentation is available on docs.rs:
There also is a reference-style documentation available here:
+ +You don't yet know what an ECS is all about? The next section +is for you! In case you already know what an ECS is, just skip it.
+What's an ECS?
+The term ECS is a shorthand for Entity-component system. These are the three
+core concepts. Each entity is associated with some components. Those entities and
+components are processed by systems. This way, you have your data (components)
+completely separated from the behaviour (systems). An entity just logically
+groups components; so a Velocity component can be applied to the Position component
+of the same entity.
ECS is sometimes seen as a counterpart to Object-Oriented Programming. I wouldn't +say that's one hundred percent true, but let me give you some comparisons.
+In OOP, your player might look like this (I've used Java for the example):
+public class Player extends Character {
+ private final Transform transform;
+ private final Inventory inventory;
+}
+There are several limitations here:
+-
+
- There is either no multiple inheritance or it brings other problems with it, +like the diamond problem; moreover, you have to think about "is the player +a collider or does it have a collider?" +
- You cannot easily extend the player with modding; all the attributes are hardcoded. +
- Imagine you want to add a NPC, which looks like this: +
public class Npc extends Character {
+ private final Transform transform;
+ private final Inventory inventory;
+ private final boolean isFriendly;
+}
+Now you have stuff duplicated; you would have to write mostly identical code for +your player and the NPC, even though e.g. they both share a transform.
+
This is where ECS comes into play: Components are associated with entities; you can just insert components, whenever you like.
+One entity may or may not have a certain component. You can see an Entity as an ID into component tables, as illustrated in the
+diagram below. We could theoretically store all the components together with the entity, but that would be very inefficient;
+you'll see how these tables work in chapter 5.
This is how an Entity is implemented; it's just
struct Entity(u32, Generation);
+where the first field is the id and the second one is the generation, used to check +if the entity has been deleted.
+Here's another illustration of the relationship between components and entities. Force, Mass and Velocity are all components here.
Entity 1 has each of those components, Entity 2 only a Force, etc.
Now we're only missing the last character in ECS - the "S" for System. Whereas components and entities are purely data,
+systems contain all the logic of your application. A system typically iterates over all entities that fulfill specific constraints,
+like "has both a force and a mass". Based on this data a system will execute code, e.g. produce a velocity out of the force and the mass.
+This is the additional advantage I wanted to point out with the Player / Npc example; in an ECS, you can simply add new attributes
+to entities and that's also how you define behaviour in Specs (this is called data-driven programming).
By simply adding a force to an entity that has a mass, you can make it move, because a Velocity will be produced for it.
Where to use an ECS?
+In case you were looking for a general-purpose library for doing things the data-oriented way, I have to disappoint you; there are none. +ECS libraries are best-suited for creating games or simulations, but they do not magically make your code more data-oriented.
++
Okay, now that you were given a rough overview, let's continue +to Chapter 2 where we'll build our first actual application with Specs.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/03_dispatcher.html b/docs/public/tutorials/03_dispatcher.html
new file mode 100644
index 000000000..345bb2202
--- /dev/null
+++ b/docs/public/tutorials/03_dispatcher.html
@@ -0,0 +1,354 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Hello,
+The
+
+
+
+
+
+ Hello, World!
+Setting up
+First of all, thanks for trying out specs. Let's
+set it up first. Add the following line to your Cargo.toml:
[dependencies]
+specs = "0.14.0"
+And add this to your crate root (main.rs or lib.rs):
extern crate specs;
+Components
+Let's start by creating some data:
+use specs::{Component, VecStorage};
+
+#[derive(Debug)]
+struct Position {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Position {
+ type Storage = VecStorage<Self>;
+}
+
+#[derive(Debug)]
+struct Velocity {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Velocity {
+ type Storage = VecStorage<Self>;
+}
+These will be our two component types. Optionally, the specs-derive crate
+provides a convenient custom #[derive] you can use to define component types
+more succinctly.
But first, you will need to add specs-derive to your crate
+[dependencies]
+specs = "0.14.0"
+specs-derive = "0.4.0"
+Now you can use this:
+extern crate specs;
+#[macro_use]
+extern crate specs_derive;
+
+use specs::{Component, VecStorage};
+
+#[derive(Component, Debug)]
+#[storage(VecStorage)]
+struct Position {
+ x: f32,
+ y: f32,
+}
+
+#[derive(Component, Debug)]
+#[storage(VecStorage)]
+struct Velocity {
+ x: f32,
+ y: f32,
+}
+If the #[storage(...)] attribute is omitted, the given component will be
+stored in a DenseVecStorage by default. But for this example, we are
+explicitly asking for these components to be kept in a VecStorage instead (see
+the later storages chapter for more details). But before we move on, we
+need to create a world in which to store all of our components.
The World
+use specs::{World, Builder};
+
+let mut world = World::new();
+world.register::<Position>();
+world.register::<Velocity>();
+This will create component storages for Positions and Velocitys.
let ball = world.create_entity().with(Position { x: 4.0, y: 7.0 }).build();
+Now you have an Entity, associated with a position.
So far this is pretty boring. We just have some data, +but we don't do anything with it. Let's change that!
+The system
+use specs::System;
+
+struct HelloWorld;
+
+impl<'a> System<'a> for HelloWorld {
+ type SystemData = ();
+
+ fn run(&mut self, data: Self::SystemData) {}
+}
+This is what a system looks like. Though it doesn't do anything (yet).
+Let's talk about this dummy implementation first.
+The SystemData is an associated type
+which specifies which components we need in order to run
+the system.
Let's see how we can read our Position components:
use specs::{ReadStorage, System};
+
+struct HelloWorld;
+
+impl<'a> System<'a> for HelloWorld {
+ type SystemData = ReadStorage<'a, Position>;
+
+ fn run(&mut self, position: Self::SystemData) {
+ use specs::Join;
+
+ for position in position.join() {
+ println!("Hello, {:?}", &position);
+ }
+ }
+}
+Note that all components that a system accesses must be registered with
+world.register::<Component>() before that system is run, or you will get a
+panic. This will usually be done automatically during setup, but we'll
+come back to that in a later chapter.
++There are many other types you can use as system data. Please see the +System Data Chapter for more information.
+
Running the system
+This just iterates through all the components and prints
+them. To execute the system, you can use RunNow like this:
use specs::RunNow;
+
+let mut hello_world = HelloWorld;
+hello_world.run_now(&world.res);
+world.maintain();
+The world.maintain() is not completely necessary here. Calling maintain should be done in general, however.
+If entities are created or deleted while a system is running, calling maintain
+will record the changes in its internal data structure.
Full example code
+Here the complete example of this chapter:
+use specs::{Builder, Component, ReadStorage, System, VecStorage, World, RunNow};
+
+#[derive(Debug)]
+struct Position {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Position {
+ type Storage = VecStorage<Self>;
+}
+
+#[derive(Debug)]
+struct Velocity {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Velocity {
+ type Storage = VecStorage<Self>;
+}
+
+struct HelloWorld;
+
+impl<'a> System<'a> for HelloWorld {
+ type SystemData = ReadStorage<'a, Position>;
+
+ fn run(&mut self, position: Self::SystemData) {
+ use specs::Join;
+
+ for position in position.join() {
+ println!("Hello, {:?}", &position);
+ }
+ }
+}
+
+fn main() {
+ let mut world = World::new();
+ world.register::<Position>();
+ world.register::<Velocity>();
+
+ world.create_entity().with(Position { x: 4.0, y: 7.0 }).build();
+
+ let mut hello_world = HelloWorld;
+ hello_world.run_now(&world.res);
+ world.maintain();
+}
++
This was a pretty basic example so far. A key feature we haven't seen is the
+Dispatcher, which allows us to configure systems to run in parallel (and it offers
+some other nice features, too).
Let's see how that works in Chapter 3: Dispatcher.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/04_resources.html b/docs/public/tutorials/04_resources.html
new file mode 100644
index 000000000..b77746c29
--- /dev/null
+++ b/docs/public/tutorials/04_resources.html
@@ -0,0 +1,280 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ When to use a
+
+
+
+
+
+ Dispatcher
+When to use a Dispatcher
+The Dispatcher allows you to automatically parallelize
+system execution where possible, using the fork-join model to split up the
+work and merge the result at the end. It requires a bit more planning
+and may have a little bit more overhead, but it's pretty convenient,
+especially when you're building a big game where you don't
+want to do this manually.
Building a dispatcher
+First of all, we have to build such a dispatcher.
+use specs::DispatcherBuilder;
+
+let mut dispatcher = DispatcherBuilder::new()
+ .with(HelloWorld, "hello_world", &[])
+ .build();
+Let's see what this does. After creating the builder, +we add a new
+-
+
- system object (
HelloWorld)
+ - with some name (
"hello_world"")
+ - and no dependencies (
&[]).
+
The name can be used to specify that system +as a dependency of another one. But we don't have a second +system yet.
+Creating another system
+struct UpdatePos;
+
+impl<'a> System<'a> for UpdatePos {
+ type SystemData = (ReadStorage<'a, Velocity>,
+ WriteStorage<'a, Position>);
+}
+Let's talk about the system data first. What you see here is a tuple, which we are using as our SystemData.
+In fact, SystemData is implemented for all tuples with up to 26 other types implementing SystemData in it.
++Notice that
+ReadStorageandWriteStorageare implementors ofSystemData+themselves, that's why we could use the first one for ourHelloWorldsystem +without wrapping it in a tuple; for more information see +the Chapter about system data.
To complete the implementation block, here's the run method:
fn run(&mut self, (vel, mut pos): Self::SystemData) {
+ use specs::Join;
+ for (vel, pos) in (&vel, &mut pos).join() {
+ pos.x += vel.x * 0.05;
+ pos.y += vel.y * 0.05;
+ }
+ }
+Now the .join() method also makes sense: it joins the two component
+storages, so that you either get no new element or a new element with
+both components, meaning that entities with only a Position, only
+a Velocity or none of them will be skipped. The 0.05 fakes the
+so called delta time which is the time needed for one frame.
+We have to hardcode it right now, because it's not a component (it's the
+same for every entity). The solution to this are Resources, see
+the next Chapter.
Adding a system with a dependency
+Okay, we'll add two more systems after the HelloWorld system:
.with(UpdatePos, "update_pos", &["hello_world"])
+ .with(HelloWorld, "hello_updated", &["update_pos"])
+The UpdatePos system now depends on the HelloWorld system and will only
+be executed after the dependency has finished. The final HelloWorld system prints the resulting updated positions.
Now to execute all the systems, just do
+dispatcher.dispatch(&mut world.res);
+Full example code
+Here the code for this chapter:
+use specs::{Builder, Component, DispatcherBuilder, ReadStorage,
+ System, VecStorage, World, WriteStorage};
+
+#[derive(Debug)]
+struct Position {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Position {
+ type Storage = VecStorage<Self>;
+}
+
+#[derive(Debug)]
+struct Velocity {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Velocity {
+ type Storage = VecStorage<Self>;
+}
+
+struct HelloWorld;
+
+impl<'a> System<'a> for HelloWorld {
+ type SystemData = ReadStorage<'a, Position>;
+
+ fn run(&mut self, position: Self::SystemData) {
+ use specs::Join;
+
+ for position in position.join() {
+ println!("Hello, {:?}", &position);
+ }
+ }
+}
+
+struct UpdatePos;
+
+impl<'a> System<'a> for UpdatePos {
+ type SystemData = (ReadStorage<'a, Velocity>,
+ WriteStorage<'a, Position>);
+
+ fn run(&mut self, (vel, mut pos): Self::SystemData) {
+ use specs::Join;
+ for (vel, pos) in (&vel, &mut pos).join() {
+ pos.x += vel.x * 0.05;
+ pos.y += vel.y * 0.05;
+ }
+ }
+}
+
+fn main() {
+ let mut world = World::new();
+ world.register::<Position>();
+ world.register::<Velocity>();
+
+ // Only the second entity will get a position update,
+ // because the first one does not have a velocity.
+ world.create_entity().with(Position { x: 4.0, y: 7.0 }).build();
+ world
+ .create_entity()
+ .with(Position { x: 2.0, y: 5.0 })
+ .with(Velocity { x: 0.1, y: 0.2 })
+ .build();
+
+ let mut dispatcher = DispatcherBuilder::new()
+ .with(HelloWorld, "hello_world", &[])
+ .with(UpdatePos, "update_pos", &["hello_world"])
+ .with(HelloWorld, "hello_updated", &["update_pos"])
+ .build();
+
+ dispatcher.dispatch(&mut world.res);
+ world.maintain();
+}
++
The next chapter will be a really short chapter about Resources,
+a way to share data between systems which only exist independent of
+entities (as opposed to 0..1 times per entity).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/05_storages.html b/docs/public/tutorials/05_storages.html
new file mode 100644
index 000000000..1b40b1b1d
--- /dev/null
+++ b/docs/public/tutorials/05_storages.html
@@ -0,0 +1,264 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Resources
+This (short) chapter will explain the concept of resources, data +which is shared between systems.
+First of all, when would you need resources? There's actually a great +example in chapter 3, where we just faked the delta time when applying +the velocity. Let's see how we can do this the right way.
+#[derive(Default)]
+struct DeltaTime(f32);
+++Note: In practice you may want to use
+std::time::Durationinstead, +because you shouldn't usef32s for durations in an actual game, because +they're not precise enough.
Adding this resource to our world is pretty easy:
+world.add_resource(DeltaTime(0.05)); // Let's use some start value
+To update the delta time, just use
+let mut delta = world.write_resource::<DeltaTime>();
+*delta = DeltaTime(0.04);
+Accessing resources from a system
+As you might have guessed, there's a type implementing system data
+specifically for resources. It's called Read (or Write for
+write access).
So we can now rewrite our system:
+use specs::{Read, ReadStorage, System, WriteStorage};
+
+struct UpdatePos;
+
+impl<'a> System<'a> for UpdatePos {
+ type SystemData = (Read<'a, DeltaTime>,
+ ReadStorage<'a, Velocity>,
+ WriteStorage<'a, Position>);
+
+ fn run(&mut self, data: Self::SystemData) {
+ let (delta, vel, mut pos) = data;
+
+ // `Read` implements `Deref`, so it
+ // coerces to `&DeltaTime`.
+ let delta = delta.0;
+
+ for (vel, pos) in (&vel, &mut pos).join() {
+ pos.x += vel.x * delta;
+ pos.y += vel.y * delta;
+ }
+ }
+}
+Note that all resources that a system accesses must be registered with
+world.add_resource(resource) before that system is run, or you will get a
+panic. If the resource has a Default implementation, this step is usually
+done during setup, but again we will come back to this in a later chapter.
For more information on SystemData, see the system data chapter.
Default for resources
+As we have learned in previous chapters, to fetch a Resource in our
+SystemData, we use Read or Write. However, there is one issue we
+have not mentioned yet, and that is the fact that Read and Write require
+Default to be implemented on the resource. This is because Specs will
+automatically try to add a Default version of a resource to the World
+during setup (we will come back to the setup stage in the next chapter).
+But how do we handle the case when we can't implement Default for our resource?
There are actually three ways of doing this:
+-
+
- Using a custom
SetupHandlerimplementation, you can provide this inSystemData+withRead<'a, Resource, TheSetupHandlerType>.
+ - By replacing
ReadandWritewithReadExpectandWriteExpect, which will +cause the first dispatch of theSystemto panic unless the resource has been +added manually toWorldfirst.
+ - By using
Option<Read<'a, Resource>>, if the resource really is optional. Note +that the order here is important, usingRead<'a, Option<Resource>>will not +result in the same behavior (it will try to fetchOption<Resource>fromWorld, +instead of doing an optional check ifResourceexists).
+
+
In the next chapter, you will learn about the different storages +and when to use which one.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/06_system_data.html b/docs/public/tutorials/06_system_data.html
new file mode 100644
index 000000000..9879b5b4c
--- /dev/null
+++ b/docs/public/tutorials/06_system_data.html
@@ -0,0 +1,299 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Storages
+Specs contains a bunch of different storages, all built and optimized for +different use cases. But let's see some basics first.
+Storage basics
+What you specify in a component impl-block is an UnprotectedStorage.
+Each UnprotectedStorage exposes an unsafe getter which does not
+perform any checks whether the requested index for the component is valid
+(the id of an entity is the index of its component). To allow checking them
+and speeding up iteration, we have something called hierarchical bitsets,
+provided by hibitset.
++Note: In case you don't know anything about bitsets, +you can safely skip the following section about it. Just keep +in mind that we have some mask which tracks for +which entities a component exists.
+
How does it speed up the iteration? A hierarchical bitset is essentially
+a multi-layer bitset, where each upper layer "summarizes" multiple bits
+of the underlying layers. That means as soon as one of the underlying
+bits is 1, the upper one also becomes 1, so that we can skip a whole
+range of indices if an upper bit is 0 in that section. In case it's 1,
+we go down by one layer and perform the same steps again (it currently
+has 4 layers).
Storage overview
+Here a list of the storages with a short description and a link +to the corresponding heading.
+| Storage Type | Description | Optimized for |
|---|---|---|
BTreeStorage | Works with a BTreeMap | no particular case |
DenseVecStorage | Uses a redirection table | fairly often used components |
HashMapStorage | Uses a HashMap | rare components |
NullStorage | Can flag entities | doesn't depend on rarity |
VecStorage | Uses a sparse Vec | commonly used components |
BTreeStorage
+It works using a BTreeMap and it's meant to be the default storage
+in case you're not sure which one to pick, because it fits all scenarios
+fairly well.
DenseVecStorage
+This storage uses two Vecs, one containing the actual data and the other
+one which provides a mapping from the entity id to the index for the data vec
+(it's a redirection table). This is useful when your component is bigger
+than a usize because it consumes less RAM.
HashMapStorage
+This should be used for components which are associated with very few entities, +because it provides a lower insertion cost and is packed together more tightly. +You should not use it for frequently used components, because the hashing cost would definitely +be noticeable.
+NullStorage
+As already described in the overview, the NullStorage does itself
+only contain a user-defined ZST (=Zero Sized Type; a struct with no data in it,
+like struct Synced;).
+Because it's wrapped in a so-called MaskedStorage, insertions and deletions
+modify the mask, so it can be used for flagging entities (like in this example
+for marking an entity as Synced, which could be used to only synchronize
+some of the entities over the network).
VecStorage
+This one has only one vector (as opposed to the DenseVecStorage). It
+just leaves uninitialized gaps where we don't have any component.
+Therefore it would be a waste of memory to use this storage for
+rare components, but it's best suited for commonly used components
+(like transform values).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/07_setup.html b/docs/public/tutorials/07_setup.html
new file mode 100644
index 000000000..e01dd8b46
--- /dev/null
+++ b/docs/public/tutorials/07_setup.html
@@ -0,0 +1,343 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Specifying
+
+
+
+
+ System Data
+Every system can request data which it needs to run. This data can be specified
+using the System::SystemData type. Typical implementors of the SystemData trait
+are ReadStorage, WriteStorage, Read, Write, ReadExpect, WriteExpect and Entities.
+A tuple of types implementing SystemData automatically also implements SystemData.
+This means you can specify your System::SystemData as follows:
++# #![allow(unused_variables)] +#fn main() { +struct Sys; + +impl<'a> System<'a> for Sys { + type SystemData = (WriteStorage<'a, Pos>, ReadStorage<'a, Vel>); + + fn run(&mut self, (pos, vel): Self::SystemData) { + /* ... */ + } +} +#}
It is very important that you don't request both a ReadStorage and a WriteStorage
+for the same component or a Read and a Write for the same resource.
+This is just like the borrowing rules of Rust, where you can't borrow something
+mutably and immutably at the same time. In Specs, we have to check this at
+runtime, thus you'll get a panic if you don't follow this rule.
Accessing Entities
+You want to create/delete entities from a system? There is
+good news for you. You can use Entities to do that.
+It implements SystemData so just put it in your SystemData tuple.
++Don't confuse
+specs::Entitieswithspecs::EntitiesRes. +While the latter one is the actual resource, the former one is a type +definition forRead<Entities>.
Please note that you may never write to these Entities, so only
+use Read. Even though it's immutable, you can atomically create
+and delete entities with it. Just use the .create() and .delete()
+methods, respectively. After dynamic entity deletion,
+a call to World::maintain is necessary in order to make the changes
+persistent and delete associated components.
Adding and removing components
+Adding or removing components can be done by modifying
+either the component storage directly with a WriteStorage
+or lazily using the LazyUpdate resource.
use specs::{Component, Read, LazyUpdate, NullStorage, System, Entities, WriteStorage};
+
+struct Stone;
+impl Component for Stone {
+ type Storage = NullStorage<Self>;
+}
+
+struct StoneCreator;
+impl<'a> System<'a> for StoneCreator {
+ type SystemData = (
+ Entities<'a>,
+ WriteStorage<'a, Stone>,
+ Read<'a, LazyUpdate>,
+ );
+
+ fn run(&mut self, (entities, mut stones, updater): Self::SystemData) {
+ let stone = entities.create();
+
+ // 1) Either we insert the component by writing to its storage
+ stones.insert(stone, Stone);
+
+ // 2) or we can lazily insert it with `LazyUpdate`
+ updater.insert(stone, Stone);
+ }
+}
+++Note: After using
+LazyUpdatea call toWorld::maintain+is necessary to actually execute the changes.
SetupHandler / Default for resources
+Please refer to the resources chapter for automatic creation of resources.
+Specifying SystemData
+As mentioned earlier, SystemData is implemented for tuples up to 26 elements. Should you ever need
+more, you could even nest these tuples. However, at some point it becomes hard to keep track of all the elements.
+That's why you can also create your own SystemData bundle using a struct:
extern crate shred;
+#[macro_use]
+extern crate shred_derive;
+extern crate specs;
+
+use specs::prelude::*;
+
+#[derive(SystemData)]
+pub struct MySystemData<'a> {
+ positions: ReadStorage<'a, Position>,
+ velocities: ReadStorage<'a, Velocity>,
+ forces: ReadStorage<'a, Force>,
+
+ delta: Read<'a, DeltaTime>,
+ game_state: Write<'a, GameState>,
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/08_join.html b/docs/public/tutorials/08_join.html
new file mode 100644
index 000000000..5dd470c84
--- /dev/null
+++ b/docs/public/tutorials/08_join.html
@@ -0,0 +1,304 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The
+Custom
+
+
+
+
+ The setup stage
+So far for all our component storages and resources, we've been adding
+them to the World manually. In Specs, this is not required if you use
+setup. This is a manually invoked stage that goes through SystemData
+and calls register, add_resource, etc. for all (with some exceptions)
+components and resources found. The setup function can be found in
+the following locations:
-
+
ReadStorage,WriteStorage,Read,Write
+SystemData
+System
+RunNow
+Dispatcher
+ParSeq
+
During setup, all components encountered will be registered, and all
+resources that have a Default implementation or a custom SetupHandler
+will be added. Note that resources encountered in ReadExpect and WriteExpect
+will not be added to the World automatically.
The recommended way to use setup is to run it on Dispatcher or ParSeq
+after the system graph is built, but before the first dispatch. This will go
+through all Systems in the graph, and call setup on each.
Let's say you began by registering Components and Resources first:
+
+struct Gravity;
+
+struct Velocity;
+
+impl Component for Position {
+ type Storage = VecStorage<Self>;
+}
+
+struct SimulationSystem;
+
+impl<'a> System<'a> for SimulationSystem {
+ type SystemData = (Read<'a, Gravity>, WriteStorage<'a, Velocity>);
+
+ fn run(_, _) {}
+}
+
+fn main() {
+ let mut world = World::new();
+ world.add_resource(Gravity);
+ world.register::<Velocity>();
+
+ for _ in 0..5 {
+ world.create_entity().with(Velocity).build();
+ }
+
+ let mut dispatcher = DispatcherBuilder::new()
+ .with(SimulationSystem, "simulation", &[])
+ .build();
+
+ dispatcher.dispatch(&mut world.res);
+ world.maintain();
+}
+
+You could get rid of that phase by calling setup() and re-ordering your main function:
fn main() {
+ let mut world = World::new();
+ let mut dispatcher = DispatcherBuilder::new()
+ .with(SimulationSystem, "simulation", &[])
+ .build();
+
+ dispatcher.setup(&mut world.res);
+
+ for _ in 0..5 {
+ world.create_entity().with(Velocity).build();
+ }
+
+ dispatcher.dispatch(&mut world.res);
+ world.maintain();
+}
+
+Custom setup functionality
+The good qualities of setup don't end here however. We can also use setup
+to create our non-Default resources, and also to initialize our Systems!
+We do this by custom implementing the setup function in our System.
Let's say we have a System that process events, using shrev::EventChannel:
struct Sys {
+ reader: ReaderId<Event>,
+}
+
+impl<'a> System<'a> for Sys {
+ type SystemData = Read<'a, EventChannel<Event>>;
+
+ fn run(&mut self, events: Self::SystemData) {
+ for event in events.read(&mut self.reader) {
+ [..]
+ }
+ }
+}
+This looks pretty OK, but there is a problem here if we want to use setup.
+The issue is that Sys needs a ReaderId on creation, but to get a ReaderId,
+we need EventChannel<Event> to be initialized. This means the user of Sys need
+to create the EventChannel themselves and add it manually to the World.
+We can do better!
use specs::prelude::Resources;
+
+#[derive(Default)]
+struct Sys {
+ reader: Option<ReaderId<Event>>,
+}
+
+impl<'a> System<'a> for Sys {
+ type SystemData = Read<'a, EventChannel<Event>>;
+
+ fn run(&mut self, events: Self::SystemData) {
+ for event in events.read(&mut self.reader.as_mut().unwrap()) {
+ [..]
+ }
+ }
+
+ fn setup(&mut self, res: &mut Resources) {
+ use specs::prelude::SystemData;
+ Self::SystemData::setup(res);
+ self.reader = Some(res.fetch_mut::<EventChannel<Event>>().register_reader());
+ }
+}
+This is much better; we can now use setup to fully initialize Sys without
+requiring our users to create and add resources manually to World!
If we override the setup function on a System, it is vitally important that we
+remember to add Self::SystemData::setup(res);, or setup will not be performed for
+the Systems SystemData. This could cause panics during setup or during
+the first dispatch.
Setting up in bulk
+In the case of libraries making use of specs, it is sometimes helpful to provide
+a way to add many things at once.
+It's generally recommended to provide a standalone function to register multiple
+Components/Resources at once, while allowing the user to add individual systems
+by themselves.
fn add_physics_engine(world: &mut World, config: LibraryConfig) -> Result<(), LibraryError> {
+ world.register::<Velocity>();
+ // etc
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/09_parallel_join.html b/docs/public/tutorials/09_parallel_join.html
new file mode 100644
index 000000000..ca2c8fe43
--- /dev/null
+++ b/docs/public/tutorials/09_parallel_join.html
@@ -0,0 +1,247 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Joining components
+In the last chapter, we learned how to access resources using SystemData.
+To access our components with it, we can just request a ReadStorage and use
+Storage::get to retrieve the component associated to an entity. This works quite
+well if you want to access a single component, but what if you want to
+iterate over many components? Maybe some of them are required, others might
+be optional and maybe there is even a need to exclude some components?
+If we wanted to do that using only Storage::get, the code would become very ugly.
+So instead we worked out a way to conveniently specify that. This concept is
+known as "joining".
Basic joining
+We've already seen some basic examples of joining in the last chapters, for +example we saw how to join over two storages:
+for (pos, vel) in (&mut pos_storage, &vel_storage).join() {
+ *pos += *vel;
+}
+This simply iterates over the position and velocity components of +all entities that have both these components. That means all the +specified components are required.
+Sometimes, we want not only get the components of entities,
+but also the entity value themselves. To do that, we can simply join over
+&EntitiesRes.
for (ent, pos, vel) in (&*entities, &mut pos_storage, &vel_storage).join() {
+ println!("Processing entity: {:?}", ent);
+ *pos += *vel;
+}
+Optional components
+If we iterate over the &EntitiesRes as shown above, we can simply
+use the returned Entity values to get components from storages as usual.
for (ent, pos, vel) in (&*entities, &mut pos_storage, &vel_storage).join() {
+ println!("Processing entity: {:?}", ent);
+ *pos += *vel;
+
+ let mass: Option<&mut Mass> = mass_storage.get_mut(ent);
+ if let Some(mass) = mass {
+ let x = *vel / 300_000_000.0;
+ let y = 1 - x * x;
+ let y = y.sqrt();
+ mass.current = mass.constant / y;
+ }
+}
+In this example we iterate over all entities with a position and a velocity +and perform the calculation for the new position as usual. +However, in case the entity has a mass, we also calculate the current +mass based on the velocity. Thus, mass is an optional component here.
+Excluding components
+If you want to filter your selection by excluding all entities
+with a certain component type, you can use the not operator (!)
+on the respective component storage. Its return value is a unit (()).
for (ent, pos, vel, ()) in (
+ &*entities,
+ &mut pos_storage,
+ &vel_storage,
+ !&frozen_storage,
+).join() {
+ println!("Processing entity: {:?}", ent);
+ *pos += *vel;
+}
+This will simply iterate over all entities that
+-
+
- have a position +
- have a velocity +
- do not have a
Frozencomponent
+
How joining works
+You can call join() on everything that implements the Join trait.
+The method call always returns an iterator. Join is implemented for
-
+
&ReadStorage/&WriteStorage(gives back a reference to the components)
+&mut WriteStorage(gives back a mutable reference to the components)
+&EntitiesRes(returnsEntityvalues)
+- bitsets +
We think the last point here is pretty interesting, because +it allows for even more flexibility, as you will see in the next +section.
+Joining over bitsets
+Specs is using hibitset, a library which provides layered bitsets
+(those were part of Specs once, but it was decided that a separate
+library could be useful for others).
These bitsets are used with the component storages to determine
+which entities the storage provides a component value for. Also,
+Entities is using bitsets, too. You can even create your
+own bitsets and add or remove entity ids:
use hibitset::{BitSet, BitSetLike};
+
+let mut bitset = BitSet::new();
+bitset.add(entity1.id());
+bitset.add(entity2.id());
+BitSets can be combined using the standard binary operators,
+&, | and ^. Additionally, you can negate them using !.
+This allows you to combine and filter components in multiple ways.
+
This chapter has been all about looping over components; but we can do more +than sequential iteration! Let's look at some parallel code in the next +chapter.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/10_rendering.html b/docs/public/tutorials/10_rendering.html
new file mode 100644
index 000000000..15f92e027
--- /dev/null
+++ b/docs/public/tutorials/10_rendering.html
@@ -0,0 +1,243 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Parallel Join
+As mentioned in the chapter dedicated to how to dispatch systems,
+Specs automatically parallelizes system execution when there are non-conflicting
+system data requirements (Two Systems conflict if their SystemData needs access
+to the same resource where at least one of them needs write access to it).
Basic parallelization
+What isn't automatically parallelized by Specs are +the joins made within a single system:
+ fn run(&mut self, (vel, mut pos): Self::SystemData) {
+ use specs::Join;
+ // This loop runs sequentially on a single thread.
+ for (vel, pos) in (&vel, &mut pos).join() {
+ pos.x += vel.x * 0.05;
+ pos.y += vel.y * 0.05;
+ }
+ }
+This means that, if there are hundreds of thousands of entities and only a few +systems that actually can be executed in parallel, then the full power +of CPU cores cannot be fully utilized.
+To fix this potential inefficiency and to parallelize the joining, the join
+method call can be exchanged for par_join:
fn run(&mut self, (vel, mut pos): Self::SystemData) {
+ use rayon::prelude::*;
+ use specs::ParJoin;
+
+ // Parallel joining behaves similarly to normal joining
+ // with the difference that iteration can potentially be
+ // executed in parallel by a thread pool.
+ (&vel, &mut pos)
+ .par_join()
+ .for_each(|(vel, pos)| {
+ pos.x += vel.x * 0.05;
+ pos.y += vel.y * 0.05;
+ });
+}
+++There is always overhead in parallelization, so you should carefully profile to see if there are benefits in the +switch. If you have only a few things to iterate over then sequential join is faster.
+
The par_join method produces a type implementing rayon's ParallelIterator
+trait which provides lots of helper methods to manipulate the iteration,
+the same way the normal Iterator trait does.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/11_advanced_component.html b/docs/public/tutorials/11_advanced_component.html
new file mode 100644
index 000000000..edc8df14d
--- /dev/null
+++ b/docs/public/tutorials/11_advanced_component.html
@@ -0,0 +1,338 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rendering
+Rendering is often a little bit tricky when you're dealing with a multi-threaded ECS. +That's why we have something called "thread-local systems".
+There are two things to keep in mind about thread-local systems:
+-
+
- They're always executed at the end of dispatch. +
- They cannot have dependencies; you just add them in the order you want them to run. +
Adding one is a simple line added to the builder code:
+DispatcherBuilder::new()
+ .with_thread_local(RenderSys);
+Amethyst
+As for Amethyst, it's very easy because Specs is already integrated. So there's no special effort +required, just look at the current examples.
+Piston
+Piston has an event loop which looks like this:
+while let Some(event) = window.poll_event() {
+ // Handle event
+}
+Now, we'd like to do as much as possible in the ECS, so we feed in input as a +resource. +This is what your code could look like:
+struct ResizeEvents(Vec<(u32, u32)>);
+
+world.add_resource(ResizeEvents(Vec::new()));
+
+while let Some(event) = window.poll_event() {
+ match event {
+ Input::Resize(x, y) => world.write_resource::<ResizeEvents>().0.push((x, y)),
+ // ...
+ }
+}
+The actual dispatching should happen every time the Input::Update event occurs.
+
++ +If you want a section for your game engine added, feel free to submit a PR!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/12_tracked.html b/docs/public/tutorials/12_tracked.html
new file mode 100644
index 000000000..9904ef981
--- /dev/null
+++ b/docs/public/tutorials/12_tracked.html
@@ -0,0 +1,272 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Advanced strategies for components
+So now that we have a fairly good grasp on the basics of Specs, +it's time that we start experimenting with more advanced patterns!
+Marker components
+Say we want to add a drag force to only some entities that have velocity, but +let other entities move about freely without drag.
+The most common way is to use a marker component for this. A marker component
+is a component without any data that can be added to entities to "mark" them
+for processing, and can then be used to narrow down result sets using Join.
Some code for the drag example to clarify:
+#[derive(Component)]
+#[storage(NullStorage)]
+pub struct Drag;
+
+#[derive(Component)]
+pub struct Position {
+ pub pos: [f32; 3],
+}
+
+#[derive(Component)]
+pub struct Velocity {
+ pub velocity: [f32; 3],
+}
+
+struct Sys {
+ drag: f32,
+}
+
+impl<'a> System<'a> for Sys {
+ type SystemData = (
+ ReadStorage<'a, Drag>,
+ ReadStorage<'a, Velocity>,
+ WriteStorage<'a, Position>,
+ );
+
+ fn run(&mut self, (drag, velocity, mut position): Self::SystemData) {
+ // Update positions with drag
+ for (pos, vel, _) in (&mut position, &velocity, &drag).join() {
+ pos += vel - self.drag * vel * vel;
+ }
+ // Update positions without drag
+ for (pos, vel, _) in (&mut position, &velocity, !&drag).join() {
+ pos += vel;
+ }
+ }
+}
+Using NullStorage is recommended for marker components, since they don't contain
+any data and as such will not consume any memory. This means we can represent them using
+only a bitset. Note that NullStorage will only work for components that are ZST (i.e. a
+struct without fields).
Modeling entity relationships and hierarchy
+A common use case where we need a relationship between entities is having a third person +camera following the player around. We can model this using a targeting component +referencing the player entity.
+A simple implementation might look something like this:
+
+#[derive(Component)]
+pub struct Target {
+ target: Entity,
+ offset: Vector3,
+}
+
+pub struct FollowTargetSys;
+
+impl<'a> System<'a> for FollowTargetSys {
+ type SystemData = (
+ Entities<'a>,
+ ReadStorage<'a, Target>,
+ WriteStorage<'a, Transform>,
+ );
+
+ fn run(&mut self, (entity, target, transform): Self::SystemData) {
+ for (entity, t) in (&*entity, &target).join() {
+ let new_transform = transform.get(t.target).cloned().unwrap() + t.offset;
+ *transform.get_mut(entity).unwrap() = new_transform;
+ }
+ }
+}
+We could also model this as a resource (more about that in the next section), but it could
+be useful to be able to have multiple entities following targets, so modeling this with
+a component makes sense. This could in extension be used to model large scale hierarchical
+structure (scene graphs). For a generic implementation of such a hierarchical system, check
+out the crate specs-hierarchy.
Entity targeting
+Imagine we're building a team based FPS game, and we want to add a spectator mode, where the +spectator can pick a player to follow. In this scenario each player will have a camera defined +that is following them around, and what we want to do is to pick the camera that +we should use to render the scene on the spectator screen.
+The easiest way to deal with this problem is to have a resource with a target entity, that +we can use to fetch the actual camera entity.
+pub struct ActiveCamera(Entity);
+
+pub struct Render;
+
+impl<'a> System<'a> for Render {
+ type SystemData = (
+ Read<'a, ActiveCamera>,
+ ReadStorage<'a, Camera>,
+ ReadStorage<'a, Transform>,
+ ReadStorage<'a, Mesh>,
+ );
+
+ fn run(&mut self, (active_cam, camera, transform, mesh) : Self::SystemData) {
+ let camera = camera.get(active_cam.0).unwrap();
+ let view_matrix = transform.get(active_cam.0).unwrap().invert();
+ // Set projection and view matrix uniforms
+ for (mesh, transform) in (&mesh, &transform).join() {
+ // Set world transform matrix
+ // Render mesh
+ }
+ }
+}
+By doing this, whenever the spectator chooses a new player to follow, we simply change
+what Entity is referenced in the ActiveCamera resource, and the scene will be
+rendered from that viewpoint instead.
Sorting entities based on component value
+In a lot of scenarios we encounter a need to sort entities based on either a component's
+value, or a combination of component values. There are a couple of ways to deal with this
+problem. The first and most straightforward is to just sort Join results.
let data = (&entities, &comps).join().collect::<Vec<_>>();
+data.sort_by(|&a, &b| ...);
+for entity in data.iter().map(|d| d.0) {
+ // Here we get entities in sorted order
+}
+There are a couple of limitations with this approach, the first being that we will always
+process all matched entities every frame (if this is called in a System somewhere). This
+can be fixed by using FlaggedStorage to maintain a sorted Entity list in the System.
+We will talk more about FlaggedStorage in the next chapter.
The second limitation is that we do a Vec allocation every time, however this can be
+alleviated by having a Vec in the System struct that we reuse every frame. Since we
+are likely to keep a fairly steady amount of entities in most situations this could work well.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/FontAwesome/css/font-awesome.css b/docs/public/tutorials/FontAwesome/css/font-awesome.css
new file mode 100644
index 000000000..540440ce8
--- /dev/null
+++ b/docs/public/tutorials/FontAwesome/css/font-awesome.css
@@ -0,0 +1,4 @@
+/*!
+ * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome
+ * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
+ */@font-face{font-family:'FontAwesome';src:url('../fonts/fontawesome-webfont.eot?v=4.7.0');src:url('../fonts/fontawesome-webfont.eot?#iefix&v=4.7.0') format('embedded-opentype'),url('../fonts/fontawesome-webfont.woff2?v=4.7.0') format('woff2'),url('../fonts/fontawesome-webfont.woff?v=4.7.0') format('woff'),url('../fonts/fontawesome-webfont.ttf?v=4.7.0') format('truetype'),url('../fonts/fontawesome-webfont.svg?v=4.7.0#fontawesomeregular') format('svg');font-weight:normal;font-style:normal}.fa{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571429em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14285714em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14285714em;width:2.14285714em;top:.14285714em;text-align:center}.fa-li.fa-lg{left:-1.85714286em}.fa-border{padding:.2em .25em .15em;border:solid .08em #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa.fa-pull-left{margin-right:.3em}.fa.fa-pull-right{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left{margin-right:.3em}.fa.pull-right{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s infinite linear;animation:fa-spin 2s infinite linear}.fa-pulse{-webkit-animation:fa-spin 1s infinite steps(8);animation:fa-spin 1s infinite steps(8)}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scale(-1, 1);-ms-transform:scale(-1, 1);transform:scale(-1, 1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scale(1, -1);-ms-transform:scale(1, -1);transform:scale(1, -1)}:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270,:root .fa-flip-horizontal,:root .fa-flip-vertical{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:"\f000"}.fa-music:before{content:"\f001"}.fa-search:before{content:"\f002"}.fa-envelope-o:before{content:"\f003"}.fa-heart:before{content:"\f004"}.fa-star:before{content:"\f005"}.fa-star-o:before{content:"\f006"}.fa-user:before{content:"\f007"}.fa-film:before{content:"\f008"}.fa-th-large:before{content:"\f009"}.fa-th:before{content:"\f00a"}.fa-th-list:before{content:"\f00b"}.fa-check:before{content:"\f00c"}.fa-remove:before,.fa-close:before,.fa-times:before{content:"\f00d"}.fa-search-plus:before{content:"\f00e"}.fa-search-minus:before{content:"\f010"}.fa-power-off:before{content:"\f011"}.fa-signal:before{content:"\f012"}.fa-gear:before,.fa-cog:before{content:"\f013"}.fa-trash-o:before{content:"\f014"}.fa-home:before{content:"\f015"}.fa-file-o:before{content:"\f016"}.fa-clock-o:before{content:"\f017"}.fa-road:before{content:"\f018"}.fa-download:before{content:"\f019"}.fa-arrow-circle-o-down:before{content:"\f01a"}.fa-arrow-circle-o-up:before{content:"\f01b"}.fa-inbox:before{content:"\f01c"}.fa-play-circle-o:before{content:"\f01d"}.fa-rotate-right:before,.fa-repeat:before{content:"\f01e"}.fa-refresh:before{content:"\f021"}.fa-list-alt:before{content:"\f022"}.fa-lock:before{content:"\f023"}.fa-flag:before{content:"\f024"}.fa-headphones:before{content:"\f025"}.fa-volume-off:before{content:"\f026"}.fa-volume-down:before{content:"\f027"}.fa-volume-up:before{content:"\f028"}.fa-qrcode:before{content:"\f029"}.fa-barcode:before{content:"\f02a"}.fa-tag:before{content:"\f02b"}.fa-tags:before{content:"\f02c"}.fa-book:before{content:"\f02d"}.fa-bookmark:before{content:"\f02e"}.fa-print:before{content:"\f02f"}.fa-camera:before{content:"\f030"}.fa-font:before{content:"\f031"}.fa-bold:before{content:"\f032"}.fa-italic:before{content:"\f033"}.fa-text-height:before{content:"\f034"}.fa-text-width:before{content:"\f035"}.fa-align-left:before{content:"\f036"}.fa-align-center:before{content:"\f037"}.fa-align-right:before{content:"\f038"}.fa-align-justify:before{content:"\f039"}.fa-list:before{content:"\f03a"}.fa-dedent:before,.fa-outdent:before{content:"\f03b"}.fa-indent:before{content:"\f03c"}.fa-video-camera:before{content:"\f03d"}.fa-photo:before,.fa-image:before,.fa-picture-o:before{content:"\f03e"}.fa-pencil:before{content:"\f040"}.fa-map-marker:before{content:"\f041"}.fa-adjust:before{content:"\f042"}.fa-tint:before{content:"\f043"}.fa-edit:before,.fa-pencil-square-o:before{content:"\f044"}.fa-share-square-o:before{content:"\f045"}.fa-check-square-o:before{content:"\f046"}.fa-arrows:before{content:"\f047"}.fa-step-backward:before{content:"\f048"}.fa-fast-backward:before{content:"\f049"}.fa-backward:before{content:"\f04a"}.fa-play:before{content:"\f04b"}.fa-pause:before{content:"\f04c"}.fa-stop:before{content:"\f04d"}.fa-forward:before{content:"\f04e"}.fa-fast-forward:before{content:"\f050"}.fa-step-forward:before{content:"\f051"}.fa-eject:before{content:"\f052"}.fa-chevron-left:before{content:"\f053"}.fa-chevron-right:before{content:"\f054"}.fa-plus-circle:before{content:"\f055"}.fa-minus-circle:before{content:"\f056"}.fa-times-circle:before{content:"\f057"}.fa-check-circle:before{content:"\f058"}.fa-question-circle:before{content:"\f059"}.fa-info-circle:before{content:"\f05a"}.fa-crosshairs:before{content:"\f05b"}.fa-times-circle-o:before{content:"\f05c"}.fa-check-circle-o:before{content:"\f05d"}.fa-ban:before{content:"\f05e"}.fa-arrow-left:before{content:"\f060"}.fa-arrow-right:before{content:"\f061"}.fa-arrow-up:before{content:"\f062"}.fa-arrow-down:before{content:"\f063"}.fa-mail-forward:before,.fa-share:before{content:"\f064"}.fa-expand:before{content:"\f065"}.fa-compress:before{content:"\f066"}.fa-plus:before{content:"\f067"}.fa-minus:before{content:"\f068"}.fa-asterisk:before{content:"\f069"}.fa-exclamation-circle:before{content:"\f06a"}.fa-gift:before{content:"\f06b"}.fa-leaf:before{content:"\f06c"}.fa-fire:before{content:"\f06d"}.fa-eye:before{content:"\f06e"}.fa-eye-slash:before{content:"\f070"}.fa-warning:before,.fa-exclamation-triangle:before{content:"\f071"}.fa-plane:before{content:"\f072"}.fa-calendar:before{content:"\f073"}.fa-random:before{content:"\f074"}.fa-comment:before{content:"\f075"}.fa-magnet:before{content:"\f076"}.fa-chevron-up:before{content:"\f077"}.fa-chevron-down:before{content:"\f078"}.fa-retweet:before{content:"\f079"}.fa-shopping-cart:before{content:"\f07a"}.fa-folder:before{content:"\f07b"}.fa-folder-open:before{content:"\f07c"}.fa-arrows-v:before{content:"\f07d"}.fa-arrows-h:before{content:"\f07e"}.fa-bar-chart-o:before,.fa-bar-chart:before{content:"\f080"}.fa-twitter-square:before{content:"\f081"}.fa-facebook-square:before{content:"\f082"}.fa-camera-retro:before{content:"\f083"}.fa-key:before{content:"\f084"}.fa-gears:before,.fa-cogs:before{content:"\f085"}.fa-comments:before{content:"\f086"}.fa-thumbs-o-up:before{content:"\f087"}.fa-thumbs-o-down:before{content:"\f088"}.fa-star-half:before{content:"\f089"}.fa-heart-o:before{content:"\f08a"}.fa-sign-out:before{content:"\f08b"}.fa-linkedin-square:before{content:"\f08c"}.fa-thumb-tack:before{content:"\f08d"}.fa-external-link:before{content:"\f08e"}.fa-sign-in:before{content:"\f090"}.fa-trophy:before{content:"\f091"}.fa-github-square:before{content:"\f092"}.fa-upload:before{content:"\f093"}.fa-lemon-o:before{content:"\f094"}.fa-phone:before{content:"\f095"}.fa-square-o:before{content:"\f096"}.fa-bookmark-o:before{content:"\f097"}.fa-phone-square:before{content:"\f098"}.fa-twitter:before{content:"\f099"}.fa-facebook-f:before,.fa-facebook:before{content:"\f09a"}.fa-github:before{content:"\f09b"}.fa-unlock:before{content:"\f09c"}.fa-credit-card:before{content:"\f09d"}.fa-feed:before,.fa-rss:before{content:"\f09e"}.fa-hdd-o:before{content:"\f0a0"}.fa-bullhorn:before{content:"\f0a1"}.fa-bell:before{content:"\f0f3"}.fa-certificate:before{content:"\f0a3"}.fa-hand-o-right:before{content:"\f0a4"}.fa-hand-o-left:before{content:"\f0a5"}.fa-hand-o-up:before{content:"\f0a6"}.fa-hand-o-down:before{content:"\f0a7"}.fa-arrow-circle-left:before{content:"\f0a8"}.fa-arrow-circle-right:before{content:"\f0a9"}.fa-arrow-circle-up:before{content:"\f0aa"}.fa-arrow-circle-down:before{content:"\f0ab"}.fa-globe:before{content:"\f0ac"}.fa-wrench:before{content:"\f0ad"}.fa-tasks:before{content:"\f0ae"}.fa-filter:before{content:"\f0b0"}.fa-briefcase:before{content:"\f0b1"}.fa-arrows-alt:before{content:"\f0b2"}.fa-group:before,.fa-users:before{content:"\f0c0"}.fa-chain:before,.fa-link:before{content:"\f0c1"}.fa-cloud:before{content:"\f0c2"}.fa-flask:before{content:"\f0c3"}.fa-cut:before,.fa-scissors:before{content:"\f0c4"}.fa-copy:before,.fa-files-o:before{content:"\f0c5"}.fa-paperclip:before{content:"\f0c6"}.fa-save:before,.fa-floppy-o:before{content:"\f0c7"}.fa-square:before{content:"\f0c8"}.fa-navicon:before,.fa-reorder:before,.fa-bars:before{content:"\f0c9"}.fa-list-ul:before{content:"\f0ca"}.fa-list-ol:before{content:"\f0cb"}.fa-strikethrough:before{content:"\f0cc"}.fa-underline:before{content:"\f0cd"}.fa-table:before{content:"\f0ce"}.fa-magic:before{content:"\f0d0"}.fa-truck:before{content:"\f0d1"}.fa-pinterest:before{content:"\f0d2"}.fa-pinterest-square:before{content:"\f0d3"}.fa-google-plus-square:before{content:"\f0d4"}.fa-google-plus:before{content:"\f0d5"}.fa-money:before{content:"\f0d6"}.fa-caret-down:before{content:"\f0d7"}.fa-caret-up:before{content:"\f0d8"}.fa-caret-left:before{content:"\f0d9"}.fa-caret-right:before{content:"\f0da"}.fa-columns:before{content:"\f0db"}.fa-unsorted:before,.fa-sort:before{content:"\f0dc"}.fa-sort-down:before,.fa-sort-desc:before{content:"\f0dd"}.fa-sort-up:before,.fa-sort-asc:before{content:"\f0de"}.fa-envelope:before{content:"\f0e0"}.fa-linkedin:before{content:"\f0e1"}.fa-rotate-left:before,.fa-undo:before{content:"\f0e2"}.fa-legal:before,.fa-gavel:before{content:"\f0e3"}.fa-dashboard:before,.fa-tachometer:before{content:"\f0e4"}.fa-comment-o:before{content:"\f0e5"}.fa-comments-o:before{content:"\f0e6"}.fa-flash:before,.fa-bolt:before{content:"\f0e7"}.fa-sitemap:before{content:"\f0e8"}.fa-umbrella:before{content:"\f0e9"}.fa-paste:before,.fa-clipboard:before{content:"\f0ea"}.fa-lightbulb-o:before{content:"\f0eb"}.fa-exchange:before{content:"\f0ec"}.fa-cloud-download:before{content:"\f0ed"}.fa-cloud-upload:before{content:"\f0ee"}.fa-user-md:before{content:"\f0f0"}.fa-stethoscope:before{content:"\f0f1"}.fa-suitcase:before{content:"\f0f2"}.fa-bell-o:before{content:"\f0a2"}.fa-coffee:before{content:"\f0f4"}.fa-cutlery:before{content:"\f0f5"}.fa-file-text-o:before{content:"\f0f6"}.fa-building-o:before{content:"\f0f7"}.fa-hospital-o:before{content:"\f0f8"}.fa-ambulance:before{content:"\f0f9"}.fa-medkit:before{content:"\f0fa"}.fa-fighter-jet:before{content:"\f0fb"}.fa-beer:before{content:"\f0fc"}.fa-h-square:before{content:"\f0fd"}.fa-plus-square:before{content:"\f0fe"}.fa-angle-double-left:before{content:"\f100"}.fa-angle-double-right:before{content:"\f101"}.fa-angle-double-up:before{content:"\f102"}.fa-angle-double-down:before{content:"\f103"}.fa-angle-left:before{content:"\f104"}.fa-angle-right:before{content:"\f105"}.fa-angle-up:before{content:"\f106"}.fa-angle-down:before{content:"\f107"}.fa-desktop:before{content:"\f108"}.fa-laptop:before{content:"\f109"}.fa-tablet:before{content:"\f10a"}.fa-mobile-phone:before,.fa-mobile:before{content:"\f10b"}.fa-circle-o:before{content:"\f10c"}.fa-quote-left:before{content:"\f10d"}.fa-quote-right:before{content:"\f10e"}.fa-spinner:before{content:"\f110"}.fa-circle:before{content:"\f111"}.fa-mail-reply:before,.fa-reply:before{content:"\f112"}.fa-github-alt:before{content:"\f113"}.fa-folder-o:before{content:"\f114"}.fa-folder-open-o:before{content:"\f115"}.fa-smile-o:before{content:"\f118"}.fa-frown-o:before{content:"\f119"}.fa-meh-o:before{content:"\f11a"}.fa-gamepad:before{content:"\f11b"}.fa-keyboard-o:before{content:"\f11c"}.fa-flag-o:before{content:"\f11d"}.fa-flag-checkered:before{content:"\f11e"}.fa-terminal:before{content:"\f120"}.fa-code:before{content:"\f121"}.fa-mail-reply-all:before,.fa-reply-all:before{content:"\f122"}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:"\f123"}.fa-location-arrow:before{content:"\f124"}.fa-crop:before{content:"\f125"}.fa-code-fork:before{content:"\f126"}.fa-unlink:before,.fa-chain-broken:before{content:"\f127"}.fa-question:before{content:"\f128"}.fa-info:before{content:"\f129"}.fa-exclamation:before{content:"\f12a"}.fa-superscript:before{content:"\f12b"}.fa-subscript:before{content:"\f12c"}.fa-eraser:before{content:"\f12d"}.fa-puzzle-piece:before{content:"\f12e"}.fa-microphone:before{content:"\f130"}.fa-microphone-slash:before{content:"\f131"}.fa-shield:before{content:"\f132"}.fa-calendar-o:before{content:"\f133"}.fa-fire-extinguisher:before{content:"\f134"}.fa-rocket:before{content:"\f135"}.fa-maxcdn:before{content:"\f136"}.fa-chevron-circle-left:before{content:"\f137"}.fa-chevron-circle-right:before{content:"\f138"}.fa-chevron-circle-up:before{content:"\f139"}.fa-chevron-circle-down:before{content:"\f13a"}.fa-html5:before{content:"\f13b"}.fa-css3:before{content:"\f13c"}.fa-anchor:before{content:"\f13d"}.fa-unlock-alt:before{content:"\f13e"}.fa-bullseye:before{content:"\f140"}.fa-ellipsis-h:before{content:"\f141"}.fa-ellipsis-v:before{content:"\f142"}.fa-rss-square:before{content:"\f143"}.fa-play-circle:before{content:"\f144"}.fa-ticket:before{content:"\f145"}.fa-minus-square:before{content:"\f146"}.fa-minus-square-o:before{content:"\f147"}.fa-level-up:before{content:"\f148"}.fa-level-down:before{content:"\f149"}.fa-check-square:before{content:"\f14a"}.fa-pencil-square:before{content:"\f14b"}.fa-external-link-square:before{content:"\f14c"}.fa-share-square:before{content:"\f14d"}.fa-compass:before{content:"\f14e"}.fa-toggle-down:before,.fa-caret-square-o-down:before{content:"\f150"}.fa-toggle-up:before,.fa-caret-square-o-up:before{content:"\f151"}.fa-toggle-right:before,.fa-caret-square-o-right:before{content:"\f152"}.fa-euro:before,.fa-eur:before{content:"\f153"}.fa-gbp:before{content:"\f154"}.fa-dollar:before,.fa-usd:before{content:"\f155"}.fa-rupee:before,.fa-inr:before{content:"\f156"}.fa-cny:before,.fa-rmb:before,.fa-yen:before,.fa-jpy:before{content:"\f157"}.fa-ruble:before,.fa-rouble:before,.fa-rub:before{content:"\f158"}.fa-won:before,.fa-krw:before{content:"\f159"}.fa-bitcoin:before,.fa-btc:before{content:"\f15a"}.fa-file:before{content:"\f15b"}.fa-file-text:before{content:"\f15c"}.fa-sort-alpha-asc:before{content:"\f15d"}.fa-sort-alpha-desc:before{content:"\f15e"}.fa-sort-amount-asc:before{content:"\f160"}.fa-sort-amount-desc:before{content:"\f161"}.fa-sort-numeric-asc:before{content:"\f162"}.fa-sort-numeric-desc:before{content:"\f163"}.fa-thumbs-up:before{content:"\f164"}.fa-thumbs-down:before{content:"\f165"}.fa-youtube-square:before{content:"\f166"}.fa-youtube:before{content:"\f167"}.fa-xing:before{content:"\f168"}.fa-xing-square:before{content:"\f169"}.fa-youtube-play:before{content:"\f16a"}.fa-dropbox:before{content:"\f16b"}.fa-stack-overflow:before{content:"\f16c"}.fa-instagram:before{content:"\f16d"}.fa-flickr:before{content:"\f16e"}.fa-adn:before{content:"\f170"}.fa-bitbucket:before{content:"\f171"}.fa-bitbucket-square:before{content:"\f172"}.fa-tumblr:before{content:"\f173"}.fa-tumblr-square:before{content:"\f174"}.fa-long-arrow-down:before{content:"\f175"}.fa-long-arrow-up:before{content:"\f176"}.fa-long-arrow-left:before{content:"\f177"}.fa-long-arrow-right:before{content:"\f178"}.fa-apple:before{content:"\f179"}.fa-windows:before{content:"\f17a"}.fa-android:before{content:"\f17b"}.fa-linux:before{content:"\f17c"}.fa-dribbble:before{content:"\f17d"}.fa-skype:before{content:"\f17e"}.fa-foursquare:before{content:"\f180"}.fa-trello:before{content:"\f181"}.fa-female:before{content:"\f182"}.fa-male:before{content:"\f183"}.fa-gittip:before,.fa-gratipay:before{content:"\f184"}.fa-sun-o:before{content:"\f185"}.fa-moon-o:before{content:"\f186"}.fa-archive:before{content:"\f187"}.fa-bug:before{content:"\f188"}.fa-vk:before{content:"\f189"}.fa-weibo:before{content:"\f18a"}.fa-renren:before{content:"\f18b"}.fa-pagelines:before{content:"\f18c"}.fa-stack-exchange:before{content:"\f18d"}.fa-arrow-circle-o-right:before{content:"\f18e"}.fa-arrow-circle-o-left:before{content:"\f190"}.fa-toggle-left:before,.fa-caret-square-o-left:before{content:"\f191"}.fa-dot-circle-o:before{content:"\f192"}.fa-wheelchair:before{content:"\f193"}.fa-vimeo-square:before{content:"\f194"}.fa-turkish-lira:before,.fa-try:before{content:"\f195"}.fa-plus-square-o:before{content:"\f196"}.fa-space-shuttle:before{content:"\f197"}.fa-slack:before{content:"\f198"}.fa-envelope-square:before{content:"\f199"}.fa-wordpress:before{content:"\f19a"}.fa-openid:before{content:"\f19b"}.fa-institution:before,.fa-bank:before,.fa-university:before{content:"\f19c"}.fa-mortar-board:before,.fa-graduation-cap:before{content:"\f19d"}.fa-yahoo:before{content:"\f19e"}.fa-google:before{content:"\f1a0"}.fa-reddit:before{content:"\f1a1"}.fa-reddit-square:before{content:"\f1a2"}.fa-stumbleupon-circle:before{content:"\f1a3"}.fa-stumbleupon:before{content:"\f1a4"}.fa-delicious:before{content:"\f1a5"}.fa-digg:before{content:"\f1a6"}.fa-pied-piper-pp:before{content:"\f1a7"}.fa-pied-piper-alt:before{content:"\f1a8"}.fa-drupal:before{content:"\f1a9"}.fa-joomla:before{content:"\f1aa"}.fa-language:before{content:"\f1ab"}.fa-fax:before{content:"\f1ac"}.fa-building:before{content:"\f1ad"}.fa-child:before{content:"\f1ae"}.fa-paw:before{content:"\f1b0"}.fa-spoon:before{content:"\f1b1"}.fa-cube:before{content:"\f1b2"}.fa-cubes:before{content:"\f1b3"}.fa-behance:before{content:"\f1b4"}.fa-behance-square:before{content:"\f1b5"}.fa-steam:before{content:"\f1b6"}.fa-steam-square:before{content:"\f1b7"}.fa-recycle:before{content:"\f1b8"}.fa-automobile:before,.fa-car:before{content:"\f1b9"}.fa-cab:before,.fa-taxi:before{content:"\f1ba"}.fa-tree:before{content:"\f1bb"}.fa-spotify:before{content:"\f1bc"}.fa-deviantart:before{content:"\f1bd"}.fa-soundcloud:before{content:"\f1be"}.fa-database:before{content:"\f1c0"}.fa-file-pdf-o:before{content:"\f1c1"}.fa-file-word-o:before{content:"\f1c2"}.fa-file-excel-o:before{content:"\f1c3"}.fa-file-powerpoint-o:before{content:"\f1c4"}.fa-file-photo-o:before,.fa-file-picture-o:before,.fa-file-image-o:before{content:"\f1c5"}.fa-file-zip-o:before,.fa-file-archive-o:before{content:"\f1c6"}.fa-file-sound-o:before,.fa-file-audio-o:before{content:"\f1c7"}.fa-file-movie-o:before,.fa-file-video-o:before{content:"\f1c8"}.fa-file-code-o:before{content:"\f1c9"}.fa-vine:before{content:"\f1ca"}.fa-codepen:before{content:"\f1cb"}.fa-jsfiddle:before{content:"\f1cc"}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-saver:before,.fa-support:before,.fa-life-ring:before{content:"\f1cd"}.fa-circle-o-notch:before{content:"\f1ce"}.fa-ra:before,.fa-resistance:before,.fa-rebel:before{content:"\f1d0"}.fa-ge:before,.fa-empire:before{content:"\f1d1"}.fa-git-square:before{content:"\f1d2"}.fa-git:before{content:"\f1d3"}.fa-y-combinator-square:before,.fa-yc-square:before,.fa-hacker-news:before{content:"\f1d4"}.fa-tencent-weibo:before{content:"\f1d5"}.fa-qq:before{content:"\f1d6"}.fa-wechat:before,.fa-weixin:before{content:"\f1d7"}.fa-send:before,.fa-paper-plane:before{content:"\f1d8"}.fa-send-o:before,.fa-paper-plane-o:before{content:"\f1d9"}.fa-history:before{content:"\f1da"}.fa-circle-thin:before{content:"\f1db"}.fa-header:before{content:"\f1dc"}.fa-paragraph:before{content:"\f1dd"}.fa-sliders:before{content:"\f1de"}.fa-share-alt:before{content:"\f1e0"}.fa-share-alt-square:before{content:"\f1e1"}.fa-bomb:before{content:"\f1e2"}.fa-soccer-ball-o:before,.fa-futbol-o:before{content:"\f1e3"}.fa-tty:before{content:"\f1e4"}.fa-binoculars:before{content:"\f1e5"}.fa-plug:before{content:"\f1e6"}.fa-slideshare:before{content:"\f1e7"}.fa-twitch:before{content:"\f1e8"}.fa-yelp:before{content:"\f1e9"}.fa-newspaper-o:before{content:"\f1ea"}.fa-wifi:before{content:"\f1eb"}.fa-calculator:before{content:"\f1ec"}.fa-paypal:before{content:"\f1ed"}.fa-google-wallet:before{content:"\f1ee"}.fa-cc-visa:before{content:"\f1f0"}.fa-cc-mastercard:before{content:"\f1f1"}.fa-cc-discover:before{content:"\f1f2"}.fa-cc-amex:before{content:"\f1f3"}.fa-cc-paypal:before{content:"\f1f4"}.fa-cc-stripe:before{content:"\f1f5"}.fa-bell-slash:before{content:"\f1f6"}.fa-bell-slash-o:before{content:"\f1f7"}.fa-trash:before{content:"\f1f8"}.fa-copyright:before{content:"\f1f9"}.fa-at:before{content:"\f1fa"}.fa-eyedropper:before{content:"\f1fb"}.fa-paint-brush:before{content:"\f1fc"}.fa-birthday-cake:before{content:"\f1fd"}.fa-area-chart:before{content:"\f1fe"}.fa-pie-chart:before{content:"\f200"}.fa-line-chart:before{content:"\f201"}.fa-lastfm:before{content:"\f202"}.fa-lastfm-square:before{content:"\f203"}.fa-toggle-off:before{content:"\f204"}.fa-toggle-on:before{content:"\f205"}.fa-bicycle:before{content:"\f206"}.fa-bus:before{content:"\f207"}.fa-ioxhost:before{content:"\f208"}.fa-angellist:before{content:"\f209"}.fa-cc:before{content:"\f20a"}.fa-shekel:before,.fa-sheqel:before,.fa-ils:before{content:"\f20b"}.fa-meanpath:before{content:"\f20c"}.fa-buysellads:before{content:"\f20d"}.fa-connectdevelop:before{content:"\f20e"}.fa-dashcube:before{content:"\f210"}.fa-forumbee:before{content:"\f211"}.fa-leanpub:before{content:"\f212"}.fa-sellsy:before{content:"\f213"}.fa-shirtsinbulk:before{content:"\f214"}.fa-simplybuilt:before{content:"\f215"}.fa-skyatlas:before{content:"\f216"}.fa-cart-plus:before{content:"\f217"}.fa-cart-arrow-down:before{content:"\f218"}.fa-diamond:before{content:"\f219"}.fa-ship:before{content:"\f21a"}.fa-user-secret:before{content:"\f21b"}.fa-motorcycle:before{content:"\f21c"}.fa-street-view:before{content:"\f21d"}.fa-heartbeat:before{content:"\f21e"}.fa-venus:before{content:"\f221"}.fa-mars:before{content:"\f222"}.fa-mercury:before{content:"\f223"}.fa-intersex:before,.fa-transgender:before{content:"\f224"}.fa-transgender-alt:before{content:"\f225"}.fa-venus-double:before{content:"\f226"}.fa-mars-double:before{content:"\f227"}.fa-venus-mars:before{content:"\f228"}.fa-mars-stroke:before{content:"\f229"}.fa-mars-stroke-v:before{content:"\f22a"}.fa-mars-stroke-h:before{content:"\f22b"}.fa-neuter:before{content:"\f22c"}.fa-genderless:before{content:"\f22d"}.fa-facebook-official:before{content:"\f230"}.fa-pinterest-p:before{content:"\f231"}.fa-whatsapp:before{content:"\f232"}.fa-server:before{content:"\f233"}.fa-user-plus:before{content:"\f234"}.fa-user-times:before{content:"\f235"}.fa-hotel:before,.fa-bed:before{content:"\f236"}.fa-viacoin:before{content:"\f237"}.fa-train:before{content:"\f238"}.fa-subway:before{content:"\f239"}.fa-medium:before{content:"\f23a"}.fa-yc:before,.fa-y-combinator:before{content:"\f23b"}.fa-optin-monster:before{content:"\f23c"}.fa-opencart:before{content:"\f23d"}.fa-expeditedssl:before{content:"\f23e"}.fa-battery-4:before,.fa-battery:before,.fa-battery-full:before{content:"\f240"}.fa-battery-3:before,.fa-battery-three-quarters:before{content:"\f241"}.fa-battery-2:before,.fa-battery-half:before{content:"\f242"}.fa-battery-1:before,.fa-battery-quarter:before{content:"\f243"}.fa-battery-0:before,.fa-battery-empty:before{content:"\f244"}.fa-mouse-pointer:before{content:"\f245"}.fa-i-cursor:before{content:"\f246"}.fa-object-group:before{content:"\f247"}.fa-object-ungroup:before{content:"\f248"}.fa-sticky-note:before{content:"\f249"}.fa-sticky-note-o:before{content:"\f24a"}.fa-cc-jcb:before{content:"\f24b"}.fa-cc-diners-club:before{content:"\f24c"}.fa-clone:before{content:"\f24d"}.fa-balance-scale:before{content:"\f24e"}.fa-hourglass-o:before{content:"\f250"}.fa-hourglass-1:before,.fa-hourglass-start:before{content:"\f251"}.fa-hourglass-2:before,.fa-hourglass-half:before{content:"\f252"}.fa-hourglass-3:before,.fa-hourglass-end:before{content:"\f253"}.fa-hourglass:before{content:"\f254"}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:"\f255"}.fa-hand-stop-o:before,.fa-hand-paper-o:before{content:"\f256"}.fa-hand-scissors-o:before{content:"\f257"}.fa-hand-lizard-o:before{content:"\f258"}.fa-hand-spock-o:before{content:"\f259"}.fa-hand-pointer-o:before{content:"\f25a"}.fa-hand-peace-o:before{content:"\f25b"}.fa-trademark:before{content:"\f25c"}.fa-registered:before{content:"\f25d"}.fa-creative-commons:before{content:"\f25e"}.fa-gg:before{content:"\f260"}.fa-gg-circle:before{content:"\f261"}.fa-tripadvisor:before{content:"\f262"}.fa-odnoklassniki:before{content:"\f263"}.fa-odnoklassniki-square:before{content:"\f264"}.fa-get-pocket:before{content:"\f265"}.fa-wikipedia-w:before{content:"\f266"}.fa-safari:before{content:"\f267"}.fa-chrome:before{content:"\f268"}.fa-firefox:before{content:"\f269"}.fa-opera:before{content:"\f26a"}.fa-internet-explorer:before{content:"\f26b"}.fa-tv:before,.fa-television:before{content:"\f26c"}.fa-contao:before{content:"\f26d"}.fa-500px:before{content:"\f26e"}.fa-amazon:before{content:"\f270"}.fa-calendar-plus-o:before{content:"\f271"}.fa-calendar-minus-o:before{content:"\f272"}.fa-calendar-times-o:before{content:"\f273"}.fa-calendar-check-o:before{content:"\f274"}.fa-industry:before{content:"\f275"}.fa-map-pin:before{content:"\f276"}.fa-map-signs:before{content:"\f277"}.fa-map-o:before{content:"\f278"}.fa-map:before{content:"\f279"}.fa-commenting:before{content:"\f27a"}.fa-commenting-o:before{content:"\f27b"}.fa-houzz:before{content:"\f27c"}.fa-vimeo:before{content:"\f27d"}.fa-black-tie:before{content:"\f27e"}.fa-fonticons:before{content:"\f280"}.fa-reddit-alien:before{content:"\f281"}.fa-edge:before{content:"\f282"}.fa-credit-card-alt:before{content:"\f283"}.fa-codiepie:before{content:"\f284"}.fa-modx:before{content:"\f285"}.fa-fort-awesome:before{content:"\f286"}.fa-usb:before{content:"\f287"}.fa-product-hunt:before{content:"\f288"}.fa-mixcloud:before{content:"\f289"}.fa-scribd:before{content:"\f28a"}.fa-pause-circle:before{content:"\f28b"}.fa-pause-circle-o:before{content:"\f28c"}.fa-stop-circle:before{content:"\f28d"}.fa-stop-circle-o:before{content:"\f28e"}.fa-shopping-bag:before{content:"\f290"}.fa-shopping-basket:before{content:"\f291"}.fa-hashtag:before{content:"\f292"}.fa-bluetooth:before{content:"\f293"}.fa-bluetooth-b:before{content:"\f294"}.fa-percent:before{content:"\f295"}.fa-gitlab:before{content:"\f296"}.fa-wpbeginner:before{content:"\f297"}.fa-wpforms:before{content:"\f298"}.fa-envira:before{content:"\f299"}.fa-universal-access:before{content:"\f29a"}.fa-wheelchair-alt:before{content:"\f29b"}.fa-question-circle-o:before{content:"\f29c"}.fa-blind:before{content:"\f29d"}.fa-audio-description:before{content:"\f29e"}.fa-volume-control-phone:before{content:"\f2a0"}.fa-braille:before{content:"\f2a1"}.fa-assistive-listening-systems:before{content:"\f2a2"}.fa-asl-interpreting:before,.fa-american-sign-language-interpreting:before{content:"\f2a3"}.fa-deafness:before,.fa-hard-of-hearing:before,.fa-deaf:before{content:"\f2a4"}.fa-glide:before{content:"\f2a5"}.fa-glide-g:before{content:"\f2a6"}.fa-signing:before,.fa-sign-language:before{content:"\f2a7"}.fa-low-vision:before{content:"\f2a8"}.fa-viadeo:before{content:"\f2a9"}.fa-viadeo-square:before{content:"\f2aa"}.fa-snapchat:before{content:"\f2ab"}.fa-snapchat-ghost:before{content:"\f2ac"}.fa-snapchat-square:before{content:"\f2ad"}.fa-pied-piper:before{content:"\f2ae"}.fa-first-order:before{content:"\f2b0"}.fa-yoast:before{content:"\f2b1"}.fa-themeisle:before{content:"\f2b2"}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:"\f2b3"}.fa-fa:before,.fa-font-awesome:before{content:"\f2b4"}.fa-handshake-o:before{content:"\f2b5"}.fa-envelope-open:before{content:"\f2b6"}.fa-envelope-open-o:before{content:"\f2b7"}.fa-linode:before{content:"\f2b8"}.fa-address-book:before{content:"\f2b9"}.fa-address-book-o:before{content:"\f2ba"}.fa-vcard:before,.fa-address-card:before{content:"\f2bb"}.fa-vcard-o:before,.fa-address-card-o:before{content:"\f2bc"}.fa-user-circle:before{content:"\f2bd"}.fa-user-circle-o:before{content:"\f2be"}.fa-user-o:before{content:"\f2c0"}.fa-id-badge:before{content:"\f2c1"}.fa-drivers-license:before,.fa-id-card:before{content:"\f2c2"}.fa-drivers-license-o:before,.fa-id-card-o:before{content:"\f2c3"}.fa-quora:before{content:"\f2c4"}.fa-free-code-camp:before{content:"\f2c5"}.fa-telegram:before{content:"\f2c6"}.fa-thermometer-4:before,.fa-thermometer:before,.fa-thermometer-full:before{content:"\f2c7"}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:"\f2c8"}.fa-thermometer-2:before,.fa-thermometer-half:before{content:"\f2c9"}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:"\f2ca"}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:"\f2cb"}.fa-shower:before{content:"\f2cc"}.fa-bathtub:before,.fa-s15:before,.fa-bath:before{content:"\f2cd"}.fa-podcast:before{content:"\f2ce"}.fa-window-maximize:before{content:"\f2d0"}.fa-window-minimize:before{content:"\f2d1"}.fa-window-restore:before{content:"\f2d2"}.fa-times-rectangle:before,.fa-window-close:before{content:"\f2d3"}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:"\f2d4"}.fa-bandcamp:before{content:"\f2d5"}.fa-grav:before{content:"\f2d6"}.fa-etsy:before{content:"\f2d7"}.fa-imdb:before{content:"\f2d8"}.fa-ravelry:before{content:"\f2d9"}.fa-eercast:before{content:"\f2da"}.fa-microchip:before{content:"\f2db"}.fa-snowflake-o:before{content:"\f2dc"}.fa-superpowers:before{content:"\f2dd"}.fa-wpexplorer:before{content:"\f2de"}.fa-meetup:before{content:"\f2e0"}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}
diff --git a/docs/public/tutorials/FontAwesome/fonts/FontAwesome.ttf b/docs/public/tutorials/FontAwesome/fonts/FontAwesome.ttf
new file mode 100644
index 000000000..35acda2fa
Binary files /dev/null and b/docs/public/tutorials/FontAwesome/fonts/FontAwesome.ttf differ
diff --git a/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.eot b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.eot
new file mode 100644
index 000000000..e9f60ca95
Binary files /dev/null and b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.eot differ
diff --git a/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.svg b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.svg
new file mode 100644
index 000000000..855c845e5
--- /dev/null
+++ b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.svg
@@ -0,0 +1,2671 @@
+
+
+
diff --git a/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.ttf b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.ttf
new file mode 100644
index 000000000..35acda2fa
Binary files /dev/null and b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.ttf differ
diff --git a/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.woff b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.woff
new file mode 100644
index 000000000..400014a4b
Binary files /dev/null and b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.woff differ
diff --git a/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.woff2 b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.woff2
new file mode 100644
index 000000000..4d13fc604
Binary files /dev/null and b/docs/public/tutorials/FontAwesome/fonts/fontawesome-webfont.woff2 differ
diff --git a/docs/public/tutorials/ayu-highlight.css b/docs/public/tutorials/ayu-highlight.css
new file mode 100644
index 000000000..786063fc4
--- /dev/null
+++ b/docs/public/tutorials/ayu-highlight.css
@@ -0,0 +1,71 @@
+/*
+Based off of the Ayu theme
+Original by Dempfi (https://github.com/dempfi/ayu)
+*/
+
+.hljs {
+ display: block;
+ overflow-x: auto;
+ background: #191f26;
+ color: #e6e1cf;
+ padding: 0.5em;
+}
+
+.hljs-comment,
+.hljs-quote,
+.hljs-meta {
+ color: #5c6773;
+ font-style: italic;
+}
+
+.hljs-variable,
+.hljs-template-variable,
+.hljs-attribute,
+.hljs-attr,
+.hljs-regexp,
+.hljs-link,
+.hljs-selector-id,
+.hljs-selector-class {
+ color: #ff7733;
+}
+
+.hljs-number,
+.hljs-builtin-name,
+.hljs-literal,
+.hljs-type,
+.hljs-params {
+ color: #ffee99;
+}
+
+.hljs-string,
+.hljs-bullet {
+ color: #b8cc52;
+}
+
+.hljs-title,
+.hljs-built_in,
+.hljs-section {
+ color: #ffb454;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-symbol {
+ color: #ff7733;
+}
+
+.hljs-name {
+ color: #36a3d9;
+}
+
+.hljs-tag {
+ color: #00568d;
+}
+
+.hljs-emphasis {
+ font-style: italic;
+}
+
+.hljs-strong {
+ font-weight: bold;
+}
diff --git a/docs/public/tutorials/book.js b/docs/public/tutorials/book.js
new file mode 100644
index 000000000..4640e8fca
--- /dev/null
+++ b/docs/public/tutorials/book.js
@@ -0,0 +1,600 @@
+"use strict";
+
+// Fix back button cache problem
+window.onunload = function () { };
+
+// Global variable, shared between modules
+function playpen_text(playpen) {
+ let code_block = playpen.querySelector("code");
+
+ if (window.ace && code_block.classList.contains("editable")) {
+ let editor = window.ace.edit(code_block);
+ return editor.getValue();
+ } else {
+ return code_block.textContent;
+ }
+}
+
+(function codeSnippets() {
+ // Hide Rust code lines prepended with a specific character
+ var hiding_character = "#";
+
+ function fetch_with_timeout(url, options, timeout = 6000) {
+ return Promise.race([
+ fetch(url, options),
+ new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout))
+ ]);
+ }
+
+ var playpens = Array.from(document.querySelectorAll(".playpen"));
+ if (playpens.length > 0) {
+ fetch_with_timeout("https://play.rust-lang.org/meta/crates", {
+ headers: {
+ 'Content-Type': "application/json",
+ },
+ method: 'POST',
+ mode: 'cors',
+ })
+ .then(response => response.json())
+ .then(response => {
+ // get list of crates available in the rust playground
+ let playground_crates = response.crates.map(item => item["id"]);
+ playpens.forEach(block => handle_crate_list_update(block, playground_crates));
+ });
+ }
+
+ function handle_crate_list_update(playpen_block, playground_crates) {
+ // update the play buttons after receiving the response
+ update_play_button(playpen_block, playground_crates);
+
+ // and install on change listener to dynamically update ACE editors
+ if (window.ace) {
+ let code_block = playpen_block.querySelector("code");
+ if (code_block.classList.contains("editable")) {
+ let editor = window.ace.edit(code_block);
+ editor.addEventListener("change", function (e) {
+ update_play_button(playpen_block, playground_crates);
+ });
+ }
+ }
+ }
+
+ // updates the visibility of play button based on `no_run` class and
+ // used crates vs ones available on http://play.rust-lang.org
+ function update_play_button(pre_block, playground_crates) {
+ var play_button = pre_block.querySelector(".play-button");
+
+ // skip if code is `no_run`
+ if (pre_block.querySelector('code').classList.contains("no_run")) {
+ play_button.classList.add("hidden");
+ return;
+ }
+
+ // get list of `extern crate`'s from snippet
+ var txt = playpen_text(pre_block);
+ var re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
+ var snippet_crates = [];
+ var item;
+ while (item = re.exec(txt)) {
+ snippet_crates.push(item[1]);
+ }
+
+ // check if all used crates are available on play.rust-lang.org
+ var all_available = snippet_crates.every(function (elem) {
+ return playground_crates.indexOf(elem) > -1;
+ });
+
+ if (all_available) {
+ play_button.classList.remove("hidden");
+ } else {
+ play_button.classList.add("hidden");
+ }
+ }
+
+ function run_rust_code(code_block) {
+ var result_block = code_block.querySelector(".result");
+ if (!result_block) {
+ result_block = document.createElement('code');
+ result_block.className = 'result hljs language-bash';
+
+ code_block.append(result_block);
+ }
+
+ let text = playpen_text(code_block);
+
+ var params = {
+ version: "stable",
+ optimize: "0",
+ code: text
+ };
+
+ if (text.indexOf("#![feature") !== -1) {
+ params.version = "nightly";
+ }
+
+ result_block.innerText = "Running...";
+
+ fetch_with_timeout("https://play.rust-lang.org/evaluate.json", {
+ headers: {
+ 'Content-Type': "application/json",
+ },
+ method: 'POST',
+ mode: 'cors',
+ body: JSON.stringify(params)
+ })
+ .then(response => response.json())
+ .then(response => result_block.innerText = response.result)
+ .catch(error => result_block.innerText = "Playground Communication: " + error.message);
+ }
+
+ // Syntax highlighting Configuration
+ hljs.configure({
+ tabReplace: ' ', // 4 spaces
+ languages: [], // Languages used for auto-detection
+ });
+
+ if (window.ace) {
+ // language-rust class needs to be removed for editable
+ // blocks or highlightjs will capture events
+ Array
+ .from(document.querySelectorAll('code.editable'))
+ .forEach(function (block) { block.classList.remove('language-rust'); });
+
+ Array
+ .from(document.querySelectorAll('code:not(.editable)'))
+ .forEach(function (block) { hljs.highlightBlock(block); });
+ } else {
+ Array
+ .from(document.querySelectorAll('code'))
+ .forEach(function (block) { hljs.highlightBlock(block); });
+ }
+
+ // Adding the hljs class gives code blocks the color css
+ // even if highlighting doesn't apply
+ Array
+ .from(document.querySelectorAll('code'))
+ .forEach(function (block) { block.classList.add('hljs'); });
+
+ Array.from(document.querySelectorAll("code.language-rust")).forEach(function (block) {
+
+ var code_block = block;
+ var pre_block = block.parentNode;
+ // hide lines
+ var lines = code_block.innerHTML.split("\n");
+ var first_non_hidden_line = false;
+ var lines_hidden = false;
+ var trimmed_line = "";
+
+ for (var n = 0; n < lines.length; n++) {
+ trimmed_line = lines[n].trim();
+ if (trimmed_line[0] == hiding_character && trimmed_line[1] != hiding_character) {
+ if (first_non_hidden_line) {
+ lines[n] = "" + "\n" + lines[n].replace(/(\s*)# ?/, "$1") + "";
+ }
+ else {
+ lines[n] = "" + lines[n].replace(/(\s*)# ?/, "$1") + "\n" + "";
+ }
+ lines_hidden = true;
+ }
+ else if (first_non_hidden_line) {
+ lines[n] = "\n" + lines[n];
+ }
+ else {
+ first_non_hidden_line = true;
+ }
+ if (trimmed_line[0] == hiding_character && trimmed_line[1] == hiding_character) {
+ lines[n] = lines[n].replace("##", "#")
+ }
+ }
+ code_block.innerHTML = lines.join("");
+
+ // If no lines were hidden, return
+ if (!lines_hidden) { return; }
+
+ var buttons = document.createElement('div');
+ buttons.className = 'buttons';
+ buttons.innerHTML = "";
+
+ // add expand button
+ pre_block.insertBefore(buttons, pre_block.firstChild);
+
+ pre_block.querySelector('.buttons').addEventListener('click', function (e) {
+ if (e.target.classList.contains('fa-expand')) {
+ var lines = pre_block.querySelectorAll('span.hidden');
+
+ e.target.classList.remove('fa-expand');
+ e.target.classList.add('fa-compress');
+ e.target.title = 'Hide lines';
+ e.target.setAttribute('aria-label', e.target.title);
+
+ Array.from(lines).forEach(function (line) {
+ line.classList.remove('hidden');
+ line.classList.add('unhidden');
+ });
+ } else if (e.target.classList.contains('fa-compress')) {
+ var lines = pre_block.querySelectorAll('span.unhidden');
+
+ e.target.classList.remove('fa-compress');
+ e.target.classList.add('fa-expand');
+ e.target.title = 'Show hidden lines';
+ e.target.setAttribute('aria-label', e.target.title);
+
+ Array.from(lines).forEach(function (line) {
+ line.classList.remove('unhidden');
+ line.classList.add('hidden');
+ });
+ }
+ });
+ });
+
+ Array.from(document.querySelectorAll('pre code')).forEach(function (block) {
+ var pre_block = block.parentNode;
+ if (!pre_block.classList.contains('playpen')) {
+ var buttons = pre_block.querySelector(".buttons");
+ if (!buttons) {
+ buttons = document.createElement('div');
+ buttons.className = 'buttons';
+ pre_block.insertBefore(buttons, pre_block.firstChild);
+ }
+
+ var clipButton = document.createElement('button');
+ clipButton.className = 'fa fa-copy clip-button';
+ clipButton.title = 'Copy to clipboard';
+ clipButton.setAttribute('aria-label', clipButton.title);
+ clipButton.innerHTML = '';
+
+ buttons.insertBefore(clipButton, buttons.firstChild);
+ }
+ });
+
+ // Process playpen code blocks
+ Array.from(document.querySelectorAll(".playpen")).forEach(function (pre_block) {
+ // Add play button
+ var buttons = pre_block.querySelector(".buttons");
+ if (!buttons) {
+ buttons = document.createElement('div');
+ buttons.className = 'buttons';
+ pre_block.insertBefore(buttons, pre_block.firstChild);
+ }
+
+ var runCodeButton = document.createElement('button');
+ runCodeButton.className = 'fa fa-play play-button';
+ runCodeButton.hidden = true;
+ runCodeButton.title = 'Run this code';
+ runCodeButton.setAttribute('aria-label', runCodeButton.title);
+
+ var copyCodeClipboardButton = document.createElement('button');
+ copyCodeClipboardButton.className = 'fa fa-copy clip-button';
+ copyCodeClipboardButton.innerHTML = '';
+ copyCodeClipboardButton.title = 'Copy to clipboard';
+ copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title);
+
+ buttons.insertBefore(runCodeButton, buttons.firstChild);
+ buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild);
+
+ runCodeButton.addEventListener('click', function (e) {
+ run_rust_code(pre_block);
+ });
+
+ let code_block = pre_block.querySelector("code");
+ if (window.ace && code_block.classList.contains("editable")) {
+ var undoChangesButton = document.createElement('button');
+ undoChangesButton.className = 'fa fa-history reset-button';
+ undoChangesButton.title = 'Undo changes';
+ undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
+
+ buttons.insertBefore(undoChangesButton, buttons.firstChild);
+
+ undoChangesButton.addEventListener('click', function () {
+ let editor = window.ace.edit(code_block);
+ editor.setValue(editor.originalCode);
+ editor.clearSelection();
+ });
+ }
+ });
+})();
+
+(function themes() {
+ var html = document.querySelector('html');
+ var themeToggleButton = document.getElementById('theme-toggle');
+ var themePopup = document.getElementById('theme-list');
+ var themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
+ var stylesheets = {
+ ayuHighlight: document.querySelector("[href$='ayu-highlight.css']"),
+ tomorrowNight: document.querySelector("[href$='tomorrow-night.css']"),
+ highlight: document.querySelector("[href$='highlight.css']"),
+ };
+
+ function showThemes() {
+ themePopup.style.display = 'block';
+ themeToggleButton.setAttribute('aria-expanded', true);
+ themePopup.querySelector("button#" + document.body.className).focus();
+ }
+
+ function hideThemes() {
+ themePopup.style.display = 'none';
+ themeToggleButton.setAttribute('aria-expanded', false);
+ themeToggleButton.focus();
+ }
+
+ function set_theme(theme) {
+ let ace_theme;
+
+ if (theme == 'coal' || theme == 'navy') {
+ stylesheets.ayuHighlight.disabled = true;
+ stylesheets.tomorrowNight.disabled = false;
+ stylesheets.highlight.disabled = true;
+
+ ace_theme = "ace/theme/tomorrow_night";
+ } else if (theme == 'ayu') {
+ stylesheets.ayuHighlight.disabled = false;
+ stylesheets.tomorrowNight.disabled = true;
+ stylesheets.highlight.disabled = true;
+
+ ace_theme = "ace/theme/tomorrow_night";
+ } else {
+ stylesheets.ayuHighlight.disabled = true;
+ stylesheets.tomorrowNight.disabled = true;
+ stylesheets.highlight.disabled = false;
+
+ ace_theme = "ace/theme/dawn";
+ }
+
+ setTimeout(function () {
+ themeColorMetaTag.content = getComputedStyle(document.body).backgroundColor;
+ }, 1);
+
+ if (window.ace && window.editors) {
+ window.editors.forEach(function (editor) {
+ editor.setTheme(ace_theme);
+ });
+ }
+
+ var previousTheme;
+ try { previousTheme = localStorage.getItem('mdbook-theme'); } catch (e) { }
+ if (previousTheme === null || previousTheme === undefined) { previousTheme = default_theme; }
+
+ try { localStorage.setItem('mdbook-theme', theme); } catch (e) { }
+
+ document.body.className = theme;
+ html.classList.remove(previousTheme);
+ html.classList.add(theme);
+ }
+
+ // Set theme
+ var theme;
+ try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+ if (theme === null || theme === undefined) { theme = default_theme; }
+
+ set_theme(theme);
+
+ themeToggleButton.addEventListener('click', function () {
+ if (themePopup.style.display === 'block') {
+ hideThemes();
+ } else {
+ showThemes();
+ }
+ });
+
+ themePopup.addEventListener('click', function (e) {
+ var theme = e.target.id || e.target.parentElement.id;
+ set_theme(theme);
+ });
+
+ themePopup.addEventListener('focusout', function(e) {
+ // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
+ if (!!e.relatedTarget && !themeToggleButton.contains(e.relatedTarget) && !themePopup.contains(e.relatedTarget)) {
+ hideThemes();
+ }
+ });
+
+ // Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang-nursery/mdBook/issues/628
+ document.addEventListener('click', function(e) {
+ if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) {
+ hideThemes();
+ }
+ });
+
+ document.addEventListener('keydown', function (e) {
+ if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+ if (!themePopup.contains(e.target)) { return; }
+
+ switch (e.key) {
+ case 'Escape':
+ e.preventDefault();
+ hideThemes();
+ break;
+ case 'ArrowUp':
+ e.preventDefault();
+ var li = document.activeElement.parentElement;
+ if (li && li.previousElementSibling) {
+ li.previousElementSibling.querySelector('button').focus();
+ }
+ break;
+ case 'ArrowDown':
+ e.preventDefault();
+ var li = document.activeElement.parentElement;
+ if (li && li.nextElementSibling) {
+ li.nextElementSibling.querySelector('button').focus();
+ }
+ break;
+ case 'Home':
+ e.preventDefault();
+ themePopup.querySelector('li:first-child button').focus();
+ break;
+ case 'End':
+ e.preventDefault();
+ themePopup.querySelector('li:last-child button').focus();
+ break;
+ }
+ });
+})();
+
+(function sidebar() {
+ var html = document.querySelector("html");
+ var sidebar = document.getElementById("sidebar");
+ var sidebarLinks = document.querySelectorAll('#sidebar a');
+ var sidebarToggleButton = document.getElementById("sidebar-toggle");
+ var firstContact = null;
+
+ function showSidebar() {
+ html.classList.remove('sidebar-hidden')
+ html.classList.add('sidebar-visible');
+ Array.from(sidebarLinks).forEach(function (link) {
+ link.setAttribute('tabIndex', 0);
+ });
+ sidebarToggleButton.setAttribute('aria-expanded', true);
+ sidebar.setAttribute('aria-hidden', false);
+ try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
+ }
+
+ function hideSidebar() {
+ html.classList.remove('sidebar-visible')
+ html.classList.add('sidebar-hidden');
+ Array.from(sidebarLinks).forEach(function (link) {
+ link.setAttribute('tabIndex', -1);
+ });
+ sidebarToggleButton.setAttribute('aria-expanded', false);
+ sidebar.setAttribute('aria-hidden', true);
+ try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
+ }
+
+ // Toggle sidebar
+ sidebarToggleButton.addEventListener('click', function sidebarToggle() {
+ if (html.classList.contains("sidebar-hidden")) {
+ showSidebar();
+ } else if (html.classList.contains("sidebar-visible")) {
+ hideSidebar();
+ } else {
+ if (getComputedStyle(sidebar)['transform'] === 'none') {
+ hideSidebar();
+ } else {
+ showSidebar();
+ }
+ }
+ });
+
+ document.addEventListener('touchstart', function (e) {
+ firstContact = {
+ x: e.touches[0].clientX,
+ time: Date.now()
+ };
+ }, { passive: true });
+
+ document.addEventListener('touchmove', function (e) {
+ if (!firstContact)
+ return;
+
+ var curX = e.touches[0].clientX;
+ var xDiff = curX - firstContact.x,
+ tDiff = Date.now() - firstContact.time;
+
+ if (tDiff < 250 && Math.abs(xDiff) >= 150) {
+ if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
+ showSidebar();
+ else if (xDiff < 0 && curX < 300)
+ hideSidebar();
+
+ firstContact = null;
+ }
+ }, { passive: true });
+
+ // Scroll sidebar to current active section
+ var activeSection = sidebar.querySelector(".active");
+ if (activeSection) {
+ sidebar.scrollTop = activeSection.offsetTop;
+ }
+})();
+
+(function chapterNavigation() {
+ document.addEventListener('keydown', function (e) {
+ if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+ if (window.search && window.search.hasFocus()) { return; }
+
+ switch (e.key) {
+ case 'ArrowRight':
+ e.preventDefault();
+ var nextButton = document.querySelector('.nav-chapters.next');
+ if (nextButton) {
+ window.location.href = nextButton.href;
+ }
+ break;
+ case 'ArrowLeft':
+ e.preventDefault();
+ var previousButton = document.querySelector('.nav-chapters.previous');
+ if (previousButton) {
+ window.location.href = previousButton.href;
+ }
+ break;
+ }
+ });
+})();
+
+(function clipboard() {
+ var clipButtons = document.querySelectorAll('.clip-button');
+
+ function hideTooltip(elem) {
+ elem.firstChild.innerText = "";
+ elem.className = 'fa fa-copy clip-button';
+ }
+
+ function showTooltip(elem, msg) {
+ elem.firstChild.innerText = msg;
+ elem.className = 'fa fa-copy tooltipped';
+ }
+
+ var clipboardSnippets = new Clipboard('.clip-button', {
+ text: function (trigger) {
+ hideTooltip(trigger);
+ let playpen = trigger.closest("pre");
+ return playpen_text(playpen);
+ }
+ });
+
+ Array.from(clipButtons).forEach(function (clipButton) {
+ clipButton.addEventListener('mouseout', function (e) {
+ hideTooltip(e.currentTarget);
+ });
+ });
+
+ clipboardSnippets.on('success', function (e) {
+ e.clearSelection();
+ showTooltip(e.trigger, "Copied!");
+ });
+
+ clipboardSnippets.on('error', function (e) {
+ showTooltip(e.trigger, "Clipboard error!");
+ });
+})();
+
+(function scrollToTop () {
+ var menuTitle = document.querySelector('.menu-title');
+
+ menuTitle.addEventListener('click', function () {
+ document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
+ });
+})();
+
+(function autoHideMenu() {
+ var menu = document.getElementById('menu-bar');
+
+ var previousScrollTop = document.scrollingElement.scrollTop;
+
+ document.addEventListener('scroll', function () {
+ if (menu.classList.contains('folded') && document.scrollingElement.scrollTop < previousScrollTop) {
+ menu.classList.remove('folded');
+ } else if (!menu.classList.contains('folded') && document.scrollingElement.scrollTop > previousScrollTop) {
+ menu.classList.add('folded');
+ }
+
+ if (!menu.classList.contains('bordered') && document.scrollingElement.scrollTop > 0) {
+ menu.classList.add('bordered');
+ }
+
+ if (menu.classList.contains('bordered') && document.scrollingElement.scrollTop === 0) {
+ menu.classList.remove('bordered');
+ }
+
+ previousScrollTop = document.scrollingElement.scrollTop;
+ }, { passive: true });
+})();
diff --git a/docs/public/tutorials/clipboard.min.js b/docs/public/tutorials/clipboard.min.js
new file mode 100644
index 000000000..1993676f9
--- /dev/null
+++ b/docs/public/tutorials/clipboard.min.js
@@ -0,0 +1,7 @@
+/*!
+ * clipboard.js v1.6.1
+ * https://zenorocha.github.io/clipboard.js
+ *
+ * Licensed MIT © Zeno Rocha
+ */
+!function(e){if("object"==typeof exports&&"undefined"!=typeof module)module.exports=e();else if("function"==typeof define&&define.amd)define([],e);else{var t;t="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof self?self:this,t.Clipboard=e()}}(function(){var e,t,n;return function e(t,n,o){function i(a,c){if(!n[a]){if(!t[a]){var l="function"==typeof require&&require;if(!c&&l)return l(a,!0);if(r)return r(a,!0);var u=new Error("Cannot find module '"+a+"'");throw u.code="MODULE_NOT_FOUND",u}var s=n[a]={exports:{}};t[a][0].call(s.exports,function(e){var n=t[a][1][e];return i(n?n:e)},s,s.exports,e,t,n,o)}return n[a].exports}for(var r="function"==typeof require&&require,a=0;a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ FlaggedStorage and modification events
+In most games you will have many entities, but from frame to frame there will +usually be components that will only need to updated when something related is +modified.
+To avoid a lot of unnecessary computation when updating components it +would be nice if we could somehow check for only those entities that are updated +and recalculate only those.
+We might also need to keep an external resource in sync with changes
+to components in Specs World, and we only want to propagate actual changes, not
+do a full sync every frame.
This is where FlaggedStorage comes into play. By wrapping a component's
+actual storage in a FlaggedStorage, we can subscribe to modification events, and
+easily populate bitsets with only the entities that have actually changed.
Let's look at some code:
+pub struct Data {
+ [..]
+}
+
+impl Component for Data {
+ type Storage = FlaggedStorage<Self, DenseVecStorage<Self>>;
+}
+
+#[derive(Default)]
+pub struct Sys {
+ pub dirty: BitSet,
+ pub reader_id: Option<ReaderId<ComponentEvent>>,
+}
+
+impl<'a> System<'a> for Sys {
+ type SystemData = (
+ ReadStorage<'a, Data>,
+ WriteStorage<'a, SomeOtherData>,
+ );
+
+ fn run(&mut self, (data, mut some_other_data): Self::SystemData) {
+ self.dirty.clear();
+
+ let events = data.channel().read(self.reader_id.as_mut().unwrap());
+
+ // Note that we could use separate bitsets here, we only use one to
+ // simplify the example
+ for event in events {
+ match event {
+ ComponentEvent::Modified(id) | ComponentEvent::Inserted(id) => {
+ self.dirty.add(*id);
+ }
+ // We don't need to take this event into account since
+ // removed components will be filtered out by the join;
+ // if you want to, you can use `self.dirty.remove(*id);`
+ // so the bit set only contains IDs that still exist
+ ComponentEvent::Removed(_) => (),
+ }
+ }
+
+ for (d, other, _) in (&data, &mut some_other_data, &self.dirty).join() {
+ // Mutate `other` based on the update data in `d`
+ }
+ }
+
+ fn setup(&mut self, res: &mut Resources) {
+ Self::SystemData::setup(res);
+ self.reader_id = Some(WriteStorage::<Data>::fetch(&res).register_reader());
+ }
+}
+There are three different event types that we can receive:
+-
+
ComponentEvent::Inserted- will be sent when a component is added to the +storage
+ComponentEvent::Modified- will be sent when a component is fetched mutably +from the storage
+ComponentEvent::Removed- will be sent when a component is removed from the +storage
+
Note that because of how ComponentEvent works, if you iterate mutably over a
+component storage using Join, all entities that are fetched by the Join will
+be flagged as modified even if nothing was updated in them.
":I.tabReplace?n.replace(/\t/g,I.tabReplace):""}):e}function h(e,n,t){var r=n?L[n]:t,a=[e.trim()];return e.match(/\bhljs\b/)||a.push("hljs"),-1===e.indexOf(r)&&a.push(r),a.join(" ").trim()}function d(e){var n,t,r,o,l,s=i(e);a(s)||(I.useBR?(n=document.createElementNS("http://www.w3.org/1999/xhtml","div"),n.innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/mark.min.js b/docs/public/tutorials/mark.min.js
new file mode 100644
index 000000000..163623188
--- /dev/null
+++ b/docs/public/tutorials/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction
+Welcome to The Specs Book, an introduction to ECS and the Specs API. +This book is targeted at beginners; guiding you through all the difficulties of +setting up, building, and structuring a game with an ECS.
+Specs is an ECS library that allows parallel system execution, with both low +overhead and high flexibility, different storage types and a type-level +system data model. It is mainly used for games and simulations, where it allows +to structure code using composition over inheritance.
+Additional documentation is available on docs.rs:
There also is a reference-style documentation available here:
+ +You don't yet know what an ECS is all about? The next section +is for you! In case you already know what an ECS is, just skip it.
+What's an ECS?
+The term ECS is a shorthand for Entity-component system. These are the three
+core concepts. Each entity is associated with some components. Those entities and
+components are processed by systems. This way, you have your data (components)
+completely separated from the behaviour (systems). An entity just logically
+groups components; so a Velocity component can be applied to the Position component
+of the same entity.
ECS is sometimes seen as a counterpart to Object-Oriented Programming. I wouldn't +say that's one hundred percent true, but let me give you some comparisons.
+In OOP, your player might look like this (I've used Java for the example):
+public class Player extends Character {
+ private final Transform transform;
+ private final Inventory inventory;
+}
+There are several limitations here:
+-
+
- There is either no multiple inheritance or it brings other problems with it, +like the diamond problem; moreover, you have to think about "is the player +a collider or does it have a collider?" +
- You cannot easily extend the player with modding; all the attributes are hardcoded. +
- Imagine you want to add a NPC, which looks like this: +
public class Npc extends Character {
+ private final Transform transform;
+ private final Inventory inventory;
+ private final boolean isFriendly;
+}
+Now you have stuff duplicated; you would have to write mostly identical code for +your player and the NPC, even though e.g. they both share a transform.
+
This is where ECS comes into play: Components are associated with entities; you can just insert components, whenever you like.
+One entity may or may not have a certain component. You can see an Entity as an ID into component tables, as illustrated in the
+diagram below. We could theoretically store all the components together with the entity, but that would be very inefficient;
+you'll see how these tables work in chapter 5.
This is how an Entity is implemented; it's just
struct Entity(u32, Generation);
+where the first field is the id and the second one is the generation, used to check +if the entity has been deleted.
+Here's another illustration of the relationship between components and entities. Force, Mass and Velocity are all components here.
Entity 1 has each of those components, Entity 2 only a Force, etc.
Now we're only missing the last character in ECS - the "S" for System. Whereas components and entities are purely data,
+systems contain all the logic of your application. A system typically iterates over all entities that fulfill specific constraints,
+like "has both a force and a mass". Based on this data a system will execute code, e.g. produce a velocity out of the force and the mass.
+This is the additional advantage I wanted to point out with the Player / Npc example; in an ECS, you can simply add new attributes
+to entities and that's also how you define behaviour in Specs (this is called data-driven programming).
By simply adding a force to an entity that has a mass, you can make it move, because a Velocity will be produced for it.
Where to use an ECS?
+In case you were looking for a general-purpose library for doing things the data-oriented way, I have to disappoint you; there are none. +ECS libraries are best-suited for creating games or simulations, but they do not magically make your code more data-oriented.
++
Okay, now that you were given a rough overview, let's continue +to Chapter 2 where we'll build our first actual application with Specs.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/public/tutorials/searcher.js b/docs/public/tutorials/searcher.js
new file mode 100644
index 000000000..7fd97d487
--- /dev/null
+++ b/docs/public/tutorials/searcher.js
@@ -0,0 +1,477 @@
+"use strict";
+window.search = window.search || {};
+(function search(search) {
+ // Search functionality
+ //
+ // You can use !hasFocus() to prevent keyhandling in your key
+ // event handlers while the user is typing their search.
+
+ if (!Mark || !elasticlunr) {
+ return;
+ }
+
+ //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+ if (!String.prototype.startsWith) {
+ String.prototype.startsWith = function(search, pos) {
+ return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
+ };
+ }
+
+ var search_wrap = document.getElementById('search-wrapper'),
+ searchbar = document.getElementById('searchbar'),
+ searchbar_outer = document.getElementById('searchbar-outer'),
+ searchresults = document.getElementById('searchresults'),
+ searchresults_outer = document.getElementById('searchresults-outer'),
+ searchresults_header = document.getElementById('searchresults-header'),
+ searchicon = document.getElementById('search-toggle'),
+ content = document.getElementById('content'),
+
+ searchindex = null,
+ doc_urls = [],
+ results_options = {
+ teaser_word_count: 30,
+ limit_results: 30,
+ },
+ search_options = {
+ bool: "AND",
+ expand: true,
+ fields: {
+ title: {boost: 1},
+ body: {boost: 1},
+ breadcrumbs: {boost: 0}
+ }
+ },
+ mark_exclude = [],
+ marker = new Mark(content),
+ current_searchterm = "",
+ URL_SEARCH_PARAM = 'search',
+ URL_MARK_PARAM = 'highlight',
+ teaser_count = 0,
+
+ SEARCH_HOTKEY_KEYCODE = 83,
+ ESCAPE_KEYCODE = 27,
+ DOWN_KEYCODE = 40,
+ UP_KEYCODE = 38,
+ SELECT_KEYCODE = 13;
+
+ function hasFocus() {
+ return searchbar === document.activeElement;
+ }
+
+ function removeChildren(elem) {
+ while (elem.firstChild) {
+ elem.removeChild(elem.firstChild);
+ }
+ }
+
+ // Helper to parse a url into its building blocks.
+ function parseURL(url) {
+ var a = document.createElement('a');
+ a.href = url;
+ return {
+ source: url,
+ protocol: a.protocol.replace(':',''),
+ host: a.hostname,
+ port: a.port,
+ params: (function(){
+ var ret = {};
+ var seg = a.search.replace(/^\?/,'').split('&');
+ var len = seg.length, i = 0, s;
+ for (;i
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Hello,
+The
+
+When to use a
+
+
+
+
+
+
+
+
+
+
+Specifying
+The
+Custom
+
+
+
+
+
+
+
+ Introduction
+Welcome to The Specs Book, an introduction to ECS and the Specs API. +This book is targeted at beginners; guiding you through all the difficulties of +setting up, building, and structuring a game with an ECS.
+Specs is an ECS library that allows parallel system execution, with both low +overhead and high flexibility, different storage types and a type-level +system data model. It is mainly used for games and simulations, where it allows +to structure code using composition over inheritance.
+Additional documentation is available on docs.rs:
There also is a reference-style documentation available here:
+ +You don't yet know what an ECS is all about? The next section +is for you! In case you already know what an ECS is, just skip it.
+What's an ECS?
+The term ECS is a shorthand for Entity-component system. These are the three
+core concepts. Each entity is associated with some components. Those entities and
+components are processed by systems. This way, you have your data (components)
+completely separated from the behaviour (systems). An entity just logically
+groups components; so a Velocity component can be applied to the Position component
+of the same entity.
ECS is sometimes seen as a counterpart to Object-Oriented Programming. I wouldn't +say that's one hundred percent true, but let me give you some comparisons.
+In OOP, your player might look like this (I've used Java for the example):
+public class Player extends Character {
+ private final Transform transform;
+ private final Inventory inventory;
+}
+There are several limitations here:
+-
+
- There is either no multiple inheritance or it brings other problems with it, +like the diamond problem; moreover, you have to think about "is the player +a collider or does it have a collider?" +
- You cannot easily extend the player with modding; all the attributes are hardcoded. +
- Imagine you want to add a NPC, which looks like this: +
public class Npc extends Character {
+ private final Transform transform;
+ private final Inventory inventory;
+ private final boolean isFriendly;
+}
+Now you have stuff duplicated; you would have to write mostly identical code for +your player and the NPC, even though e.g. they both share a transform.
+
This is where ECS comes into play: Components are associated with entities; you can just insert components, whenever you like.
+One entity may or may not have a certain component. You can see an Entity as an ID into component tables, as illustrated in the
+diagram below. We could theoretically store all the components together with the entity, but that would be very inefficient;
+you'll see how these tables work in chapter 5.
This is how an Entity is implemented; it's just
struct Entity(u32, Generation);
+where the first field is the id and the second one is the generation, used to check +if the entity has been deleted.
+Here's another illustration of the relationship between components and entities. Force, Mass and Velocity are all components here.
Entity 1 has each of those components, Entity 2 only a Force, etc.
Now we're only missing the last character in ECS - the "S" for System. Whereas components and entities are purely data,
+systems contain all the logic of your application. A system typically iterates over all entities that fulfill specific constraints,
+like "has both a force and a mass". Based on this data a system will execute code, e.g. produce a velocity out of the force and the mass.
+This is the additional advantage I wanted to point out with the Player / Npc example; in an ECS, you can simply add new attributes
+to entities and that's also how you define behaviour in Specs (this is called data-driven programming).
By simply adding a force to an entity that has a mass, you can make it move, because a Velocity will be produced for it.
Where to use an ECS?
+In case you were looking for a general-purpose library for doing things the data-oriented way, I have to disappoint you; there are none. +ECS libraries are best-suited for creating games or simulations, but they do not magically make your code more data-oriented.
++
Okay, now that you were given a rough overview, let's continue +to Chapter 2 where we'll build our first actual application with Specs.
+Hello, World!
+Setting up
+First of all, thanks for trying out specs. Let's
+set it up first. Add the following line to your Cargo.toml:
[dependencies]
+specs = "0.14.0"
+And add this to your crate root (main.rs or lib.rs):
extern crate specs;
+Components
+Let's start by creating some data:
+use specs::{Component, VecStorage};
+
+#[derive(Debug)]
+struct Position {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Position {
+ type Storage = VecStorage<Self>;
+}
+
+#[derive(Debug)]
+struct Velocity {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Velocity {
+ type Storage = VecStorage<Self>;
+}
+These will be our two component types. Optionally, the specs-derive crate
+provides a convenient custom #[derive] you can use to define component types
+more succinctly.
But first, you will need to add specs-derive to your crate
+[dependencies]
+specs = "0.14.0"
+specs-derive = "0.4.0"
+Now you can use this:
+extern crate specs;
+#[macro_use]
+extern crate specs_derive;
+
+use specs::{Component, VecStorage};
+
+#[derive(Component, Debug)]
+#[storage(VecStorage)]
+struct Position {
+ x: f32,
+ y: f32,
+}
+
+#[derive(Component, Debug)]
+#[storage(VecStorage)]
+struct Velocity {
+ x: f32,
+ y: f32,
+}
+If the #[storage(...)] attribute is omitted, the given component will be
+stored in a DenseVecStorage by default. But for this example, we are
+explicitly asking for these components to be kept in a VecStorage instead (see
+the later storages chapter for more details). But before we move on, we
+need to create a world in which to store all of our components.
The World
+use specs::{World, Builder};
+
+let mut world = World::new();
+world.register::<Position>();
+world.register::<Velocity>();
+This will create component storages for Positions and Velocitys.
let ball = world.create_entity().with(Position { x: 4.0, y: 7.0 }).build();
+Now you have an Entity, associated with a position.
So far this is pretty boring. We just have some data, +but we don't do anything with it. Let's change that!
+The system
+use specs::System;
+
+struct HelloWorld;
+
+impl<'a> System<'a> for HelloWorld {
+ type SystemData = ();
+
+ fn run(&mut self, data: Self::SystemData) {}
+}
+This is what a system looks like. Though it doesn't do anything (yet).
+Let's talk about this dummy implementation first.
+The SystemData is an associated type
+which specifies which components we need in order to run
+the system.
Let's see how we can read our Position components:
use specs::{ReadStorage, System};
+
+struct HelloWorld;
+
+impl<'a> System<'a> for HelloWorld {
+ type SystemData = ReadStorage<'a, Position>;
+
+ fn run(&mut self, position: Self::SystemData) {
+ use specs::Join;
+
+ for position in position.join() {
+ println!("Hello, {:?}", &position);
+ }
+ }
+}
+Note that all components that a system accesses must be registered with
+world.register::<Component>() before that system is run, or you will get a
+panic. This will usually be done automatically during setup, but we'll
+come back to that in a later chapter.
++There are many other types you can use as system data. Please see the +System Data Chapter for more information.
+
Running the system
+This just iterates through all the components and prints
+them. To execute the system, you can use RunNow like this:
use specs::RunNow;
+
+let mut hello_world = HelloWorld;
+hello_world.run_now(&world.res);
+world.maintain();
+The world.maintain() is not completely necessary here. Calling maintain should be done in general, however.
+If entities are created or deleted while a system is running, calling maintain
+will record the changes in its internal data structure.
Full example code
+Here the complete example of this chapter:
+use specs::{Builder, Component, ReadStorage, System, VecStorage, World, RunNow};
+
+#[derive(Debug)]
+struct Position {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Position {
+ type Storage = VecStorage<Self>;
+}
+
+#[derive(Debug)]
+struct Velocity {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Velocity {
+ type Storage = VecStorage<Self>;
+}
+
+struct HelloWorld;
+
+impl<'a> System<'a> for HelloWorld {
+ type SystemData = ReadStorage<'a, Position>;
+
+ fn run(&mut self, position: Self::SystemData) {
+ use specs::Join;
+
+ for position in position.join() {
+ println!("Hello, {:?}", &position);
+ }
+ }
+}
+
+fn main() {
+ let mut world = World::new();
+ world.register::<Position>();
+ world.register::<Velocity>();
+
+ world.create_entity().with(Position { x: 4.0, y: 7.0 }).build();
+
+ let mut hello_world = HelloWorld;
+ hello_world.run_now(&world.res);
+ world.maintain();
+}
++
This was a pretty basic example so far. A key feature we haven't seen is the
+Dispatcher, which allows us to configure systems to run in parallel (and it offers
+some other nice features, too).
Let's see how that works in Chapter 3: Dispatcher.
+Dispatcher
+When to use a Dispatcher
+The Dispatcher allows you to automatically parallelize
+system execution where possible, using the fork-join model to split up the
+work and merge the result at the end. It requires a bit more planning
+and may have a little bit more overhead, but it's pretty convenient,
+especially when you're building a big game where you don't
+want to do this manually.
Building a dispatcher
+First of all, we have to build such a dispatcher.
+use specs::DispatcherBuilder;
+
+let mut dispatcher = DispatcherBuilder::new()
+ .with(HelloWorld, "hello_world", &[])
+ .build();
+Let's see what this does. After creating the builder, +we add a new
+-
+
- system object (
HelloWorld)
+ - with some name (
"hello_world"")
+ - and no dependencies (
&[]).
+
The name can be used to specify that system +as a dependency of another one. But we don't have a second +system yet.
+Creating another system
+struct UpdatePos;
+
+impl<'a> System<'a> for UpdatePos {
+ type SystemData = (ReadStorage<'a, Velocity>,
+ WriteStorage<'a, Position>);
+}
+Let's talk about the system data first. What you see here is a tuple, which we are using as our SystemData.
+In fact, SystemData is implemented for all tuples with up to 26 other types implementing SystemData in it.
++Notice that
+ReadStorageandWriteStorageare implementors ofSystemData+themselves, that's why we could use the first one for ourHelloWorldsystem +without wrapping it in a tuple; for more information see +the Chapter about system data.
To complete the implementation block, here's the run method:
fn run(&mut self, (vel, mut pos): Self::SystemData) {
+ use specs::Join;
+ for (vel, pos) in (&vel, &mut pos).join() {
+ pos.x += vel.x * 0.05;
+ pos.y += vel.y * 0.05;
+ }
+ }
+Now the .join() method also makes sense: it joins the two component
+storages, so that you either get no new element or a new element with
+both components, meaning that entities with only a Position, only
+a Velocity or none of them will be skipped. The 0.05 fakes the
+so called delta time which is the time needed for one frame.
+We have to hardcode it right now, because it's not a component (it's the
+same for every entity). The solution to this are Resources, see
+the next Chapter.
Adding a system with a dependency
+Okay, we'll add two more systems after the HelloWorld system:
.with(UpdatePos, "update_pos", &["hello_world"])
+ .with(HelloWorld, "hello_updated", &["update_pos"])
+The UpdatePos system now depends on the HelloWorld system and will only
+be executed after the dependency has finished. The final HelloWorld system prints the resulting updated positions.
Now to execute all the systems, just do
+dispatcher.dispatch(&mut world.res);
+Full example code
+Here the code for this chapter:
+use specs::{Builder, Component, DispatcherBuilder, ReadStorage,
+ System, VecStorage, World, WriteStorage};
+
+#[derive(Debug)]
+struct Position {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Position {
+ type Storage = VecStorage<Self>;
+}
+
+#[derive(Debug)]
+struct Velocity {
+ x: f32,
+ y: f32,
+}
+
+impl Component for Velocity {
+ type Storage = VecStorage<Self>;
+}
+
+struct HelloWorld;
+
+impl<'a> System<'a> for HelloWorld {
+ type SystemData = ReadStorage<'a, Position>;
+
+ fn run(&mut self, position: Self::SystemData) {
+ use specs::Join;
+
+ for position in position.join() {
+ println!("Hello, {:?}", &position);
+ }
+ }
+}
+
+struct UpdatePos;
+
+impl<'a> System<'a> for UpdatePos {
+ type SystemData = (ReadStorage<'a, Velocity>,
+ WriteStorage<'a, Position>);
+
+ fn run(&mut self, (vel, mut pos): Self::SystemData) {
+ use specs::Join;
+ for (vel, pos) in (&vel, &mut pos).join() {
+ pos.x += vel.x * 0.05;
+ pos.y += vel.y * 0.05;
+ }
+ }
+}
+
+fn main() {
+ let mut world = World::new();
+ world.register::<Position>();
+ world.register::<Velocity>();
+
+ // Only the second entity will get a position update,
+ // because the first one does not have a velocity.
+ world.create_entity().with(Position { x: 4.0, y: 7.0 }).build();
+ world
+ .create_entity()
+ .with(Position { x: 2.0, y: 5.0 })
+ .with(Velocity { x: 0.1, y: 0.2 })
+ .build();
+
+ let mut dispatcher = DispatcherBuilder::new()
+ .with(HelloWorld, "hello_world", &[])
+ .with(UpdatePos, "update_pos", &["hello_world"])
+ .with(HelloWorld, "hello_updated", &["update_pos"])
+ .build();
+
+ dispatcher.dispatch(&mut world.res);
+ world.maintain();
+}
++
The next chapter will be a really short chapter about Resources,
+a way to share data between systems which only exist independent of
+entities (as opposed to 0..1 times per entity).
Resources
+This (short) chapter will explain the concept of resources, data +which is shared between systems.
+First of all, when would you need resources? There's actually a great +example in chapter 3, where we just faked the delta time when applying +the velocity. Let's see how we can do this the right way.
+#[derive(Default)]
+struct DeltaTime(f32);
+++Note: In practice you may want to use
+std::time::Durationinstead, +because you shouldn't usef32s for durations in an actual game, because +they're not precise enough.
Adding this resource to our world is pretty easy:
+world.add_resource(DeltaTime(0.05)); // Let's use some start value
+To update the delta time, just use
+let mut delta = world.write_resource::<DeltaTime>();
+*delta = DeltaTime(0.04);
+Accessing resources from a system
+As you might have guessed, there's a type implementing system data
+specifically for resources. It's called Read (or Write for
+write access).
So we can now rewrite our system:
+use specs::{Read, ReadStorage, System, WriteStorage};
+
+struct UpdatePos;
+
+impl<'a> System<'a> for UpdatePos {
+ type SystemData = (Read<'a, DeltaTime>,
+ ReadStorage<'a, Velocity>,
+ WriteStorage<'a, Position>);
+
+ fn run(&mut self, data: Self::SystemData) {
+ let (delta, vel, mut pos) = data;
+
+ // `Read` implements `Deref`, so it
+ // coerces to `&DeltaTime`.
+ let delta = delta.0;
+
+ for (vel, pos) in (&vel, &mut pos).join() {
+ pos.x += vel.x * delta;
+ pos.y += vel.y * delta;
+ }
+ }
+}
+Note that all resources that a system accesses must be registered with
+world.add_resource(resource) before that system is run, or you will get a
+panic. If the resource has a Default implementation, this step is usually
+done during setup, but again we will come back to this in a later chapter.
For more information on SystemData, see the system data chapter.
Default for resources
+As we have learned in previous chapters, to fetch a Resource in our
+SystemData, we use Read or Write. However, there is one issue we
+have not mentioned yet, and that is the fact that Read and Write require
+Default to be implemented on the resource. This is because Specs will
+automatically try to add a Default version of a resource to the World
+during setup (we will come back to the setup stage in the next chapter).
+But how do we handle the case when we can't implement Default for our resource?
There are actually three ways of doing this:
+-
+
- Using a custom
SetupHandlerimplementation, you can provide this inSystemData+withRead<'a, Resource, TheSetupHandlerType>.
+ - By replacing
ReadandWritewithReadExpectandWriteExpect, which will +cause the first dispatch of theSystemto panic unless the resource has been +added manually toWorldfirst.
+ - By using
Option<Read<'a, Resource>>, if the resource really is optional. Note +that the order here is important, usingRead<'a, Option<Resource>>will not +result in the same behavior (it will try to fetchOption<Resource>fromWorld, +instead of doing an optional check ifResourceexists).
+
+
In the next chapter, you will learn about the different storages +and when to use which one.
+Storages
+Specs contains a bunch of different storages, all built and optimized for +different use cases. But let's see some basics first.
+Storage basics
+What you specify in a component impl-block is an UnprotectedStorage.
+Each UnprotectedStorage exposes an unsafe getter which does not
+perform any checks whether the requested index for the component is valid
+(the id of an entity is the index of its component). To allow checking them
+and speeding up iteration, we have something called hierarchical bitsets,
+provided by hibitset.
++Note: In case you don't know anything about bitsets, +you can safely skip the following section about it. Just keep +in mind that we have some mask which tracks for +which entities a component exists.
+
How does it speed up the iteration? A hierarchical bitset is essentially
+a multi-layer bitset, where each upper layer "summarizes" multiple bits
+of the underlying layers. That means as soon as one of the underlying
+bits is 1, the upper one also becomes 1, so that we can skip a whole
+range of indices if an upper bit is 0 in that section. In case it's 1,
+we go down by one layer and perform the same steps again (it currently
+has 4 layers).
Storage overview
+Here a list of the storages with a short description and a link +to the corresponding heading.
+| Storage Type | Description | Optimized for |
|---|---|---|
BTreeStorage | Works with a BTreeMap | no particular case |
DenseVecStorage | Uses a redirection table | fairly often used components |
HashMapStorage | Uses a HashMap | rare components |
NullStorage | Can flag entities | doesn't depend on rarity |
VecStorage | Uses a sparse Vec | commonly used components |
BTreeStorage
+It works using a BTreeMap and it's meant to be the default storage
+in case you're not sure which one to pick, because it fits all scenarios
+fairly well.
DenseVecStorage
+This storage uses two Vecs, one containing the actual data and the other
+one which provides a mapping from the entity id to the index for the data vec
+(it's a redirection table). This is useful when your component is bigger
+than a usize because it consumes less RAM.
HashMapStorage
+This should be used for components which are associated with very few entities, +because it provides a lower insertion cost and is packed together more tightly. +You should not use it for frequently used components, because the hashing cost would definitely +be noticeable.
+NullStorage
+As already described in the overview, the NullStorage does itself
+only contain a user-defined ZST (=Zero Sized Type; a struct with no data in it,
+like struct Synced;).
+Because it's wrapped in a so-called MaskedStorage, insertions and deletions
+modify the mask, so it can be used for flagging entities (like in this example
+for marking an entity as Synced, which could be used to only synchronize
+some of the entities over the network).
VecStorage
+This one has only one vector (as opposed to the DenseVecStorage). It
+just leaves uninitialized gaps where we don't have any component.
+Therefore it would be a waste of memory to use this storage for
+rare components, but it's best suited for commonly used components
+(like transform values).
System Data
+Every system can request data which it needs to run. This data can be specified
+using the System::SystemData type. Typical implementors of the SystemData trait
+are ReadStorage, WriteStorage, Read, Write, ReadExpect, WriteExpect and Entities.
+A tuple of types implementing SystemData automatically also implements SystemData.
+This means you can specify your System::SystemData as follows:
++# #![allow(unused_variables)] +#fn main() { +struct Sys; + +impl<'a> System<'a> for Sys { + type SystemData = (WriteStorage<'a, Pos>, ReadStorage<'a, Vel>); + + fn run(&mut self, (pos, vel): Self::SystemData) { + /* ... */ + } +} +#}
It is very important that you don't request both a ReadStorage and a WriteStorage
+for the same component or a Read and a Write for the same resource.
+This is just like the borrowing rules of Rust, where you can't borrow something
+mutably and immutably at the same time. In Specs, we have to check this at
+runtime, thus you'll get a panic if you don't follow this rule.
Accessing Entities
+You want to create/delete entities from a system? There is
+good news for you. You can use Entities to do that.
+It implements SystemData so just put it in your SystemData tuple.
++Don't confuse
+specs::Entitieswithspecs::EntitiesRes. +While the latter one is the actual resource, the former one is a type +definition forRead<Entities>.
Please note that you may never write to these Entities, so only
+use Read. Even though it's immutable, you can atomically create
+and delete entities with it. Just use the .create() and .delete()
+methods, respectively. After dynamic entity deletion,
+a call to World::maintain is necessary in order to make the changes
+persistent and delete associated components.
Adding and removing components
+Adding or removing components can be done by modifying
+either the component storage directly with a WriteStorage
+or lazily using the LazyUpdate resource.
use specs::{Component, Read, LazyUpdate, NullStorage, System, Entities, WriteStorage};
+
+struct Stone;
+impl Component for Stone {
+ type Storage = NullStorage<Self>;
+}
+
+struct StoneCreator;
+impl<'a> System<'a> for StoneCreator {
+ type SystemData = (
+ Entities<'a>,
+ WriteStorage<'a, Stone>,
+ Read<'a, LazyUpdate>,
+ );
+
+ fn run(&mut self, (entities, mut stones, updater): Self::SystemData) {
+ let stone = entities.create();
+
+ // 1) Either we insert the component by writing to its storage
+ stones.insert(stone, Stone);
+
+ // 2) or we can lazily insert it with `LazyUpdate`
+ updater.insert(stone, Stone);
+ }
+}
+++Note: After using
+LazyUpdatea call toWorld::maintain+is necessary to actually execute the changes.
SetupHandler / Default for resources
+Please refer to the resources chapter for automatic creation of resources.
+Specifying SystemData
+As mentioned earlier, SystemData is implemented for tuples up to 26 elements. Should you ever need
+more, you could even nest these tuples. However, at some point it becomes hard to keep track of all the elements.
+That's why you can also create your own SystemData bundle using a struct:
extern crate shred;
+#[macro_use]
+extern crate shred_derive;
+extern crate specs;
+
+use specs::prelude::*;
+
+#[derive(SystemData)]
+pub struct MySystemData<'a> {
+ positions: ReadStorage<'a, Position>,
+ velocities: ReadStorage<'a, Velocity>,
+ forces: ReadStorage<'a, Force>,
+
+ delta: Read<'a, DeltaTime>,
+ game_state: Write<'a, GameState>,
+}
+The setup stage
+So far for all our component storages and resources, we've been adding
+them to the World manually. In Specs, this is not required if you use
+setup. This is a manually invoked stage that goes through SystemData
+and calls register, add_resource, etc. for all (with some exceptions)
+components and resources found. The setup function can be found in
+the following locations:
-
+
ReadStorage,WriteStorage,Read,Write
+SystemData
+System
+RunNow
+Dispatcher
+ParSeq
+
During setup, all components encountered will be registered, and all
+resources that have a Default implementation or a custom SetupHandler
+will be added. Note that resources encountered in ReadExpect and WriteExpect
+will not be added to the World automatically.
The recommended way to use setup is to run it on Dispatcher or ParSeq
+after the system graph is built, but before the first dispatch. This will go
+through all Systems in the graph, and call setup on each.
Let's say you began by registering Components and Resources first:
+
+struct Gravity;
+
+struct Velocity;
+
+impl Component for Position {
+ type Storage = VecStorage<Self>;
+}
+
+struct SimulationSystem;
+
+impl<'a> System<'a> for SimulationSystem {
+ type SystemData = (Read<'a, Gravity>, WriteStorage<'a, Velocity>);
+
+ fn run(_, _) {}
+}
+
+fn main() {
+ let mut world = World::new();
+ world.add_resource(Gravity);
+ world.register::<Velocity>();
+
+ for _ in 0..5 {
+ world.create_entity().with(Velocity).build();
+ }
+
+ let mut dispatcher = DispatcherBuilder::new()
+ .with(SimulationSystem, "simulation", &[])
+ .build();
+
+ dispatcher.dispatch(&mut world.res);
+ world.maintain();
+}
+
+You could get rid of that phase by calling setup() and re-ordering your main function:
fn main() {
+ let mut world = World::new();
+ let mut dispatcher = DispatcherBuilder::new()
+ .with(SimulationSystem, "simulation", &[])
+ .build();
+
+ dispatcher.setup(&mut world.res);
+
+ for _ in 0..5 {
+ world.create_entity().with(Velocity).build();
+ }
+
+ dispatcher.dispatch(&mut world.res);
+ world.maintain();
+}
+
+Custom setup functionality
+The good qualities of setup don't end here however. We can also use setup
+to create our non-Default resources, and also to initialize our Systems!
+We do this by custom implementing the setup function in our System.
Let's say we have a System that process events, using shrev::EventChannel:
struct Sys {
+ reader: ReaderId<Event>,
+}
+
+impl<'a> System<'a> for Sys {
+ type SystemData = Read<'a, EventChannel<Event>>;
+
+ fn run(&mut self, events: Self::SystemData) {
+ for event in events.read(&mut self.reader) {
+ [..]
+ }
+ }
+}
+This looks pretty OK, but there is a problem here if we want to use setup.
+The issue is that Sys needs a ReaderId on creation, but to get a ReaderId,
+we need EventChannel<Event> to be initialized. This means the user of Sys need
+to create the EventChannel themselves and add it manually to the World.
+We can do better!
use specs::prelude::Resources;
+
+#[derive(Default)]
+struct Sys {
+ reader: Option<ReaderId<Event>>,
+}
+
+impl<'a> System<'a> for Sys {
+ type SystemData = Read<'a, EventChannel<Event>>;
+
+ fn run(&mut self, events: Self::SystemData) {
+ for event in events.read(&mut self.reader.as_mut().unwrap()) {
+ [..]
+ }
+ }
+
+ fn setup(&mut self, res: &mut Resources) {
+ use specs::prelude::SystemData;
+ Self::SystemData::setup(res);
+ self.reader = Some(res.fetch_mut::<EventChannel<Event>>().register_reader());
+ }
+}
+This is much better; we can now use setup to fully initialize Sys without
+requiring our users to create and add resources manually to World!
If we override the setup function on a System, it is vitally important that we
+remember to add Self::SystemData::setup(res);, or setup will not be performed for
+the Systems SystemData. This could cause panics during setup or during
+the first dispatch.
Setting up in bulk
+In the case of libraries making use of specs, it is sometimes helpful to provide
+a way to add many things at once.
+It's generally recommended to provide a standalone function to register multiple
+Components/Resources at once, while allowing the user to add individual systems
+by themselves.
fn add_physics_engine(world: &mut World, config: LibraryConfig) -> Result<(), LibraryError> {
+ world.register::<Velocity>();
+ // etc
+}
+Joining components
+In the last chapter, we learned how to access resources using SystemData.
+To access our components with it, we can just request a ReadStorage and use
+Storage::get to retrieve the component associated to an entity. This works quite
+well if you want to access a single component, but what if you want to
+iterate over many components? Maybe some of them are required, others might
+be optional and maybe there is even a need to exclude some components?
+If we wanted to do that using only Storage::get, the code would become very ugly.
+So instead we worked out a way to conveniently specify that. This concept is
+known as "joining".
Basic joining
+We've already seen some basic examples of joining in the last chapters, for +example we saw how to join over two storages:
+for (pos, vel) in (&mut pos_storage, &vel_storage).join() {
+ *pos += *vel;
+}
+This simply iterates over the position and velocity components of +all entities that have both these components. That means all the +specified components are required.
+Sometimes, we want not only get the components of entities,
+but also the entity value themselves. To do that, we can simply join over
+&EntitiesRes.
for (ent, pos, vel) in (&*entities, &mut pos_storage, &vel_storage).join() {
+ println!("Processing entity: {:?}", ent);
+ *pos += *vel;
+}
+Optional components
+If we iterate over the &EntitiesRes as shown above, we can simply
+use the returned Entity values to get components from storages as usual.
for (ent, pos, vel) in (&*entities, &mut pos_storage, &vel_storage).join() {
+ println!("Processing entity: {:?}", ent);
+ *pos += *vel;
+
+ let mass: Option<&mut Mass> = mass_storage.get_mut(ent);
+ if let Some(mass) = mass {
+ let x = *vel / 300_000_000.0;
+ let y = 1 - x * x;
+ let y = y.sqrt();
+ mass.current = mass.constant / y;
+ }
+}
+In this example we iterate over all entities with a position and a velocity +and perform the calculation for the new position as usual. +However, in case the entity has a mass, we also calculate the current +mass based on the velocity. Thus, mass is an optional component here.
+Excluding components
+If you want to filter your selection by excluding all entities
+with a certain component type, you can use the not operator (!)
+on the respective component storage. Its return value is a unit (()).
for (ent, pos, vel, ()) in (
+ &*entities,
+ &mut pos_storage,
+ &vel_storage,
+ !&frozen_storage,
+).join() {
+ println!("Processing entity: {:?}", ent);
+ *pos += *vel;
+}
+This will simply iterate over all entities that
+-
+
- have a position +
- have a velocity +
- do not have a
Frozencomponent
+
How joining works
+You can call join() on everything that implements the Join trait.
+The method call always returns an iterator. Join is implemented for
-
+
&ReadStorage/&WriteStorage(gives back a reference to the components)
+&mut WriteStorage(gives back a mutable reference to the components)
+&EntitiesRes(returnsEntityvalues)
+- bitsets +
We think the last point here is pretty interesting, because +it allows for even more flexibility, as you will see in the next +section.
+Joining over bitsets
+Specs is using hibitset, a library which provides layered bitsets
+(those were part of Specs once, but it was decided that a separate
+library could be useful for others).
These bitsets are used with the component storages to determine
+which entities the storage provides a component value for. Also,
+Entities is using bitsets, too. You can even create your
+own bitsets and add or remove entity ids:
use hibitset::{BitSet, BitSetLike};
+
+let mut bitset = BitSet::new();
+bitset.add(entity1.id());
+bitset.add(entity2.id());
+BitSets can be combined using the standard binary operators,
+&, | and ^. Additionally, you can negate them using !.
+This allows you to combine and filter components in multiple ways.
+
This chapter has been all about looping over components; but we can do more +than sequential iteration! Let's look at some parallel code in the next +chapter.
+Parallel Join
+As mentioned in the chapter dedicated to how to dispatch systems,
+Specs automatically parallelizes system execution when there are non-conflicting
+system data requirements (Two Systems conflict if their SystemData needs access
+to the same resource where at least one of them needs write access to it).
Basic parallelization
+What isn't automatically parallelized by Specs are +the joins made within a single system:
+ fn run(&mut self, (vel, mut pos): Self::SystemData) {
+ use specs::Join;
+ // This loop runs sequentially on a single thread.
+ for (vel, pos) in (&vel, &mut pos).join() {
+ pos.x += vel.x * 0.05;
+ pos.y += vel.y * 0.05;
+ }
+ }
+This means that, if there are hundreds of thousands of entities and only a few +systems that actually can be executed in parallel, then the full power +of CPU cores cannot be fully utilized.
+To fix this potential inefficiency and to parallelize the joining, the join
+method call can be exchanged for par_join:
fn run(&mut self, (vel, mut pos): Self::SystemData) {
+ use rayon::prelude::*;
+ use specs::ParJoin;
+
+ // Parallel joining behaves similarly to normal joining
+ // with the difference that iteration can potentially be
+ // executed in parallel by a thread pool.
+ (&vel, &mut pos)
+ .par_join()
+ .for_each(|(vel, pos)| {
+ pos.x += vel.x * 0.05;
+ pos.y += vel.y * 0.05;
+ });
+}
+++There is always overhead in parallelization, so you should carefully profile to see if there are benefits in the +switch. If you have only a few things to iterate over then sequential join is faster.
+
The par_join method produces a type implementing rayon's ParallelIterator
+trait which provides lots of helper methods to manipulate the iteration,
+the same way the normal Iterator trait does.
Rendering
+Rendering is often a little bit tricky when you're dealing with a multi-threaded ECS. +That's why we have something called "thread-local systems".
+There are two things to keep in mind about thread-local systems:
+-
+
- They're always executed at the end of dispatch. +
- They cannot have dependencies; you just add them in the order you want them to run. +
Adding one is a simple line added to the builder code:
+DispatcherBuilder::new()
+ .with_thread_local(RenderSys);
+Amethyst
+As for Amethyst, it's very easy because Specs is already integrated. So there's no special effort +required, just look at the current examples.
+Piston
+Piston has an event loop which looks like this:
+while let Some(event) = window.poll_event() {
+ // Handle event
+}
+Now, we'd like to do as much as possible in the ECS, so we feed in input as a +resource. +This is what your code could look like:
+struct ResizeEvents(Vec<(u32, u32)>);
+
+world.add_resource(ResizeEvents(Vec::new()));
+
+while let Some(event) = window.poll_event() {
+ match event {
+ Input::Resize(x, y) => world.write_resource::<ResizeEvents>().0.push((x, y)),
+ // ...
+ }
+}
+The actual dispatching should happen every time the Input::Update event occurs.
+
++If you want a section for your game engine added, feel free to submit a PR!
+
Advanced strategies for components
+So now that we have a fairly good grasp on the basics of Specs, +it's time that we start experimenting with more advanced patterns!
+Marker components
+Say we want to add a drag force to only some entities that have velocity, but +let other entities move about freely without drag.
+The most common way is to use a marker component for this. A marker component
+is a component without any data that can be added to entities to "mark" them
+for processing, and can then be used to narrow down result sets using Join.
Some code for the drag example to clarify:
+#[derive(Component)]
+#[storage(NullStorage)]
+pub struct Drag;
+
+#[derive(Component)]
+pub struct Position {
+ pub pos: [f32; 3],
+}
+
+#[derive(Component)]
+pub struct Velocity {
+ pub velocity: [f32; 3],
+}
+
+struct Sys {
+ drag: f32,
+}
+
+impl<'a> System<'a> for Sys {
+ type SystemData = (
+ ReadStorage<'a, Drag>,
+ ReadStorage<'a, Velocity>,
+ WriteStorage<'a, Position>,
+ );
+
+ fn run(&mut self, (drag, velocity, mut position): Self::SystemData) {
+ // Update positions with drag
+ for (pos, vel, _) in (&mut position, &velocity, &drag).join() {
+ pos += vel - self.drag * vel * vel;
+ }
+ // Update positions without drag
+ for (pos, vel, _) in (&mut position, &velocity, !&drag).join() {
+ pos += vel;
+ }
+ }
+}
+Using NullStorage is recommended for marker components, since they don't contain
+any data and as such will not consume any memory. This means we can represent them using
+only a bitset. Note that NullStorage will only work for components that are ZST (i.e. a
+struct without fields).
Modeling entity relationships and hierarchy
+A common use case where we need a relationship between entities is having a third person +camera following the player around. We can model this using a targeting component +referencing the player entity.
+A simple implementation might look something like this:
+
+#[derive(Component)]
+pub struct Target {
+ target: Entity,
+ offset: Vector3,
+}
+
+pub struct FollowTargetSys;
+
+impl<'a> System<'a> for FollowTargetSys {
+ type SystemData = (
+ Entities<'a>,
+ ReadStorage<'a, Target>,
+ WriteStorage<'a, Transform>,
+ );
+
+ fn run(&mut self, (entity, target, transform): Self::SystemData) {
+ for (entity, t) in (&*entity, &target).join() {
+ let new_transform = transform.get(t.target).cloned().unwrap() + t.offset;
+ *transform.get_mut(entity).unwrap() = new_transform;
+ }
+ }
+}
+We could also model this as a resource (more about that in the next section), but it could
+be useful to be able to have multiple entities following targets, so modeling this with
+a component makes sense. This could in extension be used to model large scale hierarchical
+structure (scene graphs). For a generic implementation of such a hierarchical system, check
+out the crate specs-hierarchy.
Entity targeting
+Imagine we're building a team based FPS game, and we want to add a spectator mode, where the +spectator can pick a player to follow. In this scenario each player will have a camera defined +that is following them around, and what we want to do is to pick the camera that +we should use to render the scene on the spectator screen.
+The easiest way to deal with this problem is to have a resource with a target entity, that +we can use to fetch the actual camera entity.
+pub struct ActiveCamera(Entity);
+
+pub struct Render;
+
+impl<'a> System<'a> for Render {
+ type SystemData = (
+ Read<'a, ActiveCamera>,
+ ReadStorage<'a, Camera>,
+ ReadStorage<'a, Transform>,
+ ReadStorage<'a, Mesh>,
+ );
+
+ fn run(&mut self, (active_cam, camera, transform, mesh) : Self::SystemData) {
+ let camera = camera.get(active_cam.0).unwrap();
+ let view_matrix = transform.get(active_cam.0).unwrap().invert();
+ // Set projection and view matrix uniforms
+ for (mesh, transform) in (&mesh, &transform).join() {
+ // Set world transform matrix
+ // Render mesh
+ }
+ }
+}
+By doing this, whenever the spectator chooses a new player to follow, we simply change
+what Entity is referenced in the ActiveCamera resource, and the scene will be
+rendered from that viewpoint instead.
Sorting entities based on component value
+In a lot of scenarios we encounter a need to sort entities based on either a component's
+value, or a combination of component values. There are a couple of ways to deal with this
+problem. The first and most straightforward is to just sort Join results.
let data = (&entities, &comps).join().collect::<Vec<_>>();
+data.sort_by(|&a, &b| ...);
+for entity in data.iter().map(|d| d.0) {
+ // Here we get entities in sorted order
+}
+There are a couple of limitations with this approach, the first being that we will always
+process all matched entities every frame (if this is called in a System somewhere). This
+can be fixed by using FlaggedStorage to maintain a sorted Entity list in the System.
+We will talk more about FlaggedStorage in the next chapter.
The second limitation is that we do a Vec allocation every time, however this can be
+alleviated by having a Vec in the System struct that we reuse every frame. Since we
+are likely to keep a fairly steady amount of entities in most situations this could work well.
FlaggedStorage and modification events
+In most games you will have many entities, but from frame to frame there will +usually be components that will only need to updated when something related is +modified.
+To avoid a lot of unnecessary computation when updating components it +would be nice if we could somehow check for only those entities that are updated +and recalculate only those.
+We might also need to keep an external resource in sync with changes
+to components in Specs World, and we only want to propagate actual changes, not
+do a full sync every frame.
This is where FlaggedStorage comes into play. By wrapping a component's
+actual storage in a FlaggedStorage, we can subscribe to modification events, and
+easily populate bitsets with only the entities that have actually changed.
Let's look at some code:
+pub struct Data {
+ [..]
+}
+
+impl Component for Data {
+ type Storage = FlaggedStorage<Self, DenseVecStorage<Self>>;
+}
+
+#[derive(Default)]
+pub struct Sys {
+ pub dirty: BitSet,
+ pub reader_id: Option<ReaderId<ComponentEvent>>,
+}
+
+impl<'a> System<'a> for Sys {
+ type SystemData = (
+ ReadStorage<'a, Data>,
+ WriteStorage<'a, SomeOtherData>,
+ );
+
+ fn run(&mut self, (data, mut some_other_data): Self::SystemData) {
+ self.dirty.clear();
+
+ let events = data.channel().read(self.reader_id.as_mut().unwrap());
+
+ // Note that we could use separate bitsets here, we only use one to
+ // simplify the example
+ for event in events {
+ match event {
+ ComponentEvent::Modified(id) | ComponentEvent::Inserted(id) => {
+ self.dirty.add(*id);
+ }
+ // We don't need to take this event into account since
+ // removed components will be filtered out by the join;
+ // if you want to, you can use `self.dirty.remove(*id);`
+ // so the bit set only contains IDs that still exist
+ ComponentEvent::Removed(_) => (),
+ }
+ }
+
+ for (d, other, _) in (&data, &mut some_other_data, &self.dirty).join() {
+ // Mutate `other` based on the update data in `d`
+ }
+ }
+
+ fn setup(&mut self, res: &mut Resources) {
+ Self::SystemData::setup(res);
+ self.reader_id = Some(WriteStorage::<Data>::fetch(&res).register_reader());
+ }
+}
+There are three different event types that we can receive:
+-
+
ComponentEvent::Inserted- will be sent when a component is added to the +storage
+ComponentEvent::Modified- will be sent when a component is fetched mutably +from the storage
+ComponentEvent::Removed- will be sent when a component is removed from the +storage
+
Note that because of how ComponentEvent works, if you iterate mutably over a
+component storage using Join, all entities that are fetched by the Join will
+be flagged as modified even if nothing was updated in them.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {% block footer %}
+ {% endblock footer %}
+
+
+ {% block js_body %}
+
+ {% endblock js_body %}
+
+
+
+ {% block content %}
+
+
+ {% for page in paginator.pages %}
+
+ {{ post_macros::title(page=page) }}
+
+ {% endfor %}
+
+
+ {% endblock content %}
+