Micro MusicBox

Play some tunes

Bevy tracking Crates.io docs.rs

What?

This library provides a convenience wrapper around bevykiraaudio, handling all the setup for the common game audio scenario. This includes channel management, giving you control of the audio levels for your music, ambiance, sound effects and UI separately from the start.

Channel Types

Musicbox is configured with 4 channels, which a re split into two types:

Volume

Volume is calculated by multiplying a given channel's volume setting by the master volume setting. This means you can let players adjust either the overall game volume, or each of the three types individually. The 4 channels are assigned as such:

There are two types of channel: Singleton "main" channels, and multi-sound channels. Audio played on a main channel will loop until stopped, and will replace any currently playing audio on that same channel. multi-sound channels work exactly as they, well, sound - play one-off sounds without worrying about coordinating them with other sources.

Main channels also expose a cross-fade feature - either a basic cross-fade, in which the same audio tween is applied to the outgoing and incoming music tracks, or an in-out fade where the two tracks can have independent tweens.

How?

Quickstart

rust 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"); }); }

In-Depth

There is a plugin that just provides the layering on top of bevykiraaudio if you are already integrating with it, and a plugin group that will setup and configure bevykiraaudio for you if not. Some bevyiraaudio types are re-exported, so you can depend solely on microbevymusicbox if you don't have any advanced needs.

```rust use microbevymusicbox::{CombinedAudioPlugins, MusicBoxPlugin};

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

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

In order to use the the MusicBox type, you will need to implement the SuppliesAudio trait on a resource. This resource will need to be able to retrieve the requested audio track by name, although the specifics of what that name represents will depend on how you implement the trait.

Out of the box, there is a SuppliesAudio impl for AssetServer, allowing you to use resource paths. It is, however, recommended that you create your own impl for your own resource type.

```rust /// An example storage resource that allows assets to be retrieved by name, /// rather than by file path pub struct AssetHandles { // ...Other types... pub sounds: HashMap>, }

impl SuppliesAudio for AssetHandles { fn getaudiotrack(&self, name: T) -> Option> { self.sounds.get(&name.tostring()).map(Handle::cloneweak) } } ```

Finally, you need to use the MusicBox type as a SystemParam, alongside your SuppliesAudio impl. There is no binding of between MusicBox and SuppliesAudio, so you can use different impls in different systems as you please, as long as the SuppliesAudio resource has been added to your world

```rust /// 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 playsounds( mut events: EventReader, musicbox: MusicBox, ) { for PlaySoundEvent { sound } in events.iter() { musicbox.playeffect_once(sound); } } ```

Asset Licenses

The examples in this repository use assets available under the following licenses:

Compatibility

| musicbox version | bevy version | bka version | |------------------|--------------|-------------| | 0.6 | 0.10 | 0.15 | | 0.5 | 0.9 | 0.13 | | 0.4 | 0.8.0 | 0.12 |