Deprecate SpatialBundle (#15830)

NiseVoid · web-flow · commit bdd0af6bfbab · 2024-10-13T17:28:22.000Z
# Objective

- Required components replace bundles, but `SpatialBundle` is yet to be
deprecated

## Solution

- Deprecate `SpatialBundle`
- Insert `Transform` and `Visibility` instead in examples using it
- In `spawn` or `insert` inserting a default `Transform` or `Visibility`
with component already requiring either, remove those components from
the tuple

## Testing

- Did you test these changes? If so, how?
Yes, I ran the examples I changed and tests
- Are there any parts that need more testing?
The `gamepad_viewer` and and `custom_shader_instancing` examples don't
work as intended due to entirely unrelated code, didn't check main.
- How can other people (reviewers) test your changes? Is there anything
specific they need to know?
Run examples, or just check that all spawned values are identical
- If relevant, what platforms did you test these changes on, and are
there any important ones you can't test?
Linux, wayland trough x11 (cause that's the default feature)

---

## Migration Guide

`SpatialBundle` is now deprecated, insert `Transform` and `Visibility`
instead which will automatically insert all other components that were
in the bundle. If you do not specify these values and any other
components in your `spawn`/`insert` call already requires either of
these components you can leave that one out.

before:
```rust
commands.spawn(SpatialBundle::default());
```

after:
```rust
commands.spawn((Transform::default(), Visibility::default());
```
diff --git a/crates/bevy_gltf/src/loader.rs b/crates/bevy_gltf/src/loader.rs
@@ -28,14 +28,14 @@ use bevy_render::{
         skinning::{SkinnedMesh, SkinnedMeshInverseBindposes},
         Indices, Mesh, Mesh3d, MeshVertexAttribute, VertexAttributeValues,
     },
-    prelude::SpatialBundle,
     primitives::Aabb,
     render_asset::RenderAssetUsages,
     render_resource::{Face, PrimitiveTopology},
     texture::{
         CompressedImageFormats, Image, ImageAddressMode, ImageFilterMode, ImageLoaderSettings,
         ImageSampler, ImageSamplerDescriptor, ImageType, TextureError,
     },
+    view::Visibility,
 };
 use bevy_scene::Scene;
 #[cfg(not(target_arch = "wasm32"))]
@@ -822,7 +822,7 @@ async fn load_gltf<'a, 'b, 'c>(
         let mut scene_load_context = load_context.begin_labeled_asset();
 
         let world_root_id = world
-            .spawn(SpatialBundle::INHERITED_IDENTITY)
+            .spawn((Transform::default(), Visibility::default()))
             .with_children(|parent| {
                 for node in scene.nodes() {
                     let result = load_node(
@@ -1359,7 +1359,7 @@ fn load_node(
     // of negative scale factors is odd. if so we will assign a copy of the material with face
     // culling inverted, rather than modifying the mesh data directly.
     let is_scale_inverted = world_transform.scale.is_negative_bitmask().count_ones() & 1 == 1;
-    let mut node = world_builder.spawn(SpatialBundle::from(transform));
+    let mut node = world_builder.spawn((transform, Visibility::default()));
 
     let name = node_name(gltf_node);
     node.insert(name.clone());
diff --git a/crates/bevy_render/src/spatial_bundle.rs b/crates/bevy_render/src/spatial_bundle.rs
@@ -1,3 +1,4 @@
+#![expect(deprecated)]
 use bevy_ecs::prelude::Bundle;
 use bevy_transform::prelude::{GlobalTransform, Transform};
 
@@ -16,6 +17,12 @@ use crate::view::{InheritedVisibility, ViewVisibility, Visibility};
 ///
 /// [`Component`]: bevy_ecs::component::Component
 #[derive(Bundle, Clone, Debug, Default)]
+#[deprecated(
+    since = "0.15.0",
+    note = "Use the `Transform` and `Visibility` components instead.
+        Inserting `Transform` will now also insert a `GlobalTransform` automatically.
+        Inserting 'Visibility' will now also insert `InheritedVisibility` and `ViewVisibility` automatically."
+)]
 pub struct SpatialBundle {
     /// The visibility of the entity.
     pub visibility: Visibility,
diff --git a/examples/2d/bounding_2d.rs b/examples/2d/bounding_2d.rs
@@ -203,31 +203,22 @@ const OFFSET_Y: f32 = 75.;
 fn setup(mut commands: Commands) {
     commands.spawn(Camera2d);
     commands.spawn((
-        SpatialBundle {
-            transform: Transform::from_xyz(-OFFSET_X, OFFSET_Y, 0.),
-            ..default()
-        },
+        Transform::from_xyz(-OFFSET_X, OFFSET_Y, 0.),
         Shape::Circle(Circle::new(45.)),
         DesiredVolume::Aabb,
         Intersects::default(),
     ));
 
     commands.spawn((
-        SpatialBundle {
-            transform: Transform::from_xyz(0., OFFSET_Y, 0.),
-            ..default()
-        },
+        Transform::from_xyz(0., OFFSET_Y, 0.),
         Shape::Rectangle(Rectangle::new(80., 80.)),
         Spin,
         DesiredVolume::Circle,
         Intersects::default(),
     ));
 
     commands.spawn((
-        SpatialBundle {
-            transform: Transform::from_xyz(OFFSET_X, OFFSET_Y, 0.),
-            ..default()
-        },
+        Transform::from_xyz(OFFSET_X, OFFSET_Y, 0.),
         Shape::Triangle(Triangle2d::new(
             Vec2::new(-40., -40.),
             Vec2::new(-20., 40.),
@@ -239,32 +230,23 @@ fn setup(mut commands: Commands) {
     ));
 
     commands.spawn((
-        SpatialBundle {
-            transform: Transform::from_xyz(-OFFSET_X, -OFFSET_Y, 0.),
-            ..default()
-        },
+        Transform::from_xyz(-OFFSET_X, -OFFSET_Y, 0.),
         Shape::Line(Segment2d::new(Dir2::from_xy(1., 0.3).unwrap(), 90.)),
         Spin,
         DesiredVolume::Circle,
         Intersects::default(),
     ));
 
     commands.spawn((
-        SpatialBundle {
-            transform: Transform::from_xyz(0., -OFFSET_Y, 0.),
-            ..default()
-        },
+        Transform::from_xyz(0., -OFFSET_Y, 0.),
         Shape::Capsule(Capsule2d::new(25., 50.)),
         Spin,
         DesiredVolume::Aabb,
         Intersects::default(),
     ));
 
     commands.spawn((
-        SpatialBundle {
-            transform: Transform::from_xyz(OFFSET_X, -OFFSET_Y, 0.),
-            ..default()
-        },
+        Transform::from_xyz(OFFSET_X, -OFFSET_Y, 0.),
         Shape::Polygon(RegularPolygon::new(50., 6)),
         Spin,
         DesiredVolume::Circle,
diff --git a/examples/2d/mesh2d_manual.rs b/examples/2d/mesh2d_manual.rs
@@ -110,8 +110,6 @@ fn star(
         ColoredMesh2d,
         // The `Handle<Mesh>` needs to be wrapped in a `Mesh2d` for 2D rendering
         Mesh2d(meshes.add(star)),
-        // This bundle's components are needed for something to be rendered
-        SpatialBundle::INHERITED_IDENTITY,
     ));
 
     // Spawn the camera
diff --git a/examples/3d/fog_volumes.rs b/examples/3d/fog_volumes.rs
@@ -30,20 +30,17 @@ fn main() {
 /// Spawns all the objects in the scene.
 fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     // Spawn a fog volume with a voxelized version of the Stanford bunny.
-    commands
-        .spawn(SpatialBundle {
-            visibility: Visibility::Visible,
-            transform: Transform::from_xyz(0.0, 0.5, 0.0),
-            ..default()
-        })
-        .insert(FogVolume {
+    commands.spawn((
+        Transform::from_xyz(0.0, 0.5, 0.0),
+        FogVolume {
             density_texture: Some(asset_server.load("volumes/bunny.ktx2")),
             density_factor: 1.0,
             // Scatter as much of the light as possible, to brighten the bunny
             // up.
             scattering: 1.0,
             ..default()
-        });
+        },
+    ));
 
     // Spawn a bright directional light that illuminates the fog well.
     commands.spawn((
diff --git a/examples/3d/irradiance_volumes.rs b/examples/3d/irradiance_volumes.rs
@@ -243,16 +243,14 @@ fn spawn_camera(commands: &mut Commands, assets: &ExampleAssets) {
 }
 
 fn spawn_irradiance_volume(commands: &mut Commands, assets: &ExampleAssets) {
-    commands
-        .spawn(SpatialBundle {
-            transform: Transform::from_matrix(VOXEL_FROM_WORLD),
-            ..SpatialBundle::default()
-        })
-        .insert(IrradianceVolume {
+    commands.spawn((
+        Transform::from_matrix(VOXEL_FROM_WORLD),
+        IrradianceVolume {
             voxels: assets.irradiance_volume.clone(),
             intensity: IRRADIANCE_VOLUME_INTENSITY,
-        })
-        .insert(LightProbe);
+        },
+        LightProbe,
+    ));
 }
 
 fn spawn_light(commands: &mut Commands) {
@@ -277,12 +275,7 @@ fn spawn_sphere(commands: &mut Commands, assets: &ExampleAssets) {
 }
 
 fn spawn_voxel_cube_parent(commands: &mut Commands) {
-    commands
-        .spawn(SpatialBundle {
-            visibility: Visibility::Hidden,
-            ..default()
-        })
-        .insert(VoxelCubeParent);
+    commands.spawn((Visibility::Hidden, Transform::default(), VoxelCubeParent));
 }
 
 fn spawn_fox(commands: &mut Commands, assets: &ExampleAssets) {
diff --git a/examples/3d/scrolling_fog.rs b/examples/3d/scrolling_fog.rs
@@ -113,11 +113,7 @@ fn setup(
 
     // Spawn a FogVolume and use the repeating noise texture as its density texture.
     commands.spawn((
-        SpatialBundle {
-            visibility: Visibility::Visible,
-            transform: Transform::from_xyz(0.0, 32.0, 0.0).with_scale(Vec3::splat(64.0)),
-            ..default()
-        },
+        Transform::from_xyz(0.0, 32.0, 0.0).with_scale(Vec3::splat(64.0)),
         FogVolume {
             density_texture: Some(noise_texture),
             density_factor: 0.05,
diff --git a/examples/3d/shadow_biases.rs b/examples/3d/shadow_biases.rs
@@ -46,13 +46,7 @@ fn setup(
 
     let light_transform = Transform::from_xyz(5.0, 5.0, 0.0).looking_at(Vec3::ZERO, Vec3::Y);
     commands
-        .spawn((
-            SpatialBundle {
-                transform: light_transform,
-                ..default()
-            },
-            Lights,
-        ))
+        .spawn((light_transform, Visibility::default(), Lights))
         .with_children(|builder| {
             builder.spawn(PointLight {
                 intensity: 0.0,
diff --git a/examples/animation/animated_transform.rs b/examples/animation/animated_transform.rs
@@ -151,7 +151,8 @@ fn setup(
         .with_children(|p| {
             // This entity is just used for animation, but doesn't display anything
             p.spawn((
-                SpatialBundle::INHERITED_IDENTITY,
+                Transform::default(),
+                Visibility::default(),
                 orbit_controller,
                 AnimationTarget {
                     id: orbit_controller_animation_target_id,
diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
@@ -44,7 +44,11 @@ fn setup(
 
     let listener = SpatialListener::new(gap);
     commands
-        .spawn((SpatialBundle::default(), listener.clone()))
+        .spawn((
+            Transform::default(),
+            Visibility::default(),
+            listener.clone(),
+        ))
         .with_children(|parent| {
             // left ear
             parent.spawn((
diff --git a/examples/audio/spatial_audio_3d.rs b/examples/audio/spatial_audio_3d.rs
@@ -35,7 +35,11 @@ fn setup(
 
     let listener = SpatialListener::new(gap);
     commands
-        .spawn((SpatialBundle::default(), listener.clone()))
+        .spawn((
+            Transform::default(),
+            Visibility::default(),
+            listener.clone(),
+        ))
         .with_children(|parent| {
             // left ear indicator
             parent.spawn((
diff --git a/examples/camera/first_person_view_model.rs b/examples/camera/first_person_view_model.rs
@@ -108,10 +108,8 @@ fn spawn_view_model(
         .spawn((
             Player,
             CameraSensitivity::default(),
-            SpatialBundle {
-                transform: Transform::from_xyz(0.0, 1.0, 0.0),
-                ..default()
-            },
+            Transform::from_xyz(0.0, 1.0, 0.0),
+            Visibility::default(),
         ))
         .with_children(|parent| {
             parent.spawn((
diff --git a/examples/games/desk_toy.rs b/examples/games/desk_toy.rs
@@ -146,9 +146,7 @@ fn setup(
 
                 // sclera
                 commands
-                    .spawn(SpatialBundle::from_transform(Transform::from_xyz(
-                        x, y, 2.0,
-                    )))
+                    .spawn((Transform::from_xyz(x, y, 2.0), Visibility::default()))
                     .with_children(|commands| {
                         // sclera
                         commands.spawn((
@@ -163,7 +161,8 @@ fn setup(
                         // pupil
                         commands
                             .spawn((
-                                SpatialBundle::from_transform(Transform::from_xyz(0.0, 0.0, 1.0)),
+                                Transform::from_xyz(0.0, 0.0, 1.0),
+                                Visibility::default(),
                                 Pupil {
                                     eye_radius: radius,
                                     pupil_radius,
diff --git a/examples/picking/sprite_picking.rs b/examples/picking/sprite_picking.rs
@@ -35,7 +35,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     let sprite_size = Vec2::splat(len / 2.0);
 
     commands
-        .spawn(SpatialBundle::default())
+        .spawn((Transform::default(), Visibility::default()))
         .with_children(|commands| {
             for (anchor_index, anchor) in [
                 Anchor::TopLeft,
diff --git a/examples/shader/custom_phase_item.rs b/examples/shader/custom_phase_item.rs
@@ -198,18 +198,16 @@ fn main() {
 fn setup(mut commands: Commands) {
     // Spawn a single entity that has custom rendering. It'll be extracted into
     // the render world via [`ExtractComponent`].
-    commands
-        .spawn(SpatialBundle {
-            visibility: Visibility::Visible,
-            transform: Transform::IDENTITY,
-            ..default()
-        })
+    commands.spawn((
+        Visibility::default(),
+        Transform::default(),
         // This `Aabb` is necessary for the visibility checks to work.
-        .insert(Aabb {
+        Aabb {
             center: Vec3A::ZERO,
             half_extents: Vec3A::splat(0.5),
-        })
-        .insert(CustomRenderedEntity);
+        },
+        CustomRenderedEntity,
+    ));
 
     // Spawn the camera.
     commands.spawn((
diff --git a/examples/shader/custom_shader_instancing.rs b/examples/shader/custom_shader_instancing.rs
@@ -49,7 +49,6 @@ fn main() {
 fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>) {
     commands.spawn((
         Mesh3d(meshes.add(Cuboid::new(0.5, 0.5, 0.5))),
-        SpatialBundle::INHERITED_IDENTITY,
         InstanceMaterialData(
             (1..=10)
                 .flat_map(|x| (1..=10).map(move |y| (x as f32 / 10.0, y as f32 / 10.0)))
diff --git a/examples/shader/specialized_mesh_pipeline.rs b/examples/shader/specialized_mesh_pipeline.rs
@@ -80,11 +80,7 @@ fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>) {
             CustomRenderedEntity,
             // We need to add the mesh handle to the entity
             Mesh3d(meshes.add(mesh.clone())),
-            // This bundle's components are needed for something to be rendered
-            SpatialBundle {
-                transform: Transform::from_xyz(x, y, 0.0),
-                ..SpatialBundle::INHERITED_IDENTITY
-            },
+            Transform::from_xyz(x, y, 0.0),
         ));
     }
 
diff --git a/examples/stress_tests/many_foxes.rs b/examples/stress_tests/many_foxes.rs
@@ -156,7 +156,8 @@ fn setup(
         let (base_rotation, ring_direction) = ring_directions[ring_index % 2];
         let ring_parent = commands
             .spawn((
-                SpatialBundle::INHERITED_IDENTITY,
+                Transform::default(),
+                Visibility::default(),
                 ring_direction,
                 Ring { radius },
             ))
diff --git a/examples/tools/gamepad_viewer.rs b/examples/tools/gamepad_viewer.rs
