Sounds and events
In this section we will work on adding sound effects. In short, we want to play sounds in these circumstances:
- when the player hits a wall or an obstacle - to let them know they cannot get through
- when the player places a box on the correct spot - as an indication of "you've done it correctly"
- when the player places a box on the incorrect spot - as an indication that the move was wrong
Actually playing audio will not be too difficult as ggez provides this ability, but the biggest issue we have right now is that we need to determine when to play the sounds.
Let's take the box on correct spot example. We could probably use our game state system and loop through the boxes and the spots and determine when we are in this state and play the sound. But that is not going to work because we will be interating many times per second, and we will always be in this state as long as the box doesn't move, so we will attempt to play many times per second, which is not what we want. We could try to keep some state to know what we are currently playing, but that doesn't feel right. The problem is we cannot do this by iteratively checking state, we instead need a reactive model where we can be told something has just happenned, and we need to take an action. What I've described here is an event model, we need to fire an event when a box gets placed on a spot, and then when we receive this event on the other end we need to play the sound. The really good thing about this is that we will be able to re-use this event system for many other purposes.
Events infrastructure: How
Let's start by discussing how we will implement events. We will not use components or entities (although we could), instead we will use a resource very similar to the input queue. The parts of the code that need to enqueue events will need to get access to this resource, and we will then have a system which processes these events and take the appropriate actions.
What events
Let's discuss in more detail what events we will need:
- player hit obstacle - this can be an event in itself which we fire from the input system when we try to move but can't
- box placed on correct/incorrect spot - we can model this as a single event with a property inside it that tells us if the box/spot combination is correct - thinking a bit deeper about how we can achieve this, we can have an entity moved event, and when we receive that event we can check the entity id of that entity that just moved to see if it's a box and if it's on the right/wrong/any spot (this is an example of creating an event chain - an event from an event)
Events types
Now let's go into the implementation of events. We'll use an enum to define various event types. Now, we've used enums before (for the rendering type and the box colours) but this time we will take full advantage of the power of Rust enums. One of the most interesting things about them is that we actually attach properties to each enum variant.
Let's look at our events enum.
#![allow(unused)] fn main() { // events.rs #[derive(Debug)] pub enum Event { // Fired when the player hits an obstacle like a wall PlayerHitObstacle, // Fired when an entity is moved EntityMoved(EntityMoved), // Fired when the box is placed on a spot BoxPlacedOnSpot(BoxPlacedOnSpot), } }
Note the second EntityMoved and the second BoxPlacedOnSpot. Those are actually struct definitions where we can attach properties. Let's look at those structs now.
#![allow(unused)] fn main() { // events.rs pub type EntityId = u32; #[derive(Debug)] pub struct EntityMoved { pub id: EntityId, } #[derive(Debug)] pub struct BoxPlacedOnSpot { pub is_correct_spot: bool, } }
Event queue resource
Now let's add a resource for the event queue. We will have various systems writing to this queue and one system (the event system) consuming this queue. It's basically a multiple producer single consumer model.
#![allow(unused)] fn main() { // resources.rs #[derive(Default)] pub struct EventQueue { pub events: Vec<Event>, } }
And as always let's register this resource.
#![allow(unused)] fn main() { // resources.rs pub fn register_resources(world: &mut World) { world.insert(InputQueue::default()); world.insert(Gameplay::default()); world.insert(Time::default()); world.insert(EventQueue::default()); } }
Sending events
Now that we have a way to enqueue events, let's add the two events we need in the input_system: EntityMoved and PlayerHitObstacle.
#![allow(unused)] fn main() { // input_system.rs use crate::components::*; use crate::constants::*; use crate::events::{EntityMoved, Event}; use crate::resources::{EventQueue, Gameplay, InputQueue}; use ggez::event::KeyCode; use specs::{world::Index, Entities, Join, ReadStorage, System, Write, WriteStorage}; use std::collections::HashMap; pub struct InputSystem {} // System implementation impl<'a> System<'a> for InputSystem { // Data type SystemData = ( Write<'a, EventQueue>, Write<'a, InputQueue>, Write<'a, Gameplay>, Entities<'a>, WriteStorage<'a, Position>, ReadStorage<'a, Player>, ReadStorage<'a, Movable>, ReadStorage<'a, Immovable>, ); fn run(&mut self, data: Self::SystemData) { let ( mut events, mut input_queue, mut gameplay, entities, mut positions, players, movables, immovables, ) = data; let mut to_move = Vec::new(); for (position, _player) in (&positions, &players).join() { // Get the first key pressed if let Some(key) = input_queue.keys_pressed.pop() { // ... // ... // if it exists, we need to stop and not move anything // if it doesn't exist, we stop because we found a gap match immov.get(&pos) { Some(_id) => { to_move.clear(); events.events.push(Event::PlayerHitObstacle {}) } None => break, } } } } } } // We've just moved, so let's increase the number of moves if to_move.len() > 0 { gameplay.moves_count += 1; } // Now actually move what needs to be moved for (key, id) in to_move { let position = positions.get_mut(entities.entity(id)); if let Some(position) = position { match key { KeyCode::Up => position.y -= 1, KeyCode::Down => position.y += 1, KeyCode::Left => position.x -= 1, KeyCode::Right => position.x += 1, _ => (), } } // Fire an event for the entity that just moved events.events.push(Event::EntityMoved(EntityMoved { id })); } } } }
I've omitted some of the code in the original file for readability, but we are really just adding two lines in the right places.
Consuming events - event system
Now it's time to add a way to consume the events, which will be the events system. This system will contain the logic for what should happen when a specific event is received.
Let discuss how we will handle each event:
- Event::PlayerHitObstacle -> this is where the sound playing will go, but we'll come back to this when we add the audio bits
- Event::EntityMoved(EntityMoved { id }) -> this is where we will add the logic for checking if the entity that just moved is a box and whether it's on a spot or not
- Event::BoxPlacedOnSpot(BoxPlacedOnSpot { is_correct_spot }) -> this is where the sound playing will go, but we'll come back to this when we add the audio bits
#![allow(unused)] fn main() { // event_system.rs use crate::{ audio::AudioStore, components::*, events::{BoxPlacedOnSpot, EntityMoved, Event}, resources::EventQueue, }; use specs::{Entities, Join, ReadStorage, System, Write}; use std::collections::HashMap; pub struct EventSystem<'a> { pub context: &'a mut ggez::Context, } // System implementation impl<'a> System<'a> for EventSystem<'a> { // Data type SystemData = ( Write<'a, EventQueue>, Write<'a, AudioStore>, Entities<'a>, ReadStorage<'a, Box>, ReadStorage<'a, BoxSpot>, ReadStorage<'a, Position>, ); fn run(&mut self, data: Self::SystemData) { let (mut event_queue, mut audio_store, entities, boxes, box_spots, positions) = data; let mut new_events = Vec::new(); for event in event_queue.events.drain(..) { println!("New event: {:?}", event); match event { // play sound here audio_store.play_sound(self.context, &"wall".to_string()); } Event::EntityMoved(EntityMoved { id }) => { // An entity was just moved, check if it was a box and fire // more events if it's been moved on a spot. if let Some(the_box) = boxes.get(entities.entity(id)) { let box_spots_with_positions: HashMap<(u8, u8), &BoxSpot> = (&box_spots, &positions) .join() .map(|t| ((t.1.x, t.1.y), t.0)) .collect::<HashMap<_, _>>(); if let Some(box_position) = positions.get(entities.entity(id)) { // Check if there is a spot on this position, and if there // is if it's the correct or incorrect type if let Some(box_spot) = box_spots_with_positions.get(&(box_position.x, box_position.y)) { new_events.push(Event::BoxPlacedOnSpot(BoxPlacedOnSpot { is_correct_spot: (box_spot.colour == the_box.colour), })); } } } } Event::BoxPlacedOnSpot(BoxPlacedOnSpot { is_correct_spot }) => { // play sound here } } } event_queue.events.append(&mut new_events); } } }
Audio assets
Now that we have the event bits in place, let's add audio assets. I've selected 3 sounds from this asset pack, but feel free to select your own.
Correct sound here
Incorrect sound here
Wall sound here
Let's add these sounds to a new folder under resources.
.
├── resources
│ ├── images
│ │ ├── box_blue_1.png
│ │ ├── box_blue_2.png
│ │ ├── box_red_1.png
│ │ ├── box_red_2.png
│ │ ├── box_spot_blue.png
│ │ ├── box_spot_red.png
│ │ ├── floor.png
│ │ ├── player_1.png
│ │ ├── player_2.png
│ │ ├── player_3.png
│ │ └── wall.png
│ └── sounds
│ ├── correct.wav
│ ├── incorrect.wav
│ └── wall.wav
├── Cargo.lock
└── Cargo.toml
Audio store
Now in order to play the sound the wav files need to be loaded. To avoid loading them on the fly every time before we play the sound we'll create an audio store and load them up at the beginning of the game.
We'll use a resource for the audio store.
#![allow(unused)] fn main() { // audio.rs #[derive(Default)] pub struct AudioStore { pub sounds: HashMap<String, audio::Source>, } }
And as always let's register this resource.
#![allow(unused)] fn main() { // resources.rs pub fn register_resources(world: &mut World) { world.insert(InputQueue::default()); world.insert(Gameplay::default()); world.insert(Time::default()); world.insert(EventQueue::default()); world.insert(AudioStore::default()); } }
And let's add the code for initializing the store.
#![allow(unused)] fn main() { // audio.rs pub fn initialize_sounds(world: &mut World, context: &mut Context) { let mut audio_store = world.write_resource::<AudioStore>(); let sounds = ["correct", "incorrect", "wall"]; for sound in sounds.iter() { let sound_name = sound.to_string(); let sound_path = format!("/sounds/{}.wav", sound_name); let sound_source = audio::Source::new(context, sound_path).expect("expected sound loaded"); audio_store.sounds.insert(sound_name, sound_source); } } }
Playing audio
Finally, let's add the ability to play the sound in the store.
#![allow(unused)] fn main() { // audio.rs impl AudioStore { pub fn play_sound(&mut self, context: &mut Context, sound: &String) { let _ = self .sounds .get_mut(sound) .expect("expected sound") .play_detached(context); } } }
And now let's play in the event system.
#![allow(unused)] fn main() { // event_system.rs ); fn run(&mut self, data: Self::SystemData) { let (mut event_queue, mut audio_store, entities, boxes, box_spots, positions) = data; let mut new_events = Vec::new(); for event in event_queue.events.drain(..) { println!("New event: {:?}", event); match event { Event::PlayerHitObstacle => { // play sound here audio_store.play_sound(self.context, &"wall".to_string()); // ... } Event::BoxPlacedOnSpot(BoxPlacedOnSpot { is_correct_spot }) => { // play sound here let sound = if is_correct_spot { "correct" } else { "incorrect" }; audio_store.play_sound(self.context, &sound.to_string()) } } } }
Now let's run the game and enjoy those sound effects!
CODELINK: You can see the full code in this example here.