Update migration guide (#1366)

bevyengine · Jun 5, 2024 · d24994e · d24994e
1 parent db75d3a
commit d24994e
Show file tree

Hide file tree

Showing 22 changed files with 188 additions and 4 deletions.
diff --git a/...migration-guides/12038_fix_node2d_typo.md → .../migration-guides/12038_fix_some_typos.md b/...migration-guides/12038_fix_node2d_typo.md → .../migration-guides/12038_fix_some_typos.md
diff --git a/...-guides/12512_update_to_fixedbitset_05.md → ...-guides/12512_Update_to_fixedbitset_05.md b/...-guides/12512_update_to_fixedbitset_05.md → ...-guides/12512_Update_to_fixedbitset_05.md
diff --git a/...ase-content/0.14/migration-guides/13238_More_idiomatic_texture_atlas_builder.md b/...ase-content/0.14/migration-guides/13238_More_idiomatic_texture_atlas_builder.md
@@ -0,0 +1,8 @@
+```diff
+- let mut texture_atlas_builder = TextureAtlasBuilder::default().padding(UVec2::default()).format(..);
++ let mut texture_atlas_builder = TextureAtlasBuilder::default();
++ texture_atlas_builder.padding(UVec2::default()).format(..);
+
+- let (texture_atlas_layout, texture) = texture_atlas_builder.finish().unwrap();
++ let (texture_atlas_layout, texture) = texture_atlas_builder.build().unwrap();
+```
diff --git a/release-content/0.14/migration-guides/13261_More_gizmos_builders.md b/release-content/0.14/migration-guides/13261_More_gizmos_builders.md
@@ -0,0 +1,2 @@
+- Some `gizmos.primitive_nd` methods now return some or different builders. You may need to adjust types and match statements
+- Replace any calls to `circle_segments()` with `.segments()`
diff --git a/release-content/0.14/migration-guides/13366_fix_upgrade_to_winit_v030.md b/release-content/0.14/migration-guides/13366_fix_upgrade_to_winit_v030.md
@@ -0,0 +1,17 @@
+The custom UserEvent is now renamed as WakeUp, used to wake up the loop if anything happens outside the app (a new [custom_user_event](https://github.com/bevyengine/bevy/pull/13366/files#diff-2de8c0a8d3028d0059a3d80ae31b2bbc1cde2595ce2d317ea378fe3e0cf6ef2d) shows this behavior.
+
+The internal `UpdateState` has been removed and replaced internally by the AppLifecycle. When changed, the AppLifecycle is sent as an event.
+
+The `UpdateMode` now accepts only two values: `Continuous` and `Reactive`, but the latter exposes 3 new properties to enable reactive to device, user or window events. The previous `UpdateMode::Reactive` is now equivalent to `UpdateMode::reactive()`, while `UpdateMode::ReactiveLowPower` to `UpdateMode::reactive_low_power()`.
+
+The `ApplicationLifecycle` has been renamed as `AppLifecycle`, and now contains the possible values of the application state inside the event loop: 
+
+- `Idle`: the loop has not started yet
+- `Running` (previously called `Started`): the loop is running
+- `WillSuspend`: the loop is going to be suspended
+- `Suspended`: the loop is suspended
+- `WillResume`: the loop is going to be resumed
+
+Note: the `Resumed` state has been removed since the resumed app is just running.
+
+Finally, now that `winit` enables this, it extends the `WinitPlugin` to support custom events.
diff --git a/...tion-guides/13442_constrain_WorldQueryinit_state_argument_to_ComponentInitia.md b/...tion-guides/13442_constrain_WorldQueryinit_state_argument_to_ComponentInitia.md
@@ -0,0 +1 @@
+Instead of passing `&mut World` to `WorldQuery::init_state` directly, pass in a mutable reference to the struct returned from `World::component_initializer`.
diff --git a/release-content/0.14/migration-guides/13489_Normalise_matrix_naming.md b/release-content/0.14/migration-guides/13489_Normalise_matrix_naming.md
@@ -0,0 +1,14 @@
+- `Frustum`’s `from_view_projection`, `from_view_projection_custom_far` and `from_view_projection_no_far` were renamed to `from_clip_from_world`, `from_clip_from_world_custom_far` and `from_clip_from_world_no_far`.
+- `ComputedCameraValues::projection_matrix` was renamed to `clip_from_view`.
+- `CameraProjection::get_projection_matrix` was renamed to `get_clip_from_view` (this affects implementations on `Projection`, `PerspectiveProjection` and `OrthographicProjection`).
+- `ViewRangefinder3d::from_view_matrix` was renamed to `from_world_from_view`.
+- `PreviousViewData`’s members were renamed to `view_from_world` and `clip_from_world`.
+- `ExtractedView`’s `projection`, `transform` and `view_projection` were renamed to `clip_from_view`, `world_from_view` and `clip_from_world`.
+- `ViewUniform`’s `view_proj`, `unjittered_view_proj`, `inverse_view_proj`, `view`, `inverse_view`, `projection` and `inverse_projection` were renamed to `clip_from_world`, `unjittered_clip_from_world`, `world_from_clip`, `world_from_view`, `view_from_world`, `clip_from_view` and `view_from_clip`.
+- `GpuDirectionalCascade::view_projection` was renamed to `clip_from_world`.
+- `MeshTransforms`’ `transform` and `previous_transform` were renamed to `world_from_local` and `previous_world_from_local`.
+- `MeshUniform`’s `transform`, `previous_transform`, `inverse_transpose_model_a` and `inverse_transpose_model_b` were renamed to `world_from_local`, `previous_world_from_local`, `local_from_world_transpose_a` and `local_from_world_transpose_b` (the `Mesh` type in WGSL mirrors this, however `transform` and `previous_transform` were named `model` and `previous_model`).
+- `Mesh2dTransforms::transform` was renamed to `world_from_local`.
+- `Mesh2dUniform`’s `transform`, `inverse_transpose_model_a` and `inverse_transpose_model_b` were renamed to `world_from_local`, `local_from_world_transpose_a` and `local_from_world_transpose_b` (the `Mesh2d` type in WGSL mirrors this).
+- In WGSL, in `bevy_pbr::mesh_functions`, `get_model_matrix` and `get_previous_model_matrix` were renamed to `get_world_from_local` and `get_previous_world_from_local`.
+- In WGSL, `bevy_sprite::mesh2d_functions::get_model_matrix` was renamed to `get_world_from_local`.
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
@@ -0,0 +1,16 @@
+Hi maintainers! I believe `DevToolsPlugin` was added within the same release as this PR, so I don’t think a migration guide is needed.
+
+`DevToolsPlugin` is no longer included in `MinimalPlugins`, so you will need to remove it manually.
+
+```rust
+// Before
+App::new()
+ .add_plugins(MinimalPlugins)
+ .run();
+
+// After
+App::new()
+ .add_plugins(MinimalPlugins)
+ .add_plugins(DevToolsPlugin)
+ .run();
+```
diff --git a/release-content/0.14/migration-guides/13534_Make_gizmos_take_primitives_by_ref.md b/release-content/0.14/migration-guides/13534_Make_gizmos_take_primitives_by_ref.md
@@ -0,0 +1 @@
+- Any usages of `gizmos.primitive_2d()` and/or `gizmos.primitive_3d()` need to be updated to pass the primitive in by reference.
diff --git a/...tion-guides/13549_Generalize_component_reflection_to_operate_on_FilteredEnti.md b/...tion-guides/13549_Generalize_component_reflection_to_operate_on_FilteredEnti.md
@@ -0,0 +1 @@
+- `ReflectComponent::contains`, `ReflectComponent::reflect`, and `ReflectComponent::reflect_mut` now take `FilteredEntityRef` (in the case of `contains()` and `reflect()`) and `FilteredEntityMut` (in the case of `reflect_mut()`) parameters. `FilteredEntityRef` and `FilteredEntityMut` have very similar APIs to `EntityRef` and `EntityMut` respectively, but optionally restrict the components that can be accessed.
diff --git a/...ase-content/0.14/migration-guides/13580_Add_subdivisions_to_PlaneMeshBuilder.md b/...ase-content/0.14/migration-guides/13580_Add_subdivisions_to_PlaneMeshBuilder.md
@@ -0,0 +1,3 @@
+If you were using `Plane` `subdivisions`, you now need to use `Plane3d::default().mesh().subdivisions(10)`
+
+fixes https://github.com/bevyengine/bevy/issues/13258
diff --git a/...ent/0.14/migration-guides/13594_Unify_transition_names_to_exited_and_entered.md b/...ent/0.14/migration-guides/13594_Unify_transition_names_to_exited_and_entered.md
@@ -0,0 +1 @@
+- `StateTransitionEvent<S>` and `OnTransition<S>` schedule had their fields renamed to `exited` and `entered` to match schedules.
diff --git a/...e-content/0.14/migration-guides/13603_Updates_default_Text_font_size_to_24px.md b/...e-content/0.14/migration-guides/13603_Updates_default_Text_font_size_to_24px.md
@@ -0,0 +1 @@
+- The default font size has been increased to 24px from 12px. Make sure you set the font to the appropriate values in places you were using `Default` text style.
diff --git a/...se-content/0.14/migration-guides/13605_Additional_options_to_mesh_primitives.md b/...se-content/0.14/migration-guides/13605_Additional_options_to_mesh_primitives.md
@@ -0,0 +1 @@
+<!-- TODO -->
diff --git a/...-content/0.14/migration-guides/13626_Combine_transition_systems_of_Substates.md b/...-content/0.14/migration-guides/13626_Combine_transition_systems_of_Substates.md
@@ -0,0 +1 @@
+- `apply_state_transition` is no longer publicly available, run the `StateTransition` schedule instead.
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
@@ -0,0 +1 @@
+`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.
diff --git a/...tion-guides/13640_Move_clusteringrelated_types_and_functions_into_their_own_.md b/...tion-guides/13640_Move_clusteringrelated_types_and_functions_into_their_own_.md
@@ -0,0 +1 @@
+- Clustering-related types and functions (e.g. `assign_lights_to_clusters`) have moved under `bevy_pbr::cluster`, in preparation for the ability to cluster objects other than lights.
diff --git a/...tion-guides/13654_Rename_point_light_to_clusterable_object_in_cluster_contex.md b/...tion-guides/13654_Rename_point_light_to_clusterable_object_in_cluster_contex.md
@@ -0,0 +1 @@
+- In the PBR shaders, `point_lights` is now known as `clusterable_objects`, `PointLight` is now known as `ClusterableObject`, and `cluster_light_index_lists` is now known as `clusterable_object_index_lists`.
diff --git a/.../0.14/migration-guides/13660_rename_touchpad_to_gesture_and_add_new_gestures.md b/.../0.14/migration-guides/13660_rename_touchpad_to_gesture_and_add_new_gestures.md
@@ -0,0 +1,2 @@
+- `TouchpadMagnify` has been renamed to `PinchGesture`
+- `TouchpadRotate` has been renamed to `RotationGesture `
diff --git a/...4/migration-guides/13678_flush_key_input_cache_when_Bevy_loses_focus_Adopted.md b/...4/migration-guides/13678_flush_key_input_cache_when_Bevy_loses_focus_Adopted.md
@@ -0,0 +1 @@
+`WinitEvent` has a new enum variant: `WinitEvent::KeyboardFocusLost`.
diff --git a/release-content/0.14/migration-guides/_guides.toml b/release-content/0.14/migration-guides/_guides.toml
@@ -2,13 +2,13 @@
 title = "Fix `Node2d` typo"
 url = "https://github.com/bevyengine/bevy/pull/12038"
 areas = []
-file_name = "12038_fix_node2d_typo.md"
+file_name = "12038_fix_some_typos.md"
 
 [[guides]]
 title = "Update to `fixedbitset` 0.5"
 url = "https://github.com/bevyengine/bevy/pull/12512"
 areas = []
-file_name = "12512_update_to_fixedbitset_05.md"
+file_name = "12512_Update_to_fixedbitset_05.md"
 
 [[guides]]
 title = "Move WASM panic handler from `LogPlugin` to `PanicHandlerPlugin`"
@@ -46,6 +46,12 @@ url = "https://github.com/bevyengine/bevy/pull/13080"
 areas = ["App"]
 file_name = "13080_Deprecate_dynamic_plugins.md"
 
+[[guides]]
+title = "Move state installation methods from `bevy_app` 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"
+
 [[guides]]
 title = "Remove the `UpdateAssets` and `AssetEvents` schedules"
 url = "https://github.com/bevyengine/bevy/pull/11986"
@@ -124,6 +130,12 @@ 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"
 url = "https://github.com/bevyengine/bevy/pull/13209"
@@ -304,6 +316,24 @@ url = "https://github.com/bevyengine/bevy/pull/13343"
 areas = ["ECS"]
 file_name = "13343_constrain_WorldQueryget_state_to_only_use_Components.md"
 
+[[guides]]
+title = "constrain WorldQuery::init_state argument to ComponentInitializer"
+url = "https://github.com/bevyengine/bevy/pull/13442"
+areas = ["ECS"]
+file_name = "13442_constrain_WorldQueryinit_state_argument_to_ComponentInitia.md"
+
+[[guides]]
+title = "Unify transition names to `exited` and `entered`"
+url = "https://github.com/bevyengine/bevy/pull/13594"
+areas = ["ECS"]
+file_name = "13594_Unify_transition_names_to_exited_and_entered.md"
+
+[[guides]]
+title = "Combine transition systems of `Substates`"
+url = "https://github.com/bevyengine/bevy/pull/13626"
+areas = ["ECS"]
+file_name = "13626_Combine_transition_systems_of_Substates.md"
+
 [[guides]]
 title = "Replace `FromWorld` requirement on `ReflectResource` and reflect `Resource` for `State<S>`"
 url = "https://github.com/bevyengine/bevy/pull/12136"
@@ -322,6 +352,12 @@ url = "https://github.com/bevyengine/bevy/pull/12499"
 areas = ["ECS","Reflection"]
 file_name = "12499_Make_from_reflect_or_world_also_try_ReflectDefault_and_imp.md"
 
+[[guides]]
+title = "Generalize component reflection to operate on `FilteredEntityRef` and `FilteredEntityMut`, not `EntityRef` and `EntityMut`."
+url = "https://github.com/bevyengine/bevy/pull/13549"
+areas = ["ECS","Reflection"]
+file_name = "13549_Generalize_component_reflection_to_operate_on_FilteredEnti.md"
+
 [[guides]]
 title = "multi_threaded feature rename"
 url = "https://github.com/bevyengine/bevy/pull/12997"
@@ -358,12 +394,36 @@ url = "https://github.com/bevyengine/bevy/pull/13438"
 areas = ["Gizmos"]
 file_name = "13438_Inconsistent_segmentsresolution_naming.md"
 
+[[guides]]
+title = "Make gizmos take primitives by ref"
+url = "https://github.com/bevyengine/bevy/pull/13534"
+areas = ["Gizmos"]
+file_name = "13534_Make_gizmos_take_primitives_by_ref.md"
+
+[[guides]]
+title = "More gizmos builders"
+url = "https://github.com/bevyengine/bevy/pull/13261"
+areas = ["Gizmos"]
+file_name = "13261_More_gizmos_builders.md"
+
+[[guides]]
+title = "rename touchpad to gesture, and add new gestures"
+url = "https://github.com/bevyengine/bevy/pull/13660"
+areas = ["Input"]
+file_name = "13660_rename_touchpad_to_gesture_and_add_new_gestures.md"
+
 [[guides]]
 title = "Deprecate `ReceivedCharacter`"
 url = "https://github.com/bevyengine/bevy/pull/12868"
 areas = ["Input","Windowing"]
 file_name = "12868_Deprecate_ReceivedCharacter.md"
 
+[[guides]]
+title = "flush key_input cache when Bevy loses focus (Adopted)"
+url = "https://github.com/bevyengine/bevy/pull/13678"
+areas = ["Input","Windowing"]
+file_name = "13678_flush_key_input_cache_when_Bevy_loses_focus_Adopted.md"
+
 [[guides]]
 title = "Add `Direction3dA` and move direction types out of `primitives`"
 url = "https://github.com/bevyengine/bevy/pull/12018"
@@ -418,6 +478,18 @@ url = "https://github.com/bevyengine/bevy/pull/13411"
 areas = ["Math","Rendering"]
 file_name = "13411_Common_MeshBuilder_trait.md"
 
+[[guides]]
+title = "Additional options to mesh primitives"
+url = "https://github.com/bevyengine/bevy/pull/13605"
+areas = ["Math","Rendering"]
+file_name = "13605_Additional_options_to_mesh_primitives.md"
+
+[[guides]]
+title = "Add subdivisions to PlaneMeshBuilder"
+url = "https://github.com/bevyengine/bevy/pull/13580"
+areas = ["Math","Rendering"]
+file_name = "13580_Add_subdivisions_to_PlaneMeshBuilder.md"
+
 [[guides]]
 title = "Make `Transform::rotate_axis` and `Transform::rotate_local_axis` use `Dir3`"
 url = "https://github.com/bevyengine/bevy/pull/12986"
@@ -658,6 +730,30 @@ url = "https://github.com/bevyengine/bevy/pull/13277"
 areas = ["Rendering"]
 file_name = "13277_Make_render_phases_render_world_resources_instead_of_compo.md"
 
+[[guides]]
+title = "More idiomatic texture atlas builder"
+url = "https://github.com/bevyengine/bevy/pull/13238"
+areas = ["Rendering"]
+file_name = "13238_More_idiomatic_texture_atlas_builder.md"
+
+[[guides]]
+title = "Move clustering-related types and functions into their own module."
+url = "https://github.com/bevyengine/bevy/pull/13640"
+areas = ["Rendering"]
+file_name = "13640_Move_clusteringrelated_types_and_functions_into_their_own_.md"
+
+[[guides]]
+title = "Normalise matrix naming"
+url = "https://github.com/bevyengine/bevy/pull/13489"
+areas = ["Rendering"]
+file_name = "13489_Normalise_matrix_naming.md"
+
+[[guides]]
+title = "Rename \"point light\" to \"clusterable object\" in cluster contexts."
+url = "https://github.com/bevyengine/bevy/pull/13654"
+areas = ["Rendering"]
+file_name = "13654_Rename_point_light_to_clusterable_object_in_cluster_contex.md"
+
 [[guides]]
 title = "Deprecate `SpriteSheetBundle` and `AtlasImageBundle`"
 url = "https://github.com/bevyengine/bevy/pull/12218"
@@ -712,6 +808,12 @@ url = "https://github.com/bevyengine/bevy/pull/13452"
 areas = ["UI"]
 file_name = "13452_Rename_Rect_inset_method_to_inflate.md"
 
+[[guides]]
+title = "Updates default Text font size to 24px"
+url = "https://github.com/bevyengine/bevy/pull/13603"
+areas = ["UI"]
+file_name = "13603_Updates_default_Text_font_size_to_24px.md"
+
 [[guides]]
 title = "Disentangle bevy_utils/bevy_core's reexported dependencies"
 url = "https://github.com/bevyengine/bevy/pull/12313"
@@ -736,3 +838,9 @@ url = "https://github.com/bevyengine/bevy/pull/13236"
 areas = ["Windowing"]
 file_name = "13236_Ensure_clean_exit.md"
 
+[[guides]]
+title = "fix: upgrade to winit v0.30"
+url = "https://github.com/bevyengine/bevy/pull/13366"
+areas = ["Windowing"]
+file_name = "13366_fix_upgrade_to_winit_v030.md"
+
diff --git a/typos.toml b/typos.toml
@@ -7,8 +7,11 @@ extend-exclude = [
  "content/learn/migration-guides/0.[1-8]-to-0.[2-9].md",
  "content/learn/migration-guides/0.9-to-0.10.md",
  "content/learn/migration-guides/0.1[0-2]-to-0.1[1-3].md",
- # Ignore a migration guide for a typo fix
- "release-content/0.14/migration-guides/12038_fix_node2d_typo.md",
+ # Ignore specific migration guides that fix typos or truncate titles.
+ "release-content/0.14/migration-guides/_guides.toml",
+ "release-content/0.14/migration-guides/12038_fix_some_typos.md",
+ "release-content/0.14/migration-guides/13261_More_gizmos_builders.md",
+ "release-content/0.14/migration-guides/13654_Rename_point_light_to_clusterable_object_in_cluster_contex.md",
  # Ignore changelogs and release notes (titles should be verbatim)
  "release-content/*/changelog.toml",
  "release-content/*/_release-notes.toml",