diff --git a/content/news/2023-07-07-bevy-0.11/index.md b/content/news/2023-07-07-bevy-0.11/index.md index 640a5e7b16..0a2c34c1ef 100644 --- a/content/news/2023-07-07-bevy-0.11/index.md +++ b/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 + +
authors: @MrGVSV
+ +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 `::downcast_ref::`; +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 = vec![1, 2, 3]; + +let reflect: &dyn Reflect = &data; +let cloned: Box = reflect.clone_value(); + +// `reflect` really is a `Vec` +assert!(reflect.is::>()); +assert!(reflect.represents::>()); + +// `cloned` is a `DynamicList`, but represents a `Vec` +assert!(cloned.is::()); +assert!(cloned.represents::>()); + +// `cloned` is equivalent to the original `reflect`, despite not being a `Vec` +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(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
authors: @johanhelsing, @nicopap