The Amethyst Engine

Howdy! This book will teach you everything you need to know about building video games and interactive simulations with the Amethyst game engine. This engine is written entirely in Rust, a safe and fast systems programming language, and sports a clean and modern design. More correctly, though, Amethyst is actually a suite of separate libraries and tools that collectively make up a game engine.

Amethyst is free and open source software, distributed under a dual license of MIT and Apache. This means that the engine is given to you at no cost and its source code is completely yours to tinker with. The code is available on GitHub. Contributions and feature requests will always be welcomed!

This book is split into seven chapters (more coming). This page is the first. The others are:

• Getting Started – Prepare your computer for Amethyst development.
• Pong Tutorial – Build a basic pong game in Rust.
• Animation – Explains the architecture of the amethyst_animation crate.
• Custom GameData - Shows you how to structure more complex games that need to change the system graph.
• Glossary - Defines special terms used throughout the book.
• Appendix A: Config Files - Shows you how to define your data in RON files.

Read the crate-level API documentation for more details.

Please note that the default github branch is develop, while the documentation in this document is based on the master/release branch. The documentation for the develop branch is located here.

Most of us have worked with quite a few game engines over the years, namely Unity, Unreal Engine, JMonkeyEngine and many more. While they all are pretty solid solutions if you want to build a quality game, each have their own pros and cons that you have to weigh before using them, especially in regards to performance and scalability.

We think that basing the Amethyst engine on good and modern principles will allow us to make an open source game engine that can actually be more performant than those engines. Those principles are:

1. Modularity.

   Modularity is at the core of the Unix philosophy, which proved itself to be an excellent way of developing software over the years. You will always be free to use the built-in modules, or to write your own and integrate them easily into the engine. Since modules are small and well integrated, it is easier to reason about what they do and how they relate to other modules.

2. Parallelism.

   Modern computers, even cheap ones, all have multithread / multicores CPU. With the years, there will be more and more opportunities for parallelism to improve performance. With a proper parallel engine, we are convinced that your game will be more and more performant over the years without even needing you to update it.

3. Data-oriented/Data-driven.

   Building your game around the data makes it really easy to prototype and quickly build a game. Complex behaviours like swapping assets during gameplay become a breeze, making testing and balancing a lot faster.

We are always happy to welcome new contributors!

If you want to contribute, or have questions, let us know either on GitHub, on Gitter or on Discord.

We recommend using rustup to easily install the latest stable version of rust. Instructions should be on screen once rustup is downloaded.

If you are on Linux, you'll need to install libasound2-dev and libx11-xcb-dev.

You can either use the Amethyst CLI or just cargo to set up your project. After executing

amethyst new game

you should get Cargo.toml, src/main.rs and resources/display_config.ron. In case you're doing this with cargo, here's what you need to do:

• Add amethyst as dependency in your Cargo.toml.
• Create a resources folder and put a display_config.ron in it.
• Start with one of the [examples][ex] from the Amethyst repository (e.g. window) for the source code. Watch out to use the right example for the version of Amethyst you specified in Cargo.toml.

We don't have any tutorials yet, but there's a Gitter room where you can ask in case you want an explanation for something. If you'd like to help out, a tutorial would be much appreciated!

To get a better feeling for how Amethyst works, we're going to implement a Pong clone. You can find a full Pong example (our end goal) in Amethyst's examples folder. This tutorial breaks that project up into discrete steps so it's easier to understand what everything is doing. If you've cloned the Amethyst repo, you can run any of the examples like so:

cargo run --example pong_tutorial_01

The main difference between real game code and the example code is where the resources and assets folders are located.

For instance, in the pong_tutorial_01 example we have:

let path = format!(
    "{}/examples/pong_tutorial_01/resources/display_config.ron",
    env!("CARGO_MANIFEST_DIR"));

But for your own project you'll probably want something like this:

let path = "./resources/display_config.ron";

• Opening (and closing!) a window
• Drawing the paddles

Let's start a new project:

amethyst new pong

If you run this project with cargo run, you'll end up with a window titled "pong" that renders a really delightful shade of green. Press Esc to quit. If you're having trouble getting the project to run, double check the Getting Started guide.

We've opened and closed a window, so we're basically done! But let's write this functionality ourselves so we're sure we know what's going on.

In src there's a main.rs file. Delete everything, then add these imports:

extern crate amethyst;

use amethyst::Result;
use amethyst::prelude::*;
use amethyst::renderer::{DisplayConfig, DrawFlat, Event, KeyboardInput,
                         Pipeline, PosTex, RenderBundle, Stage, 
                         VirtualKeyCode, WindowEvent};

We'll be learning more about these as we go through this tutorial. The prelude includes the basic (and most important) types like Application, World, and State.

Now we create our core game struct:

struct Pong; 

We'll be implementing the State trait on this struct, which is used by Amethyst's state machine to start, stop, and update the game. But for now we'll just implement one method:

impl<'a, 'b> State<GameData<'a, 'b>> for Pong {
    fn handle_event(&mut self, _: StateData<GameData>, event: Event) -> Trans<GameData<'a, 'b>> {
        match event {
            Event::WindowEvent { event, .. } => match event {
                WindowEvent::KeyboardInput {
                    input:
                        KeyboardInput {
                            virtual_keycode: Some(VirtualKeyCode::Escape),
                            ..
                        },
                    ..
                } => Trans::Quit,
                _ => Trans::None,
            },
            _ => Trans::None,
        }
    }

    fn update(&mut self, data: StateData<GameData>) -> Trans<GameData<'a, 'b>> {
        data.data.update(&data.world);
        Trans::None
    }
}

The handle_event method is executed for every event before updating, and it's used to react to events. It returns a Trans, which is an enum of state machine transitions. In this case, we're watching for the Escape keycode from the Window. If we receive it, we'll return Trans::Quit which will be used to clean up the State and close the application. All other keyboard input is ignored for now.

The update method is executed after events have happened. In this instance we're just using it to execute our dispatcher. More on that later.

Now that we know we can quit, let's add some code to actually get things started! We'll use a run() function, which returns a Result and thus allows us to use ?.

fn run() -> Result<()> {

    //We'll put the rest of the code here

    Ok(())
}

Inside run() we first define a path for our display_config.ron file and load it.

let path = "./resources/display_config.ron";

let config = DisplayConfig::load(&path);

This .ron file was automatically generated by amethyst new. If you didn't use amethyst new, now would be a good time to create this config file inside a folder named resources. If you already have this file, we have some changes to make, anyway:

(
  title: "Pong!",
  dimensions: Some((500, 500)),
  max_dimensions: None,
  min_dimensions: None,
  fullscreen: false,
  multisampling: 0,
  visibility: true,
  vsync: true,
)

This will set the default window dimensions to 500 x 500, and make the title bar say "Pong!" instead of the sad, lowercase default of "pong".

Now, back inside our run() function in main.rs, let's copy and paste some rendering code so we can keep moving. We'll cover rendering in more depth later in this tutorial.

let pipe = Pipeline::build().with_stage(
    Stage::with_backbuffer()
        .clear_target([0.0, 0.0, 0.0, 1.0], 1.0)
        .with_pass(DrawFlat::<PosTex>::new()),
);

The important thing to know right now is that this renders a black background. If you want a different color you can tweak the RGBA values inside the .clear_target method. Values range from 0.0 to 1.0, so to get that cool green color we started with back, for instance, you can try [0.00196, 0.23726, 0.21765, 1.0].

Now let's pack everything up and run it:

let game_data = GameDataBuilder::default().with_bundle(RenderBundle::new(pipe, Some(config)))?;
let mut game = Application::new("./", Pong, game_data)?;
game.run();
Ok(())

We've discovered Amethyst's root object: Application. It binds the OS event loop, state machines, timers and other core components in a central place. Here we're creating a new RenderBundle, adding the Pipeline we created, along with our config, and building.

Then we call .run() on game which begins the gameloop. The game will continue to run until our State returns Trans::Quit, or when all states have been popped off the state machine's stack.

Now all that's left is to write a main() function to call our run() function:

fn main() {
    if let Err(e) = run() {
        println!("Error occurred during game execution: {}", e);
        ::std::process::exit(1);
    }
}

Success! Now we should be able to compile and run this code and get a window. It should look something like this:

Now let's do some drawing! But to draw something, we need something to draw. In Amethyst, those "somethings" are called Entities, which are described by Components.

Amethyst uses Specs for its ECS (Entity-component system), which is a parallel Entity-component system written in Rust. You can learn more about Specs in the The Specs Book. Here's a basic explanation of ECS from there:

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.

I recommend at least skimming the rest of The Specs Book to get a good intuition of how Amethyst works, especially if you're new to ECS.

Let's create a new file called pong.rs to hold our core game logic. We can move the Pong struct over here, and the impl State for Pong block as well. Then, in main.rs declare a module:

mod pong;

And in the run() function add:

use pong::Pong;

Now you can just delete various main.rs use statements until the Rust compiler stops complaining about unused imports. In pong.rs we'll need these use statements to make it through this chapter:

use amethyst::assets::Loader;
use amethyst::core::cgmath::Vector3;
use amethyst::core::transform::{GlobalTransform, Transform};
use amethyst::ecs::prelude::{Component, DenseVecStorage};
use amethyst::prelude::*;
use amethyst::renderer::{Camera, Event, KeyboardInput, Material, MaterialDefaults, MeshHandle,
                         PosTex, VirtualKeyCode, WindowEvent};

In pong.rs let's create our first Component, a definition of a paddle.

#[derive(PartialEq, Eq)]
enum Side {
    Left,
    Right,
}

struct Paddle {
    pub side: Side,
    pub width: f32,
    pub height: f32,
}

impl Paddle {
    fn new(side: Side) -> Paddle {
        Paddle {
            side: side,
            width: 1.0,
            height: 1.0,
        }
    }
}

"But that just looks like a regular struct!" you might say. And you're right, here's the special sauce:

impl Component for Paddle {
    type Storage = DenseVecStorage<Self>;
}

By implementing Component for our Paddle struct, and defining the way we'd like that Component data stored, we can now add the Paddle component to entities in our game. For more on storage types, check out the Specs documentation.

Now it's time to add a new method to our State implementation: on_start. Inside this function, we'll register our Paddle component on the mutable World object we're passed by Amethyst's state machine when the game starts up.

fn on_start(&mut self, world: &mut World) {
    world.register::<Paddle>();
}

This World gets passed around everywhere. It carries with it all the components in our game. Not only the components we create, but the ones the Amethyst engine itself relies on. For instance, in our main.rs we added a RenderBundle::new() to our game before calling run(). That added default rendering components like Camera, Material, and Mesh to the World, some of which we'll be using soon.

Now that we have a Paddle component, let's define some paddle entities that include that component and add them to our World.

First let's look at our math imports:

use amethyst::core::cgmath::Vector3;
use amethyst::core::transform::{GlobalTransform, Transform};

Amethyst uses the cgmath crate under the hood and exposes it for our use. Today we just grabbed the Vector3 type, which is a very good math thing to have.

Transform and GlobalTransform are Amethyst ECS components which carry position and orientation information. Transform is relative to a parent if one exists, while GlobalTransform is, well, global.

Let's also define some constants for convenience:

const PADDLE_HEIGHT: f32 = 0.30;
const PADDLE_WIDTH: f32 = 0.05;
const PADDLE_COLOUR: [f32; 4] = [0.0, 0.0, 1.0, 1.0];

Okay, let's make some entities! We'll define an initialise_paddles function which will create left and right paddle entities and attach Transform components to them to position them in our world. Our canvas goes from -1.0,-1.0 on the bottom left to 1.0,1.0 on the top right, which will make more sense when we define the camera.

/// Initialises one paddle on the left, and one paddle on the right.
fn initialise_paddles(world: &mut World) {

    let mut left_transform = Transform::default();
    let mut right_transform = Transform::default();

    // Correctly position the paddles.
    let y = -PADDLE_HEIGHT / 2.0;
    left_transform.translation = Vector3::new(-1.0, y, 0.0);
    right_transform.translation = Vector3::new(1.0 - PADDLE_WIDTH, y, 0.0);

    // Create a left plank entity.
    world
        .create_entity()
        .with(Paddle::new(Side::Left))
        .with(GlobalTransform::default())
        .with(left_transform)
        .build();

    // Create right plank entity.
    world
        .create_entity()
        .with(Paddle::new(Side::Right))
        .with(GlobalTransform::default())
        .with(right_transform)
        .build();
}

This is all the information Amethyst needs to track and move the paddles in our virtual world, but we'll need to do some more work to actually draw them.

Here's a utility function to generate the six vertices of a rectangle (a rectangle in computer graphics is typically drawn with two triangles):

fn generate_rectangle_vertices(left: f32,
                               bottom: f32,
                               right: f32,
                               top: f32) -> Vec<PosTex> {
    vec![
        PosTex {
            position: [left, bottom, 0.],
            tex_coord: [0.0, 0.0],
        },
        PosTex {
            position: [right, bottom, 0.0],
            tex_coord: [1.0, 0.0],
        },
        PosTex {
            position: [left, top, 0.0],
            tex_coord: [1.0, 1.0],
        },
        PosTex {
            position: [right, top, 0.],
            tex_coord: [1.0, 1.0],
        },
        PosTex {
            position: [left, top, 0.],
            tex_coord: [0.0, 1.0],
        },
        PosTex {
            position: [right, bottom, 0.0],
            tex_coord: [0.0, 0.0],
        },
    ]
}

PosTex is a type defined by amethyst_renderer. It's a vertex format with position and UV texture coordinate attributes. In our rendering pipeline, if you'll recall, we created a DrawFlat::<PosTex> pass, which draws a PosTex mesh. Right now our vertices are simply in a standard Rust Vector. To create a mesh from them we'll write another utility function, which generates a MeshHandle:

fn create_mesh(world: &World, vertices: Vec<PosTex>) -> MeshHandle {
    let loader = world.read_resource::<Loader>();
    loader.load_from_data(vertices.into(), (), &world.read_resource())
}

The Loader is an asset loader which is defined as a resource (not a Entity , Component, or System, but still a part of our ECS world). It was created when we built our Application in main.rs, and it can read assets like .obj files, but also it can load_from_data as in our use case.

Resources in Specs are a type of data which can be shared between systems, while being independent from entities, in contrast to components, which are attached to specific entities. We'll explore this more later on.

The load_from_data function returns a Handle<Mesh>, also known as a MeshHandle. Since Handle implements component, we can attach it to our entity. Once the mesh is fully loaded, a system which asks the handle for the mesh will receive it. If the mesh isn't loaded yet, the handle will return None. In this minimal scenario, the mesh will be available on the next frame.

In addition to mesh data, we also need a material to draw our mesh with. We'll use the Amethyst renderer's MaterialDefaults (another resource) and only change the albedo color:

/// Creates a solid material of the specified colour.
fn create_colour_material(world: &World, colour: [f32; 4]) -> Material {
    let mat_defaults = world.read_resource::<MaterialDefaults>();
    let loader = world.read_resource::<Loader>();

    let albedo = loader.load_from_data(colour.into(),
                                       (),
                                       &world.read_resource());

    Material {
        albedo,
        ..mat_defaults.0.clone()
    }
}

Now let's return to inside our initialise_paddles function and actually create this mesh and material.

let mesh = create_mesh(
    world,
    generate_rectangle_vertices(0.0, 0.0, PADDLE_WIDTH, PADDLE_HEIGHT),
);

let material = create_colour_material(world, PADDLE_COLOUR);

Now we just add these components to our paddle entities:

// Create a left plank entity.
world
    .create_entity()
    .with(mesh.clone())
    .with(material.clone())
    .with(Paddle::new(Side::Left))
    .with(GlobalTransform::default())
    .with(left_transform)
    .build();

// Create right plank entity.
world
    .create_entity()
    .with(mesh)
    .with(material)
    .with(Paddle::new(Side::Right))
    .with(GlobalTransform::default())
    .with(right_transform)
    .build();

We're almost done! We just need to create a camera to view all our beautiful graphics (two blue pong paddles) with.

fn initialise_camera(world: &mut World) {
    world
        .create_entity()
        .with(Camera::standard_2d())
        .build();
}

The camera is another entity, with a Camera component. Amethyst's standard_2d camera uses an orthographic projection, and defines a screenspace coordinate system of -1.0,-1.0 in the bottom left and 1.0,1.0 in the top right.

If you want to to define your own coordinate system, you can use something like this:

fn initialise_camera(world: &mut World) {
    world.create_entity()
        .with(Camera::from(Projection::orthographic(0.0, WIDTH, HEIGHT, 0.0)))
        .with(GlobalTransform(Matrix4::from_translation
                (Vector3::new(0.0, 0.0, 1.0)).into())
             )
        .build();
}

To use that custom camera you'll need to define WIDTH and HEIGHT constants, and redo the position math in the initialise_paddles function.

Now let's add our initialise functions to the on_start function in impl State for Pong.

fn on_start(&mut self, world: &mut World) {
    world.register::<Paddle>();
    initialise_paddles(world);
    initialise_camera(world);
}

Okay! We've defined our Paddle component, and created two entities which have Paddle, GlobalTransform, MeshHandle, and Material components. When our game starts, we'll register the Paddle component and then add the left and right paddles to the world, along with a camera.

Let's run this and see what happens. On my machine I get a panic that reads:

thread 'main' panicked at 'Tried to fetch a resource, but the resource does not exist.
Try adding the resource by inserting it manually or using the `setup` method.

It looks like we're missing at least one component registration. In addition to components we define ourselves, Amethyst has a lot of internal systems and components it uses to keep things running. For simplicity, these have been wrapped up into "Bundles" which include related components, systems, and resources. We can add these to our Application using the with_bundle method, and in fact we already have one of these in main.rs: the RenderBundle.

As it turns out, the components we're missing are GlobalTransform and Transform, and we can add those with the TransformBundle, which will also add the TransformSystem for working with those components:

let mut game = Application::build("./", Pong)?
    .with_bundle(TransformBundle::new())? //Add this bundle
    .with_bundle(RenderBundle::new(pipe, Some(config)))?
    .build()?;

Also we'll need to import that structure:

use amethyst::core::transform::TransformBundle;

Now when we run the game we should get something that looks like this:

In the next chapter we'll explore the "S" in ECS and actually get these paddles moving!

In the previous chapter, we learned about the relationship between entities and components, and how they represent the "things" in our games. This chapter introduces Systems - the S in "ECS". Systems are objects that represent operations over entities, or more specifically, combinations of components. Let's add a system that moves the paddles based on user input.

A system is nothing more than a function that runs once each frame and potentially makes some changes to components. If you've used other game engines, this probably sounds familiar: Unity engine calls these objects MonoBehaviours and Unreal engine calls them Actors, but these all represent the same basic idea.

Systems in specs/Amethyst are slightly different. Rather than describe the behavior of a single instance (eg, a single enemy in your game), they describe the behavior of all components of a specific type (all enemies). This makes your code more modular, easier to test, and makes it run faster.

Let's get started.

To capture user input, we'll need to introduce a few more files to our game. Let's start by creating a resource file under the resources directory of our project, called bindings_config.ron:

(
  axes: {
    "left_paddle": (pos: Key(W), neg: Key(S)),
    "right_paddle": (pos: Key(Up), neg: Key(Down)),
  },
  actions: {},
)

In Amethyst, inputs can be either scalar inputs (a button that is either pressed or not), or axes (a range that relates two buttons as opposite ends of a range). In this file, we're creating two axes: W and S will move the left paddle up and down, and the Up and Down arrow keys will move the right paddle up and down.

Next, we'll add an input bundle to the game's Application object, that contains an input handler system which captures inputs and maps them to the axes we defined. Let's make the following changes to main.rs.

use amethyst::input::InputBundle;

let binding_path = format!(
    "{}/resources/bindings_config.ron",
    env!("CARGO_MANIFEST_DIR")
);

let input_bundle = InputBundle::<String, String>::new().with_bindings_from_file(binding_path);

let game_data = GameDataBuilder::default()
    .with_bundle(TransformBundle::new())?
    .with_bundle(RenderBundle::new(pipe, Some(config)))?
    .with_bundle(input_bundle)?
    .with(systems::PaddleSystem, "paddle_system", &["input_system"]);
let mut game = Application::new("./", Pong, game_data)?;
game.run();

At this point, we're ready to write a system that reads input from the InputHandler, and moves the paddles accordingly. First, we'll create a directory called systems under src to hold all our systems. We'll use a module to collect and export each of our systems to the rest of the application. Here's our mod.rs for src/systems:

mod paddle;

pub use self::paddle::PaddleSystem;

We're finally ready to implement the PaddleSystem:

use pong::{Paddle, Side};
use amethyst::ecs::{System, Join, Fetch};
use amethyst::input::InputHandler;
use amethyst::core::transform::components::Transform;
use amethyst::ecs::{ReadStorage, WriteStorage};

pub struct PaddleSystem;

impl<'s> System<'s> for PaddleSystem {
  type SystemData = (
    WriteStorage<'s, Transform>,
    ReadStorage<'s, Paddle>,
    Read<'s, InputHandler<String, String>>,
  );

  fn run(&mut self, (mut transforms, paddles, input): Self::SystemData) {
    for paddle in (&paddles).join() {
      let movement = match paddle.side {
        Side::Left => input.axis_value("left_paddle"),
        Side::Right => input.axis_value("right_paddle"),
      };
      if let Some(mv_amount) = movement {
        if mv_amount != 0.0 {
          println!("Side {:?} moving {}", paddle.side, mv_amount);
        }
      }
    }
  }
}

Note: We had to make our Paddle and Side public in pong.rs

Now lets add this system to our ApplicationBuilder in main.rs:

mod systems;

// in the run() function
let mut game = Application::build("./", Pong)?
    .with_bundle(TransformBundle::new())?
    .with_bundle(RenderBundle::new(pipe, Some(config)))?
    .with_bundle(input_bundle)?
    .with(systems::PaddleSystem, "paddle_system", &["input_system"])
    .build()?;

Let's review what our system does, because there's quite a bit there.

We create a unit struct, called PaddleSystem, and implement the System trait for it. The trait specifies the lifetime of the components on which it operates. Inside the implementation, we define the SystemData the system operates on, a tuple of WriteStorage, ReadStorage, and Read. More specifically, the generic types we've used here tell us that the PaddleSystem mutates LocalTransform components, WriteStorage<'s, LocalTransform>, it reads Paddle components, ReadStorage<'s, Paddle>, and also accesses the InputHandler<String, String> resource we created earlier, using the Read structure.

It's worth noting an important difference between the objects our system accesses. A system will iterate over entities that contain one of each of the components that it specifies in its SystemData. Going back to our example, the PaddleSystem will ignore any entity that is missing a Paddle, LocalTransform or both.

If we run the game now, we'll see the console print our keypresses. Let's make it update the position of the paddle. To do this, we'll modify the y component of the transform's translation.

  fn run(&mut self, (mut transforms, paddles, input): Self::SystemData) {
    for (paddle, mut transform) in (&paddles, &mut transforms).join() {
      let movement = match paddle.side {
        Side::Left => input.axis_value("left_paddle"),
        Side::Right => input.axis_value("right_paddle"),
      };
      if let Some(mv_amount) = movement {
        let scaled_amount = (1.0 / 60.0) * mv_amount as f32;
        transform.translation[1] += scaled_amount;
      }
    }
  }

This is our first attempt at moving the paddles: we take the movement, and scale it by some factor to make the motion seem smooth. In a real game, we would use the time elapsed between frames to determine how far to move the paddle, so that the behavior of the game would not be tied to the game's framerate, but this will do for now. If you run the game now, you'll notice the paddles are able to "fall" off the edges of the game area.

To fix this, we'll clamp the translation's y component to be at least -1.0 and at most 1.0 - PADDLE_HEIGHT (since the translation indicates the paddle's bottom edge).

Our run function should now look something like this:

  fn run(&mut self, (mut transforms, paddles, input): Self::SystemData) {
    for (paddle, mut transform) in (&paddles, &mut transforms).join() {
      let movement = match paddle.side {
        Side::Left => input.axis_value("left_paddle"),
        Side::Right => input.axis_value("right_paddle"),
      };
      if let Some(mv_amount) = movement {
        let scaled_amount = (1.0 / 60.0) * mv_amount as f32;
        transform.translation[1] = (transform.translation[1] + scaled_amount)
        .min(1.0 - PADDLE_HEIGHT)
        .max(-1.0);
      }
    }
  }

Note: For the above to work, we'll have to mark PADDLE_HEIGHT as being public in pong.rs, and then import it in paddle.rs.

In this chapter, we added an input handler to our game, so that we could capture keypresses. We then created a system that would interpret these keypresses, and move our game's paddles accordingly. In the next chapter, we'll explore another key concept in real-time games: time. We'll make our game aware of time, and add a ball for our paddles to bounce back and forth.

Animation in computer graphics can be viewed as controlled mutation of attributes of objects over time, using a predefined function. Examples of this are:

• Changing coordinates of vertices — movement, scaling up or down
• Changing the hue of a texture — for a "power up" effect

To determine the values each attribute should have at a particular point in time, we define a set of known values at certain points in the animation — called key frames — and a function to interpolate the value for the attribute.

This section will guide you in learning how to make use of the animation functionality in Amethyst.

Interpolation is the calculation of an attribute value that lies in between two key frames.

For example, if an object should move in a circle, then we can define an animation that mutates its X and Y coordinate attributes.

The animation definition can represent this using 5 key frames:

For a perfect circle, the values in between the key frames can be calculated by the sin(..) function for the X coordinate, and the cos(..) function for the Y coordinate. So, if we were trying to calculate what the coordinates should be when t = 0.5, we could go sin( 0.5 * π ).

However, what if we do not have such perfect coordinate control, and we only have the values at the specified key frames?

To move in a circle, the X coordinate first increases with a larger step, and the step size decreases as it approaches the circle boundary on the X axis, where it then flips, and increases in the negative direction. For the Y coordinate, the magnitude of the step size increases downwards, then decreases once it has gotten past the halfway point.

The changing step size means, given the first two key frames, 0 and 1, the values do not change in constant step increments — linearly (LERP) —, but spherical linearly (SLERP).

The spherical linear function is a way of saying, given these two key frame values, and some proportion of time between the two key frames, what should the actual value be given that the step increments change as they would on a sphere?

In computer graphics, there are a number of methods commonly used to calculate the interpolated values. The following functions are available in Amethyst, implemented by the minterpolate library, namely:

• Linear
• SphericalLinear
• Step
• CatmullRomSpline
• CubicSpline

Amethyst also allows you to specify your own custom interpolation function.

An independent grouping or type of functions that operate on attributes of a component.

Some attributes may be mutated by different functions. These functions can be independent of each other, or they may also be dependent each other. An example of these are translation, scaling, and rotation.

Given the following functions are part of the same animation:

• Translate the object to the right
• Translate the object upwards
• Scale the object up

We want to be able to individually apply related functions, i.e. "apply all translations", "apply all scalings", and "apply all rotations". Each of these groupings is called a channel.

In Amethyst, a Sampler is the lowest level working block of an animation. It defines the interpolation function, and what attribute or set of attributes the function mutates.

The input holds the timing of the key frames. The output holds the values used in the interpolation function for each of the key frames.

You can imagine the interpolation function as fn(Time) -> ChannelValue

Animations can be defined for objects made of a single entity, or complex objects made up of multiple entities.

Right now we do not have a tutorial for defining an animation from scratch, but take a look at the following resources to get an idea of how to write one:

• animation example
• gltf example
• API docs

So far we've been using the Amethyst supplied GameData struct to handle our Systems. This works well for smaller games and demos, but once we start building a larger game, we will quickly realise we need to manipulate the System dispatch based on game State, or we need to pass data between States that aren't Send + Sync which can't be added to World.

The solution to our troubles here is to create a custom GameData structure to house what we need that can not be added to World.

In this tutorial we will look at how one could structure a Paused State, which disables the game logic, only leaving a few core systems running that are essential (like rendering, input and UI).

Let's start by creating the GameData structure:

pub struct CustomGameData<'a, 'b> {
    core_dispatcher: Dispatcher<'a, 'b>,
    running_dispatcher: Dispatcher<'a, 'b>,
}

We also add a utility function for performing dispatch:

impl<'a, 'b> CustomGameData<'a, 'b> {
    /// Update game data
    pub fn update(&mut self, world: &World, running: bool) {
        if running {
            self.running_dispatcher.dispatch(&world.res);
        }
        self.core_dispatcher.dispatch(&world.res);
    }
}

To be able to use this structure with Amethysts Application we need to create a builder that implements DataInit. This is the only requirement placed on the GameData structure.

pub struct CustomGameDataBuilder<'a, 'b> {
    pub core: DispatcherBuilder<'a, 'b>,
    pub running: DispatcherBuilder<'a, 'b>,
}

impl<'a, 'b> Default for CustomGameDataBuilder<'a, 'b> {
    fn default() -> Self {
        CustomGameDataBuilder::new()
    }
}

impl<'a, 'b> CustomGameDataBuilder<'a, 'b> {
    pub fn new() -> Self {
        CustomGameDataBuilder {
            core: DispatcherBuilder::new(),
            running: DispatcherBuilder::new(),
        }
    }

    pub fn with_base_bundle<B>(mut self, bundle: B) -> Result<Self>
    where
        B: SystemBundle<'a, 'b>,
    {
        bundle
            .build(&mut self.core)
            .map_err(|err| Error::Core(err))?;
        Ok(self)
    }

    pub fn with_running<S>(mut self, system: S, name: &str, dependencies: &[&str]) -> Self
    where
        for<'c> S: System<'c> + Send + 'a,
    {
        self.running.add(system, name, dependencies);
        self
    }
}

impl<'a, 'b> DataInit<CustomGameData<'a, 'b>> for CustomGameDataBuilder<'a, 'b> {
    fn build(self, world: &mut World) -> CustomGameData<'a, 'b> {
        let pool = world.read_resource::<ThreadPool>().clone();

        let mut core_dispatcher = self.core.with_pool(pool.clone()).build();
        let mut running_dispatcher = self.running.with_pool(pool.clone()).build();
        core_dispatcher.setup(&mut world.res);
        running_dispatcher.setup(&mut world.res);

        CustomGameData { core_dispatcher, running_dispatcher }
    }
}

We can now use CustomGameData in place of the provided GameData when building our Application, but first we should create some States.

struct Main;
struct Paused;

impl<'a, 'b> State<CustomGameData<'a, 'b>> for Paused {
    fn on_start(&mut self, data: StateData<CustomGameData>) {
        create_paused_ui(data.world);
    }

    fn handle_event(
        &mut self,
        data: StateData<CustomGameData>,
        event: Event,
    ) -> Trans<CustomGameData<'a, 'b>> {
        if is_exit(event.clone()) {
            Trans::Quit
        } else if is_pause(event) {
            delete_paused_ui(data.world);
            Trans::Pop
        } else {
            Trans::None
        }
    }

    fn update(&mut self, data: StateData<CustomGameData>) -> Trans<CustomGameData<'a, 'b>> {
        data.data.update(&data.world, false); // false to say we should not dispatch running
        Trans::None
    }
}

impl<'a, 'b> State<CustomGameData<'a, 'b>> for Main {
    fn on_start(&mut self, data: StateData<CustomGameData>) {
        initialise(data.world);
    }

    fn handle_event(
        &mut self,
        _: StateData<CustomGameData>,
        event: Event,
    ) -> Trans<CustomGameData<'a, 'b>> {
        if is_exit(event.clone()) {
            Trans::Quit
        } else if is_pause(event) {
            Trans::Push(Box::new(Paused))
        } else {
            Trans::None
        }
    }

    fn update(&mut self, data: StateData<CustomGameData>) -> Trans<CustomGameData<'a, 'b>> {
        data.data.update(&data.world, true); // true to say we should dispatch running
        Trans::None
    }
}

The only thing that remains now is to use our CustomGameDataBuilder when building the Application.

    let game_data = CustomGameDataBuilder::default()
        .with_running::<ExampleSystem>(ExampleSystem, "example_system", &[])
        .with_base_bundle(TransformBundle::new())?
        .with_base_bundle(UiBundle::<String, String>::new())?
        .with_base_bundle(RenderBundle::new(pipeline_builder, Some(display_config)))?
        .with_base_bundle(InputBundle::<String, String>::new())?;

    let mut game = Application::new(resources_directory, Main, game_data)?;
    game.run();

Those are the basics of creating a custom GameData structure. Now get out there and build your game!

Describes a program that has its logic defined largely in data rather than in compiled code. Ideally, this would permit the user to edit their code and resources using offline tools and have the program hot-reload the changes at run-time for instant feedback without the need for recompilation. The bare minimum qualification for a data-driven program is the ability to read external content (text files, scripts, byte streams) and mutate its behavior accordingly.

Not to be confused with data-driven design, data-oriented programming is a programming paradigm, like object-oriented programming (OOP) or procedural programming. Where OOP focuses on modeling a problem in terms of interacting objects, and procedural programming tries to model a problem in terms of sequential or recursive steps or procedures, data-oriented programming shifts the focus towards the data being operated on: the data type, its memory layout, how it will be processed. Software written in a data-oriented manner tends toward high-throughput pipelining, modularity, separation of concerns, and massive parallelism. If architected correctly, data-oriented software can be very cache-friendly and easy to scale on systems with multiple cores.

Note: Data-oriented programming does not necessarily imply that a program is data-driven. Data-driven behavior can be implemented with any programming approach you like.

Describes a game programming design pattern invented as a reaction to the deep-rooted problems with using inheritance (is-a relationship) to represent game objects, including the deadly diamond of death and god objects. The inheritance-based approach was especially common in the game industry during the 1990's and early 2000's.

This alternative model makes use of composition (has-a relationship) instead of inheritance to represent objects in the game world, flattening the hierarchy and eliminating the problems above, while increasing flexibility. The holistic ECS approach is broken into three key pieces:

1. Entity: Represents a single object in the game world. Has no functionality on its own. The world owns a collection of entities (either in a flat list or a hierarchy). Each entity has a unique identifier or name, for the sake of ease of use.
2. Component: A plain-old-data structure that describes a certain trait an entity can have. Can be "attached" to entities to grant them certain abilities, e.g. a Light component contains parameters to make an entity glow, or a Collidable component can grant an entity collision detection properties. These components do not have any logic. They contain only data.
3. System: This is where the magic happens! Systems are centralized game engine subsystems that perform a specific function, such as rendering, physics, audio, etc. Every frame, they process each entity in the game world looking for components that are relevant to them, reading their contents, and performing actions. For example, a Rendering system could search for all entities that have Light, Mesh, or Emitter components and draw them to the screen.

This approach could potentially be stretched to fit the model-view-controller (MVC) paradigm popular in GUI and Web development circles: entities and components together represent the model, and systems represent either views (Rendering, Audio) or controllers (Input, AI, Physics), depending on their purpose.

Another great advantage of the ECS model is the ability to rapidly prototype a game simply by describing objects' characteristics in terms of creating entities and attaching components to them, with very little game code involved. And all of this data can be easily serialized or de-serialized into a human-friendly plain text format like YAML (what we use) or JSON.

For more detailed explanations of entity-component-system designs, please see this great post on Reddit and this Stack Overflow answer.

In the full Pong example, the paddle sizes, ball sizes, colors, and arena size are all hard-coded into the implementation. This means that if you want to change any of these, you need to recompile the project. Wouldn't it be nice to not have to recompile the project each time you wanted to change one or all of these things?

Luckily, Amethyst uses RON configuration files and has infrastructure in the form of the Config trait to help us implement our own config files.

The existing example uses the following constants:

const ARENA_HEIGHT: f32 = 100.0;
const ARENA_WIDTH: f32 = 100.0;
const PADDLE_HEIGHT: f32 = 15.0;
const PADDLE_WIDTH: f32 = 2.5;
const PADDLE_VELOCITY: f32 = 75.0;
const PADDLE_COLOUR: [f32; 4] = [0.0, 0.0, 1.0, 1.0];

const BALL_VELOCITY_X: f32 = 75.0;
const BALL_VELOCITY_Y: f32 = 50.0;
const BALL_RADIUS: f32 = 2.5;
const BALL_COLOUR: [f32; 4] = [1.0, 0.0, 0.0, 1.0];

to specify the look of the game. We want to replace this with something more flexible in the form of a config file. To start, let's create a new file, config.rs, to hold our configuration structures. Add the following use statements to the top of this file:

use std::path::Path;

use amethyst::config::Config;

For this project, we'll be placing a config.ron file in the same location as the display_config.ron and input.ron files (likely the resources/ folder).

• Adding an ArenaConfig
• Adding a Ball Config
• Adding Paddle Configs

To begin with, let's make the Arena dimensions configurable. Add this structure to a new file config.rs.

#[derive(Debug, Deserialize, Serialize)]
struct ArenaConfig {
    pub height: f32,
    pub width: f32,
}

impl Default for ArenaConfig {
    fn default() -> Self {
        ArenaConfig {
            height: 100.0,
            width: 100.0,
        }
    }
}

The default values match the values used in the full example, so if we don't use a config file things will look just like the Pong example. Another option would be to use [#serde(default)], which allows you to set the default value of a field if that field is not present in the config file. This is different than the Default trait in that you can set default values for some fields while requiring others be present. For now though, let's just use the Default trait.

Now, in main.rs, add the following lines:

use config::ArenaConfig;

We'll need to load the config at startup, so let's add this to the run function in main.rs

let arena_config = ArenaConfig::load(&config);

Now that we have loaded our config, we want to add it to the world so other modules can access it. We do this by adding the config as a resource during Application creation:

    .with_resource(arena_config)
    .with_bundle(PongBundle::default())?

Now for the difficult part: replacing every use of ARENA_WIDTH and ARENA_HEIGHT with our config object. First, let's change our initialisation steps in pong.rs.

Add the following line to the top of pong.rs:

use config::ArenaConfig;

Now, in the initialise_paddles() function, add the following lines after the initialisation of the left_transform and right_transform.

let (arena_height, arena_width) = {
    let config = &world.read_resource::<ArenaConfig>();
    (config.height, config.width)
};

Now replace all references to ARENA_HEIGHT with arena_height and all references to ARENA_WIDTH with arena_width. Do this for each initialisation function in pong.rs.

It is actually simpler to access a Config file from a system than via the World directly. To access it in the System's run() function, add it to the SystemData type. This is what the BounceSystem looks like when it wants to access the ArenaConfig.

use config::ArenaConfig;
...
type SystemData = (
    WriteStorage<'s, Ball>,
    ReadStorage<'s, Paddle>,
    ReadStorage<'s, Transform>,
    Fetch<'s, AssetStorage<Source>>,
    Fetch<'s, Sounds>,
    Fetch<'s, Option<Output>>,
    Fetch<'s, ArenaConfig>,
);
...
fn run(&mut self, 
       (mut balls, paddles, transforms, storage, sounds, audio_output, arena_config): SystemData) {

Now, in the run() function, replace the reference to ARENA_HEIGHT with arena_config.height.

Add Fetch<'s, ArenaConfig> to the WinnerSystem and PaddleSystem as well, replacing the reference to ARENA_WIDTH with arena_config.width.

Now for the final part: actually creating our config.ron file. This will be very simple right now, and expand as we add more configurable items. For now, just copy and paste the following into a new file. Feel free to modify the height and width if you want.

arena: (
    height: 100.0,
    width: 100.0,
)

Click here to continue to the next chapter

For simplicity, we will wrap all of our Config objects into a single PongConfig object backed by a single config.ron file, but know that you can just as easily keep them in separate files and read from each file separately.

To prepare for our BallConfig, add the following line to the top of config.rs:

use amethyst::core::cgmath::Vector2;

The BallConfig will replace the BALL_VELOCITY_X, BALL_VELOCITY_Y, BALL_RADIUS, and BALL_COLOR variables. We'll use a Vector2 to store the velocity for simplicity and to demonstrate how to add a non-trivial data type to a RON file. The BALL_COLOR was originally an array, but [Serde][serde] and RON handle arrays as tuples, so it will read in a tuple and convert the colour values to an array if needed by a particular function (e.g., in pong.rs).

#[derive(Debug, Deserialize, Serialize)]
pub struct BallConfig {
    pub velocity: Vector2<f32>,
    pub radius: f32,
    pub colour: (f32, f32, f32, f32),
}

We'll also add the Default trait to this config that will match what the full example uses.

impl Default for BallConfig {
    fn default() -> Self {
        BallConfig {
            velocity: Vector2::new(75.0, 50.0),
            radius: 2.5,
            colour: (1.0, 0.0, 0.0, 1.0),
        }
    }
}

Still in config.rs, add the following structure definition at the very bottom. This structure will be backed by the whole config.ron file.

#[derive(Debug, Default, Deserialize, Serialize)]
pub struct PongConfig {
    pub arena: ArenaConfig,
    pub ball: BallConfig,
}

Now we need to replace our usage of the BALL_* constants with our new BallConfig.

We use these values in pong.rs in the initialise_ball() function, so the substition is even simpler than the ArenaConfig.

In pong.rs, underneath our loading of the ArenaConfig, add the following lines

let (velocity_x, velocity_y, radius, colour) = {
    let config = world.read_resource::<BallConfig>();
    let c: [f32; 4] = [
        config.colour.0,
        config.colour.1,
        config.colour.2,
        config.colour.3,
    ];
    (config.velocity.x, config.velocity.y, config.radius, c)
};

Our functions expect a [f32; 4] array, so we had to convert the tuple to an array. This is relatively simple to do, but for more complex arrays it might be worth it to add a function to the impl BallConfig to avoid duplicating this effort.

Now, within the initialise_ball function, replace BALL_VELOCITY_X with velocity_x, BALL_VELOCITY_Y with velocity_y, BALL_RADIUS with radius, and BALL_COLOR with color.

Now we will modify our application initialisation. We don't want everyone to always access all the config files, so we need to add each resource separately so systems can use only what they want.

First, we need to change what main.rs is using. Change

use config::ArenaConfig;

to

use config::PongConfig;

Now, modify the run() function, from

let arena_config = ArenaConfig::load(&config);
[..]
    .with_resource(arena_config)
    .with_bundle(PongBundle::default())?

to

let pong_config = PongConfig::load(&config);
[..]
    .with_resource(pong_config.arena)
    .with_resource(pong_config.ball)
    .with_bundle(PongBundle::default())?

Now we need to modify our configuration file to allow multiple structures to be included. This is actually very easy with RON; we just add an additional level of nesting.

(
    arena: (
        height: 100.0,
        width: 100.0,
    ),
    ball: (
        velocity: Vector2(
            x: 75.0,
            y: 50.0,
        ),
        radius: 2.5,
        color: (1.0, 0.647, 0.0, 1.0),
    ),
)

This configuration sets the ball to be orange, while retaining the same size and velocity as the original example.

Click here to continue to the last chapter, configuring paddles

We're finally going to add a configuration struct for our Paddles. Because our Pong clone supports two players, we should let them configure each separately. Add the following to the config.rs file:

#[derive(Debug, Deserialize, Serialize)]
pub struct PaddleConfig {
    pub height: f32,
    pub width: f32,
    pub velocity: f32,
    pub colour: (f32, f32, f32, f32),
}

impl Default for PaddleConfig {
    fn default() -> Self {
        PaddleConfig {
            height: 15.0,
            width: 2.5,
            velocity: 75.0,
            color: (0.0, 0.0, 1.0, 1.0),
        }
    }
}

Just like the BallConfig, we need to read in the colour as a tuple instead of an array.

Now, to allow us to have two separate PaddleConfigs, we will wrap them in a bigger structure as follows:

#[derive(Debug, Default, Deserialize, Serialize)]
pub struct PaddlesConfig {
    pub left: PaddleConfig,
    pub right: PaddleConfig,
}

Now we need to add the PaddlesConfig to our PongConfig as shown below

pub struct PongConfig {
    pub arena: ArenaConfig,
    pub ball: BallConfig,
    pub paddles: PaddlesConfig,
}

and modify the main.rs's run() function to add our PaddleConfigs.

    .with_resource(pong_config.arena)
    .with_resource(pong_config.ball)
    .with_resource(pong_config.paddles)
    .with_bundle(PongBundle::default())?

We add the PaddlesConfig to the World, rather than as separate left and right configurations because Systems can only access resources with ID 0. Any resource added using World::add_resource is added using a default ID of 0. You must use World::add_resource_with_id to add multiple resources of the same type, but then the Systems cannot properly differentiate between them.

Replacing all instances of PADDLE_* will be similar to the BallConfig, as we only use those values for creating the paddle entities. However, we will need to separate the PaddlesConfig into left and right. To avoid issues with the borrow checker, we read the PaddlesConfig once and copy all of the values, unwrapping them in one big assignment statement. In initialise_paddles() in pong.rs, add this code below reading the ArenaConfig.

let (
    left_height,
    left_width,
    left_velocity,
    left_colour,
    right_height,
    right_width,
    right_velocity,
    right_colour,
) = {
    let config = &world.read_resource::<PaddlesConfig>();
    let cl: [f32; 4] = [
        config.left.colour.0,
        config.left.colour.1,
        config.left.colour.2,
        config.left.colour.3,
    ];
    let cr: [f32; 4] = [
        config.right.colour.0,
        config.right.colour.1,
        config.right.colour.2,
        config.right.colour.3,
    ];
    (
        config.left.height,
        config.left.width,
        config.left.velocity,
        cl,
        config.right.height,
        config.right.width,
        config.right.velocity,
        cr,
    )
};

Now, within this function, replace

let y = (arena_height - PADDLE_HEIGHT) / 2.0;

with

let left_y = (arena_height - left_height) / 2.0;
let right_y = (arena_height - right_height) / 2.0;

You will also need to repeat the calls to create_mesh and create_colour_material() so that you have a left and right mesh and left and right colour.

Now, use the left- and right-specific values in the world.create_entity() calls.

Now for the final modification of our config.ron file. For fun, let's make the right paddle yellow and keep the left paddle blue so the final config.ron file will be as follows:

(
    arena: (
        height: 100.0,
        width: 100.0,
    ),
    ball: (
        velocity: Vector2(
            x: 75.0,
            y: 50.0,
        ),
        radius: 2.5,
        color: (1.0, 0.647, 0.0, 1.0),
    ),
    paddles: (
        left: (
            height: 15.0,
            width: 2.5,
            velocity: 75.0,
            color: (0.0, 0.0, 1.0, 1.0),
        ),
        right: (
            height: 15.0,
            width: 2.5,
            velocity: 75.0,
            color: (0.0, 1.0, 1.0, 1.0),
        ),
    )
)