bevy::scene::Entity renamed to bevy::scene::DynamicEntity. (#3448)

Basic documentation added to bevy::scene::DynamicEntity and bevy::scene::DynamicScene.

# Objective

- Rename bevy::scene::Entity to bevy::scene::DynamicEntity
- fixes #3233

## Solution

- Renamed the struct as requested.
- Added basic documentation.

Co-authored-by: r4gus <david@thesugar.de>

crates/bevy_scene/src/dynamic_scene.rs

@@ -8,34 +8,46 @@ use bevy_ecs::{
 use bevy_reflect::{Reflect, TypeRegistryArc, TypeUuid};
 use serde::Serialize;
 
+/// A collection of serializable dynamic entities, each with its own run-time defined set of components.
 #[derive(Default, TypeUuid)]
 #[uuid = "749479b1-fb8c-4ff8-a775-623aa76014f5"]
 pub struct DynamicScene {
-    pub entities: Vec<Entity>,
+    pub entities: Vec<DynamicEntity>,
 }
 
-pub struct Entity {
+/// A reflection-powered serializable representation of an entity and its components.
+pub struct DynamicEntity {
+    /// The transiently unique identifier of a corresponding `Entity`.
     pub entity: u32,
+    /// A vector of boxed components that belong to the given entity and
+    /// implement the `Reflect` trait.
     pub components: Vec<Box<dyn Reflect>>,
 }
 
 impl DynamicScene {
+    /// Create a new dynamic scene from a given scene.
     pub fn from_scene(scene: &Scene, type_registry: &TypeRegistryArc) -> Self {
         Self::from_world(&scene.world, type_registry)
     }
 
+    /// Create a new dynamic scene from a given world.
     pub fn from_world(world: &World, type_registry: &TypeRegistryArc) -> Self {
         let mut scene = DynamicScene::default();
         let type_registry = type_registry.read();
+
         for archetype in world.archetypes().iter() {
             let entities_offset = scene.entities.len();
+
+            // Create a new dynamic entity for each entity of the given archetype
+            // and insert it into the dynamic scene.
             for entity in archetype.entities() {
-                scene.entities.push(Entity {
+                scene.entities.push(DynamicEntity {
                     entity: entity.id(),
                     components: Vec::new(),
                 });
             }
 
+            // Add each reflection-powered component to the entity it belongs to.
             for component_id in archetype.components() {
                 let reflect_component = world
                     .components()
@@ -58,17 +70,27 @@ impl DynamicScene {
         scene
     }
 
+    /// Write the dynamic entities and their corresponding components to the given world.
+    ///
+    /// This method will return a `SceneSpawnError` if either a type is not registered
+    /// or doesn't reflect the `Component` trait.
     pub fn write_to_world(
         &self,
         world: &mut World,
         entity_map: &mut EntityMap,
     ) -> Result<(), SceneSpawnError> {
         let registry = world.get_resource::<TypeRegistryArc>().unwrap().clone();
         let type_registry = registry.read();
+
         for scene_entity in self.entities.iter() {
+            // Fetch the entity with the given entity id from the `entity_map`
+            // or spawn a new entity with a transiently unique id if there is
+            // no corresponding entry.
             let entity = *entity_map
                 .entry(bevy_ecs::entity::Entity::new(scene_entity.entity))
                 .or_insert_with(|| world.spawn().id());
+
+            // Apply/ add each component to the given entity.
             for component in scene_entity.components.iter() {
                 let registration = type_registry
                     .get_with_name(component.type_name())
@@ -81,6 +103,10 @@ impl DynamicScene {
                             type_name: component.type_name().to_string(),
                         }
                     })?;
+
+                // If the entity already has the given component attached,
+                // just apply the (possibly) new value, otherwise add the
+                // component to the entity.
                 if world
                     .entity(entity)
                     .contains_type_id(registration.type_id())
@@ -104,11 +130,13 @@ impl DynamicScene {
     }
 
     // TODO: move to AssetSaver when it is implemented
+    /// Serialize this dynamic scene into rust object notation (ron).
     pub fn serialize_ron(&self, registry: &TypeRegistryArc) -> Result<String, ron::Error> {
         serialize_ron(SceneSerializer::new(self, registry))
     }
 }
 
+/// Serialize a given Rust data structure into rust object notation (ron).
 pub fn serialize_ron<S>(serialize: S) -> Result<String, ron::Error>
 where
     S: Serialize,

crates/bevy_scene/src/serde.rs

@@ -1,4 +1,4 @@
-use crate::{DynamicScene, Entity};
+use crate::{DynamicEntity, DynamicScene};
 use anyhow::Result;
 use bevy_reflect::{
     serde::{ReflectDeserializer, ReflectSerializer},
@@ -38,7 +38,7 @@ impl<'a> Serialize for SceneSerializer<'a> {
 }
 
 pub struct EntitySerializer<'a> {
-    pub entity: &'a Entity,
+    pub entity: &'a DynamicEntity,
     pub registry: &'a TypeRegistryArc,
 }
 
@@ -105,7 +105,7 @@ struct SceneEntitySeqVisitor<'a> {
 }
 
 impl<'a, 'de> Visitor<'de> for SceneEntitySeqVisitor<'a> {
-    type Value = Vec<Entity>;
+    type Value = Vec<DynamicEntity>;
 
     fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
         formatter.write_str("list of entities")
@@ -131,7 +131,7 @@ pub struct SceneEntityDeserializer<'a> {
 }
 
 impl<'a, 'de> DeserializeSeed<'de> for SceneEntityDeserializer<'a> {
-    type Value = Entity;
+    type Value = DynamicEntity;
 
     fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
     where
@@ -163,7 +163,7 @@ struct SceneEntityVisitor<'a> {
 }
 
 impl<'a, 'de> Visitor<'de> for SceneEntityVisitor<'a> {
-    type Value = Entity;
+    type Value = DynamicEntity;
 
     fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
         formatter.write_str("entities")
@@ -202,7 +202,7 @@ impl<'a, 'de> Visitor<'de> for SceneEntityVisitor<'a> {
         let components = components
             .take()
             .ok_or_else(|| Error::missing_field(ENTITY_FIELD_COMPONENTS))?;
-        Ok(Entity {
+        Ok(DynamicEntity {
             entity: *entity,
             components,
         })