39c68e3f92
# Objective
Spatial audio was heroically thrown together at the last minute for Bevy
0.10, but right now it's a bit of a pain to use -- users need to
manually update audio sinks with the position of the listener / emitter.
Hopefully the migration guide entry speaks for itself.
## Solution
Add a new `SpatialListener` component and automatically update sinks
with the position of the listener and and emitter.
## Changelog
`SpatialAudioSink`s are now automatically updated with positions of
emitters and listeners.
## Migration Guide
Spatial audio now automatically uses the transform of the `AudioBundle`
and of an entity with a `SpatialListener` component.
If you were manually scaling emitter/listener positions, you can use the
`spatial_scale` field of `AudioPlugin` instead.
```rust
// Old
commands.spawn(
SpatialAudioBundle {
source: asset_server.load("sounds/Windless Slopes.ogg"),
settings: PlaybackSettings::LOOP,
spatial: SpatialSettings::new(listener_position, gap, emitter_position),
},
);
fn update(
emitter_query: Query<(&Transform, &SpatialAudioSink)>,
listener_query: Query<&Transform, With<Listener>>,
) {
let listener = listener_query.single();
for (transform, sink) in &emitter_query {
sink.set_emitter_position(transform.translation);
sink.set_listener_position(*listener, gap);
}
}
// New
commands.spawn((
SpatialBundle::from_transform(Transform::from_translation(emitter_position)),
AudioBundle {
source: asset_server.load("sounds/Windless Slopes.ogg"),
settings: PlaybackSettings::LOOP.with_spatial(true),
},
));
commands.spawn((
SpatialBundle::from_transform(Transform::from_translation(listener_position)),
SpatialListener::new(gap),
));
```
## Discussion
I removed `SpatialAudioBundle` because the `SpatialSettings` component
was made mostly redundant, and without that it was identical to
`AudioBundle`.
`SpatialListener` is a bare component and not a bundle which is feeling
like a maybe a strange choice. That happened from a natural aversion
both to nested bundles and to duplicating `Transform` etc in bundles and
from figuring that it is likely to just be tacked on to some other
bundle (player, head, camera) most of the time.
Let me know what you think about these things / everything else.
---------
Co-authored-by: Mike <mike.hsu@gmail.com>
112 lines
3.4 KiB
Rust
112 lines
3.4 KiB
Rust
//! Audio support for the game engine Bevy
|
|
//!
|
|
//! ```no_run
|
|
//! # use bevy_ecs::prelude::*;
|
|
//! # use bevy_audio::{AudioBundle, AudioPlugin, PlaybackSettings};
|
|
//! # use bevy_asset::{AssetPlugin, AssetServer};
|
|
//! # use bevy_app::{App, AppExit, NoopPluginGroup as MinimalPlugins, Startup};
|
|
//! fn main() {
|
|
//! App::new()
|
|
//! .add_plugins((MinimalPlugins, AssetPlugin::default(), AudioPlugin::default()))
|
|
//! .add_systems(Startup, play_background_audio)
|
|
//! .run();
|
|
//! }
|
|
//!
|
|
//! fn play_background_audio(asset_server: Res<AssetServer>, mut commands: Commands) {
|
|
//! commands.spawn(AudioBundle {
|
|
//! source: asset_server.load("background_audio.ogg"),
|
|
//! settings: PlaybackSettings::LOOP,
|
|
//! });
|
|
//! }
|
|
//! ```
|
|
|
|
#![forbid(unsafe_code)]
|
|
#![allow(clippy::type_complexity)]
|
|
#![warn(missing_docs)]
|
|
|
|
mod audio;
|
|
mod audio_output;
|
|
mod audio_source;
|
|
mod pitch;
|
|
mod sinks;
|
|
|
|
#[allow(missing_docs)]
|
|
pub mod prelude {
|
|
#[doc(hidden)]
|
|
pub use crate::{
|
|
AudioBundle, AudioSink, AudioSinkPlayback, AudioSource, AudioSourceBundle, Decodable,
|
|
GlobalVolume, Pitch, PitchBundle, PlaybackSettings, SpatialAudioSink, SpatialListener,
|
|
};
|
|
}
|
|
|
|
pub use audio::*;
|
|
pub use audio_source::*;
|
|
pub use pitch::*;
|
|
|
|
pub use rodio::cpal::Sample as CpalSample;
|
|
pub use rodio::source::Source;
|
|
pub use rodio::Sample;
|
|
pub use sinks::*;
|
|
|
|
use bevy_app::prelude::*;
|
|
use bevy_asset::{Asset, AssetApp};
|
|
use bevy_ecs::prelude::*;
|
|
use bevy_transform::TransformSystem;
|
|
|
|
use audio_output::*;
|
|
|
|
/// Set for the audio playback systems, so they can share a run condition
|
|
#[derive(SystemSet, Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
|
|
struct AudioPlaySet;
|
|
|
|
/// Adds support for audio playback to a Bevy Application
|
|
///
|
|
/// Insert an [`AudioBundle`] onto your entities to play audio.
|
|
#[derive(Default)]
|
|
pub struct AudioPlugin {
|
|
/// The global volume for all audio entities with a [`Volume::Relative`] volume.
|
|
pub global_volume: GlobalVolume,
|
|
/// The scale factor applied to the positions of audio sources and listeners for
|
|
/// spatial audio.
|
|
pub spatial_scale: SpatialScale,
|
|
}
|
|
|
|
impl Plugin for AudioPlugin {
|
|
fn build(&self, app: &mut App) {
|
|
app.insert_resource(self.global_volume)
|
|
.insert_resource(self.spatial_scale)
|
|
.configure_sets(
|
|
PostUpdate,
|
|
AudioPlaySet
|
|
.run_if(audio_output_available)
|
|
.after(TransformSystem::TransformPropagate), // For spatial audio transforms
|
|
)
|
|
.init_resource::<AudioOutput>();
|
|
|
|
#[cfg(any(feature = "mp3", feature = "flac", feature = "wav", feature = "vorbis"))]
|
|
{
|
|
app.add_audio_source::<AudioSource>();
|
|
app.init_asset_loader::<AudioLoader>();
|
|
}
|
|
|
|
app.add_audio_source::<Pitch>();
|
|
}
|
|
}
|
|
|
|
impl AddAudioSource for App {
|
|
fn add_audio_source<T>(&mut self) -> &mut Self
|
|
where
|
|
T: Decodable + Asset,
|
|
f32: rodio::cpal::FromSample<T::DecoderItem>,
|
|
{
|
|
self.init_asset::<T>().add_systems(
|
|
PostUpdate,
|
|
play_queued_audio_system::<T>.in_set(AudioPlaySet),
|
|
);
|
|
self.add_systems(PostUpdate, cleanup_finished_audio::<T>.in_set(AudioPlaySet));
|
|
self.add_systems(PostUpdate, update_emitter_positions.in_set(AudioPlaySet));
|
|
self.add_systems(PostUpdate, update_listener_positions.in_set(AudioPlaySet));
|
|
self
|
|
}
|
|
}
|