From 66f35a5efeec0391deda3d8be6327809f278c051 Mon Sep 17 00:00:00 2001
From: RockasMockas <6405564+RockasMockas@users.noreply.github.com>
Date: Sat, 24 Aug 2024 05:01:17 +0200
Subject: [PATCH] feat: Integrating AudioCenter into bones (#445)

Moved AudioCenter out of jumpy -> bones.

Reworked to remove the dependency on using a game's settings struct
directly + streamlining the interfaces such as having both play_sound
and play_music be super easy to use, with extra _advanced and _custom
methods for different levels of advanced features/usability on music.

Tested both music/sounds work.
---
 Cargo.lock                                    |  28 +-
 framework_crates/bones_framework/Cargo.toml   |   2 +-
 framework_crates/bones_framework/src/audio.rs |  43 +++
 .../bones_framework/src/audio/audio_center.rs | 348 ++++++++++++++++++
 .../audio.rs => audio/audio_manager.rs}       |  20 +-
 framework_crates/bones_framework/src/lib.rs   |   5 +-
 .../bones_framework/src/render.rs             |   5 +-
 7 files changed, 419 insertions(+), 32 deletions(-)
 create mode 100644 framework_crates/bones_framework/src/audio.rs
 create mode 100644 framework_crates/bones_framework/src/audio/audio_center.rs
 rename framework_crates/bones_framework/src/{render/audio.rs => audio/audio_manager.rs} (89%)

diff --git a/Cargo.lock b/Cargo.lock
index a275607be0..358c9ce48f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -392,12 +392,6 @@ dependencies = [
  "syn 2.0.71",
 ]
 
-[[package]]
-name = "atomic-arena"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5450eca8ce5abcfd5520727e975ebab30ccca96030550406b0ca718b224ead10"
-
 [[package]]
 name = "atomic-polyfill"
 version = "1.0.3"
@@ -3207,9 +3201,9 @@ dependencies = [
 
 [[package]]
 name = "glam"
-version = "0.25.0"
+version = "0.28.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "151665d9be52f9bb40fc7966565d39666f2d1e69233571b71b87791c7e0528b3"
+checksum = "779ae4bf7e8421cf91c0b3b64e7e8b40b862fba4d393f59150042de7c4965a94"
 dependencies = [
  "mint",
 ]
@@ -4169,17 +4163,18 @@ dependencies = [
 
 [[package]]
 name = "kira"
-version = "0.8.7"
+version = "0.9.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8968f1eda49cdf4f6406fd5ffe590c3ca2778a1b0e50b5684974b138a99dfb2f"
+checksum = "5c48d4719537e9af8467214f42c76425afbde24fb33e8d06686ab764e2a98e0b"
 dependencies = [
- "atomic-arena",
  "cpal",
- "glam 0.25.0",
+ "glam 0.28.0",
  "mint",
+ "paste",
  "ringbuf",
  "send_wrapper",
  "symphonia",
+ "triple_buffer",
 ]
 
 [[package]]
@@ -7439,6 +7434,15 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "triple_buffer"
+version = "8.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e66931c8eca6381f0d34656a9341f09bd462010488c1a3bc0acd3f2d08dffce"
+dependencies = [
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "try-lock"
 version = "0.2.5"
diff --git a/framework_crates/bones_framework/Cargo.toml b/framework_crates/bones_framework/Cargo.toml
index eb67bf0e67..766498f60d 100644
--- a/framework_crates/bones_framework/Cargo.toml
+++ b/framework_crates/bones_framework/Cargo.toml
@@ -105,7 +105,7 @@ egui_plot  = "0.23"
 ttf-parser = { version = "0.24", default-features = false, optional = true }
 
 # Audio
-kira = { version = "0.8.6", features = ["cpal"], default-features = false, optional = true }
+kira = { version = "0.9.4", features = ["cpal"], default-features = false, optional = true }
 
 # Localization
 fluent         = { version = "0.15", optional = true }
diff --git a/framework_crates/bones_framework/src/audio.rs b/framework_crates/bones_framework/src/audio.rs
new file mode 100644
index 0000000000..c0ac4b6967
--- /dev/null
+++ b/framework_crates/bones_framework/src/audio.rs
@@ -0,0 +1,43 @@
+//! Audio session, systems, and resources.
+
+pub mod audio_center;
+pub mod audio_manager;
+
+use crate::prelude::*;
+pub use audio_center::*;
+pub use audio_manager::*;
+pub use kira;
+pub use kira::sound::static_sound::StaticSoundData;
+use kira::sound::static_sound::StaticSoundHandle;
+
+/// Name of the default bones audio session
+pub const DEFAULT_BONES_AUDIO_SESSION: &str = "BONES_AUDIO";
+
+/// Sets up audio-related resources and the default bones audio session
+pub fn game_plugin(game: &mut Game) {
+    AudioSource::register_schema();
+    game.init_shared_resource::<AudioCenter>();
+    game.insert_shared_resource(AudioManager::default());
+    game.init_shared_resource::<AssetServer>();
+
+    let session = game.sessions.create(DEFAULT_BONES_AUDIO_SESSION);
+    // Audio doesn't do any rendering
+    session.visible = false;
+    session
+        .stages
+        .add_system_to_stage(First, _process_audio_events)
+        .add_system_to_stage(Last, _kill_finished_audios);
+}
+
+/// Holds the handles and the volume to be played for a piece of Audio.
+#[derive(HasSchema)]
+#[schema(no_clone, no_default, opaque)]
+#[repr(C)]
+pub struct Audio {
+    /// The handle for the audio.
+    handle: StaticSoundHandle,
+    /// The original volume requested for the audio.
+    volume: f64,
+    /// The bones handle for the audio source.
+    bones_handle: Handle<AudioSource>,
+}
diff --git a/framework_crates/bones_framework/src/audio/audio_center.rs b/framework_crates/bones_framework/src/audio/audio_center.rs
new file mode 100644
index 0000000000..9440ea832c
--- /dev/null
+++ b/framework_crates/bones_framework/src/audio/audio_center.rs
@@ -0,0 +1,348 @@
+//! Audio Center resource and systems.
+
+use super::{Audio, AudioManager, AudioSource};
+use crate::prelude::*;
+use kira;
+use kira::{
+    sound::{static_sound::StaticSoundSettings, PlaybackState},
+    tween,
+    tween::Tween,
+    Volume,
+};
+use std::collections::VecDeque;
+use std::time::Duration;
+use tracing::warn;
+
+/// A resource that can be used to control game audios.
+#[derive(HasSchema)]
+#[schema(no_clone)]
+pub struct AudioCenter {
+    /// Buffer for audio events that have not yet been processed.
+    events: VecDeque<AudioEvent>,
+    /// The handle to the current music.
+    music: Option<Audio>,
+    /// The volume scale for main audio.
+    main_volume_scale: f32,
+    /// The volume scale for music.
+    music_volume_scale: f32,
+    /// The volume scale for sound effects.
+    effects_volume_scale: f32,
+    /// How long music should fade out for when stopping.
+    music_fade_duration: Duration,
+}
+
+impl Default for AudioCenter {
+    fn default() -> Self {
+        Self {
+            events: VecDeque::with_capacity(16),
+            music: None,
+            main_volume_scale: 1.0,
+            music_volume_scale: 1.0,
+            effects_volume_scale: 1.0,
+            music_fade_duration: Duration::from_millis(500),
+        }
+    }
+}
+
+impl AudioCenter {
+    /// Push an audio event to the queue for later processing.
+    pub fn push_event(&mut self, event: AudioEvent) {
+        self.events.push_back(event);
+    }
+
+    /// Returns the currently played music.
+    pub fn music(&self) -> Option<&Audio> {
+        self.music.as_ref()
+    }
+
+    /// Get the playback state of the current music.
+    pub fn music_state(&self) -> Option<PlaybackState> {
+        self.music().map(|m| m.handle.state())
+    }
+
+    /// Play a sound. These are usually short audios that indicate something
+    /// happened in game, e.g. a player jump, an explosion, etc.
+    /// Volume is scaled by both main_volume_scale, and effects_volume_scale.
+    pub fn play_sound(&mut self, sound_source: Handle<AudioSource>, volume: f64) {
+        self.events.push_back(AudioEvent::PlaySound {
+            sound_source,
+            volume,
+        })
+    }
+
+    /// Plays music, forcibly stopping any current music.
+    /// Volume is scaled by both main_volume_scale and music_volume_scale.
+    pub fn play_music(&mut self, sound_source: Handle<AudioSource>, volume: f64, loop_music: bool) {
+        let clamped_volume = volume.clamp(0.0, 1.0);
+        let mut settings = StaticSoundSettings::new().volume(Volume::Amplitude(clamped_volume));
+
+        if loop_music {
+            settings = settings.loop_region(kira::sound::Region {
+                start: 0.0.into(),
+                end: kira::sound::EndPosition::EndOfAudio,
+            });
+        }
+
+        self.events.push_back(AudioEvent::PlayMusic {
+            sound_source,
+            sound_settings: Box::new(settings),
+            force_restart: true,
+        });
+    }
+
+    /// Plays music with advanced settings.
+    /// Volume is scaled by both main_volume_scale and music_volume_scale.
+    ///
+    /// # Parameters
+    ///
+    /// * `sound_source` - The handle for the audio source to play
+    /// * `volume` - The volume to play the music at (0.0 to 1.0)
+    /// * `loop_music` - Whether the music should loop indefinitely
+    /// * `reverse` - Whether to play the audio in reverse
+    /// * `start_position` - The position in seconds to start playback from
+    /// * `playback_rate` - The playback rate (1.0 is normal speed, 0.5 is half speed, 2.0 is double speed)
+    /// * `skip_restart` - If true, won't restart the music if it's already playing the same track
+    #[allow(clippy::too_many_arguments)]
+    pub fn play_music_advanced(
+        &mut self,
+        sound_source: Handle<AudioSource>,
+        volume: f64,
+        loop_music: bool,
+        reverse: bool,
+        start_position: f64,
+        playback_rate: f64,
+        skip_restart: bool,
+    ) {
+        let clamped_volume = volume.clamp(0.0, 1.0);
+        let mut settings = StaticSoundSettings::new()
+            .volume(Volume::Amplitude(clamped_volume))
+            .start_position(kira::sound::PlaybackPosition::Seconds(start_position))
+            .reverse(reverse)
+            .playback_rate(playback_rate);
+
+        if loop_music {
+            settings = settings.loop_region(kira::sound::Region {
+                start: 0.0.into(),
+                end: kira::sound::EndPosition::EndOfAudio,
+            });
+        }
+
+        self.events.push_back(AudioEvent::PlayMusic {
+            sound_source,
+            sound_settings: Box::new(settings),
+            force_restart: !skip_restart,
+        });
+    }
+
+    /// Plays music with custom StaticSoundSettings.
+    /// Volume is scaled by both main_volume_scale and music_volume_scale.
+    pub fn play_music_custom(
+        &mut self,
+        sound_source: Handle<AudioSource>,
+        sound_settings: StaticSoundSettings,
+        skip_restart: bool,
+    ) {
+        self.events.push_back(AudioEvent::PlayMusic {
+            sound_source,
+            sound_settings: Box::new(sound_settings),
+            force_restart: !skip_restart,
+        });
+    }
+
+    /// Sets the volume scale for main audio within the range of 0.0 to 1.0.
+    /// The main volume scale impacts all other volume scales.
+    pub fn set_main_volume_scale(&mut self, main: f32) {
+        self.main_volume_scale = main.clamp(0.0, 1.0);
+    }
+
+    /// Sets the volume scale for music within the range of 0.0 to 1.0.
+    pub fn set_music_volume_scale(&mut self, music: f32) {
+        self.music_volume_scale = music.clamp(0.0, 1.0);
+    }
+
+    /// Sets the volume scale for effects within the range of 0.0 to 1.0.
+    pub fn set_effects_volume_scale(&mut self, effects: f32) {
+        self.effects_volume_scale = effects.clamp(0.0, 1.0);
+    }
+
+    /// Sets the volume scales for main, music, and effects within the range of 0.0 to 1.0.
+    pub fn set_volume_scales(&mut self, main: f32, music: f32, effects: f32) {
+        self.set_main_volume_scale(main);
+        self.set_music_volume_scale(music);
+        self.set_effects_volume_scale(effects);
+        self.events.push_back(AudioEvent::VolumeScaleUpdate {
+            main_volume_scale: self.main_volume_scale,
+            music_volume_scale: self.music_volume_scale,
+            effects_volume_scale: self.effects_volume_scale,
+        });
+    }
+
+    /// Returns the main volume scale (which impacts all other volume scales).
+    pub fn main_volume_scale(&self) -> f32 {
+        self.main_volume_scale
+    }
+
+    /// Returns the music volume scale.
+    pub fn music_volume_scale(&self) -> f32 {
+        self.music_volume_scale
+    }
+
+    /// Returns the volume scale for sound effects.
+    pub fn effects_volume_scale(&self) -> f32 {
+        self.effects_volume_scale
+    }
+    /// Returns the duration for music fade out.
+    pub fn music_fade_duration(&self) -> Duration {
+        self.music_fade_duration
+    }
+
+    /// Sets the duration for music fade out.
+    pub fn set_music_fade_duration(&mut self, duration: Duration) {
+        self.music_fade_duration = duration;
+    }
+}
+
+/// An audio event that may be sent to the [`AudioCenter`] resource for
+/// processing.
+#[derive(Clone, Debug)]
+pub enum AudioEvent {
+    /// Update the volume of all audios using the new scale values.
+    /// This event is used to adjust the overall volume of the application.
+    VolumeScaleUpdate {
+        /// The main volume scale factor.
+        main_volume_scale: f32,
+        /// The music volume scale factor.
+        music_volume_scale: f32,
+        /// The effects volume scale factor.
+        effects_volume_scale: f32,
+    },
+    /// Play some music.
+    ///
+    /// Any current music is stopped if force_restart is true or if the new music is different.
+    PlayMusic {
+        /// The handle for the music.
+        sound_source: Handle<AudioSource>,
+        /// The settings for the music.
+        sound_settings: Box<StaticSoundSettings>,
+        /// Whether to force restart the music even if it's the same as the current music.
+        force_restart: bool,
+    },
+    /// Play a sound.
+    PlaySound {
+        /// The handle to the sound to play.
+        sound_source: Handle<AudioSource>,
+        /// The volume to play the sound at.
+        volume: f64,
+    },
+}
+
+/// Internally used sytem for processing audio events in the bones audio session.
+pub fn _process_audio_events(
+    mut audio_manager: ResMut<AudioManager>,
+    mut audio_center: ResMut<AudioCenter>,
+    assets: ResInit<AssetServer>,
+    mut entities: ResMut<Entities>,
+    mut audios: CompMut<Audio>,
+) {
+    for event in audio_center.events.drain(..).collect::<Vec<_>>() {
+        match event {
+            AudioEvent::VolumeScaleUpdate {
+                main_volume_scale,
+                music_volume_scale,
+                effects_volume_scale,
+            } => {
+                let tween = Tween::default();
+                // Update music volume
+                if let Some(music) = &mut audio_center.music {
+                    let volume =
+                        (main_volume_scale as f64) * (music_volume_scale as f64) * music.volume;
+                    music.handle.set_volume(volume, tween);
+                }
+                // Update sound volumes
+                for audio in audios.iter_mut() {
+                    let volume =
+                        (main_volume_scale as f64) * (effects_volume_scale as f64) * audio.volume;
+                    audio.handle.set_volume(volume, tween);
+                }
+            }
+            AudioEvent::PlayMusic {
+                sound_source,
+                mut sound_settings,
+                force_restart,
+            } => {
+                let should_play = force_restart
+                    || audio_center.music.as_ref().map_or(true, |current_music| {
+                        sound_source != current_music.bones_handle
+                    });
+
+                if should_play {
+                    // Stop the current music
+                    if let Some(mut music) = audio_center.music.take() {
+                        let tween = Tween {
+                            start_time: kira::StartTime::Immediate,
+                            duration: audio_center.music_fade_duration,
+                            easing: tween::Easing::Linear,
+                        };
+                        music.handle.stop(tween);
+                    }
+                    // Scale the requested volume by the volume scales
+                    let volume = match sound_settings.volume {
+                        tween::Value::Fixed(vol) => vol.as_amplitude(),
+                        _ => 1.0,
+                    };
+                    let scaled_volume = (audio_center.main_volume_scale as f64)
+                        * (audio_center.music_volume_scale as f64)
+                        * volume;
+                    sound_settings.volume = tween::Value::Fixed(Volume::Amplitude(scaled_volume));
+                    // Play the new music
+                    let sound_data = assets.get(sound_source).with_settings(*sound_settings);
+                    match audio_manager.play(sound_data) {
+                        Err(err) => warn!("Error playing music: {err}"),
+                        Ok(handle) => {
+                            audio_center.music = Some(Audio {
+                                handle,
+                                volume,
+                                bones_handle: sound_source,
+                            })
+                        }
+                    }
+                }
+            }
+            AudioEvent::PlaySound {
+                sound_source,
+                volume,
+            } => {
+                let scaled_volume = (audio_center.main_volume_scale as f64)
+                    * (audio_center.effects_volume_scale as f64)
+                    * volume;
+                let sound_data = assets
+                    .get(sound_source)
+                    .with_settings(StaticSoundSettings::default().volume(scaled_volume));
+                match audio_manager.play(sound_data) {
+                    Err(err) => warn!("Error playing sound: {err}"),
+                    Ok(handle) => {
+                        let audio_ent = entities.create();
+                        audios.insert(
+                            audio_ent,
+                            Audio {
+                                handle,
+                                volume,
+                                bones_handle: sound_source,
+                            },
+                        );
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Internally used sytem for killing finished audios (generally sounds) which were emitted as separate entities.
+/// Used in the bones audio session.
+pub fn _kill_finished_audios(entities: Res<Entities>, audios: Comp<Audio>, mut commands: Commands) {
+    for (audio_ent, audio) in entities.iter_with(&audios) {
+        if audio.handle.state() == PlaybackState::Stopped {
+            commands.add(move |mut entities: ResMut<Entities>| entities.kill(audio_ent));
+        }
+    }
+}
diff --git a/framework_crates/bones_framework/src/render/audio.rs b/framework_crates/bones_framework/src/audio/audio_manager.rs
similarity index 89%
rename from framework_crates/bones_framework/src/render/audio.rs
rename to framework_crates/bones_framework/src/audio/audio_manager.rs
index 73afbcef9a..201bd513ed 100644
--- a/framework_crates/bones_framework/src/render/audio.rs
+++ b/framework_crates/bones_framework/src/audio/audio_manager.rs
@@ -1,29 +1,21 @@
-//! Audio components.
-
-use std::io::Cursor;
+//! Audio Manager resource and systems.
 
 use crate::prelude::*;
-
-pub use kira::{self, sound::static_sound::StaticSoundData};
+use kira;
 use kira::{
     manager::{
         backend::{cpal::CpalBackend, mock::MockBackend, Backend},
         AudioManager as KiraAudioManager,
     },
-    sound::SoundData,
+    sound::{static_sound::StaticSoundData, SoundData},
 };
-
-/// The game plugin for the audio system.
-pub fn game_plugin(game: &mut Game) {
-    AudioSource::register_schema();
-    game.insert_shared_resource(AudioManager::default());
-    game.init_shared_resource::<AssetServer>();
-}
+use std::io::Cursor;
 
 /// The audio manager resource which can be used to play sounds.
 #[derive(HasSchema, Deref, DerefMut)]
 #[schema(no_clone)]
 pub struct AudioManager(KiraAudioManager<CpalWithFallbackBackend>);
+
 impl Default for AudioManager {
     fn default() -> Self {
         Self(KiraAudioManager::<CpalWithFallbackBackend>::new(default()).unwrap())
@@ -93,7 +85,7 @@ impl AssetLoader for AudioLoader {
     ) -> futures::future::Boxed<anyhow::Result<SchemaBox>> {
         let bytes = bytes.to_vec();
         Box::pin(async move {
-            let data = StaticSoundData::from_cursor(Cursor::new(bytes), default())?;
+            let data = StaticSoundData::from_cursor(Cursor::new(bytes))?;
             Ok(SchemaBox::new(AudioSource(data)))
         })
     }
diff --git a/framework_crates/bones_framework/src/lib.rs b/framework_crates/bones_framework/src/lib.rs
index f12d2ab1d1..ef7ddc499c 100644
--- a/framework_crates/bones_framework/src/lib.rs
+++ b/framework_crates/bones_framework/src/lib.rs
@@ -52,6 +52,9 @@ pub mod storage;
 pub mod time;
 pub mod utils;
 
+#[cfg(feature = "audio")]
+pub mod audio;
+
 #[cfg(feature = "ui")]
 pub mod debug;
 
@@ -93,7 +96,7 @@ impl lib::GamePlugin for DefaultGamePlugin {
     #[allow(unused_variables)]
     fn install(self, game: &mut lib::Game) {
         #[cfg(feature = "audio")]
-        game.install_plugin(render::audio::game_plugin);
+        game.install_plugin(audio::game_plugin);
 
         #[cfg(feature = "scripting")]
         game.install_plugin(bones_scripting::ScriptingGamePlugin::default());
diff --git a/framework_crates/bones_framework/src/render.rs b/framework_crates/bones_framework/src/render.rs
index a1fdc863fe..ba58566c45 100644
--- a/framework_crates/bones_framework/src/render.rs
+++ b/framework_crates/bones_framework/src/render.rs
@@ -7,15 +7,12 @@ pub mod prelude {
     pub use super::{camera::*, color::*, line::*, sprite::*, tilemap::*, transform::*};
 
     #[cfg(feature = "audio")]
-    pub use super::audio::*;
+    pub use super::super::audio::*;
 
     #[cfg(feature = "ui")]
     pub use super::ui::{widgets::*, *};
 }
 
-#[cfg(feature = "audio")]
-pub mod audio;
-
 pub mod camera;
 pub mod color;
 pub mod line;