bevyengine · alice-i-cecile · Jun 10, 2024 · Jun 8, 2024 · Jun 8, 2024 · Jun 8, 2024
diff --git a/...tion-guides/12302_Allow_setting_RenderAssetUsages_for_gLTF_meshes__materials.md b/...tion-guides/12302_Allow_setting_RenderAssetUsages_for_gLTF_meshes__materials.md
@@ -1,21 +1,25 @@
-When loading gLTF assets with `asset_server.load_with_settings`, use `RenderAssetUsages` instead of `bool` when setting load_meshes e.g.
+It is now possible configure whether meshes and materials should be loaded in the main world, the render world, or both with `GltfLoaderSettings`. The `load_meshes` field has been changed from a `bool` to a `RenderAssetUsages` bitflag, and a new `load_materials` field as been added.
 
-```rust
-let _ = asset_server.load_with_settings("...", |s: &mut GltfLoaderSettings| {
-    s.load_meshes = RenderAssetUsages::RENDER_WORLD;
-});
-```
-
-Use the new load_materials field for controlling material load & retention behaviour instead of load_meshes.
+You may need to update any gLTF `.meta` files:
 
-gLTF .meta files need similar updates e.g
+```ron
+// Before
+load_meshes: true
 
-```rust
-load_meshes: true,
+// After
+load_meshes: ("MAIN_WORLD | RENDER_WORLD")
 ```
 
-to
+If you use `AssetServer::load_with_settings` instead when loading gLTF files, you will also have to update:
 
 ```rust
-load_meshes: ("MAIN_WORLD | RENDER_WORLD"),
+// Before
+asset_server.load_with_settings("model.gltf", |s: &mut GltfLoaderSettings| {
+    s.load_meshes = true;
+});
+
+// After
+asset_server.load_with_settings("model.gltf", |s: &mut GltfLoaderSettings| {
+    s.load_meshes = RenderAssetUsages::MAIN_WORLD | RenderAssetUsages::RENDER_WORLD;
+});
 ```
diff --git a/...tion-guides/12407_Fix_leftover_references_to_children_when_despawning_audio_.md b/...tion-guides/12407_Fix_leftover_references_to_children_when_despawning_audio_.md
@@ -1 +1,5 @@
-`PlaybackSettings::DESPAWN` (`PlaybackMode::Despawn`) now despawns the audio entity’s children as well. If you were relying on the previous behavior, you may be able to use `PlaybackMode::Remove`, or you may need to use `PlaybackMode::Once` and manage your audio component lifecycle manually.
+You can configure the behavior of spawned audio with the `PlaybackMode` enum. One of its variants, `PlaybackMode::Despawn`, would despawn the entity when the audio finished playing.
+
+There was previously a bug where this would only despawn the entity and not its children. This has been fixed, so now `despawn_recursive()` is called when the audio finishes.
+
+If you relied on this behavior, consider using `PlaybackMode::Remove` to just remove the audio components from the entity or `AudioSink::empty()` to check whether any audio is finished and manually `despawn()` it.
diff --git a/...tion-guides/12547_Add_AsyncSeek_trait_to_Reader_to_be_able_to_seek_inside_as.md b/...tion-guides/12547_Add_AsyncSeek_trait_to_Reader_to_be_able_to_seek_inside_as.md
@@ -1 +1 @@
-Every custom reader (which previously only needed the `AsyncRead` trait implemented) now also needs to implement the `AsyncSeek` trait to add the seek capability.
+The asset loader's `Reader` type alias now requires the new `AsyncSeek` trait. Please implement `AsyncSeek` for any structures that must be a `Reader`, or use an alternative if seeking is not supported.
diff --git a/release-content/0.14/migration-guides/12575_Color_maths_4.md b/release-content/0.14/migration-guides/12575_Color_maths_4.md
@@ -1,4 +1,4 @@
-Multiplying and dividing a `LinearRgba` by an `f32` used to skip the alpha channel, but now it is modified.
+It was previously possible to multiply and divide a `Color` by an `f32`, which is now removed. You must now operate on a specific color space, such as `LinearRgba`. Furthermore, these operations used to skip the alpha channel, but that is no longer the case.
 
 ```rust
 // Before
@@ -53,6 +53,7 @@ let mut color = LinearRgba {
     alpha: 1.0,
 } * 10.0;
 
+// Force alpha to be within [0.0, 1.0].
 color.alpha = color.alpha.clamp(0.0, 1.0);
 ```
 

diff --git a/...ation-guides/12605_Make_AssetActionIgnore_not_copy_assets_to_imported_assets.md b/...ation-guides/12605_Make_AssetActionIgnore_not_copy_assets_to_imported_assets.md
@@ -1 +1 @@
-The asset processor no longer copies over `.meta` files that specify `asset: Ignore`. With this change, the `Ignore` variant has been added to the `ProcessResult` enum. Make sure to update your `match` statements.
+The `ProcessResult` enum, used in asset loading, has a new `Ignore` variant. You may need to update your `match` statements.
diff --git a/...ent/0.14/migration-guides/12709_Error_info_has_been_added_to_LoadStateFailed.md b/...ent/0.14/migration-guides/12709_Error_info_has_been_added_to_LoadStateFailed.md
@@ -1,14 +1,19 @@
-Added [AssetLoadError](https://docs.rs/bevy/latest/bevy/asset/enum.AssetLoadError.html) to the [LoadState::Failed](https://docs.rs/bevy/latest/bevy/asset/enum.LoadState.html) variant.
+Rust prides itself on its error handling, and Bevy has been steadily catching up. Previously, when checking if an asset was loaded using `AssetServer::load_state` (and variants), the only information returned on an error was the empty `LoadState::Failed`. Not very useful for debugging!
 
-If you're comparing for equality with `LoadState::Failed`, you'll need to use pattern matching instead.
+Now, a full `AssetLoadError` is included inside `Failed` to tell you exactly what went wrong. You may need to update your `match` and `if let` statements to handle this new value:
 
 ```rust
-// 0.13
-if state == LoadState::Failed {}
-// 0.14
-if matches!(state, LoadState::Failed(_)) {}
-```
+// Before
+match asset_server.load_state(asset_id) {
+    // ...
+    LoadState::Failed => eprintln!("Could not load asset!"),
+}
 
-Removed `Copy`, `Ord` and `PartialOrd` implementations for [LoadState](https://docs.rs/bevy/latest/bevy/asset/enum.LoadState.html) enum
+// After
+match asset_server.load_state(asset_id) {
+    // ...
+    LoadState::Failed(error) => eprintln!("Could not load asset! Error: {}", error),
+}
+```
 
-Added `Eq` and `PartialEq` implementations for [MissingAssetSourceError](https://docs.rs/bevy/latest/bevy/asset/io/struct.MissingAssetSourceError.html), [MissingProcessedAssetReaderError](https://docs.rs/bevy/latest/bevy/asset/io/struct.MissingProcessedAssetReaderError.html), [DeserializeMetaError](https://docs.rs/bevy/latest/bevy/asset/enum.DeserializeMetaError.html), [LoadState](https://docs.rs/bevy/latest/bevy/asset/enum.LoadState.html), [AssetLoadError](https://docs.rs/bevy/latest/bevy/asset/enum.AssetLoadError.html), [MissingAssetLoaderForTypeNameError](https://docs.rs/bevy/latest/bevy/asset/struct.MissingAssetLoaderForTypeNameError.html) and [MissingAssetLoaderForTypeIdError](https://docs.rs/bevy/latest/bevy/asset/struct.MissingAssetLoaderForTypeIdError.html)
+Furthermore, the `Copy`, `PartialOrd`, and `Ord` implementations have been removed from `LoadState`. You can explicitly call `.clone()` instead of copying the enum, and you can manually re-implement `Ord` as a helper method if required.
diff --git a/....14/migration-guides/12827_Consolidate_RenderUiMaterials2d_into_RenderAssets.md b/....14/migration-guides/12827_Consolidate_RenderUiMaterials2d_into_RenderAssets.md
@@ -1 +1,19 @@
-`RenderAsset` is now implemented for the destination type rather that the source asset type. The source asset type is now the `RenderAsset` trait’s `SourceAsset` associated type.
+`RenderMaterials`, `RenderMaterials2d`, and `RenderUiMaterials` have all been replaced with the `RenderAssets` resource. If you need access a `PreparedMaterial<T>` using an `AssetId`, use `RenderAssets::get` instead.
+
+Furthermore, the `RenderAsset` trait should now be implemented for destination types rather than source types. If you need to access the source type, use the `RenderAsset::SourceAsset` associated type.
+
+```rust
+// Before
+impl RenderAsset for Image {
+    type PreparedAsset = GpuImage;
+
+    // ...
+}
+
+// After
+impl RenderAsset for GpuImage {
+    type SourceAsset = Image;
+
+    // ...
+}
+```
diff --git a/release-content/0.14/migration-guides/12923_tools_Refactor_CI_to_use_argh.md b/release-content/0.14/migration-guides/12923_tools_Refactor_CI_to_use_argh.md
diff --git a/.../0.14/migration-guides/13177_Make_AssetMetaCheck_a_field_on_the_asset_plugin.md b/.../0.14/migration-guides/13177_Make_AssetMetaCheck_a_field_on_the_asset_plugin.md
@@ -1 +1,17 @@
-Changes to how bevy handles asset meta files now need to be specified when inserting the `AssetPlugin`.
+`AssetMetaCheck` is used to configure how the `AssetPlugin` reads `.meta` files. It was previously a resource, but now has been changed to a field in `AssetPlugin`. If you use `DefaultPlugins`, you can use `.set` to configure this field.
+
+```rust
+// Before
+App::new()
+    .add_plugins(DefaultPlugins)
+    .insert_resource(AssetMetaCheck::Never)
+    .run();
+
+// After
+App::new()
+    .add_plugins(DefaultPlugins.set(AssetPlugin {
+        meta_check: AssetMetaCheck::Never,
+        ..default()
+    }))
+    .run();
+```
diff --git a/...gration-guides/13209_move_wgsl_color_operations_from_bevy_pbr_to_bevy_render.md b/...gration-guides/13209_move_wgsl_color_operations_from_bevy_pbr_to_bevy_render.md
@@ -1 +1,9 @@
-In user’s shader code replace usage of mathematical constants from `bevy_pbr::utils` to the usage of the same constants from `bevy_render::maths`.
+Mathematical constants and color conversion functions for shaders have been moved from `bevy_pbr::utils` to `bevy_render::maths` and `bevy_render::color_operations`. If you depended on these in your own shaders, please update your import statements:
+
+```wgsl
+// Before
+#import bevy_pbr::utils::{PI, rgb_to_hsv}
+
+// After
+#import bevy_render::{maths::PI, color_operations::rgb_to_hsv}
+```
diff --git a/release-content/0.14/migration-guides/13307_Remove_ClampColor.md b/release-content/0.14/migration-guides/13307_Remove_ClampColor.md
diff --git a/...ase-content/0.14/migration-guides/13415_Add_more_load_direct_implementations.md b/...ase-content/0.14/migration-guides/13415_Add_more_load_direct_implementations.md
diff --git a/...tion-guides/13465_Make_LoadContext_use_the_builder_pattern_for_loading_depen.md b/...tion-guides/13465_Make_LoadContext_use_the_builder_pattern_for_loading_depen.md
@@ -1,10 +1,25 @@
-Several `LoadContext` method calls will need to be updated:
-
-- `load_context.load_with_settings(path, settings)` => `load_context.loader().with_settings(settings).load(path)`
-- `load_context.load_untyped(path)` => `load_context.loader().untyped().load(path)`
-- `load_context.load_direct(path)` => `load_context.loader().direct().load(path)`
-- `load_context.load_direct_untyped(path)` => `load_context.loader().direct().untyped().load(path)`
-- `load_context.load_direct_with_settings(path, settings)` => `load_context.loader().with_settings(settings).direct().load(path)`
-- `load_context.load_direct_with_reader(reader, path)` => `load_context.loader().direct().with_reader(reader).load(path)`
-- `load_context.load_direct_with_reader_and_settings(reader, path, settings)` => `load_context.loader().with_settings(settings).direct().with_reader(reader).load(path)`
-- `load_context.load_direct_untyped_with_reader(reader, path)` => `load_context.loader().direct().with_reader(reader).untyped().load(path)`
+<!-- Note: This is the migration guide for both #13465 AND #13415. -->
+
+`LoadContext`, used by `AssetLoader`, has been updated so all of its `load_*` methods have been merged into a builder struct.
+
+```rust
+// Before
+load_context.load_direct(path);
+// After
+load_context.loader().direct().untyped().load(path);
+
+// Before
+load_context.load_direct_with_reader(reader, path);
+// After
+load_context.loader().direct().with_reader(reader).untyped().load(path);
+
+// Before
+load_context.load_untyped(path);
+// After
+load_context.loader().untyped().load(path);
+
+// Before
+load_context.load_with_settings(path, settings);
+// After
+load_context.loader().with_settings(settings).load(path);
+```
diff --git a/...gration-guides/13513_Refactor_ci_testing_and_separate_it_from_DevToolsPlugin.md b/...gration-guides/13513_Refactor_ci_testing_and_separate_it_from_DevToolsPlugin.md
diff --git a/...tion-guides/13637_Move_state_installation_methods_from_bevy_app_to_bevy_stat.md b/...tion-guides/13637_Move_state_installation_methods_from_bevy_app_to_bevy_stat.md
@@ -1 +1,17 @@
-`App::init_state` is now provided by the `bevy_state::app::AppExtStates;` trait: import it if you need this method and are not blob-importing the `bevy` prelude.
+`State` has been moved to `bevy::state`. With it, `App::init_state` has been moved from a normal method to an extension trait. You may now need to import `AppExtStates` in order to use this method. (This trait is behind the `bevy_app` feature flag, which you may need to enable.)
+
+```rust
+// Before
+App::new()
+    .init_state::<MyState>()
+    .run();
+
+// After
+use bevy::state::app::AppExtStates as _;
+
+App::new()
+    .init_state::<MyState>()
+    .run();
+```
+
+If you import the prelude (such as with `use bevy::prelude::*`), you do not need to do this.
diff --git a/release-content/0.14/migration-guides/_guides.toml b/release-content/0.14/migration-guides/_guides.toml
@@ -47,7 +47,7 @@ areas = ["App"]
 file_name = "13080_Deprecate_dynamic_plugins.md"
 
 [[guides]]
-title = "Move state installation methods from `bevy_app` to `bevy_state`"
+title = "Move state initialization methods to `bevy::state`"
 url = "https://github.com/bevyengine/bevy/pull/13637"
 areas = ["App","ECS"]
 file_name = "13637_Move_state_installation_methods_from_bevy_app_to_bevy_stat.md"
@@ -89,31 +89,25 @@ areas = ["Assets"]
 file_name = "12709_Error_info_has_been_added_to_LoadStateFailed.md"
 
 [[guides]]
-title = "Make `AssetMetaCheck` a field on the asset plugin"
+title = "Make `AssetMetaCheck` a field of `AssetPlugin`"
 url = "https://github.com/bevyengine/bevy/pull/13177"
 areas = ["Assets"]
 file_name = "13177_Make_AssetMetaCheck_a_field_on_the_asset_plugin.md"
 
 [[guides]]
-title = "Add more load_direct implementations"
-url = "https://github.com/bevyengine/bevy/pull/13415"
-areas = ["Assets"]
-file_name = "13415_Add_more_load_direct_implementations.md"
-
-[[guides]]
-title = "Make LoadContext use the builder pattern for loading dependent assets"
+title = "Make `LoadContext` use the builder pattern"
 url = "https://github.com/bevyengine/bevy/pull/13465"
 areas = ["Assets"]
 file_name = "13465_Make_LoadContext_use_the_builder_pattern_for_loading_depen.md"
 
 [[guides]]
-title = "Allow setting RenderAssetUsages for gLTF meshes & materials during load"
+title = "Use `RenderAssetUsages` to configure gLTF meshes & materials during load"
 url = "https://github.com/bevyengine/bevy/pull/12302"
 areas = ["Assets","Rendering"]
 file_name = "12302_Allow_setting_RenderAssetUsages_for_gLTF_meshes__materials.md"
 
 [[guides]]
-title = "Consolidate Render(Ui)Materials(2d) into RenderAssets"
+title = "Consolidate `RenderMaterials` and similar into `RenderAssets`, implement `RenderAsset` for destination type"
 url = "https://github.com/bevyengine/bevy/pull/12827"
 areas = ["Assets","Rendering"]
 file_name = "12827_Consolidate_RenderUiMaterials2d_into_RenderAssets.md"
@@ -125,29 +119,11 @@ areas = ["Audio"]
 file_name = "12407_Fix_leftover_references_to_children_when_despawning_audio_.md"
 
 [[guides]]
-title = "tools: Refactor CI to use `argh`"
-url = "https://github.com/bevyengine/bevy/pull/12923"
-areas = ["Build-System"]
-file_name = "12923_tools_Refactor_CI_to_use_argh.md"
-
-[[guides]]
-title = "Refactor `ci_testing` and separate it from `DevToolsPlugin`"
-url = "https://github.com/bevyengine/bevy/pull/13513"
-areas = ["Build-System"]
-file_name = "13513_Refactor_ci_testing_and_separate_it_from_DevToolsPlugin.md"
-
-[[guides]]
-title = "move wgsl color operations from bevy_pbr to bevy_render"
+title = "Move WGSL math constants and color operations from `bevy_pbr` to `bevy_render`"
 url = "https://github.com/bevyengine/bevy/pull/13209"
 areas = ["Color"]
 file_name = "13209_move_wgsl_color_operations_from_bevy_pbr_to_bevy_render.md"
 
-[[guides]]
-title = "Remove `ClampColor`"
-url = "https://github.com/bevyengine/bevy/pull/13307"
-areas = ["Color"]
-file_name = "13307_Remove_ClampColor.md"
-
 [[guides]]
 title = "Migrate from `LegacyColor` to `bevy_color::Color`"
 url = "https://github.com/bevyengine/bevy/pull/12163"

diff --git a/...lease-notes/12547_Add_AsyncSeek_trait_to_Reader_to_be_able_to_seek_inside_as.md b/...lease-notes/12547_Add_AsyncSeek_trait_to_Reader_to_be_able_to_seek_inside_as.md
@@ -1 +1 @@
-The asset loader's `Reader` type alias now requires the new `AsyncSeek` trait. Please implement `AsyncSeek` for any structures that must be a `Reader`, or use an alternative to `Reader` if seeking is not supported.
+TODO
diff --git a/...ontent/0.14/release-notes/12709_Error_info_has_been_added_to_LoadStateFailed.md b/...ontent/0.14/release-notes/12709_Error_info_has_been_added_to_LoadStateFailed.md
@@ -1,17 +1,7 @@
-Rust prides itself on its error handling, and Bevy has been steadily catching up. Previously, when checking if an asset was loaded using `AssetServer::load_state` (and variants), the only information returned on an error was the empty `LoadState::Failed`. Not very useful for debugging!
+Rust prides itself on its error handling, and Bevy has been steadily catching up.
+Previously, when checking if an asset was loaded using [`AssetServer::get_load_state`](https://dev-docs.bevyengine.org/bevy/asset/struct.AssetServer.html#method.get_load_state),
+all you'd get back was a data-less [`LoadState::Failed`](https://dev-docs.bevyengine.org/bevy/asset/enum.LoadState.html) if something went wrong.
+Not very useful for debugging!
 
-Now, a full `AssetLoadError` is included inside `Failed` to tell you exactly what went wrong. You may need to update your `match` and `if let` statements to handle this new value:
-
-```rust
-// Before
-match asset_server.load_state(asset_id) {
-    // ...
-    LoadState::Failed => eprintln!("Could not load asset!"),
-}
-
-// After
-match asset_server.load_state(asset_id) {
-    // ...
-    LoadState::Failed(error) => eprintln!("Could not load asset! Error: {}", error),
-}
-```
+Now, a full [`AssetLoadError`](https://dev-docs.bevyengine.org/bevy/asset/enum.AssetLoadError.html) is included, with 14 different variants telling you exactly what went wrong.
+Great for troubleshooting, and it opens the door to proper error handling in more complex apps.