More ergonomic spatial audio

[rparrett]

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

SpatialAudioSinks 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.

// 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.

[nerdachse]

Glancing over the changes I must applaud you. Looks way nicer to use. As soonish I want to incorporate spatial audio in my game, this would be a welcome addition!

[hymm]

Made some comments, but nothing blocking. This API definitely makes more sense to me than the status quo.

[rparrett]

I fixed a few major issues that weren't showing up in the examples and expanded the examples a bit so that you can move the listener around.

This has changed enough that previous approvals should probably be invalidated.

[rparrett]

Sorry for the noise. I'm done fiddling with this now.

[hymm]

Approving, but my nits should probably be fixed before merging.