Migration writing pass 1 (#2053)

Co-authored-by: Alice Cecile <[email protected]>

Author: BD103

release-content/0.16/migration-guides/15487_Remove_the_meta_field_from_LoadedAsset_and_ErasedLoadedAss.md

@@ -1,3 +1,5 @@
-- `ErasedAssetLoader` now takes a borrow to `AssetMetaDyn` instead of a `Box`.
-- `LoadedAsset::new_with_dependencies` no longer requires a `meta` argument.
-- `LoadContext::finish` no longer requires a `meta` argument.
+`LoadedAsset` used to have a `meta` field for storing metadata. This field was unused and inaccessible, however, so in 0.16 it has been removed. Due to this change, several method signatures have also changed:
+
+- `ErasedAssetLoader::load()` now takes `meta: &(dyn AssetMetaDyn + 'static)` instead of a `Box<dyn AssetMetaDyn>`.
+- `LoadedAsset::new_with_dependencies()` no longer requires a `meta` argument.
+- `LoadContext::finish()` no longer requires a `meta` argument.

release-content/0.16/migration-guides/16279_Incorporate_all_node_weights_in_additive_blending.md

@@ -1 +1 @@
-- The `asset_events` system is no longer public. Users should order their systems relative to the `AssetEvents` system set.
+The `Assets::asset_events()` system is no longer public. If you wish to order your systems relative to asset events, use the new `AssetEvents` system set instead.

release-content/0.16/migration-guides/16401_Headless_by_features.md

@@ -1,29 +1,20 @@
-- The `AudioSinkPlayback` trait now has 4 new methods to allow you to mute audio sinks: `is_muted`, `mute`, `unmute` and `toggle_mute`. You can use these methods on `bevy_audio`’s `AudioSink` and `SpatialAudioSink` components to manage the sink’s mute state.
-- `AudioSinkPlayback`’s `set_volume` method now takes a mutable reference instead of an immutable one. Update your code which calls `set_volume` on `AudioSink` and `SpatialAudioSink` components to take a mutable reference. E.g.:
+It is now possible to mute audio sinks. Several breaking changes have been introduced to implement this feature.
 
-Before:
+First, `AudioSinkPlayback::set_volume()` now takes a mutable `&mut AudioSinkPlayback` argument instead of an immutable one. This may require you to update your system parameters:
 
 ```rust
-fn increase_volume(sink: Single<&AudioSink>) {
+// 0.15
+fn increase_volume(sink: Single<&AudioSink, With<Music>>) {
     sink.set_volume(sink.volume() + 0.1);
 }
-```
-
-After:
 
-```rust
-fn increase_volume(mut sink: Single<&mut AudioSink>) {
+// 0.16
+fn increase_volume(mut sink: Single<&mut AudioSink, With<Music>>) {
     let current_volume = sink.volume();
     sink.set_volume(current_volume + 0.1);
 }
 ```
 
-- The `PlaybackSettings` component now has a `muted` field which you can use to spawn your audio in a muted state. `PlaybackSettings` also now has a helper method `muted` which you can use when building the component. E.g.: 
+Secondly, `PlaybackSettings` has a new `muted` field to specify whether an entity should start muted. You may need to set this field when creating `PlaybackSettings` if you do not use function update syntax (`..default()`).
 
-```rust
-commands.spawn((
-    // ...
-    AudioPlayer::new(asset_server.load("sounds/Windless Slopes.ogg")),
-    PlaybackSettings::LOOP.with_spatial(true).muted(),
-));
-```
+Finally, if you manually implemented audio muting using an audio sink's volume, you can switch over to using the new `AudioSinkPlayback` methods: `is_muted()`, `mute()`, `unmute()` and `toggle_mute()`.

release-content/0.16/migration-guides/16810_Add_AssetChanged_query_filter.md

@@ -1,21 +1,19 @@
-- `AudioSinkPlayback`’s `toggle` method has been renamed to `toggle_playback`. This was done to create consistency with the `toggle_mute` method added in https://github.com/bevyengine/bevy/pull/16813. Change instances of `toggle` to `toggle_playback`. E.g.:
-
-Before:
+`AudioSinkPlayback::toggle()` has been renamed to `toggle_playback()`. This was done to create consistency with the `toggle_mute()` method added in [#16813]. Please update all references to use the new name.
 
 ```rust
+// 0.15
 fn pause(keyboard_input: Res<ButtonInput<KeyCode>>, sink: Single<&AudioSink>) {
     if keyboard_input.just_pressed(KeyCode::Space) {
         sink.toggle();
     }
 }
-```
-
-After:
 
-```rust
+// 0.16
 fn pause(keyboard_input: Res<ButtonInput<KeyCode>>, sink: Single<&AudioSink>) {
     if keyboard_input.just_pressed(KeyCode::Space) {
         sink.toggle_playback();
     }
 }
 ```
+
+[#16813]: https://github.com/bevyengine/bevy/pull/16813

release-content/0.16/migration-guides/16813_Add_ability_to_mute_audio_sinks.md

@@ -1 +1 @@
-`bevy_a11y::Focus` has been replaced with `bevy_input_focus::Focus`.
+Bevy now has first-class input handling, available in the `bevy::input_focus` module. As such, `bevy::a11y::Focus` has been replaced with `bevy::input_focus::Focus`. Please replace all references and imports.

release-content/0.16/migration-guides/16837_Rename_AudioSinkPlaybacktoggle_to_toggle_playback.md

@@ -1,3 +1,5 @@
-This release of bevy slightly tweaked the definitions of `EaseFunction::ExponentialIn`, `EaseFunction::ExponentialOut`, and `EaseFunction::ExponentialInOut`.  The previous definitions had small discontinuities, while the new ones are slightly rescaled to be continuous.  For the output values that changed, that change was less than 0.001, so visually you might not even notice the difference.
+`EaseFunction::ExponentialIn`, `EaseFunction::ExponentialOut`, and `EaseFunction::ExponentialInOut` has slight discontinuities in 0.15, leading to [jumping behavior at the start and end of the function][jumping behavior]. In 0.16, these functions have been slightly adjusted so that they are continuous.
 
-However, if you depended on them for determinism, you’ll need to define your own curves with the previous definitions.
+The new functions differ from the old by less than 0.001, so in most cases this change is not breaking. If, however, you depend on these easing functions for determinism, you will need to define custom curves using the previous functions.
+
+[jumping behavior]: https://github.com/bevyengine/bevy/issues/16676

release-content/0.16/migration-guides/16863_Replace_bevy_a11yFocus_with_InputFocus.md

@@ -1,20 +1,18 @@
-Audio volume can now be configured using decibel values, as well as using linear scale values. To enable this, some types and functions in `bevy_audio` have changed.
-
-- `Volume` is now an enum with `Linear` and `Decibels` variants.
-
-Before:
+Audio volume can now be configured using decibel values, as well as using linear scale values. To enable this, some types and functions in `bevy::audio` have changed. First, `Volume` is now an enum with `Linear` and `Decibels` variants:
 
 ```rust
+// 0.15
 let v = Volume(1.0);
-```
-
-After:
 
-```rust
+// 0.16
 let volume = Volume::Linear(1.0);
-let volume = Volume::Decibels(0.0); // or now you can deal with decibels if you prefer
+
+// Alternatively, you can use decibels instead.
+let volume = Volume::Decibels(0.0);
 ```
 
-- `Volume::ZERO` has been renamed to the more semantically correct `Volume::SILENT` because `Volume` now supports decibels and “zero volume” in decibels actually means “normal volume”.
-- The `AudioSinkPlayback` trait’s volume-related methods now deal with `Volume` types rather than `f32`s. `AudioSinkPlayback::volume()` now returns a `Volume` rather than an `f32`. `AudioSinkPlayback::set_volume` now receives a `Volume` rather than an `f32`. This affects the `AudioSink` and `SpatialAudioSink` implementations of the trait. The previous `f32` values are equivalent to the volume converted to linear scale so the  `Volume:: Linear` variant should be used to migrate between `f32`s and `Volume`.
-- The `GlobalVolume::new` function now receives a `Volume` instead of an `f32`.
+`Volume::Linear` is equivalent to the old `f32` volume.
+
+With this change, `AudioSinkPlayback`'s volume-related methods (`volume()` and `set_volume()`) and `GlobalVolume` now deal in `Volume`s rather than `f32`s.
+
+Finally, `Volume::ZERO` has been renamed to the more semantically correct `Volume::SILENT`. This is because 0 decibals is equivalent to "normal volume", which could lead to confusion with the old naming.

release-content/0.16/migration-guides/16910_Fix_EaseFunctionExponential_to_exactly_hit_0_0_and_1_1.md

@@ -1 +1,9 @@
-Replace `Handle::weak_from_u128` with `weak_handle!` and a random UUID.
+`Handle::weak_from_u128()` has been deprecated in favor of the new `weak_handle!` macro, which takes a UUID as a string instead of a `u128`. `weak_handle!` is preferred because it both makes the string form of the UUID visible and it verifies that the UUID is compliant with UUIDv4.
+
+```rust
+// 0.15
+const SHADER: Handle<Shader> = Handle::weak_from_u128(314685653797097581405914117016993910609);
+
+// 0.16
+const SHADER: Handle<Shader> = weak_handle!("1347c9b7-c46a-48e7-b7b8-023a354b7cac");
+```