bevy/examples/audio/spatial_audio_2d.rs

141 lines
4.1 KiB
Rust
Raw Normal View History

//! This example illustrates how to load and play an audio file, and control where the sounds seems to come from.
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
use bevy::{
audio::{AudioPlugin, SpatialScale},
Migrate from `LegacyColor` to `bevy_color::Color` (#12163) # Objective - As part of the migration process we need to a) see the end effect of the migration on user ergonomics b) check for serious perf regressions c) actually migrate the code - To accomplish this, I'm going to attempt to migrate all of the remaining user-facing usages of `LegacyColor` in one PR, being careful to keep a clean commit history. - Fixes #12056. ## Solution I've chosen to use the polymorphic `Color` type as our standard user-facing API. - [x] Migrate `bevy_gizmos`. - [x] Take `impl Into<Color>` in all `bevy_gizmos` APIs - [x] Migrate sprites - [x] Migrate UI - [x] Migrate `ColorMaterial` - [x] Migrate `MaterialMesh2D` - [x] Migrate fog - [x] Migrate lights - [x] Migrate StandardMaterial - [x] Migrate wireframes - [x] Migrate clear color - [x] Migrate text - [x] Migrate gltf loader - [x] Register color types for reflection - [x] Remove `LegacyColor` - [x] Make sure CI passes Incidental improvements to ease migration: - added `Color::srgba_u8`, `Color::srgba_from_array` and friends - added `set_alpha`, `is_fully_transparent` and `is_fully_opaque` to the `Alpha` trait - add and immediately deprecate (lol) `Color::rgb` and friends in favor of more explicit and consistent `Color::srgb` - standardized on white and black for most example text colors - added vector field traits to `LinearRgba`: ~~`Add`, `Sub`, `AddAssign`, `SubAssign`,~~ `Mul<f32>` and `Div<f32>`. Multiplications and divisions do not scale alpha. `Add` and `Sub` have been cut from this PR. - added `LinearRgba` and `Srgba` `RED/GREEN/BLUE` - added `LinearRgba_to_f32_array` and `LinearRgba::to_u32` ## Migration Guide Bevy's color types have changed! Wherever you used a `bevy::render::Color`, a `bevy::color::Color` is used instead. These are quite similar! Both are enums storing a color in a specific color space (or to be more precise, using a specific color model). However, each of the different color models now has its own type. TODO... - `Color::rgba`, `Color::rgb`, `Color::rbga_u8`, `Color::rgb_u8`, `Color::rgb_from_array` are now `Color::srgba`, `Color::srgb`, `Color::srgba_u8`, `Color::srgb_u8` and `Color::srgb_from_array`. - `Color::set_a` and `Color::a` is now `Color::set_alpha` and `Color::alpha`. These are part of the `Alpha` trait in `bevy_color`. - `Color::is_fully_transparent` is now part of the `Alpha` trait in `bevy_color` - `Color::r`, `Color::set_r`, `Color::with_r` and the equivalents for `g`, `b` `h`, `s` and `l` have been removed due to causing silent relatively expensive conversions. Convert your `Color` into the desired color space, perform your operations there, and then convert it back into a polymorphic `Color` enum. - `Color::hex` is now `Srgba::hex`. Call `.into` or construct a `Color::Srgba` variant manually to convert it. - `WireframeMaterial`, `ExtractedUiNode`, `ExtractedDirectionalLight`, `ExtractedPointLight`, `ExtractedSpotLight` and `ExtractedSprite` now store a `LinearRgba`, rather than a polymorphic `Color` - `Color::rgb_linear` and `Color::rgba_linear` are now `Color::linear_rgb` and `Color::linear_rgba` - The various CSS color constants are no longer stored directly on `Color`. Instead, they're defined in the `Srgba` color space, and accessed via `bevy::color::palettes::css`. Call `.into()` on them to convert them into a `Color` for quick debugging use, and consider using the much prettier `tailwind` palette for prototyping. - The `LIME_GREEN` color has been renamed to `LIMEGREEN` to comply with the standard naming. - Vector field arithmetic operations on `Color` (add, subtract, multiply and divide by a f32) have been removed. Instead, convert your colors into `LinearRgba` space, and perform your operations explicitly there. This is particularly relevant when working with emissive or HDR colors, whose color channel values are routinely outside of the ordinary 0 to 1 range. - `Color::as_linear_rgba_f32` has been removed. Call `LinearRgba::to_f32_array` instead, converting if needed. - `Color::as_linear_rgba_u32` has been removed. Call `LinearRgba::to_u32` instead, converting if needed. - Several other color conversion methods to transform LCH or HSL colors into float arrays or `Vec` types have been removed. Please reimplement these externally or open a PR to re-add them if you found them particularly useful. - Various methods on `Color` such as `rgb` or `hsl` to convert the color into a specific color space have been removed. Convert into `LinearRgba`, then to the color space of your choice. - Various implicitly-converting color value methods on `Color` such as `r`, `g`, `b` or `h` have been removed. Please convert it into the color space of your choice, then check these properties. - `Color` no longer implements `AsBindGroup`. Store a `LinearRgba` internally instead to avoid conversion costs. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com> Co-authored-by: Afonso Lage <lage.afonso@gmail.com> Co-authored-by: Rob Parrett <robparrett@gmail.com> Co-authored-by: Zachary Harrold <zac@harrold.com.au>
2024-02-29 19:35:12 +00:00
color::palettes::css::*,
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
prelude::*,
sprite::MaterialMesh2dBundle,
};
/// Spatial audio uses the distance to attenuate the sound volume. In 2D with the default camera,
/// 1 pixel is 1 unit of distance, so we use a scale so that 100 pixels is 1 unit of distance for
/// audio.
const AUDIO_SCALE: f32 = 1. / 100.0;
fn main() {
App::new()
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
.add_plugins(DefaultPlugins.set(AudioPlugin {
default_spatial_scale: SpatialScale::new_2d(AUDIO_SCALE),
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
..default()
}))
.add_systems(Startup, setup)
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
.add_systems(Update, update_emitters)
.add_systems(Update, update_listener)
.run();
}
fn setup(
mut commands: Commands,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<ColorMaterial>>,
asset_server: Res<AssetServer>,
) {
// Space between the two ears
let gap = 400.0;
bevy_audio: ECS-based API redesign (#8424) # Objective Improve the `bevy_audio` API to make it more user-friendly and ECS-idiomatic. This PR is a first-pass at addressing some of the most obvious (to me) problems. In the interest of keeping the scope small, further improvements can be done in future PRs. The current `bevy_audio` API is very clunky to work with, due to how it (ab)uses bevy assets to represent audio sinks. The user needs to write a lot of boilerplate (accessing `Res<Assets<AudioSink>>`) and deal with a lot of cognitive overhead (worry about strong vs. weak handles, etc.) in order to control audio playback. Audio playback is initiated via a centralized `Audio` resource, which makes it difficult to keep track of many different sounds playing in a typical game. Further, everything carries a generic type parameter for the sound source type, making it difficult to mix custom sound sources (such as procedurally generated audio or unofficial formats) with regular audio assets. Let's fix these issues. ## Solution Refactor `bevy_audio` to a more idiomatic ECS API. Remove the `Audio` resource. Do everything via entities and components instead. Audio playback data is now stored in components: - `PlaybackSettings`, `SpatialSettings`, `Handle<AudioSource>` are now components. The user inserts them to tell Bevy to play a sound and configure the initial playback parameters. - `AudioSink`, `SpatialAudioSink` are now components instead of special magical "asset" types. They are inserted by Bevy when it actually begins playing the sound, and can be queried for by the user in order to control the sound during playback. Bundles: `AudioBundle` and `SpatialAudioBundle` are available to make it easy for users to play sounds. Spawn an entity with one of these bundles (or insert them to a complex entity alongside other stuff) to play a sound. Each entity represents a sound to be played. There is also a new "auto-despawn" feature (activated using `PlaybackSettings`), which, if enabled, tells Bevy to despawn entities when the sink playback finishes. This allows for "fire-and-forget" sound playback. Users can simply spawn entities whenever they want to play sounds and not have to worry about leaking memory. ## Unsolved Questions I think the current design is *fine*. I'd be happy for it to be merged. It has some possibly-surprising usability pitfalls, but I think it is still much better than the old `bevy_audio`. Here are some discussion questions for things that we could further improve. I'm undecided on these questions, which is why I didn't implement them. We should decide which of these should be addressed in this PR, and what should be left for future PRs. Or if they should be addressed at all. ### What happens when sounds start playing? Currently, the audio sink components are inserted and the bundle components are kept. Should Bevy remove the bundle components? Something else? The current design allows an entity to be reused for playing the same sound with the same parameters repeatedly. This is a niche use case I'd like to be supported, but if we have to give it up for a simpler design, I'd be fine with that. ### What happens if users remove any of the components themselves? As described above, currently, entities can be reused. Removing the audio sink causes it to be "detached" (I kept the old `Drop` impl), so the sound keeps playing. However, if the audio bundle components are not removed, Bevy will detect this entity as a "queued" sound entity again (has the bundle compoenents, without a sink component), just like before playing the sound the first time, and start playing the sound again. This behavior might be surprising? Should we do something different? ### Should mutations to `PlaybackSettings` be applied to the audio sink? We currently do not do that. `PlaybackSettings` is just for the initial settings when the sound starts playing. This is clearly documented. Do we want to keep this behavior, or do we want to allow users to use `PlaybackSettings` instead of `AudioSink`/`SpatialAudioSink` to control sounds during playback too? I think I prefer for them to be kept separate. It is not a bad mental model once you understand it, and it is documented. ### Should `AudioSink` and `SpatialAudioSink` be unified into a single component type? They provide a similar API (via the `AudioSinkPlayback` trait) and it might be annoying for users to have to deal with both of them. The unification could be done using an enum that is matched on internally by the methods. Spatial audio has extra features, so this might make it harder to access. I think we shouldn't. ### Automatic synchronization of spatial sound properties from Transforms? Should Bevy automatically apply changes to Transforms to spatial audio entities? How do we distinguish between listener and emitter? Which one does the transform represent? Where should the other one come from? Alternatively, leave this problem for now, and address it in a future PR. Or do nothing, and let users deal with it, as shown in the `spatial_audio_2d` and `spatial_audio_3d` examples. --- ## Changelog Added: - `AudioBundle`/`SpatialAudioBundle`, add them to entities to play sounds. Removed: - The `Audio` resource. - `AudioOutput` is no longer `pub`. Changed: - `AudioSink`, `SpatialAudioSink` are now components instead of assets. ## Migration Guide // TODO: write a more detailed migration guide, after the "unsolved questions" are answered and this PR is finalized. Before: ```rust /// Need to store handles somewhere #[derive(Resource)] struct MyMusic { sink: Handle<AudioSink>, } fn play_music( asset_server: Res<AssetServer>, audio: Res<Audio>, audio_sinks: Res<Assets<AudioSink>>, mut commands: Commands, ) { let weak_handle = audio.play_with_settings( asset_server.load("music.ogg"), PlaybackSettings::LOOP.with_volume(0.5), ); // upgrade to strong handle and store it commands.insert_resource(MyMusic { sink: audio_sinks.get_handle(weak_handle), }); } fn toggle_pause_music( audio_sinks: Res<Assets<AudioSink>>, mymusic: Option<Res<MyMusic>>, ) { if let Some(mymusic) = &mymusic { if let Some(sink) = audio_sinks.get(&mymusic.sink) { sink.toggle(); } } } ``` Now: ```rust /// Marker component for our music entity #[derive(Component)] struct MyMusic; fn play_music( mut commands: Commands, asset_server: Res<AssetServer>, ) { commands.spawn(( AudioBundle::from_audio_source(asset_server.load("music.ogg")) .with_settings(PlaybackSettings::LOOP.with_volume(0.5)), MyMusic, )); } fn toggle_pause_music( // `AudioSink` will be inserted by Bevy when the audio starts playing query_music: Query<&AudioSink, With<MyMusic>>, ) { if let Ok(sink) = query.get_single() { sink.toggle(); } } ```
2023-07-07 23:01:17 +00:00
// sound emitter
commands.spawn((
MaterialMesh2dBundle {
Deprecate shapes in `bevy_render::mesh::shape` (#11773) # Objective #11431 and #11688 implemented meshing support for Bevy's new geometric primitives. The next step is to deprecate the shapes in `bevy_render::mesh::shape` and to later remove them completely for 0.14. ## Solution Deprecate the shapes and reduce code duplication by utilizing the primitive meshing API for the old shapes where possible. Note that some shapes have behavior that can't be exactly reproduced with the new primitives yet: - `Box` is more of an AABB with min/max extents - `Plane` supports a subdivision count - `Quad` has a `flipped` property These types have not been changed to utilize the new primitives yet. --- ## Changelog - Deprecated all shapes in `bevy_render::mesh::shape` - Changed all examples to use new primitives for meshing ## Migration Guide Bevy has previously used rendering-specific types like `UVSphere` and `Quad` for primitive mesh shapes. These have now been deprecated to use the geometric primitives newly introduced in version 0.13. Some examples: ```rust let before = meshes.add(shape::Box::new(5.0, 0.15, 5.0)); let after = meshes.add(Cuboid::new(5.0, 0.15, 5.0)); let before = meshes.add(shape::Quad::default()); let after = meshes.add(Rectangle::default()); let before = meshes.add(shape::Plane::from_size(5.0)); // The surface normal can now also be specified when using `new` let after = meshes.add(Plane3d::default().mesh().size(5.0, 5.0)); let before = meshes.add( Mesh::try_from(shape::Icosphere { radius: 0.5, subdivisions: 5, }) .unwrap(), ); let after = meshes.add(Sphere::new(0.5).mesh().ico(5).unwrap()); ```
2024-02-08 18:01:34 +00:00
mesh: meshes.add(Circle::new(15.0)).into(),
Migrate from `LegacyColor` to `bevy_color::Color` (#12163) # Objective - As part of the migration process we need to a) see the end effect of the migration on user ergonomics b) check for serious perf regressions c) actually migrate the code - To accomplish this, I'm going to attempt to migrate all of the remaining user-facing usages of `LegacyColor` in one PR, being careful to keep a clean commit history. - Fixes #12056. ## Solution I've chosen to use the polymorphic `Color` type as our standard user-facing API. - [x] Migrate `bevy_gizmos`. - [x] Take `impl Into<Color>` in all `bevy_gizmos` APIs - [x] Migrate sprites - [x] Migrate UI - [x] Migrate `ColorMaterial` - [x] Migrate `MaterialMesh2D` - [x] Migrate fog - [x] Migrate lights - [x] Migrate StandardMaterial - [x] Migrate wireframes - [x] Migrate clear color - [x] Migrate text - [x] Migrate gltf loader - [x] Register color types for reflection - [x] Remove `LegacyColor` - [x] Make sure CI passes Incidental improvements to ease migration: - added `Color::srgba_u8`, `Color::srgba_from_array` and friends - added `set_alpha`, `is_fully_transparent` and `is_fully_opaque` to the `Alpha` trait - add and immediately deprecate (lol) `Color::rgb` and friends in favor of more explicit and consistent `Color::srgb` - standardized on white and black for most example text colors - added vector field traits to `LinearRgba`: ~~`Add`, `Sub`, `AddAssign`, `SubAssign`,~~ `Mul<f32>` and `Div<f32>`. Multiplications and divisions do not scale alpha. `Add` and `Sub` have been cut from this PR. - added `LinearRgba` and `Srgba` `RED/GREEN/BLUE` - added `LinearRgba_to_f32_array` and `LinearRgba::to_u32` ## Migration Guide Bevy's color types have changed! Wherever you used a `bevy::render::Color`, a `bevy::color::Color` is used instead. These are quite similar! Both are enums storing a color in a specific color space (or to be more precise, using a specific color model). However, each of the different color models now has its own type. TODO... - `Color::rgba`, `Color::rgb`, `Color::rbga_u8`, `Color::rgb_u8`, `Color::rgb_from_array` are now `Color::srgba`, `Color::srgb`, `Color::srgba_u8`, `Color::srgb_u8` and `Color::srgb_from_array`. - `Color::set_a` and `Color::a` is now `Color::set_alpha` and `Color::alpha`. These are part of the `Alpha` trait in `bevy_color`. - `Color::is_fully_transparent` is now part of the `Alpha` trait in `bevy_color` - `Color::r`, `Color::set_r`, `Color::with_r` and the equivalents for `g`, `b` `h`, `s` and `l` have been removed due to causing silent relatively expensive conversions. Convert your `Color` into the desired color space, perform your operations there, and then convert it back into a polymorphic `Color` enum. - `Color::hex` is now `Srgba::hex`. Call `.into` or construct a `Color::Srgba` variant manually to convert it. - `WireframeMaterial`, `ExtractedUiNode`, `ExtractedDirectionalLight`, `ExtractedPointLight`, `ExtractedSpotLight` and `ExtractedSprite` now store a `LinearRgba`, rather than a polymorphic `Color` - `Color::rgb_linear` and `Color::rgba_linear` are now `Color::linear_rgb` and `Color::linear_rgba` - The various CSS color constants are no longer stored directly on `Color`. Instead, they're defined in the `Srgba` color space, and accessed via `bevy::color::palettes::css`. Call `.into()` on them to convert them into a `Color` for quick debugging use, and consider using the much prettier `tailwind` palette for prototyping. - The `LIME_GREEN` color has been renamed to `LIMEGREEN` to comply with the standard naming. - Vector field arithmetic operations on `Color` (add, subtract, multiply and divide by a f32) have been removed. Instead, convert your colors into `LinearRgba` space, and perform your operations explicitly there. This is particularly relevant when working with emissive or HDR colors, whose color channel values are routinely outside of the ordinary 0 to 1 range. - `Color::as_linear_rgba_f32` has been removed. Call `LinearRgba::to_f32_array` instead, converting if needed. - `Color::as_linear_rgba_u32` has been removed. Call `LinearRgba::to_u32` instead, converting if needed. - Several other color conversion methods to transform LCH or HSL colors into float arrays or `Vec` types have been removed. Please reimplement these externally or open a PR to re-add them if you found them particularly useful. - Various methods on `Color` such as `rgb` or `hsl` to convert the color into a specific color space have been removed. Convert into `LinearRgba`, then to the color space of your choice. - Various implicitly-converting color value methods on `Color` such as `r`, `g`, `b` or `h` have been removed. Please convert it into the color space of your choice, then check these properties. - `Color` no longer implements `AsBindGroup`. Store a `LinearRgba` internally instead to avoid conversion costs. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com> Co-authored-by: Afonso Lage <lage.afonso@gmail.com> Co-authored-by: Rob Parrett <robparrett@gmail.com> Co-authored-by: Zachary Harrold <zac@harrold.com.au>
2024-02-29 19:35:12 +00:00
material: materials.add(Color::from(BLUE)),
bevy_audio: ECS-based API redesign (#8424) # Objective Improve the `bevy_audio` API to make it more user-friendly and ECS-idiomatic. This PR is a first-pass at addressing some of the most obvious (to me) problems. In the interest of keeping the scope small, further improvements can be done in future PRs. The current `bevy_audio` API is very clunky to work with, due to how it (ab)uses bevy assets to represent audio sinks. The user needs to write a lot of boilerplate (accessing `Res<Assets<AudioSink>>`) and deal with a lot of cognitive overhead (worry about strong vs. weak handles, etc.) in order to control audio playback. Audio playback is initiated via a centralized `Audio` resource, which makes it difficult to keep track of many different sounds playing in a typical game. Further, everything carries a generic type parameter for the sound source type, making it difficult to mix custom sound sources (such as procedurally generated audio or unofficial formats) with regular audio assets. Let's fix these issues. ## Solution Refactor `bevy_audio` to a more idiomatic ECS API. Remove the `Audio` resource. Do everything via entities and components instead. Audio playback data is now stored in components: - `PlaybackSettings`, `SpatialSettings`, `Handle<AudioSource>` are now components. The user inserts them to tell Bevy to play a sound and configure the initial playback parameters. - `AudioSink`, `SpatialAudioSink` are now components instead of special magical "asset" types. They are inserted by Bevy when it actually begins playing the sound, and can be queried for by the user in order to control the sound during playback. Bundles: `AudioBundle` and `SpatialAudioBundle` are available to make it easy for users to play sounds. Spawn an entity with one of these bundles (or insert them to a complex entity alongside other stuff) to play a sound. Each entity represents a sound to be played. There is also a new "auto-despawn" feature (activated using `PlaybackSettings`), which, if enabled, tells Bevy to despawn entities when the sink playback finishes. This allows for "fire-and-forget" sound playback. Users can simply spawn entities whenever they want to play sounds and not have to worry about leaking memory. ## Unsolved Questions I think the current design is *fine*. I'd be happy for it to be merged. It has some possibly-surprising usability pitfalls, but I think it is still much better than the old `bevy_audio`. Here are some discussion questions for things that we could further improve. I'm undecided on these questions, which is why I didn't implement them. We should decide which of these should be addressed in this PR, and what should be left for future PRs. Or if they should be addressed at all. ### What happens when sounds start playing? Currently, the audio sink components are inserted and the bundle components are kept. Should Bevy remove the bundle components? Something else? The current design allows an entity to be reused for playing the same sound with the same parameters repeatedly. This is a niche use case I'd like to be supported, but if we have to give it up for a simpler design, I'd be fine with that. ### What happens if users remove any of the components themselves? As described above, currently, entities can be reused. Removing the audio sink causes it to be "detached" (I kept the old `Drop` impl), so the sound keeps playing. However, if the audio bundle components are not removed, Bevy will detect this entity as a "queued" sound entity again (has the bundle compoenents, without a sink component), just like before playing the sound the first time, and start playing the sound again. This behavior might be surprising? Should we do something different? ### Should mutations to `PlaybackSettings` be applied to the audio sink? We currently do not do that. `PlaybackSettings` is just for the initial settings when the sound starts playing. This is clearly documented. Do we want to keep this behavior, or do we want to allow users to use `PlaybackSettings` instead of `AudioSink`/`SpatialAudioSink` to control sounds during playback too? I think I prefer for them to be kept separate. It is not a bad mental model once you understand it, and it is documented. ### Should `AudioSink` and `SpatialAudioSink` be unified into a single component type? They provide a similar API (via the `AudioSinkPlayback` trait) and it might be annoying for users to have to deal with both of them. The unification could be done using an enum that is matched on internally by the methods. Spatial audio has extra features, so this might make it harder to access. I think we shouldn't. ### Automatic synchronization of spatial sound properties from Transforms? Should Bevy automatically apply changes to Transforms to spatial audio entities? How do we distinguish between listener and emitter? Which one does the transform represent? Where should the other one come from? Alternatively, leave this problem for now, and address it in a future PR. Or do nothing, and let users deal with it, as shown in the `spatial_audio_2d` and `spatial_audio_3d` examples. --- ## Changelog Added: - `AudioBundle`/`SpatialAudioBundle`, add them to entities to play sounds. Removed: - The `Audio` resource. - `AudioOutput` is no longer `pub`. Changed: - `AudioSink`, `SpatialAudioSink` are now components instead of assets. ## Migration Guide // TODO: write a more detailed migration guide, after the "unsolved questions" are answered and this PR is finalized. Before: ```rust /// Need to store handles somewhere #[derive(Resource)] struct MyMusic { sink: Handle<AudioSink>, } fn play_music( asset_server: Res<AssetServer>, audio: Res<Audio>, audio_sinks: Res<Assets<AudioSink>>, mut commands: Commands, ) { let weak_handle = audio.play_with_settings( asset_server.load("music.ogg"), PlaybackSettings::LOOP.with_volume(0.5), ); // upgrade to strong handle and store it commands.insert_resource(MyMusic { sink: audio_sinks.get_handle(weak_handle), }); } fn toggle_pause_music( audio_sinks: Res<Assets<AudioSink>>, mymusic: Option<Res<MyMusic>>, ) { if let Some(mymusic) = &mymusic { if let Some(sink) = audio_sinks.get(&mymusic.sink) { sink.toggle(); } } } ``` Now: ```rust /// Marker component for our music entity #[derive(Component)] struct MyMusic; fn play_music( mut commands: Commands, asset_server: Res<AssetServer>, ) { commands.spawn(( AudioBundle::from_audio_source(asset_server.load("music.ogg")) .with_settings(PlaybackSettings::LOOP.with_volume(0.5)), MyMusic, )); } fn toggle_pause_music( // `AudioSink` will be inserted by Bevy when the audio starts playing query_music: Query<&AudioSink, With<MyMusic>>, ) { if let Ok(sink) = query.get_single() { sink.toggle(); } } ```
2023-07-07 23:01:17 +00:00
transform: Transform::from_translation(Vec3::new(0.0, 50.0, 0.0)),
..default()
},
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
Emitter::default(),
AudioBundle {
bevy_audio: ECS-based API redesign (#8424) # Objective Improve the `bevy_audio` API to make it more user-friendly and ECS-idiomatic. This PR is a first-pass at addressing some of the most obvious (to me) problems. In the interest of keeping the scope small, further improvements can be done in future PRs. The current `bevy_audio` API is very clunky to work with, due to how it (ab)uses bevy assets to represent audio sinks. The user needs to write a lot of boilerplate (accessing `Res<Assets<AudioSink>>`) and deal with a lot of cognitive overhead (worry about strong vs. weak handles, etc.) in order to control audio playback. Audio playback is initiated via a centralized `Audio` resource, which makes it difficult to keep track of many different sounds playing in a typical game. Further, everything carries a generic type parameter for the sound source type, making it difficult to mix custom sound sources (such as procedurally generated audio or unofficial formats) with regular audio assets. Let's fix these issues. ## Solution Refactor `bevy_audio` to a more idiomatic ECS API. Remove the `Audio` resource. Do everything via entities and components instead. Audio playback data is now stored in components: - `PlaybackSettings`, `SpatialSettings`, `Handle<AudioSource>` are now components. The user inserts them to tell Bevy to play a sound and configure the initial playback parameters. - `AudioSink`, `SpatialAudioSink` are now components instead of special magical "asset" types. They are inserted by Bevy when it actually begins playing the sound, and can be queried for by the user in order to control the sound during playback. Bundles: `AudioBundle` and `SpatialAudioBundle` are available to make it easy for users to play sounds. Spawn an entity with one of these bundles (or insert them to a complex entity alongside other stuff) to play a sound. Each entity represents a sound to be played. There is also a new "auto-despawn" feature (activated using `PlaybackSettings`), which, if enabled, tells Bevy to despawn entities when the sink playback finishes. This allows for "fire-and-forget" sound playback. Users can simply spawn entities whenever they want to play sounds and not have to worry about leaking memory. ## Unsolved Questions I think the current design is *fine*. I'd be happy for it to be merged. It has some possibly-surprising usability pitfalls, but I think it is still much better than the old `bevy_audio`. Here are some discussion questions for things that we could further improve. I'm undecided on these questions, which is why I didn't implement them. We should decide which of these should be addressed in this PR, and what should be left for future PRs. Or if they should be addressed at all. ### What happens when sounds start playing? Currently, the audio sink components are inserted and the bundle components are kept. Should Bevy remove the bundle components? Something else? The current design allows an entity to be reused for playing the same sound with the same parameters repeatedly. This is a niche use case I'd like to be supported, but if we have to give it up for a simpler design, I'd be fine with that. ### What happens if users remove any of the components themselves? As described above, currently, entities can be reused. Removing the audio sink causes it to be "detached" (I kept the old `Drop` impl), so the sound keeps playing. However, if the audio bundle components are not removed, Bevy will detect this entity as a "queued" sound entity again (has the bundle compoenents, without a sink component), just like before playing the sound the first time, and start playing the sound again. This behavior might be surprising? Should we do something different? ### Should mutations to `PlaybackSettings` be applied to the audio sink? We currently do not do that. `PlaybackSettings` is just for the initial settings when the sound starts playing. This is clearly documented. Do we want to keep this behavior, or do we want to allow users to use `PlaybackSettings` instead of `AudioSink`/`SpatialAudioSink` to control sounds during playback too? I think I prefer for them to be kept separate. It is not a bad mental model once you understand it, and it is documented. ### Should `AudioSink` and `SpatialAudioSink` be unified into a single component type? They provide a similar API (via the `AudioSinkPlayback` trait) and it might be annoying for users to have to deal with both of them. The unification could be done using an enum that is matched on internally by the methods. Spatial audio has extra features, so this might make it harder to access. I think we shouldn't. ### Automatic synchronization of spatial sound properties from Transforms? Should Bevy automatically apply changes to Transforms to spatial audio entities? How do we distinguish between listener and emitter? Which one does the transform represent? Where should the other one come from? Alternatively, leave this problem for now, and address it in a future PR. Or do nothing, and let users deal with it, as shown in the `spatial_audio_2d` and `spatial_audio_3d` examples. --- ## Changelog Added: - `AudioBundle`/`SpatialAudioBundle`, add them to entities to play sounds. Removed: - The `Audio` resource. - `AudioOutput` is no longer `pub`. Changed: - `AudioSink`, `SpatialAudioSink` are now components instead of assets. ## Migration Guide // TODO: write a more detailed migration guide, after the "unsolved questions" are answered and this PR is finalized. Before: ```rust /// Need to store handles somewhere #[derive(Resource)] struct MyMusic { sink: Handle<AudioSink>, } fn play_music( asset_server: Res<AssetServer>, audio: Res<Audio>, audio_sinks: Res<Assets<AudioSink>>, mut commands: Commands, ) { let weak_handle = audio.play_with_settings( asset_server.load("music.ogg"), PlaybackSettings::LOOP.with_volume(0.5), ); // upgrade to strong handle and store it commands.insert_resource(MyMusic { sink: audio_sinks.get_handle(weak_handle), }); } fn toggle_pause_music( audio_sinks: Res<Assets<AudioSink>>, mymusic: Option<Res<MyMusic>>, ) { if let Some(mymusic) = &mymusic { if let Some(sink) = audio_sinks.get(&mymusic.sink) { sink.toggle(); } } } ``` Now: ```rust /// Marker component for our music entity #[derive(Component)] struct MyMusic; fn play_music( mut commands: Commands, asset_server: Res<AssetServer>, ) { commands.spawn(( AudioBundle::from_audio_source(asset_server.load("music.ogg")) .with_settings(PlaybackSettings::LOOP.with_volume(0.5)), MyMusic, )); } fn toggle_pause_music( // `AudioSink` will be inserted by Bevy when the audio starts playing query_music: Query<&AudioSink, With<MyMusic>>, ) { if let Ok(sink) = query.get_single() { sink.toggle(); } } ```
2023-07-07 23:01:17 +00:00
source: asset_server.load("sounds/Windless Slopes.ogg"),
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
settings: PlaybackSettings::LOOP.with_spatial(true),
bevy_audio: ECS-based API redesign (#8424) # Objective Improve the `bevy_audio` API to make it more user-friendly and ECS-idiomatic. This PR is a first-pass at addressing some of the most obvious (to me) problems. In the interest of keeping the scope small, further improvements can be done in future PRs. The current `bevy_audio` API is very clunky to work with, due to how it (ab)uses bevy assets to represent audio sinks. The user needs to write a lot of boilerplate (accessing `Res<Assets<AudioSink>>`) and deal with a lot of cognitive overhead (worry about strong vs. weak handles, etc.) in order to control audio playback. Audio playback is initiated via a centralized `Audio` resource, which makes it difficult to keep track of many different sounds playing in a typical game. Further, everything carries a generic type parameter for the sound source type, making it difficult to mix custom sound sources (such as procedurally generated audio or unofficial formats) with regular audio assets. Let's fix these issues. ## Solution Refactor `bevy_audio` to a more idiomatic ECS API. Remove the `Audio` resource. Do everything via entities and components instead. Audio playback data is now stored in components: - `PlaybackSettings`, `SpatialSettings`, `Handle<AudioSource>` are now components. The user inserts them to tell Bevy to play a sound and configure the initial playback parameters. - `AudioSink`, `SpatialAudioSink` are now components instead of special magical "asset" types. They are inserted by Bevy when it actually begins playing the sound, and can be queried for by the user in order to control the sound during playback. Bundles: `AudioBundle` and `SpatialAudioBundle` are available to make it easy for users to play sounds. Spawn an entity with one of these bundles (or insert them to a complex entity alongside other stuff) to play a sound. Each entity represents a sound to be played. There is also a new "auto-despawn" feature (activated using `PlaybackSettings`), which, if enabled, tells Bevy to despawn entities when the sink playback finishes. This allows for "fire-and-forget" sound playback. Users can simply spawn entities whenever they want to play sounds and not have to worry about leaking memory. ## Unsolved Questions I think the current design is *fine*. I'd be happy for it to be merged. It has some possibly-surprising usability pitfalls, but I think it is still much better than the old `bevy_audio`. Here are some discussion questions for things that we could further improve. I'm undecided on these questions, which is why I didn't implement them. We should decide which of these should be addressed in this PR, and what should be left for future PRs. Or if they should be addressed at all. ### What happens when sounds start playing? Currently, the audio sink components are inserted and the bundle components are kept. Should Bevy remove the bundle components? Something else? The current design allows an entity to be reused for playing the same sound with the same parameters repeatedly. This is a niche use case I'd like to be supported, but if we have to give it up for a simpler design, I'd be fine with that. ### What happens if users remove any of the components themselves? As described above, currently, entities can be reused. Removing the audio sink causes it to be "detached" (I kept the old `Drop` impl), so the sound keeps playing. However, if the audio bundle components are not removed, Bevy will detect this entity as a "queued" sound entity again (has the bundle compoenents, without a sink component), just like before playing the sound the first time, and start playing the sound again. This behavior might be surprising? Should we do something different? ### Should mutations to `PlaybackSettings` be applied to the audio sink? We currently do not do that. `PlaybackSettings` is just for the initial settings when the sound starts playing. This is clearly documented. Do we want to keep this behavior, or do we want to allow users to use `PlaybackSettings` instead of `AudioSink`/`SpatialAudioSink` to control sounds during playback too? I think I prefer for them to be kept separate. It is not a bad mental model once you understand it, and it is documented. ### Should `AudioSink` and `SpatialAudioSink` be unified into a single component type? They provide a similar API (via the `AudioSinkPlayback` trait) and it might be annoying for users to have to deal with both of them. The unification could be done using an enum that is matched on internally by the methods. Spatial audio has extra features, so this might make it harder to access. I think we shouldn't. ### Automatic synchronization of spatial sound properties from Transforms? Should Bevy automatically apply changes to Transforms to spatial audio entities? How do we distinguish between listener and emitter? Which one does the transform represent? Where should the other one come from? Alternatively, leave this problem for now, and address it in a future PR. Or do nothing, and let users deal with it, as shown in the `spatial_audio_2d` and `spatial_audio_3d` examples. --- ## Changelog Added: - `AudioBundle`/`SpatialAudioBundle`, add them to entities to play sounds. Removed: - The `Audio` resource. - `AudioOutput` is no longer `pub`. Changed: - `AudioSink`, `SpatialAudioSink` are now components instead of assets. ## Migration Guide // TODO: write a more detailed migration guide, after the "unsolved questions" are answered and this PR is finalized. Before: ```rust /// Need to store handles somewhere #[derive(Resource)] struct MyMusic { sink: Handle<AudioSink>, } fn play_music( asset_server: Res<AssetServer>, audio: Res<Audio>, audio_sinks: Res<Assets<AudioSink>>, mut commands: Commands, ) { let weak_handle = audio.play_with_settings( asset_server.load("music.ogg"), PlaybackSettings::LOOP.with_volume(0.5), ); // upgrade to strong handle and store it commands.insert_resource(MyMusic { sink: audio_sinks.get_handle(weak_handle), }); } fn toggle_pause_music( audio_sinks: Res<Assets<AudioSink>>, mymusic: Option<Res<MyMusic>>, ) { if let Some(mymusic) = &mymusic { if let Some(sink) = audio_sinks.get(&mymusic.sink) { sink.toggle(); } } } ``` Now: ```rust /// Marker component for our music entity #[derive(Component)] struct MyMusic; fn play_music( mut commands: Commands, asset_server: Res<AssetServer>, ) { commands.spawn(( AudioBundle::from_audio_source(asset_server.load("music.ogg")) .with_settings(PlaybackSettings::LOOP.with_volume(0.5)), MyMusic, )); } fn toggle_pause_music( // `AudioSink` will be inserted by Bevy when the audio starts playing query_music: Query<&AudioSink, With<MyMusic>>, ) { if let Ok(sink) = query.get_single() { sink.toggle(); } } ```
2023-07-07 23:01:17 +00:00
},
));
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
let listener = SpatialListener::new(gap);
commands
.spawn((SpatialBundle::default(), listener.clone()))
.with_children(|parent| {
// left ear
parent.spawn(SpriteBundle {
sprite: Sprite {
Migrate from `LegacyColor` to `bevy_color::Color` (#12163) # Objective - As part of the migration process we need to a) see the end effect of the migration on user ergonomics b) check for serious perf regressions c) actually migrate the code - To accomplish this, I'm going to attempt to migrate all of the remaining user-facing usages of `LegacyColor` in one PR, being careful to keep a clean commit history. - Fixes #12056. ## Solution I've chosen to use the polymorphic `Color` type as our standard user-facing API. - [x] Migrate `bevy_gizmos`. - [x] Take `impl Into<Color>` in all `bevy_gizmos` APIs - [x] Migrate sprites - [x] Migrate UI - [x] Migrate `ColorMaterial` - [x] Migrate `MaterialMesh2D` - [x] Migrate fog - [x] Migrate lights - [x] Migrate StandardMaterial - [x] Migrate wireframes - [x] Migrate clear color - [x] Migrate text - [x] Migrate gltf loader - [x] Register color types for reflection - [x] Remove `LegacyColor` - [x] Make sure CI passes Incidental improvements to ease migration: - added `Color::srgba_u8`, `Color::srgba_from_array` and friends - added `set_alpha`, `is_fully_transparent` and `is_fully_opaque` to the `Alpha` trait - add and immediately deprecate (lol) `Color::rgb` and friends in favor of more explicit and consistent `Color::srgb` - standardized on white and black for most example text colors - added vector field traits to `LinearRgba`: ~~`Add`, `Sub`, `AddAssign`, `SubAssign`,~~ `Mul<f32>` and `Div<f32>`. Multiplications and divisions do not scale alpha. `Add` and `Sub` have been cut from this PR. - added `LinearRgba` and `Srgba` `RED/GREEN/BLUE` - added `LinearRgba_to_f32_array` and `LinearRgba::to_u32` ## Migration Guide Bevy's color types have changed! Wherever you used a `bevy::render::Color`, a `bevy::color::Color` is used instead. These are quite similar! Both are enums storing a color in a specific color space (or to be more precise, using a specific color model). However, each of the different color models now has its own type. TODO... - `Color::rgba`, `Color::rgb`, `Color::rbga_u8`, `Color::rgb_u8`, `Color::rgb_from_array` are now `Color::srgba`, `Color::srgb`, `Color::srgba_u8`, `Color::srgb_u8` and `Color::srgb_from_array`. - `Color::set_a` and `Color::a` is now `Color::set_alpha` and `Color::alpha`. These are part of the `Alpha` trait in `bevy_color`. - `Color::is_fully_transparent` is now part of the `Alpha` trait in `bevy_color` - `Color::r`, `Color::set_r`, `Color::with_r` and the equivalents for `g`, `b` `h`, `s` and `l` have been removed due to causing silent relatively expensive conversions. Convert your `Color` into the desired color space, perform your operations there, and then convert it back into a polymorphic `Color` enum. - `Color::hex` is now `Srgba::hex`. Call `.into` or construct a `Color::Srgba` variant manually to convert it. - `WireframeMaterial`, `ExtractedUiNode`, `ExtractedDirectionalLight`, `ExtractedPointLight`, `ExtractedSpotLight` and `ExtractedSprite` now store a `LinearRgba`, rather than a polymorphic `Color` - `Color::rgb_linear` and `Color::rgba_linear` are now `Color::linear_rgb` and `Color::linear_rgba` - The various CSS color constants are no longer stored directly on `Color`. Instead, they're defined in the `Srgba` color space, and accessed via `bevy::color::palettes::css`. Call `.into()` on them to convert them into a `Color` for quick debugging use, and consider using the much prettier `tailwind` palette for prototyping. - The `LIME_GREEN` color has been renamed to `LIMEGREEN` to comply with the standard naming. - Vector field arithmetic operations on `Color` (add, subtract, multiply and divide by a f32) have been removed. Instead, convert your colors into `LinearRgba` space, and perform your operations explicitly there. This is particularly relevant when working with emissive or HDR colors, whose color channel values are routinely outside of the ordinary 0 to 1 range. - `Color::as_linear_rgba_f32` has been removed. Call `LinearRgba::to_f32_array` instead, converting if needed. - `Color::as_linear_rgba_u32` has been removed. Call `LinearRgba::to_u32` instead, converting if needed. - Several other color conversion methods to transform LCH or HSL colors into float arrays or `Vec` types have been removed. Please reimplement these externally or open a PR to re-add them if you found them particularly useful. - Various methods on `Color` such as `rgb` or `hsl` to convert the color into a specific color space have been removed. Convert into `LinearRgba`, then to the color space of your choice. - Various implicitly-converting color value methods on `Color` such as `r`, `g`, `b` or `h` have been removed. Please convert it into the color space of your choice, then check these properties. - `Color` no longer implements `AsBindGroup`. Store a `LinearRgba` internally instead to avoid conversion costs. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com> Co-authored-by: Afonso Lage <lage.afonso@gmail.com> Co-authored-by: Rob Parrett <robparrett@gmail.com> Co-authored-by: Zachary Harrold <zac@harrold.com.au>
2024-02-29 19:35:12 +00:00
color: RED.into(),
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
custom_size: Some(Vec2::splat(20.0)),
..default()
},
transform: Transform::from_xyz(-gap / 2.0, 0.0, 0.0),
..default()
});
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
// right ear
parent.spawn(SpriteBundle {
sprite: Sprite {
color: LIME.into(),
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
custom_size: Some(Vec2::splat(20.0)),
..default()
},
transform: Transform::from_xyz(gap / 2.0, 0.0, 0.0),
..default()
});
});
// example instructions
commands.spawn(
TextBundle::from_section(
"Up/Down/Left/Right: Move Listener\nSpace: Toggle Emitter Movement",
TextStyle {
font_size: 20.0,
..default()
},
)
.with_style(Style {
position_type: PositionType::Absolute,
bottom: Val::Px(12.0),
left: Val::Px(12.0),
..default()
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
}),
);
// camera
commands.spawn(Camera2dBundle::default());
}
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
#[derive(Component, Default)]
struct Emitter {
stopped: bool,
}
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
fn update_emitters(
time: Res<Time>,
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
mut emitters: Query<(&mut Transform, &mut Emitter), With<Emitter>>,
keyboard: Res<ButtonInput<KeyCode>>,
) {
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
for (mut emitter_transform, mut emitter) in emitters.iter_mut() {
if keyboard.just_pressed(KeyCode::Space) {
emitter.stopped = !emitter.stopped;
}
if !emitter.stopped {
emitter_transform.translation.x = time.elapsed_seconds().sin() * 500.0;
bevy_audio: ECS-based API redesign (#8424) # Objective Improve the `bevy_audio` API to make it more user-friendly and ECS-idiomatic. This PR is a first-pass at addressing some of the most obvious (to me) problems. In the interest of keeping the scope small, further improvements can be done in future PRs. The current `bevy_audio` API is very clunky to work with, due to how it (ab)uses bevy assets to represent audio sinks. The user needs to write a lot of boilerplate (accessing `Res<Assets<AudioSink>>`) and deal with a lot of cognitive overhead (worry about strong vs. weak handles, etc.) in order to control audio playback. Audio playback is initiated via a centralized `Audio` resource, which makes it difficult to keep track of many different sounds playing in a typical game. Further, everything carries a generic type parameter for the sound source type, making it difficult to mix custom sound sources (such as procedurally generated audio or unofficial formats) with regular audio assets. Let's fix these issues. ## Solution Refactor `bevy_audio` to a more idiomatic ECS API. Remove the `Audio` resource. Do everything via entities and components instead. Audio playback data is now stored in components: - `PlaybackSettings`, `SpatialSettings`, `Handle<AudioSource>` are now components. The user inserts them to tell Bevy to play a sound and configure the initial playback parameters. - `AudioSink`, `SpatialAudioSink` are now components instead of special magical "asset" types. They are inserted by Bevy when it actually begins playing the sound, and can be queried for by the user in order to control the sound during playback. Bundles: `AudioBundle` and `SpatialAudioBundle` are available to make it easy for users to play sounds. Spawn an entity with one of these bundles (or insert them to a complex entity alongside other stuff) to play a sound. Each entity represents a sound to be played. There is also a new "auto-despawn" feature (activated using `PlaybackSettings`), which, if enabled, tells Bevy to despawn entities when the sink playback finishes. This allows for "fire-and-forget" sound playback. Users can simply spawn entities whenever they want to play sounds and not have to worry about leaking memory. ## Unsolved Questions I think the current design is *fine*. I'd be happy for it to be merged. It has some possibly-surprising usability pitfalls, but I think it is still much better than the old `bevy_audio`. Here are some discussion questions for things that we could further improve. I'm undecided on these questions, which is why I didn't implement them. We should decide which of these should be addressed in this PR, and what should be left for future PRs. Or if they should be addressed at all. ### What happens when sounds start playing? Currently, the audio sink components are inserted and the bundle components are kept. Should Bevy remove the bundle components? Something else? The current design allows an entity to be reused for playing the same sound with the same parameters repeatedly. This is a niche use case I'd like to be supported, but if we have to give it up for a simpler design, I'd be fine with that. ### What happens if users remove any of the components themselves? As described above, currently, entities can be reused. Removing the audio sink causes it to be "detached" (I kept the old `Drop` impl), so the sound keeps playing. However, if the audio bundle components are not removed, Bevy will detect this entity as a "queued" sound entity again (has the bundle compoenents, without a sink component), just like before playing the sound the first time, and start playing the sound again. This behavior might be surprising? Should we do something different? ### Should mutations to `PlaybackSettings` be applied to the audio sink? We currently do not do that. `PlaybackSettings` is just for the initial settings when the sound starts playing. This is clearly documented. Do we want to keep this behavior, or do we want to allow users to use `PlaybackSettings` instead of `AudioSink`/`SpatialAudioSink` to control sounds during playback too? I think I prefer for them to be kept separate. It is not a bad mental model once you understand it, and it is documented. ### Should `AudioSink` and `SpatialAudioSink` be unified into a single component type? They provide a similar API (via the `AudioSinkPlayback` trait) and it might be annoying for users to have to deal with both of them. The unification could be done using an enum that is matched on internally by the methods. Spatial audio has extra features, so this might make it harder to access. I think we shouldn't. ### Automatic synchronization of spatial sound properties from Transforms? Should Bevy automatically apply changes to Transforms to spatial audio entities? How do we distinguish between listener and emitter? Which one does the transform represent? Where should the other one come from? Alternatively, leave this problem for now, and address it in a future PR. Or do nothing, and let users deal with it, as shown in the `spatial_audio_2d` and `spatial_audio_3d` examples. --- ## Changelog Added: - `AudioBundle`/`SpatialAudioBundle`, add them to entities to play sounds. Removed: - The `Audio` resource. - `AudioOutput` is no longer `pub`. Changed: - `AudioSink`, `SpatialAudioSink` are now components instead of assets. ## Migration Guide // TODO: write a more detailed migration guide, after the "unsolved questions" are answered and this PR is finalized. Before: ```rust /// Need to store handles somewhere #[derive(Resource)] struct MyMusic { sink: Handle<AudioSink>, } fn play_music( asset_server: Res<AssetServer>, audio: Res<Audio>, audio_sinks: Res<Assets<AudioSink>>, mut commands: Commands, ) { let weak_handle = audio.play_with_settings( asset_server.load("music.ogg"), PlaybackSettings::LOOP.with_volume(0.5), ); // upgrade to strong handle and store it commands.insert_resource(MyMusic { sink: audio_sinks.get_handle(weak_handle), }); } fn toggle_pause_music( audio_sinks: Res<Assets<AudioSink>>, mymusic: Option<Res<MyMusic>>, ) { if let Some(mymusic) = &mymusic { if let Some(sink) = audio_sinks.get(&mymusic.sink) { sink.toggle(); } } } ``` Now: ```rust /// Marker component for our music entity #[derive(Component)] struct MyMusic; fn play_music( mut commands: Commands, asset_server: Res<AssetServer>, ) { commands.spawn(( AudioBundle::from_audio_source(asset_server.load("music.ogg")) .with_settings(PlaybackSettings::LOOP.with_volume(0.5)), MyMusic, )); } fn toggle_pause_music( // `AudioSink` will be inserted by Bevy when the audio starts playing query_music: Query<&AudioSink, With<MyMusic>>, ) { if let Ok(sink) = query.get_single() { sink.toggle(); } } ```
2023-07-07 23:01:17 +00:00
}
}
}
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
fn update_listener(
keyboard: Res<ButtonInput<KeyCode>>,
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
time: Res<Time>,
mut listeners: Query<&mut Transform, With<SpatialListener>>,
) {
let mut transform = listeners.single_mut();
let speed = 200.;
Update winit dependency to 0.29 (#10702) # Objective - Update winit dependency to 0.29 ## Changelog ### KeyCode changes - Removed `ScanCode`, as it was [replaced by KeyCode](https://github.com/rust-windowing/winit/blob/master/CHANGELOG.md#0292). - `ReceivedCharacter.char` is now a `SmolStr`, [relevant doc](https://docs.rs/winit/latest/winit/event/struct.KeyEvent.html#structfield.text). - Changed most `KeyCode` values, and added more. KeyCode has changed meaning. With this PR, it refers to physical position on keyboard rather than the printed letter on keyboard keys. In practice this means: - On QWERTY keyboard layouts, nothing changes - On any other keyboard layout, `KeyCode` no longer reflects the label on key. - This is "good". In bevy 0.12, when you used WASD for movement, users with non-QWERTY keyboards couldn't play your game! This was especially bad for non-latin keyboards. Now, WASD represents the physical keys. A French player will press the ZQSD keys, which are near each other, Kyrgyz players will use "Цфыв". - This is "bad" as well. You can't know in advance what the label of the key for input is. Your UI says "press WASD to move", even if in reality, they should be pressing "ZQSD" or "Цфыв". You also no longer can use `KeyCode` for text inputs. In any case, it was a pretty bad API for text input. You should use `ReceivedCharacter` now instead. ### Other changes - Use `web-time` rather than `instant` crate. (https://github.com/rust-windowing/winit/pull/2836) - winit did split `run_return` in `run_onDemand` and `pump_events`, I did the same change in bevy_winit and used `pump_events`. - Removed `return_from_run` from `WinitSettings` as `winit::run` now returns on supported platforms. - I left the example "return_after_run" as I think it's still useful. - This winit change is done partly to allow to create a new window after quitting all windows: https://github.com/emilk/egui/issues/1918 ; this PR doesn't address. - added `width` and `height` properties in the `canvas` from wasm example (https://github.com/bevyengine/bevy/pull/10702#discussion_r1420567168) ## Known regressions (important follow ups?) - Provide an API for reacting when a specific key from current layout was released. - possible solutions: use winit::Key from winit::KeyEvent ; mapping between KeyCode and Key ; or . - We don't receive characters through alt+numpad (e.g. alt + 151 = "ù") anymore ; reproduced on winit example "ime". maybe related to https://github.com/rust-windowing/winit/issues/2945 - (windows) Window content doesn't refresh at all when resizing. By reading https://github.com/rust-windowing/winit/issues/2900 ; I suspect we should just fire a `window.request_redraw();` from `AboutToWait`, and handle actual redrawing within `RedrawRequested`. I'm not sure how to move all that code so I'd appreciate it to be a follow up. - (windows) unreleased winit fix for using set_control_flow in AboutToWait https://github.com/rust-windowing/winit/issues/3215 ; ⚠️ I'm not sure what the implications are, but that feels bad 🤔 ## Follow up I'd like to avoid bloating this PR, here are a few follow up tasks worthy of a separate PR, or new issue to track them once this PR is closed, as they would either complicate reviews, or at risk of being controversial: - remove CanvasParentResizePlugin (https://github.com/bevyengine/bevy/pull/10702#discussion_r1417068856) - avoid mentionning explicitly winit in docs from bevy_window ? - NamedKey integration on bevy_input: https://github.com/rust-windowing/winit/pull/3143 introduced a new NamedKey variant. I implemented it only on the converters but we'd benefit making the same changes to bevy_input. - Add more info in KeyboardInput https://github.com/bevyengine/bevy/pull/10702#pullrequestreview-1748336313 - https://github.com/bevyengine/bevy/pull/9905 added a workaround on a bug allegedly fixed by winit 0.29. We should check if it's still necessary. - update to raw_window_handle 0.6 - blocked by wgpu - Rename `KeyCode` to `PhysicalKeyCode` https://github.com/bevyengine/bevy/pull/10702#discussion_r1404595015 - remove `instant` dependency, [replaced by](https://github.com/rust-windowing/winit/pull/2836) `web_time`), we'd need to update to : - fastrand >= 2.0 - [`async-executor`](https://github.com/smol-rs/async-executor) >= 1.7 - [`futures-lite`](https://github.com/smol-rs/futures-lite) >= 2.0 - Verify license, see [discussion](https://github.com/bevyengine/bevy/pull/8745#discussion_r1402439800) - we might be missing a short notice or description of changes made - Consider using https://github.com/rust-windowing/cursor-icon directly rather than vendoring it in bevy. - investigate [this unwrap](https://github.com/bevyengine/bevy/pull/8745#discussion_r1387044986) (`winit_window.canvas().unwrap();`) - Use more good things about winit's update - https://github.com/bevyengine/bevy/pull/10689#issuecomment-1823560428 ## Migration Guide This PR should have one.
2023-12-21 07:40:47 +00:00
if keyboard.pressed(KeyCode::ArrowRight) {
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
transform.translation.x += speed * time.delta_seconds();
}
Update winit dependency to 0.29 (#10702) # Objective - Update winit dependency to 0.29 ## Changelog ### KeyCode changes - Removed `ScanCode`, as it was [replaced by KeyCode](https://github.com/rust-windowing/winit/blob/master/CHANGELOG.md#0292). - `ReceivedCharacter.char` is now a `SmolStr`, [relevant doc](https://docs.rs/winit/latest/winit/event/struct.KeyEvent.html#structfield.text). - Changed most `KeyCode` values, and added more. KeyCode has changed meaning. With this PR, it refers to physical position on keyboard rather than the printed letter on keyboard keys. In practice this means: - On QWERTY keyboard layouts, nothing changes - On any other keyboard layout, `KeyCode` no longer reflects the label on key. - This is "good". In bevy 0.12, when you used WASD for movement, users with non-QWERTY keyboards couldn't play your game! This was especially bad for non-latin keyboards. Now, WASD represents the physical keys. A French player will press the ZQSD keys, which are near each other, Kyrgyz players will use "Цфыв". - This is "bad" as well. You can't know in advance what the label of the key for input is. Your UI says "press WASD to move", even if in reality, they should be pressing "ZQSD" or "Цфыв". You also no longer can use `KeyCode` for text inputs. In any case, it was a pretty bad API for text input. You should use `ReceivedCharacter` now instead. ### Other changes - Use `web-time` rather than `instant` crate. (https://github.com/rust-windowing/winit/pull/2836) - winit did split `run_return` in `run_onDemand` and `pump_events`, I did the same change in bevy_winit and used `pump_events`. - Removed `return_from_run` from `WinitSettings` as `winit::run` now returns on supported platforms. - I left the example "return_after_run" as I think it's still useful. - This winit change is done partly to allow to create a new window after quitting all windows: https://github.com/emilk/egui/issues/1918 ; this PR doesn't address. - added `width` and `height` properties in the `canvas` from wasm example (https://github.com/bevyengine/bevy/pull/10702#discussion_r1420567168) ## Known regressions (important follow ups?) - Provide an API for reacting when a specific key from current layout was released. - possible solutions: use winit::Key from winit::KeyEvent ; mapping between KeyCode and Key ; or . - We don't receive characters through alt+numpad (e.g. alt + 151 = "ù") anymore ; reproduced on winit example "ime". maybe related to https://github.com/rust-windowing/winit/issues/2945 - (windows) Window content doesn't refresh at all when resizing. By reading https://github.com/rust-windowing/winit/issues/2900 ; I suspect we should just fire a `window.request_redraw();` from `AboutToWait`, and handle actual redrawing within `RedrawRequested`. I'm not sure how to move all that code so I'd appreciate it to be a follow up. - (windows) unreleased winit fix for using set_control_flow in AboutToWait https://github.com/rust-windowing/winit/issues/3215 ; ⚠️ I'm not sure what the implications are, but that feels bad 🤔 ## Follow up I'd like to avoid bloating this PR, here are a few follow up tasks worthy of a separate PR, or new issue to track them once this PR is closed, as they would either complicate reviews, or at risk of being controversial: - remove CanvasParentResizePlugin (https://github.com/bevyengine/bevy/pull/10702#discussion_r1417068856) - avoid mentionning explicitly winit in docs from bevy_window ? - NamedKey integration on bevy_input: https://github.com/rust-windowing/winit/pull/3143 introduced a new NamedKey variant. I implemented it only on the converters but we'd benefit making the same changes to bevy_input. - Add more info in KeyboardInput https://github.com/bevyengine/bevy/pull/10702#pullrequestreview-1748336313 - https://github.com/bevyengine/bevy/pull/9905 added a workaround on a bug allegedly fixed by winit 0.29. We should check if it's still necessary. - update to raw_window_handle 0.6 - blocked by wgpu - Rename `KeyCode` to `PhysicalKeyCode` https://github.com/bevyengine/bevy/pull/10702#discussion_r1404595015 - remove `instant` dependency, [replaced by](https://github.com/rust-windowing/winit/pull/2836) `web_time`), we'd need to update to : - fastrand >= 2.0 - [`async-executor`](https://github.com/smol-rs/async-executor) >= 1.7 - [`futures-lite`](https://github.com/smol-rs/futures-lite) >= 2.0 - Verify license, see [discussion](https://github.com/bevyengine/bevy/pull/8745#discussion_r1402439800) - we might be missing a short notice or description of changes made - Consider using https://github.com/rust-windowing/cursor-icon directly rather than vendoring it in bevy. - investigate [this unwrap](https://github.com/bevyengine/bevy/pull/8745#discussion_r1387044986) (`winit_window.canvas().unwrap();`) - Use more good things about winit's update - https://github.com/bevyengine/bevy/pull/10689#issuecomment-1823560428 ## Migration Guide This PR should have one.
2023-12-21 07:40:47 +00:00
if keyboard.pressed(KeyCode::ArrowLeft) {
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
transform.translation.x -= speed * time.delta_seconds();
}
Update winit dependency to 0.29 (#10702) # Objective - Update winit dependency to 0.29 ## Changelog ### KeyCode changes - Removed `ScanCode`, as it was [replaced by KeyCode](https://github.com/rust-windowing/winit/blob/master/CHANGELOG.md#0292). - `ReceivedCharacter.char` is now a `SmolStr`, [relevant doc](https://docs.rs/winit/latest/winit/event/struct.KeyEvent.html#structfield.text). - Changed most `KeyCode` values, and added more. KeyCode has changed meaning. With this PR, it refers to physical position on keyboard rather than the printed letter on keyboard keys. In practice this means: - On QWERTY keyboard layouts, nothing changes - On any other keyboard layout, `KeyCode` no longer reflects the label on key. - This is "good". In bevy 0.12, when you used WASD for movement, users with non-QWERTY keyboards couldn't play your game! This was especially bad for non-latin keyboards. Now, WASD represents the physical keys. A French player will press the ZQSD keys, which are near each other, Kyrgyz players will use "Цфыв". - This is "bad" as well. You can't know in advance what the label of the key for input is. Your UI says "press WASD to move", even if in reality, they should be pressing "ZQSD" or "Цфыв". You also no longer can use `KeyCode` for text inputs. In any case, it was a pretty bad API for text input. You should use `ReceivedCharacter` now instead. ### Other changes - Use `web-time` rather than `instant` crate. (https://github.com/rust-windowing/winit/pull/2836) - winit did split `run_return` in `run_onDemand` and `pump_events`, I did the same change in bevy_winit and used `pump_events`. - Removed `return_from_run` from `WinitSettings` as `winit::run` now returns on supported platforms. - I left the example "return_after_run" as I think it's still useful. - This winit change is done partly to allow to create a new window after quitting all windows: https://github.com/emilk/egui/issues/1918 ; this PR doesn't address. - added `width` and `height` properties in the `canvas` from wasm example (https://github.com/bevyengine/bevy/pull/10702#discussion_r1420567168) ## Known regressions (important follow ups?) - Provide an API for reacting when a specific key from current layout was released. - possible solutions: use winit::Key from winit::KeyEvent ; mapping between KeyCode and Key ; or . - We don't receive characters through alt+numpad (e.g. alt + 151 = "ù") anymore ; reproduced on winit example "ime". maybe related to https://github.com/rust-windowing/winit/issues/2945 - (windows) Window content doesn't refresh at all when resizing. By reading https://github.com/rust-windowing/winit/issues/2900 ; I suspect we should just fire a `window.request_redraw();` from `AboutToWait`, and handle actual redrawing within `RedrawRequested`. I'm not sure how to move all that code so I'd appreciate it to be a follow up. - (windows) unreleased winit fix for using set_control_flow in AboutToWait https://github.com/rust-windowing/winit/issues/3215 ; ⚠️ I'm not sure what the implications are, but that feels bad 🤔 ## Follow up I'd like to avoid bloating this PR, here are a few follow up tasks worthy of a separate PR, or new issue to track them once this PR is closed, as they would either complicate reviews, or at risk of being controversial: - remove CanvasParentResizePlugin (https://github.com/bevyengine/bevy/pull/10702#discussion_r1417068856) - avoid mentionning explicitly winit in docs from bevy_window ? - NamedKey integration on bevy_input: https://github.com/rust-windowing/winit/pull/3143 introduced a new NamedKey variant. I implemented it only on the converters but we'd benefit making the same changes to bevy_input. - Add more info in KeyboardInput https://github.com/bevyengine/bevy/pull/10702#pullrequestreview-1748336313 - https://github.com/bevyengine/bevy/pull/9905 added a workaround on a bug allegedly fixed by winit 0.29. We should check if it's still necessary. - update to raw_window_handle 0.6 - blocked by wgpu - Rename `KeyCode` to `PhysicalKeyCode` https://github.com/bevyengine/bevy/pull/10702#discussion_r1404595015 - remove `instant` dependency, [replaced by](https://github.com/rust-windowing/winit/pull/2836) `web_time`), we'd need to update to : - fastrand >= 2.0 - [`async-executor`](https://github.com/smol-rs/async-executor) >= 1.7 - [`futures-lite`](https://github.com/smol-rs/futures-lite) >= 2.0 - Verify license, see [discussion](https://github.com/bevyengine/bevy/pull/8745#discussion_r1402439800) - we might be missing a short notice or description of changes made - Consider using https://github.com/rust-windowing/cursor-icon directly rather than vendoring it in bevy. - investigate [this unwrap](https://github.com/bevyengine/bevy/pull/8745#discussion_r1387044986) (`winit_window.canvas().unwrap();`) - Use more good things about winit's update - https://github.com/bevyengine/bevy/pull/10689#issuecomment-1823560428 ## Migration Guide This PR should have one.
2023-12-21 07:40:47 +00:00
if keyboard.pressed(KeyCode::ArrowUp) {
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
transform.translation.y += speed * time.delta_seconds();
}
Update winit dependency to 0.29 (#10702) # Objective - Update winit dependency to 0.29 ## Changelog ### KeyCode changes - Removed `ScanCode`, as it was [replaced by KeyCode](https://github.com/rust-windowing/winit/blob/master/CHANGELOG.md#0292). - `ReceivedCharacter.char` is now a `SmolStr`, [relevant doc](https://docs.rs/winit/latest/winit/event/struct.KeyEvent.html#structfield.text). - Changed most `KeyCode` values, and added more. KeyCode has changed meaning. With this PR, it refers to physical position on keyboard rather than the printed letter on keyboard keys. In practice this means: - On QWERTY keyboard layouts, nothing changes - On any other keyboard layout, `KeyCode` no longer reflects the label on key. - This is "good". In bevy 0.12, when you used WASD for movement, users with non-QWERTY keyboards couldn't play your game! This was especially bad for non-latin keyboards. Now, WASD represents the physical keys. A French player will press the ZQSD keys, which are near each other, Kyrgyz players will use "Цфыв". - This is "bad" as well. You can't know in advance what the label of the key for input is. Your UI says "press WASD to move", even if in reality, they should be pressing "ZQSD" or "Цфыв". You also no longer can use `KeyCode` for text inputs. In any case, it was a pretty bad API for text input. You should use `ReceivedCharacter` now instead. ### Other changes - Use `web-time` rather than `instant` crate. (https://github.com/rust-windowing/winit/pull/2836) - winit did split `run_return` in `run_onDemand` and `pump_events`, I did the same change in bevy_winit and used `pump_events`. - Removed `return_from_run` from `WinitSettings` as `winit::run` now returns on supported platforms. - I left the example "return_after_run" as I think it's still useful. - This winit change is done partly to allow to create a new window after quitting all windows: https://github.com/emilk/egui/issues/1918 ; this PR doesn't address. - added `width` and `height` properties in the `canvas` from wasm example (https://github.com/bevyengine/bevy/pull/10702#discussion_r1420567168) ## Known regressions (important follow ups?) - Provide an API for reacting when a specific key from current layout was released. - possible solutions: use winit::Key from winit::KeyEvent ; mapping between KeyCode and Key ; or . - We don't receive characters through alt+numpad (e.g. alt + 151 = "ù") anymore ; reproduced on winit example "ime". maybe related to https://github.com/rust-windowing/winit/issues/2945 - (windows) Window content doesn't refresh at all when resizing. By reading https://github.com/rust-windowing/winit/issues/2900 ; I suspect we should just fire a `window.request_redraw();` from `AboutToWait`, and handle actual redrawing within `RedrawRequested`. I'm not sure how to move all that code so I'd appreciate it to be a follow up. - (windows) unreleased winit fix for using set_control_flow in AboutToWait https://github.com/rust-windowing/winit/issues/3215 ; ⚠️ I'm not sure what the implications are, but that feels bad 🤔 ## Follow up I'd like to avoid bloating this PR, here are a few follow up tasks worthy of a separate PR, or new issue to track them once this PR is closed, as they would either complicate reviews, or at risk of being controversial: - remove CanvasParentResizePlugin (https://github.com/bevyengine/bevy/pull/10702#discussion_r1417068856) - avoid mentionning explicitly winit in docs from bevy_window ? - NamedKey integration on bevy_input: https://github.com/rust-windowing/winit/pull/3143 introduced a new NamedKey variant. I implemented it only on the converters but we'd benefit making the same changes to bevy_input. - Add more info in KeyboardInput https://github.com/bevyengine/bevy/pull/10702#pullrequestreview-1748336313 - https://github.com/bevyengine/bevy/pull/9905 added a workaround on a bug allegedly fixed by winit 0.29. We should check if it's still necessary. - update to raw_window_handle 0.6 - blocked by wgpu - Rename `KeyCode` to `PhysicalKeyCode` https://github.com/bevyengine/bevy/pull/10702#discussion_r1404595015 - remove `instant` dependency, [replaced by](https://github.com/rust-windowing/winit/pull/2836) `web_time`), we'd need to update to : - fastrand >= 2.0 - [`async-executor`](https://github.com/smol-rs/async-executor) >= 1.7 - [`futures-lite`](https://github.com/smol-rs/futures-lite) >= 2.0 - Verify license, see [discussion](https://github.com/bevyengine/bevy/pull/8745#discussion_r1402439800) - we might be missing a short notice or description of changes made - Consider using https://github.com/rust-windowing/cursor-icon directly rather than vendoring it in bevy. - investigate [this unwrap](https://github.com/bevyengine/bevy/pull/8745#discussion_r1387044986) (`winit_window.canvas().unwrap();`) - Use more good things about winit's update - https://github.com/bevyengine/bevy/pull/10689#issuecomment-1823560428 ## Migration Guide This PR should have one.
2023-12-21 07:40:47 +00:00
if keyboard.pressed(KeyCode::ArrowDown) {
More ergonomic spatial audio (#9800) # 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>
2023-10-09 19:43:56 +00:00
transform.translation.y -= speed * time.delta_seconds();
}
}