Add example

Author: MrGVSV

Cargo.toml

@@ -2195,6 +2195,17 @@ description = "Demonstrates how functions can be called dynamically using reflec
 category = "Reflection"
 wasm = false
 
+[[example]]
+name = "nested_reflection"
+path = "examples/reflection/nested_reflection.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.nested_reflection]
+name = "Nested Reflection"
+description = "Demonstrates how reflection trait objects can be nested in other reflected types"
+category = "Reflection"
+wasm = false
+
 [[example]]
 name = "generic_reflection"
 path = "examples/reflection/generic_reflection.rs"

examples/README.md

@@ -365,6 +365,7 @@ Example | Description
 [Custom Attributes](../examples/reflection/custom_attributes.rs) | Registering and accessing custom attributes on reflected types
 [Dynamic Types](../examples/reflection/dynamic_types.rs) | How dynamic types are used with reflection
 [Function Reflection](../examples/reflection/function_reflection.rs) | Demonstrates how functions can be called dynamically using reflection
+[Nested Reflection](../examples/reflection/nested_reflection.rs) | Demonstrates how reflection trait objects can be nested in other reflected types
 [Generic Reflection](../examples/reflection/generic_reflection.rs) | Registers concrete instances of generic types that may be used with reflection
 [Reflection](../examples/reflection/reflection.rs) | Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types
 [Reflection Types](../examples/reflection/reflection_types.rs) | Illustrates the various reflection types available

examples/reflection/nested_reflection.rs

@@ -0,0 +1,51 @@
+//! This example demonstrates how reflection trait objects can be nested in other reflected types
+//! using remote reflection.
+
+use bevy::prelude::*;
+
+fn main() {
+    // Bevy's reflection crate relies heavily on the `dyn Reflect` trait object.
+    // This allows the compile-time name of a type to be "erased" and passed around at runtime,
+    // most often as a `Box<dyn Reflect>`.
+    let _: Box<dyn Reflect> = Box::new(String::from("Hello, World!"));
+
+    // However, you'll notice that `Box<dyn Reflect>` itself doesn't implement `Reflect`.
+    // This makes it impossible to use `Box<dyn Reflect>` as a field in a struct that derives `Reflect`.
+    // ```
+    // #[derive(Reflect)]
+    // struct MyType {
+    //     field: Box<dyn Reflect>, // <- Compile Error
+    // }
+    // ```
+    // This is because it would be too easy to accidentally box a `Reflect` type,
+    // then accidentally box it again, and again, and so on.
+    // So instead, `bevy_reflect` exposes a `ReflectBox` type which can be used
+    // as a remote wrapper around a `Box<dyn Reflect>` (or `Box<dyn PartialReflect>`).
+    //
+    // For example, let's say we want to define some equipment for a player.
+    // We don't know what kind of equipment the player will have at compile time,
+    // so we want to store it as a `Box<dyn Reflect>`.
+    // To do this, we first need to derive `Reflect` for our `Player`.
+    #[derive(Reflect)]
+    // Next, we need to opt out of deriving `FromReflect` since `Box<dyn Reflect>`
+    // has no knowledge of `FromReflect`.
+    #[reflect(from_reflect = false)]
+    struct Player {
+        // Now we can use remote reflection to tell `Reflect` how to reflect our `Box<dyn Reflect>`.
+        #[reflect(remote = bevy::reflect::boxed::ReflectBox<dyn Reflect>)]
+        equipment: Box<dyn Reflect>,
+    }
+
+    // Now we can use any type that implements `Reflect` as equipment for our player.
+    let equipment: Box<dyn Reflect> = Box::new(String::from("Sword"));
+    let mut player: Box<dyn Struct> = Box::new(Player { equipment });
+
+    // We can also use reflection to modify our player's equipment.
+    let equipment = player.field_mut("equipment").unwrap();
+    equipment.try_apply(&String::from("Shield")).unwrap();
+    assert!(player
+        .reflect_partial_eq(&Player {
+            equipment: Box::new(String::from("Shield")),
+        })
+        .unwrap_or_default());
+}