Reframe old "scene" terminology as "world serialization" (#23630)

Part 2 of #23619 

In **Bevy 0.19** we are landing a subset of Bevy's Next Generation Scene
system (often known as BSN), which now lives in the `bevy_scene` /
`bevy::scene` crate. However the old `bevy_scene` system still needs to
stick around for a bit longer, as it provides some features that Bevy's
Next Generation Scene system doesn't (yet!):

1. It is not _yet_ possible to write a World _to_ BSN, so the old system
is still necessary for "round trip World serialization".
2. The GLTF scene loader has not yet been ported to BSN, so the old
system is still necessary to spawn GLTF scenes in Bevy.

For this reason, we have renamed the old `bevy_scene` crate to
`bevy_world_serialization`. If you were referencing `bevy_scene::*` or
`bevy::scene::*` types, rename those paths to
`bevy_world_serialization::*` and `bevy::world_serialization::*`
respectively.

Additionally, to avoid confusion / conflicts with the new scene system,
all "scene" terminology / types have been reframed as "world
serialization":

- `Scene` -> `WorldAsset` (as this was always just a World wrapper)
- `SceneRoot` -> `WorldAssetRoot`
- `DynamicScene` -> `DynamicWorld`
    - `DynamicScene::from_scene` -> `DynamicWorld::from_world_asset`
- `DynamicSceneBuilder` -> `DynamicWorldBuilder`
- `DynamicSceneRoot` -> `DynamicWorldRoot`
- `SceneInstanceReady` -> `WorldInstanceReady`
- `SceneLoader` -> `WorldAssetLoader`
- `ScenePlugin` -> `WorldSerializationPlugin`
- `SceneRootTemplate` -> `WorldAssetRootTemplate`
- `SceneSpawner` -> `WorldInstanceSpawner`
- `SceneFilter` -> `WorldFilter`
- `SceneLoaderError` -> `WorldAssetLoaderError`
- `SceneSpawnError` -> `WorldInstanceSpawnError`

Note that I went with `bevy_world_serialization` over
`bevy_ecs_serialization`, as that is what all of the internal features
described themselves as. I think it is both more specific and does a
better job of making itself decoupled from `bevy_ecs` proper.

Author: cart

.github/example-run/scene.ron …thub/example-run/world_serialization.ron.github/example-run/scene.ron renamed to .github/example-run/world_serialization.ron .github/example-run/scene.ron renamed to .github/example-run/world_serialization.ron

@@ -32,7 +32,7 @@ example_showcase_config.ron
 example-showcase-reports/
 
 # Generated by "examples/scene/scene.rs"
-assets/scenes/load_scene_example-new.scn.ron
+assets/serialized_worlds/load_scene_example-new.scn.ron
 
 # Generated by "examples/window/screenshot.rs"
 **/screenshot-*.png

.gitignore

@@ -164,7 +164,7 @@ audio = ["bevy_audio", "vorbis"]
 audio-all-formats = ["bevy_audio", "aac", "flac", "mp3", "mp4", "vorbis", "wav"]
 
 # COLLECTION: Features used to compose Bevy scenes.
-scene = ["bevy_ecs_serialization", "bevy_scene2"]
+scene = ["bevy_world_serialization", "bevy_scene2"]
 
 # COLLECTION: Enables picking with all backends.
 picking = ["bevy_picking", "mesh_picking", "sprite_picking", "ui_picking"]
@@ -318,7 +318,7 @@ bevy_picking = ["bevy_internal/bevy_picking"]
 bevy_render = ["bevy_internal/bevy_render"]
 
 # Provides ECS serialization functionality
-bevy_ecs_serialization = ["bevy_internal/bevy_ecs_serialization"]
+bevy_world_serialization = ["bevy_internal/bevy_world_serialization"]
 
 # Provides scene functionality
 bevy_scene2 = ["bevy_internal/bevy_scene2"]
@@ -3022,13 +3022,13 @@ wasm = false
 
 # Scene
 [[example]]
-name = "scene"
-path = "examples/scene/scene.rs"
+name = "world_serialization"
+path = "examples/scene/world_serialization.rs"
 doc-scrape-examples = true
 
-[package.metadata.example.scene]
-name = "Scene"
-description = "Demonstrates loading from and saving scenes to files"
+[package.metadata.example.world_serialization]
+name = "World Serialization"
+description = "Demonstrates loading from and saving world to files"
 category = "Scene"
 wasm = false
 

Cargo.toml

@@ -0,0 +1,49 @@
+---
+title: "The old `bevy_scene` is now `bevy_world_serialization"
+pull_requests: [23619, 23630]
+---
+
+In **Bevy 0.19** we landed a subset of Bevy's Next Generation Scene system (often known as BSN), which now lives in the `bevy_scene` / `bevy::scene` crate. However the old `bevy_scene` system still needs to stick around for a bit longer, as it provides some features that Bevy's Next Generation Scene system doesn't (yet!):
+
+1. It is not _yet_ possible to write a World _to_ BSN, so the old system is still necessary for "round trip World serialization".
+2. The GLTF scene loader has not yet been ported to BSN, so the old system is still necessary to spawn GLTF scenes in Bevy.
+
+For this reason, we have renamed the old `bevy_scene` crate to `bevy_world_serialization`. If you were referencing `bevy_scene::*` or `bevy::scene::*` types, rename those paths to `bevy_world_serialization::*` and `bevy::world_serialization::*` respectively.
+
+Additionally, to avoid confusion / conflicts with the new scene system, all "scene" terminology / types have been reframed as "world serialization":
+
+- `Scene` -> `WorldAsset` (as this was always just a World wrapper)
+- `SceneRoot` -> `WorldAssetRoot`
+- `DynamicScene` -> `DynamicWorld`
+  - `DynamicScene::from_scene` -> `DynamicWorld::from_world_asset`
+- `DynamicSceneBuilder` -> `DynamicWorldBuilder`
+- `DynamicSceneRoot` -> `DynamicWorldRoot`
+- `SceneInstanceReady` -> `WorldInstanceReady`
+- `SceneLoader` -> `WorldAssetLoader`
+- `ScenePlugin` -> `WorldSerializationPlugin`
+- `SceneRootTemplate` -> `WorldAssetRootTemplate`
+- `SceneSpawner` -> `WorldInstanceSpawner`
+- `SceneFilter` -> `WorldFilter`
+- `SceneLoaderError` -> `WorldAssetLoaderError`
+- `SceneSpawnError` -> `WorldInstanceSpawnError`
+
+GLTF scene spawning is the most likely source of breakage for most people, as round trip world serialization is a relatively niche use case. For most people, the migration should be as simple as:
+
+```rust
+// before
+commands.spawn(SceneRoot(asset_server.load("scene.gltf#Scene0")));
+
+// after
+commands.spawn(WorldAssetRoot(asset_server.load("scene.gltf#Scene0")));
+```
+
+We know this naming is a bit awkward. Once we port GLTF loading over to BSN (hopefully in the next release), you will be able to do cool stuff like this:
+
+```rust
+bsn! {
+    :"scene.gltf#Scene0"
+    Transform { position: Vec3 { x: 10. } }
+}
+```
+
+This would set _just_ the `x` position in the GLTF scene root to `x`, patching on top of the position defined in the gltf scene. Cool!

_release-content/migration-guides/bevy_scene_rename.md

@@ -1,6 +1,6 @@
 (
   resources: {
-    "scene::ResourceA": (
+    "world_serialization::ResourceA": (
       score: 1,
     ),
   },
@@ -14,19 +14,19 @@
           rotation: (0.0, 0.0, 0.0, 1.0),
           scale: (1.0, 1.0, 1.0),
         ),
-        "scene::ComponentA": (
+        "world_serialization::ComponentA": (
           x: 1.0,
           y: 2.0,
         ),
-        "scene::ComponentB": (
+        "world_serialization::ComponentB": (
           value: "hello",
         ),
-        "bevy_ecs_serialization::components::SceneRoot": (Path("models/FlightHelmet/FlightHelmet.gltf#Scene0")),
+        "bevy_world_serialization::components::WorldAssetRoot": (Path("models/FlightHelmet/FlightHelmet.gltf#Scene0")),
       },
     ),
     4294967298: (
       components: {
-        "scene::ComponentA": (
+        "world_serialization::ComponentA": (
           x: 3.0,
           y: 4.0,
         ),

assets/scenes/load_scene_example.scn.ron …alized_worlds/load_scene_example.scn.ronassets/scenes/load_scene_example.scn.ron renamed to assets/serialized_worlds/load_scene_example.scn.ron assets/scenes/load_scene_example.scn.ron renamed to assets/serialized_worlds/load_scene_example.scn.ron

@@ -203,9 +203,9 @@ pub struct AnimationSystems;
 #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
 pub enum SceneSpawnerSystems {
     /// Bevy's original scene system.
-    SceneSpawn,
+    WorldInstanceSpawn,
     /// Bevy's next-generation scene system
-    Scene2Spawn,
+    SceneSpawn,
 }
 
 /// Defines the schedules to be run for the [`Main`] schedule, including