Migration guide editing pass

content/learn/migration-guides/0.18-to-0.19.md

@@ -4,15 +4,37 @@ insert_anchor_links = "right"
 [extra]
 weight = 14
 long_title = "Migration Guide: 0.18 to 0.19"
-public_draft = 2474
-status = 'hidden'
 +++
 
+Like every major Bevy release, Bevy 0.19 comes with its own set of breaking changes.
+The most important changes to be aware of are listed below:
+
+1. [Resources-as-components]: resources are now stored as components on dedicated abstract entities
+2. [Render-graph-as-systems]: rendering now uses systems too!
+3. [Parley text overhaul]: we've moved from `cosmic-text` to `parley` and revamped our text internals
+4. [Cargo feature collection changes]: now more granular. Check here if your audio isn't working!
+5. [`bevy_scene` has been renamed to `bevy_world_serialization`]: making space for `BSN`
+6. [Bloom now uses linear color]: more correct, looks subtly different
+
+This list prioritizes changes which are sweeping overhauls (1-3) or break in confusing or quiet ways (4-6).
+
+For a full list of changes that may require migration, please see below. We recommend keeping this page open as you migrate your code base, and searching within it for any issues you encounter.
+
+If you run into a problem while migrating that was not covered by this migration guide, please open an issue on the [`bevy-website`] repo or file a PR directly with the correct migration advice.
+
+[`bevy-website`]: https://github.com/bevyengine/bevy-website/
+[Resources-as-components]: #resources-as-components
+[Render-graph-as-systems]: #render-graph-as-systems
+[Parley text overhaul]: #bevy-text-migration-from-cosmic-text-to-parley
+[Cargo feature collection changes]: #audio-feature-is-now-no-longer-implied-by-the-3d-2d-or-ui-features
+[`bevy_scene` has been renamed to `bevy_world_serialization`]: #the-old-bevy-scene-is-now-bevy-world-serialization
+[Bloom now uses linear color]: #bloom-luma-calculation-now-in-linear-space
+
 ### Resources as Components
 
 {{ heading_metadata(prs=[20934, 22910, 22911, 22919, 22930, 24424]) }}
 
-## `#[derive(Resource)]` implements the `Component` trait
+#### `#[derive(Resource)]` implements the `Component` trait
 
 In 0.19, `Resource` is a subtrait of `Component` and `#[derive(Resource)]` implements both `Resource` as well as `Component`.
 This means it's no longer possible to doubly derive both `Component` and `Resource`.
@@ -37,13 +59,13 @@ struct DualRes;
 
 Consequently, `UiDebugOverlay` is split into `GlobalUiDebugOverlay` (resource) and `UiDebugOverlay` (component), and `UiDebugOptions` is split into `GlobalUiDebugOptions` (resource) and `UiDebugOptions` (component).
 
-## `#[reflect(Resource)]` Changes
+#### `#[reflect(Resource)]` Changes
 
 In 0.19, the `ReflectResource` is a ZST (zero-sized type) and only functions to signify that the trait is reflected.
 Instead, `#[reflect(Resource)]` also reflects the `Component` trait, so use `ReflectComponent` instead.
 This is likely to show up in code that uses reflection, like BRP (Bevy Remote Protocol) and `bevy_world_serialization`.
 
-## Broad Queries and System Conflicts
+#### Broad Queries and System Conflicts
 
 Now that resources are components, they can be queried using 'broad' queries. These are queries that query all entities. Examples include:
 
@@ -72,7 +94,7 @@ fn system(entity_query: Query<EntityMut>, some_non_send: NonSend<MyNonSend>) {}
 
 This can be fixed by adding a `Without<MyNonSend>` filter to the query.
 
-## Renaming Non-Send Resources to Non-Send Data
+#### Renaming Non-Send Resources to Non-Send Data
 
 Previously there were two types of resources: `Send` resources and `!Send` resources.
 Now that `Send` resources are stored as components, `!Send` resources have little in common with their `Send` counterparts.
@@ -92,12 +114,12 @@ The following APIs are affected:
 - `World::init_non_send_resource` is deprecated in favor of `World::init_non_send`.
 - `World::insert_non_send_resource` is deprecated in favor of `World::insert_non_send`.
 - `World::remove_non_send_resource` is deprecated in favor of `World::remove_non_send`.
-- `World::non_send_resource` is deprecated in favor of`World::non_send`.
+- `World::non_send_resource` is deprecated in favor of `World::non_send`.
 - `World::non_send_resource_mut` is deprecated in favor of `World::non_send_mut`.
 - `World::get_non_send_resource` is deprecated in favor of `World::get_non_send`.
 - `World::get_non_send_resource_mut` is deprecated in favor of `World::get_non_send_mut`.
 
-## Component Registration
+#### Component Registration
 
 Before using components and resources they must be registered to a world.
 The registration process for components and resources is very similar and now that `Send` resources *are* components, we're able to simplify some of the code; removing / deprecating some methods.
@@ -112,10 +134,9 @@ The registration process for components and resources is very similar and now th
 - `ComponentsQueuedRegistrator::queue_register_resource_with_descriptor` was removed in favor of `ComponentsQueuedRegistrator::queue_register_component_with_descriptor`.
 - `ComponentsQueuedRegistrator::queue_register_resource` was deprecated in favor of `ComponentsQueuedRegistrator::queue_register_component`.
 - `ComponentDescriptor::new_resource` was deprecated in favor of `ComponentDescriptor::new`
-- `ComponentDescriptor::new_resource` was deprecated in favor of `ComponentDescriptor::new`
 - `World::register_resource_with_descriptor` was renamed to `World::register_non_send_with_descriptor`.
 
-## Access
+#### Access
 
 Resources were also removed from `Access`, which keeps track what data any given query / system has access to.
 
@@ -151,7 +172,7 @@ Due to the split storage it used to be possible to both access an entity and a r
 This is no longer valid. In order to access multiple different entities for a `WorldQuery` implementation, use `WorldQuery::init_nested_access`.
 See the implementation of `WorldQuery` for `AssetChanged` for an example of how this can be done correctly.
 
-## Immutable Resources
+#### Immutable Resources
 
 Since resources may now be immutable, the following now carry a `Mutability = Mutable` bound:
 
@@ -182,7 +203,7 @@ If the bound cannot be added, there are a couple of options:
 - If the resource is only sometimes mutable OR the API should not be unsafe, use `World::modify_resource` and `World::modify_resource_by_id`. They behave exactly like their component counterparts.
 - If your API can be made unsafe, use the `UnsafeWorldCell::*_assume_mutable` methods and make sure that the safety conditions are satisfied. `UnsafeWorldCell::get_resource_mut_assume_mutable` has been provided for this explicit purpose. It is also possible to use the `*_assume_mutable` component methods, but you will first have to retrieve the resource entity from `ResourceEntities`.
 
-## Miscellaneous
+#### Miscellaneous
 
 Since `MapEntities` is implemented by default for components, it's no longer necessary to add `derive(MapEntities)` to a resource.
 
@@ -212,7 +233,7 @@ The `ID` and family name of `Font` assets can be retrieved from the asset itself
 
 {{ heading_metadata(prs=[22681]) }}
 
-With the addition of `Affine3` on glam, Bevy's version was removed. To keep the functionality that Bevy's version provided we created the extension trait `Affine3Ext`. Locations that accessed  `Affine3::to_transpose` or `Affine3::inverse_transpose_3x3` will now need the extension trait to be in scope.
+With the addition of `Affine3` on glam, Bevy's version was removed. To keep the functionality that Bevy's version provided we created the extension trait `Affine3Ext`. Locations that accessed `Affine3::to_transpose` or `Affine3::inverse_transpose_3x3` will now need the extension trait to be in scope.
 
 ### `AssetPath::resolve` and `resolve_embed` now take `&AssetPath`
 
@@ -228,7 +249,7 @@ This change avoids unnecessary string allocation and parsing when an `AssetPath`
 
 `allow_copies_from_indirect_parameter_buffers` has been moved from `IndirectParametersBuffers` to a new `IndirectParametersBuffersSettings` resource.
 
-### The old `bevy_scene` is now `bevy_world_serialization
+### The old `bevy_scene` is now `bevy_world_serialization`
 
 {{ heading_metadata(prs=[23619, 23630]) }}
 
@@ -288,7 +309,7 @@ While it remains incomplete and is subject to breaking changes, it is no longer
 
 ### Rename `Font::try_from_bytes` to `Font::from_bytes`
 
-{{ heading_metadata(prs=[22879, 23777]) }}
+{{ heading_metadata(prs=[22879, 23777, 24362]) }}
 
 `Font::try_from_bytes` has been renamed to `Font::from_bytes` to reflect that it no longer returns `Result`.
 
@@ -297,7 +318,7 @@ While it remains incomplete and is subject to breaking changes, it is no longer
 let font = Font::try_from_bytes(bytes.to_vec()).unwrap();
 
 // 0.19
-let font = Font::from_bytes(bytes.to_vec(), "MyFontFamily");
+let font = Font::from_bytes(bytes.to_vec());
 ```
 
 Note that the family name is not part of this specific change, but is required in 0.19.
@@ -625,7 +646,7 @@ inner `T`, use `ref.as_ref().clone()`, `ref.deref().clone()`, or `ref.into_inner
 
 {{ heading_metadata(prs=[23098]) }}
 
-For both `Core2dSystems` and `Core3dSystems`, the `PostProcess` system set has been split into `EarlyPostProcess` and `PostProcess`.  2D now also has a `Prepass`.  Both systems have the following sets:
+For both `Core2dSystems` and `Core3dSystems`, the `PostProcess` system set has been split into `EarlyPostProcess` and `PostProcess`. 2D now also has a `Prepass`. Both systems have the following sets:
 
 - `Prepass`
 - `MainPass`
@@ -646,7 +667,7 @@ from `&dyn PartialReflect` to a tuple of `(&str, &dyn PartialReflect)`, so that
 
 {{ heading_metadata(prs=[23381]) }}
 
-`PositionedGlyph::span_idex` has been renamed to `section_index`, because only a `TextSpan` entity should be referred to as a "span". We use "section" when an entity could be either a text root or a `TextSpan`.
+`PositionedGlyph::span_index` has been renamed to `section_index`, because only a `TextSpan` entity should be referred to as a "span". We use "section" when an entity could be either a text root or a `TextSpan`.
 
 ### DynamicSceneBuilder and DynamicScene::from_scene now require a &TypeRegistry
 
@@ -715,7 +736,7 @@ Dropping a `Task<T>` in a web build now cancels it, call `Task<T>::detach()` to
 
 {{ heading_metadata(prs=[23384]) }}
 
-The return type of `Access::archetypal` has changed from `impl Iterator` to a new `&ComponentIdSet` type.  That type does implement `IntoIterator`, but callers may need to call the `iter()` method to get an `Iterator`.
+The return type of `Access::archetypal` has changed from `impl Iterator` to a new `&ComponentIdSet` type. That type does implement `IntoIterator`, but callers may need to call the `iter()` method to get an `Iterator`.
 
 ### `bevy_reflect` reorganized to de-clutter the crate root
 
@@ -830,11 +851,11 @@ In Bevy 0.18, [feature collections were introduced](https://bevy.org/learn/migra
 
 In Bevy 0.19, these have been moved from `default_app`:
 
-|Feature           |is included in... |
-|:----------------:|:-----------------|
-|`bevy_window`     |`common_api`      |
-|`bevy_input_focus`|`ui_api`          |
-|`custom_cursor`   |`default_platform`|
+|      Feature       | is included in...  |
+| :----------------: | :----------------- |
+|   `bevy_window`    | `common_api`       |
+| `bevy_input_focus` | `ui_api`           |
+|  `custom_cursor`   | `default_platform` |
 
 This change was made because:
 
@@ -858,9 +879,6 @@ bevy = { version = "0.19", default-features = false, features = [
 
 If you already depend on a high-level profile (`2d`, `3d`, `ui`), or a mid-level collection ending in '`_render`' or '`_api`', then you do not need to make any changes.
 
----
-I've erred on the side of hopefully-longer-than-it-needs-to-be.
-
 ### `extra_buffer_usages` moved from `MeshAllocator` to `MeshAllocatorSettings`
 
 {{ heading_metadata(prs=[23444]) }}
@@ -1001,7 +1019,7 @@ Similarly, `ViewTarget::is_hdr` was removed. Use `ExtractedCamera::hdr` to check
 
 `rodio` was updated to `0.22` and `cpal` to `0.17`. The following sections will guide you through the necessary changes to ensure compatibility.
 
-## Audio Feature Flags
+#### Audio Feature Flags
 
 Audio format related features were reworked with this update.
 
@@ -1029,11 +1047,11 @@ Notice that OGG/VORBIS support through `symphonia` is currently subject to issue
 
 The `audio-all-formats` feature collection was added for convenience. It will enable `bevy_audio` and all the available audio formats through their default backends.
 
-## Audio Traits
+#### Audio Traits
 
 `type DecoderItem` was removed from the `Decodable` trait. Now `rodio::Sample` is an alias for `f32`.
 
-## Android Related Features
+#### Android Related Features
 
 The `android_shared_stdcxx` feature was removed, as `cpal`'s `oboe-shared-stdcxx` feature was also removed in favor of Android NDK audio APIs.
 
@@ -1117,12 +1135,12 @@ let plugin = EasyScreenRecordPlugin {
 
 The `width` and `height` fields of `MeasureArgs` have been renamed to `known_width` and `known_height`, respectively.
 
-### `FullScreenMaterial` API changes
+### `FullscreenMaterial` API changes
 
 {{ heading_metadata(prs=[23786]) }}
 
-`FullScreenMaterial::run_in`, `FullScreenMaterial::run_after` and `FullScreenMaterial::run_before` are replaced
-by `FullScreenMaterial::schedule_configs` to configure the system order.
+`FullscreenMaterial::run_in`, `FullscreenMaterial::run_after` and `FullscreenMaterial::run_before` are replaced
+by `FullscreenMaterial::schedule_configs` to configure the system order.
 
 ```rust
 // 0.18
@@ -1467,7 +1485,7 @@ world.trigger_with(
 
 `RelationshipAccessor` now has additional fields:
 
-- `allow_self_referential` that stores value of `Relationship::ALLOW_SELF_REFERENTIAL`
+- `allow_self_referential` that stores the value of `Relationship::ALLOW_SELF_REFERENTIAL`
 - `relationship_target` for `RelationshipAccessor::Relationship` and `relationship` for `RelationshipAccessor::RelationshipTarget` which store the `ComponentId` of the counterpart component.
 
 `ComponentDescriptor::new_with_layout` now takes `Option<RelationshipAccessorInitializer>` instead of `Option<RelationshipAccessor>`, which requires providing a way to get `ComponentId` of the counterpart component.
@@ -1588,7 +1606,7 @@ impl Reader for MyReader {
 // If MyReader does not implement `AsyncSeek` 
 impl Reader for MyReader {
     fn seekable(&mut self) -> Result<&mut dyn SeekableReader, ReaderNotSeekableError> {
-        None
+        Err(ReaderNotSeekableError)
     }
 }
 ```
@@ -1686,7 +1704,7 @@ remains as the top-level schedule for non-camera rendering.
 In `bevy_state`, you can define states and transition between them.
 For example, this can be used to transition between `AppState::Menu` and `AppState::InGame`, and run different logic depending on the state the `App` is in.
 In 0.18, it became possible to transition from a state to itself: A 'same state transition'.
-However, there was a bug that made is so that `DespawnOnEnter` and `DespawnOnExit` did not trigger for same state transition when they should have.
+However, there was a bug that made it so that `DespawnOnEnter` and `DespawnOnExit` did not trigger for same state transition when they should have.
 
 In 0.19, this bug is fixed.
 If your application transitions between states using `NextState::set()`, your application will trigger `DespawnOnEnter` and `DespawnOnExit`, even in same state transitions.
@@ -1810,7 +1828,7 @@ more robust (and less spurious) warning for invalid configuration of entities.
 
 {{ heading_metadata(prs=[23225]) }}
 
-In an effort to improve performance by reducing redundant data fetches and simplify internals,
+In an effort to improve performance by reducing redundant data fetches and simplifying internals,
 system parameter validation is now done as part of fetching the data for those system parameters.
 To be more precise:
 
@@ -1837,7 +1855,7 @@ Instead, validation has been moved to be part of the trait implementation for `S
 All implementations of the `System` trait should validate that their parameters are valid during this method,
 bubbling up any errors originating in `SystemParam::get_param`.
 
-## Custom `SystemParam` implementations
+#### Custom `SystemParam` implementations
 
 If you have a custom `SystemParam` implementation, you need to:
 
@@ -1891,7 +1909,7 @@ unsafe impl SystemParam for MyParam<'_> {
 }
 ```
 
-## Custom `ExclusiveSystemParam` implementations
+#### Custom `ExclusiveSystemParam` implementations
 
 Similarly, `ExclusiveSystemParam::get_param` now returns a `Result<Self::Item<'s>, SystemParamValidationError>` instead of `Self::Item<'s>`.
 Existing implementations should wrap their return value in `Ok(...)` and return an appropriate `SystemParamValidationError` if validation fails.
@@ -1920,11 +1938,11 @@ impl ExclusiveSystemParam for MyExclusiveParam {
 }
 ```
 
-## Custom `System` implementations
+#### Custom `System` implementations
 
 If you have a custom `System` implementation, remove the `validate_param_unsafe` method. Parameter validation should now occur inside `run_unsafe` by propagating errors from `SystemParam::get_param`.
 
-## `MultithreadedExecutor` performance changes
+#### `MultithreadedExecutor` performance changes
 
 For the parallel `MultithreadedExecutor`, validation was previously done as a cheap pre-validation step,
 while checking run conditions.
@@ -1939,7 +1957,7 @@ the previous behavior can be recovered by adding run conditions.
 
 {{ heading_metadata(prs=[22766, 23334]) }}
 
-Previously, `SyncComponentPlugin`/`ExtractComponentPlugin` would despawn the render entity if the synced component was removed. This removes all the derived components too. In 0.19, the render entity is no longer despawned and only the `Target` components of `SyncComponent` trait are removed.
+Previously, `SyncComponentPlugin`/`ExtractComponentPlugin` would despawn the render entity if the synced component was removed. This removes all the derived components too. In 0.19, the render entity is no longer despawned and only the `Target` components of the `SyncComponent` trait are removed.
 
 `SyncComponent` is a subtrait of `ExtractComponent` and you must implement it to clean up extracted and derived components.
 
@@ -2132,7 +2150,7 @@ asset_server
     .load(path)
 ```
 
-## NestedLoader
+#### NestedLoader
 
 To match this change, `NestedLoader` has been replaced with
 `NestedLoadBuilder`. Similarly, `LoadContext::loader` has been replaced with
@@ -2205,7 +2223,7 @@ The `TextureAtlasLayout` parameters of `FontAtlas`'s `new` and `add_glyph_to_atl
 
 `GlyphAtlasInfo`'s `texture_atlas` and `location` fields have been removed, replaced by `rect` and `offset` fields.
 
-The `size` field has been removed from `PositionedGlyph`. The glyph’s size can now be obtained from the `Rect` stored in the `atlas_info: GlyphAtlasInfo` field.
+The `size` field has been removed from `PositionedGlyph`. The glyph's size can now be obtained from the `Rect` stored in the `atlas_info: GlyphAtlasInfo` field.
 
 `GlyphAtlasLocation::offset` is now a `Vec2`.