DEV Community: Ethan Tang

Bevy #2: Space Shooter - The Player

Ethan Tang — Sat, 26 Sep 2020 21:52:11 +0000

NOTE: Since this has been written, Bevy has received many awesome, but sadly, breaking updates. The code in this guide is no longer maintained.

Welcome back! If you didn't see the previous article, you can find that here:

The Bevy Game Engine

Ethan Tang ・ Sep 22 '20

#rust #gamedev #tutorial

You'll need to download the assets here to follow along. (Kenney assets are great for any aspiring devs with questionable art skills, make sure to check out the rest of their stuff)
Again, setup your project the same way as the last time: cargo new <your-cool-name> and

`Cargo.toml`

[dependencies]
bevy = "0.2"

Now, make a folder structure with assets/textures in your projects, and move in some images from the asset pack into this folder. You can choose whatever, but for this tutorial I'm using playerShip1_blue.png, laserRed01.png, laserBlue01.png, and enemyRed1.png

Movement code

This is going to be a lot of repeat from last time, so here's the player movement code in full.

`main.rs`

use bevy::prelude::*;

struct Player {
    speed: f32, /* #1 */
}

fn main() {
    App::build()
        .add_resource(WindowDescriptor { /* #2 */
            title: "Space Shooter".to_string(),
            width: 1024,
            height: 1024,
            vsync: true,
            resizable: false,
            ..Default::default()
        })
        .add_resource(ClearColor(Color::rgb(0.0, 0.0, 0.0)))
        .add_default_plugins()
        .add_startup_system(setup.system())
        .add_system(player_control.system())
        .run();
}

fn setup(
    mut commands: Commands, 
    asset_server: Res<AssetServer>,
    mut materials: ResMut<Assets<ColorMaterial>>
) {
    let player_texture_handle = asset_server.load("assets/textures/playerShip1_blue.png").unwrap();/* #3 */
    commands
        .spawn(Camera2dComponents::default())
        .spawn(SpriteComponents {
            material: materials.add(player_texture_handle.into()),
            transform: Transform::from_translation(Vec3::new(0.0, -256.0, 0.0)),
            ..Default::default()
        })
        .with(Player { 
            speed: 400.0
        });
}

fn player_control(
    time: Res<Time>, /* #4 */
    keyboard_input: Res<Input<KeyCode>>,
    mut query: Query<(&Player, &mut Transform)>,
) {
    let mut movement = 0.0;
    if keyboard_input.pressed(KeyCode::A) {
        movement -= 1.0;
    }
    if keyboard_input.pressed(KeyCode::D) {
        movement += 1.0;
    }

    for (player, mut transform) in &mut query.iter() {
        transform.translate(Vec3::new(movement * player.speed * time.delta_seconds, 0.0, 0.0)) /* #4 */
    }
}

Most of this should be self-explanatory, except for a few key differences I want to highlight.

Our player struct now has a speed property that controls its speed. We use this property within the player_control system to move the player accordingly. We could just move this to a constant instead, but this is cleaner and takes advantage of the powers of ECS.
We've added in a WindowDescriptor. You can find more details here, but it basically tells the Window plugin how to construct the window. The ClearColor is changed as well, to get a black background.
Here because we want to draw something other than a rectangle (boring), we have to load a handle to the texture with AssetServer, a resource added in the default plugin.
Finally, we added another resource handle to our movement system because we need to use Time.delta_seconds to move our ship regardless of framerate.

Shooting

We could make the player entity directly spawn the laser bolts into the world, but the player isn't the only thing that needs to shoot. Later when we go to implement enemy shooting, we would need to copy that code over, and we'd have to edit both every time we wanted to make a change.

Luckily, ECS lets us modularize very easily by creating a new Component.

`main.rs`

struct Weapon {
    fired: bool,
    offset: Vec3,
    cooldown: Timer,
    material_id: usize,
}

fn main() {
    /**/
        .add_system_to_stage(stage::POST_UPDATE, weapons.system())
}

fn setup(
    /**/
) {
    /**/
        .with(Player { 
            speed: 400.0
        })
        .with(Weapon {
            fired: false,
            offset: Vec3::new(0.0, 30.0, 0.0),
            cooldown: Timer::from_seconds(0.4, false),
            material_id: 0,
        });
}

fn player_control(
    time: Res<Time>,
    keyboard_input: Res<Input<KeyCode>>,
    mut query: Query<(&Player, &mut Transform, Option<&mut Weapon>)>,
) {
    /**/

    for (player, mut transform, weapon) in &mut query.iter() {
        /**/
        if let Some(mut w) = weapon {
            w.fired = weapon_fired || w.fired;
        }
    }
}

fn weapons (
    time: Res<Time>,
    materials: Res<MaterialHandles>,
    mut query: Query<(&mut Weapon, &Transform)>,
) {
    for (mut weapon, transform) in &mut query.iter() {
        weapon.cooldown.tick(time.delta_seconds);
        if weapon.cooldown.finished && weapon.fired {
            println!("I'm firin' mah lazer");
            weapon.fired = false;
            weapon.cooldown.reset();
        }
    }
}

There are three new things introduced here: Timer, Option<Component> and stages.
Timer is a helper struct provided by bevy that doesn't do much but keep track of elapsed time and whether or not it is more than the specified length. This is extremely useful for weapon cooldowns.
Optional components let us set a component as optional within the query. This lets us support things in the future (if we decide to make a player without weapons)
stages let us control when bevy executes each system. By default, all systems are in stage::UPDATE, so by placing our weapon system in stage::POST_UPDATE, we can fire our weapon the same "frame" as the button was pressed.

UPDATE: Do not follow the stage code above, adding the weapons system to the post_update stage causes some weird stalling behavior the first time it is fired. Just use add_system as normal.

Lasers, lasers, lasers!

Obviously, we want to do more than just print out a message when we fire our laser, so let's add in our lasers. But first, let's talk about Assets. Assets<T> is basically a HashMap<Handle<T>, T>. When we run materials.add(), we are returned a new handle every time. If we do this for the lasers, every time we want to shoot we'd have to load in the texture again. To avoid this, we have to store our Handles as a resource.

`main.rs`

struct MaterialHandles(Vec<Handle<ColorMaterial>>);

fn setup(
    /**/
) -> {
    let laser_texture_handle = asset_server.load("assets/textures/laserBlue01.png").unwrap();
    commands
        .insert_resource(MaterialHandles(vec![materials.add(laser_texture_handle.into())]))
}

Now let's add the code to insert our lasers into the World. We need to access Commands, a thread-safe queue of operations on the ECS World in our weapons system, just like we did in our startup system.

`main.rs`

struct Laser {
    speed: f32,
}

fn weapons (
    mut commands: Commands, /* this must be the fist argument for bevy to recognize this as a system */
    time: Res<Time>,
    materials: Res<MaterialHandles>,
    mut query: Query<(&mut Weapon, &Transform)>,
) {
    for (mut weapon, transform) in &mut query.iter() {
        weapon.cooldown.tick(time.delta_seconds);
        if weapon.cooldown.finished && weapon.fired {
            commands
                .spawn(SpriteComponents {
                    material: materials.0[weapon.material_id],
                    transform: Transform::from_translation(weapon.offset + transform.translation()),
                    ..Default::default()
                })
                .with(Laser {
                    speed: 1000.0
                });
            weapon.fired = false;
            weapon.cooldown.reset();
        }
    }
}

Finally, we can add a movement system for lasers.

`main.rs`

fn main() {
    /**/
        .add_system(player_control.system())
        .add_system(laser_move.system())
        .add_system_to_stage(stage::POST_UPDATE, weapons.system())
}

fn laser_move(
    time: Res<Time>,
    mut query: Query<(&Laser, &mut Transform)>
) {
    for (laser, mut transform) in &mut query.iter() {
        transform.translate(Vec3::new(0.0, laser.speed * time.delta_seconds, 0.0) )
    }
}

Aaaand we're done! Thanks for following along! You can find the code for this tutorial here:

EthanYidong / learn-bevy

In the next article (WIP), we'll add in our enemies.

The Bevy Game Engine

Ethan Tang — Tue, 22 Sep 2020 19:46:16 +0000

NOTE: Since this has been written, Bevy has received many awesome, but sadly, breaking updates. The code in this guide is no longer maintained.

Since rust is The Best Language™, it's no surprise that it's been an attractive choice for game development. Well, when I say game development, I mean game engine development, because there are more rust game engines than actual rust games. Whenever Rust gamedev pops up in my feed, I try the new engine, follow the tutorial, and then go back to using Godot. Most of these engines sacrificed simplicity for modularity and extensibility and were generally not fun to work with.

What is Bevy?

Bevy is, in its own words, a "A refreshingly simple data-driven game engine built in Rust". It fully delivers on this promise, with possibly the least boilerplate necessary to write a game. Enough about that though, let's actually jump straight in to making! You should:

be familiar-ish with rust
have cargo installed with the latest stable rust

Writing an ECS app in Bevy

Bevy is based on ECS (Entity-Component-System) architecture, a new way of making games that is multi-threading friendly and brings a boost in performance vs standard models. It's so useful, Unity is implementing one for their engine. You can learn more on the bevy website, but here's a quick rundown.

Entities

Entities are collections of distinct components. They are represented by a single id within the bevy engine.

Components

Components can be whatever you want. They are represented by rust objects (structs or enumss), and are attached to entities.

Systems

Systems are functions. They run on collections of components. For example, the system

fn my_system(a: &ComponentA, b: &mut ComponentB) {
    //code here
}

runs on all entities with both ComponentA and ComponentB attached. You use &mut to gain write access. This system can also be written in "query form" as

fn my_system(query: mut Query<(&ComponentA, &mut ComponentB)>) {
    for (a, b) in &mut query.iter() {
        //code here
    }
}

This function runs only once, with Query::iter() giving you an iterator, so you can loop through it manually.

Resources

Resources are also rust objects, but they aren't associated with any Entity. Instead, they are available for all systems to use. They can be accessed like so:

fn my_system(
    resA: Res<ResourceA>, 
    resB: ResMut<ResourceB>, 
    query: mut Query<(&ComponentA, &mut ComponentB)>
) {
    for (a, b) in &mut query.iter() {
        //code here
    }
}

Enough talk, let's get started.

Create a new project with cargo new <project name>, and open in your editor of choice.

Let's edit Cargo.toml and add bevy to our dependencies. As of writing, bevy 0.2.1 is the latest version.

`Cargo.toml`

[dependencies]
bevy = "0.2"

Start by importing stuff into scope. The bevy crate is actually just a helper crate that collects all the libraries most games will need into one.

`main.rs`

use bevy::prelude::*;

To start using bevy, they provide a builder pattern to initialize the app.

`main.rs`

fn main() {
    App::build()
        /* setup goes here */
        .run();
}

If we run our app now, nothing happens. That's because App provides nothing by default. We use add_default_plugins() to add basic functionality.

`main.rs`

fn main() {
    App::build()
        .add_default_plugins()
        .run();
}

You should see a gray window pop up. Now, we need to populate our app with entities and components. For this, we use a startup system.

`main.rs`

fn main() {
    App::build()
        .add_default_plugins()
        .add_startup_system(setup.system())
        .run();
}

fn setup() {
    println!("setup!");
}

Unlike regular systems, startup systems are only run once, so you should see setup! printed in your console only once.

Now, we can add a sprite. To access our ECS World, we can add arguments to the startup system that will automatically be passed by bevy.

`main.rs`

fn setup(
    mut commands: Commands, 
    mut materials: ResMut<Assets<ColorMaterial>>
) {
    commands
        .spawn(Camera2dComponents::default())
        .spawn(SpriteComponents {
            material: materials.add(Color::rgb(0.2, 0.2, 0.8).into()),
            transform: Transform::from_translation(Vec3::new(0.0, 0.0, 0.0)),
            sprite: Sprite::new(Vec2::new(32.0, 32.0)),
            ..Default::default()
        });
}

Commands is a thread-safe buffer that will execute the commands passed to it to the ECS World.
ResMut<Assets<ColorMaterial>> is a mutable handle to the Resource Assets<ColorMaterial>, which is a collection of materials that you use to create sprites.
To display sprites, we first have to add a camera entity, which is used by the built in rendering system, and a sprite entity, which gets drawn by the rendering system.
Now you should see a small blue square in the middle of the window.

To wrap up this tutorial, let's add movement to our "game". We first must create a player marker component (a regular empty struct), and add it to the small square entity.

`main.rs`

struct Player;

fn setup(
    mut commands: Commands, 
    mut materials: ResMut<Assets<ColorMaterial>>
) {
    commands
        /* cut for brevity */
        .spawn(SpriteComponents /* cut for brevity */)
        .with(Player);
}

Next, we create a new system (a regular function) that runs on all entities with Transform and Player. This system also uses the keyboard input resource, which is created in a built-in system that that's part of add_default_plugins(). Additionally, we have to register the system to the builder.

`main.rs`

fn main() {
    App::build()
        .add_default_plugins()
        .add_startup_system(setup.system())
        .add_system(player_movement.system())
        .run();
}

fn player_movement(
    keyboard_input: Res<Input<KeyCode>>,
    mut query: Query<(&mut Transform, &Player)>,
) {
    for (mut transform, _player) in &mut query.iter() {
        let translation = transform.translation_mut();
        if keyboard_input.pressed(KeyCode::Right) {
            *translation.x_mut() += 1.0;
        }
    }
}

Now, when the right arrow key is pressed, our square shifts to the right. You can complete the movement if you'd like, but I'm too lazy to do it here. You can find the completed code here:

EthanYidong / learn-bevy

In the next article, we'll start building a more complex game. What are your thoughts on bevy? Please do share!

Bevy #2: Space Shooter - The Player

Ethan Tang ・ Sep 26 '20

#rust #gamedev #tutorial