0.11 Section: FromReflect Ergonomics (#669)

Co-authored-by: Carter Anderson <[email protected]>

Author: MrGVSV

content/news/2023-07-07-bevy-0.11/index.md

@@ -20,6 +20,67 @@ Since our last release a few months ago we've added a _ton_ of new features, bug
   flat surfaces a feel of depth through parallaxing the material's textures.
 * **Gamepad Rumble API**: an ECS-friendly way of making controllers rumble
 
+## `FromReflect` Ergonomics
+
+<div class="release-feature-authors">authors: @MrGVSV</div>
+
+Bevy's [reflection API] commonly passes around data using type-erased `dyn Reflect` trait objects.
+This can usually be downcast back to its concrete type using `<dyn Reflect>::downcast_ref::<T>`;
+however, this doesn't work if the underlying data has been converted to a "dynamic" representation
+(e.g. `DynamicStruct` for struct types, `DynamicList` for list types, etc.).
+
+```rust
+let data: Vec<i32> = vec![1, 2, 3];
+
+let reflect: &dyn Reflect = &data;
+let cloned: Box<dyn Reflect> = reflect.clone_value();
+
+// `reflect` really is a `Vec<i32>`
+assert!(reflect.is::<Vec<i32>>());
+assert!(reflect.represents::<Vec<i32>>());
+
+// `cloned` is a `DynamicList`, but represents a `Vec<i32>`
+assert!(cloned.is::<DynamicList>());
+assert!(cloned.represents::<Vec<i32>>());
+
+// `cloned` is equivalent to the original `reflect`, despite not being a `Vec<i32>`
+assert!(cloned.reflect_partial_eq(reflect).unwrap_or_default());
+```
+
+To account for this, the [`FromReflect`] trait can be used to convert any `dyn Reflect` trait object
+back into its concrete type— whether it is actually that type or a dynamic representation of it.
+And it can even be called dynamically using the [`ReflectFromReflect`] type data.
+
+Before 0.11, users had to be manually derive `FromReflect` for every type that needed it,
+as well as manually register the `ReflectFromReflect` type data.
+This made it cumbersome to use and also meant that it was often forgotten about,
+resulting in reflection conversions difficulties for users downstream.
+
+Now in 0.11, `FromReflect` is automatically derived and `ReflectFromReflect` is automatically registered for all types that derive `Reflect`.
+This means most types will be `FromReflect`-capable by default,
+thus reducing boilerplate and empowering logic centered around `FromReflect`.
+
+Users can still opt out of this behavior by adding the [`#[reflect(from_reflect = false)]`][from_reflect = false] attribute to their type.
+
+```rust
+#[derive(Reflect)]
+struct Foo;
+
+#[derive(Reflect)]
+#[reflect(from_reflect = false)]
+struct Bar;
+
+fn test<T: FromReflect>(value: T) {}
+
+test(Foo); // <-- OK!
+test(Bar); // <-- ERROR! `Bar` does not implement trait `FromReflect`
+```
+
+[reflection API]: https://docs.rs/bevy_reflect/latest/bevy_reflect/index.html
+[`FromReflect`]: https://docs.rs/bevy_reflect/latest/bevy_reflect/trait.FromReflect.html
+[`ReflectFromReflect`]: https://docs.rs/bevy_reflect/latest/bevy_reflect/struct.ReflectFromReflect.html
+[from_reflect = false]: https://docs.rs/bevy_reflect/latest/bevy_reflect/derive.Reflect.html#reflectfrom_reflect--false
+
 ## Gamepad Rumble API
 
 <div class="release-feature-authors">authors: @johanhelsing, @nicopap</div>