Micro MusicBox

播放一些旋律

什么？

此库为bevy_kira_audio提供便利的包装，处理常见游戏音频场景的所有设置。这包括通道管理，让您可以从一开始就单独控制音乐、环境音、音效和UI的音量。

通道类型

Musicbox配置了4个通道，这些通道被分成两种类型

• 主通道；播放单个循环音频轨道。在此通道上开始另一个轨道将停止当前正在播放的轨道。支持当前轨道和下一轨道之间的交叉淡入。这包括“音乐”和“环境音”通道
• 背景通道；播放任意数量的单次声音。这些声音不会相互干扰或影响主通道。这包括“音效”和“UI音效”通道

音量

音量是通过将给定通道的音量设置乘以主音量设置来计算的。这意味着您可以允许玩家调整整体游戏音量，或者单独调整三种类型中的每一种。4个通道被分配如下

• "music" -> 音乐音量 * 主音量
• "ambiance" & "sfx" -> 音效音量 * 主音量
• "ui sfx" -> UI音量 * 主音量

有两种类型的通道：单例“主”通道和多声音通道。在主通道上播放的音频将循环播放，直到停止，并将替换该通道上正在播放的任何其他音频。多声音通道的工作方式就像它们听起来那样 - 播放一次性的声音，无需担心与其他来源协调。

主通道还公开了交叉淡入功能 - 要么是一个基本的交叉淡入，其中对出站和入站音乐轨道应用相同的音频缓动，要么是一个入站淡入，其中两个轨道可以具有独立的双曲函数。

如何？

快速入门

• 为资源实现SuppliesAudio（或使用内建的AssetServer上的实现）
• 将MusixBoc插件插件或CombinedAudioPlugins插件组包含在您的应用程序中，将您的SuppliesAudio实现作为泛型参数提供
• 将MusicBox<T: SuppliesAudio>用作系统上的参数
• 调用 MusicBox::play_* 方法之一来播放声音

fn main() {
    App::new()
        .add_plugins(CombinedAudioPlugins::<AssetServer>::new())
        .add_startup_system(|mut music_box: MusicBox<AssetServer>| {
            music_box.play_music("music/bing_bong.mp3");
        });
}

深入

如果已经与 bevy_kira_audio 集成，则有一个插件仅提供分层；如果没有，则有一个插件组会为您设置和配置 bevy_kira_audio。一些 bevy_ira_audio 类型被重新导出，所以如果您没有任何高级需求，可以仅依赖 micro_bevy_musicbox。

use micro_bevy_musicbox::{CombinedAudioPlugins, MusicBoxPlugin};

// Either
fn main() {
    App::new()
        .add_plugin(MusicBoxPlugin);
}

// Or
fn main() {
    App::new()
        .add_plugins(CombinedAudioPlugins);
}

为了使用 MusicBox 类型，您需要在资源上实现 SuppliesAudio 特性。此资源需要能够通过名称检索请求的音频轨道，尽管名称的具体含义将取决于您如何实现该特性。

默认情况下，有一个为 AssetServer 实现的 SuppliesAudio，允许您使用资源路径。然而，建议您为您的资源类型创建自己的实现。

/// An example storage resource that allows assets to be retrieved by name,
/// rather than by file path
#[derive(Resource)]
pub struct AssetHandles {
    // ...Other types...
    pub sounds: HashMap<String, Handle<AudioSource>>,
}

impl SuppliesAudio for AssetHandles {
	fn get_audio_track<T: ToString>(&self, name: T) -> Option<Handle<AudioSource>> {
		self.sounds.get(&name.to_string()).map(Handle::clone_weak)
	}
}

最后，您需要将 MusicBox 类型作为 SystemParam 使用，同时使用您的 SuppliesAudio 实现。MusicBox 和 SuppliesAudio 之间没有绑定，所以您可以根据需要在不同系统中使用不同的实现，只要将 SuppliesAudio 资源添加到您的世界中。

/// A simple event that causes a sound effect to be played.
/// N.B. In a real game, you probably just want to directly play a sound without events
pub struct PlaySoundEvent {
    pub sound: String,
}

// ...Register your event to your app...

/// A system that reads PlaySoundEvent events and plays the sound effect, using the
/// previously created `AssetHandles` resource as a supplier
pub fn play_sounds(
    mut events: EventReader<PlaySoundEvent>,
    music_box: MusicBox<AssetHandles>,
) {
    for PlaySoundEvent { sound } in events.iter() {
        music_box.play_effect_once(sound);
    }
}

资产许可

此存储库中的示例使用以下许可协议下的资产

• Rolemusic 的《The-Great-Madeja.mp3》根据CC-BY-4.0 Attribution License许可。
• Rolemusic 的《The-White-Kitty.mp3》根据CC-BY-4.0 Attribution License许可。
• Kenney 的《KenneyBlocks.ttf》根据CC-0 Public Domain License许可。

兼容性