Introduce ReflectConvert, a generic reflection mechanism for type

conversions, intended for asset BSN.

One of the important features of BSN is that supplying a value of type T
where a value of type U is expected is allowed if a `From` conversion
exists from T to U. This is what allows `HandleTemplate`s to be
automatically created from string literals. We need this feature for BSN
like this to be valid:

```rust
SceneRoot("models/FlightHelmet/FlightHelmet.gltf#Scene0")
```

And for this to be valid:

```rust
EnvironmentMapLight {
    diffuse_map: "environment_maps/pisa_diffuse_rgb9e5_zstd.ktx2",
    specular_map: "environment_maps/pisa_specular_rgb9e5_zstd.ktx2",
    intensity: 250.0,
}
```

Unfortunately, the `From` trait isn't reflectable, and this is a problem
as reflection drives asset BSN. It's not immediately clear how to make
`From` reflectable either, as a syntax like `#[reflect(From)]` wouldn't
work as it's a generic trait.

Instead of making `From` directly reflectable, this patch introduces
`ReflectConvert`, a new `TypeData` that encodes a generic way to convert
a value of type T to type U. You register a type conversion like this:

```rust
App::new()
    .register_type::<i32>()
    .register_type::<String>()
    .register_type_conversion::<i32, String>(|n| Ok(n.into()));
```

And you invoke the conversion like this:

```rust
let reflect_convert = registry
    .get_type_data::<ReflectConvert>(TypeId::of::<String>())
    .unwrap();

let converted = reflect_convert
    .try_convert_from(Box::new(12345i32))
    .unwrap()
    .downcast::<String>()
    .unwrap();
```

I tested `ReflectConvert` with asset BSN (PR bevyengine#23576). The
`ReflectConvert` trait as implemented in this patch successfully enables
`HandleTemplate`s to be created from strings, without hard-coding
`HandleTemplate` anywhere in the patch generation logic.

Author: pcwalton

crates/bevy_app/src/app.rs

@@ -694,6 +694,32 @@ impl App {
         self
     }
 
+    /// Registers a fallible conversion from type T to U with the reflection
+    /// system.
+    ///
+    /// The supplied closure is expected to produce a value of type U, given an
+    /// instance of type T. If the conversion fails, the closure should return
+    /// the input value, wrapped in an `Err` variant.
+    ///
+    /// # Example
+    /// ```
+    /// App::new()
+    ///     .register_type::<i32>()
+    ///     .register_type::<String>()
+    ///     .register_type_conversion::<i32, String>(|n| Ok(n.into()));
+    /// ```
+    ///
+    /// See [`bevy_reflect::TypeRegistry::register_type_conversion`].
+    #[cfg(feature = "bevy_reflect")]
+    pub fn register_type_conversion<T, U>(&mut self, function: fn(T) -> Result<U, T>) -> &mut Self
+    where
+        T: Reflect + TypePath,
+        U: Reflect + TypePath,
+    {
+        self.main_mut().register_type_conversion(function);
+        self
+    }
+
     /// Registers the given function into the [`AppFunctionRegistry`] resource.
     ///
     /// The given function will internally be stored as a [`DynamicFunction`]

crates/bevy_app/src/sub_app.rs

@@ -485,6 +485,18 @@ impl SubApp {
         self
     }
 
+    /// See [`App::register_type_conversion`].
+    #[cfg(feature = "bevy_reflect")]
+    pub fn register_type_conversion<T, U>(&mut self, function: fn(T) -> Result<U, T>) -> &mut Self
+    where
+        T: bevy_reflect::Reflect + bevy_reflect::TypePath,
+        U: bevy_reflect::Reflect + bevy_reflect::TypePath,
+    {
+        let registry = self.world.resource_mut::<AppTypeRegistry>();
+        registry.write().register_type_conversion::<T, U>(function);
+        self
+    }
+
     /// See [`App::register_function`].
     #[cfg(feature = "reflect_functions")]
     pub fn register_function<F, Marker>(&mut self, function: F) -> &mut Self

crates/bevy_asset/src/handle.rs

@@ -208,6 +208,7 @@ impl<T: Asset> FromTemplate for Handle<T> {
     type Template = HandleTemplate<T>;
 }
 
+#[derive(Reflect)]
 pub enum HandleTemplate<T: Asset> {
     Path(AssetPath<'static>),
     Handle(Handle<T>),

crates/bevy_asset/src/lib.rs

@@ -684,6 +684,7 @@ impl AssetApp for App {
             type_registry.register::<Handle<A>>();
             type_registry.register_type_data::<A, ReflectAsset>();
             type_registry.register_type_data::<Handle<A>, ReflectHandle>();
+            type_registry.register_type_conversion::<String, HandleTemplate<A>>(|s| Ok(s.into()));
         }
 
         self

crates/bevy_reflect/src/convert.rs

@@ -0,0 +1,225 @@
+//! The [`ReflectConvert`] type, which allows types to register conversions to
+//! and from one another.
+
+use alloc::boxed::Box;
+use core::any::TypeId;
+
+use bevy_utils::TypeIdMap;
+
+use crate::{Reflect, TypePath};
+
+/// Provides a mechanism for converting values of one type to another.
+///
+/// This [`crate::type_registry::TypeData`] is associated with the type to be
+/// converted *into*, not the type to be converted *from*. To convert a value,
+/// use code like the following:
+///
+/// ```rust
+/// # let mut registry = TypeRegistry::default();
+/// # registry.add_registration(i32::get_type_registration());
+/// # registry.add_registration(String::get_type_registration());
+/// # registry.register_type_conversion(|x: i32| Ok(x.to_string()));
+///
+/// let reflect_convert = registry
+///     .get_type_data::<ReflectConvert>(TypeId::of::<String>())
+///     .unwrap();
+/// let converted: String = reflect_convert
+///     .try_convert_from(Box::new(12345i32))
+///     .unwrap()
+///     .downcast::<String>()
+///     .unwrap();
+/// ```
+#[derive(Default)]
+pub struct ReflectConvert {
+    /// A mapping from the type to be converted *from* to its associated
+    /// [`Converter`].
+    conversions: TypeIdMap<Box<dyn Converter>>,
+}
+
+/// An internal trait that wraps a conversion function in an untyped interface.
+trait Converter: Send + Sync {
+    /// Converts the value to the appropriate type.
+    ///
+    /// This returns the converted value if the conversion succeeds or the
+    /// original value if the conversion fails.
+    fn convert(&self, input: Box<dyn Reflect>) -> Result<Box<dyn Reflect>, Box<dyn Reflect>>;
+
+    /// Returns a new boxed instance wrapping the same [`Converter`].
+    fn clone_converter(&self) -> Box<dyn Converter>;
+}
+
+/// A wrapper that contains a conversion function and implements [`Converter`].
+struct TypedConverter<T, U>(fn(T) -> Result<U, T>)
+where
+    T: Reflect + TypePath,
+    U: Reflect + TypePath;
+
+impl ReflectConvert {
+    /// Creates a new, empty [`ReflectConvert`] with no conversions registered.
+    pub fn new() -> ReflectConvert {
+        Self::default()
+    }
+
+    /// Attempts to construct an instance of this type from the provided
+    /// `input`.
+    ///
+    /// If the conversion fails, either because no conversion has been
+    /// registered from the type of `input` or because the conversion function
+    /// itself returned `Err`, the `input` value is returned as an error.
+    pub fn try_convert_from(
+        &self,
+        input: Box<dyn Reflect>,
+    ) -> Result<Box<dyn Reflect>, Box<dyn Reflect>> {
+        let type_id = (*input.as_any()).type_id();
+        match self.conversions.get(&type_id) {
+            Some(converter) => converter.convert(input),
+            None => Err(input),
+        }
+    }
+
+    /// Adds a conversion function from the type `T` to this type.
+    ///
+    /// If the conversion succeeds, the function should return the converted
+    /// value. If the conversion fails, the function should return the original
+    /// input value.
+    pub fn register_type_conversion<T, U>(&mut self, function: fn(T) -> Result<U, T>)
+    where
+        T: Reflect + TypePath,
+        U: Reflect + TypePath,
+    {
+        self.conversions
+            .insert(TypeId::of::<T>(), Box::new(TypedConverter(function)));
+    }
+}
+
+impl Clone for ReflectConvert {
+    fn clone(&self) -> Self {
+        ReflectConvert {
+            conversions: self
+                .conversions
+                .iter()
+                .map(|(type_id, converter)| (*type_id, converter.clone_converter()))
+                .collect(),
+        }
+    }
+}
+
+impl<T, U> Clone for TypedConverter<T, U>
+where
+    T: Reflect + TypePath,
+    U: Reflect + TypePath,
+{
+    fn clone(&self) -> Self {
+        TypedConverter(self.0)
+    }
+}
+
+impl<T, U> Converter for TypedConverter<T, U>
+where
+    T: Reflect + TypePath,
+    U: Reflect + TypePath,
+{
+    fn convert(&self, input: Box<dyn Reflect>) -> Result<Box<dyn Reflect>, Box<dyn Reflect>> {
+        match (self.0)(input.take()?) {
+            Ok(value) => Ok(Box::new(value)),
+            Err(value) => Err(Box::new(value)),
+        }
+    }
+
+    fn clone_converter(&self) -> Box<dyn Converter> {
+        Box::new(self.clone())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use alloc::{
+        borrow::ToOwned as _,
+        boxed::Box,
+        string::{String, ToString},
+    };
+    use core::any::TypeId;
+
+    use crate::{convert::ReflectConvert, type_registry::GetTypeRegistration, TypeRegistry};
+
+    /// Tests that `i32` can be converted to `String` if the appropriate
+    /// conversion is registered.
+    #[test]
+    fn convert_from_i32_to_string() {
+        // Register the types and the conversion.
+        let mut registry = TypeRegistry::default();
+        registry.add_registration(i32::get_type_registration());
+        registry.add_registration(String::get_type_registration());
+        registry.register_type_conversion(|x: i32| Ok(x.to_string()));
+
+        let reflect_convert = registry
+            .get_type_data::<ReflectConvert>(TypeId::of::<String>())
+            .unwrap();
+
+        // Test that a successful conversion works.
+        let converted = reflect_convert
+            .try_convert_from(Box::new(12345i32))
+            .unwrap()
+            .downcast::<String>()
+            .unwrap();
+        assert_eq!(&**converted, "12345");
+    }
+
+    /// Tests that `String` can be fallibly converted to `i32` if the
+    /// appropriate conversion is registered.
+    ///
+    /// This also tests that the behavior of returning the original string on
+    /// error is correct.
+    #[test]
+    fn convert_from_string_to_i32() {
+        // Register the types and the conversion.
+        let mut registry = TypeRegistry::default();
+        registry.add_registration(i32::get_type_registration());
+        registry.add_registration(String::get_type_registration());
+        registry.register_type_conversion(|x: String| match x.parse::<i32>() {
+            Ok(value) => Ok(value),
+            Err(_) => Err(x),
+        });
+
+        let reflect_convert = registry
+            .get_type_data::<ReflectConvert>(TypeId::of::<i32>())
+            .unwrap();
+
+        // Test a successful conversion from string to integer.
+        let converted = reflect_convert
+            .try_convert_from(Box::new("12345".to_owned()))
+            .unwrap()
+            .downcast::<i32>()
+            .unwrap();
+        assert_eq!(*converted, 12345);
+
+        // Test an unsuccessful conversion from string to integer.
+        let error = reflect_convert
+            .try_convert_from(Box::new("qqqqq".to_owned()))
+            .unwrap_err()
+            .downcast::<String>()
+            .unwrap();
+        assert_eq!(&**error, "qqqqq");
+    }
+
+    /// Tests that the error-handling behavior is correct when attempting a
+    /// conversion that hasn't been registered.
+    #[test]
+    fn no_such_conversion() {
+        let mut registry = TypeRegistry::default();
+        registry.add_registration(i32::get_type_registration());
+        registry.add_registration(String::get_type_registration());
+
+        let reflect_convert = registry
+            .get_type_data::<ReflectConvert>(TypeId::of::<i32>())
+            .unwrap();
+
+        // Test that we get the original value back on error.
+        let error = reflect_convert
+            .try_convert_from(Box::new("12345".to_owned()))
+            .unwrap_err()
+            .downcast::<String>()
+            .unwrap();
+        assert_eq!(&**error, "12345");
+    }
+}

crates/bevy_reflect/src/lib.rs

@@ -645,6 +645,7 @@ mod impls {
 }
 
 pub mod attributes;
+pub mod convert;
 pub mod enums;
 mod generics;
 pub mod serde;

crates/bevy_reflect/src/type_registry.rs

@@ -1,4 +1,6 @@
-use crate::{serde::Serializable, FromReflect, Reflect, TypeInfo, TypePath, Typed};
+use crate::{
+    convert::ReflectConvert, serde::Serializable, FromReflect, Reflect, TypeInfo, TypePath, Typed,
+};
 use alloc::{boxed::Box, string::String};
 use bevy_platform::{
     collections::{HashMap, HashSet},
@@ -353,6 +355,39 @@ impl TypeRegistry {
         data.insert(D::from_type());
     }
 
+    /// Registers a fallible conversion from type T to U with the reflection
+    /// system.
+    ///
+    /// The supplied closure is expected to produce a value of type U, given an
+    /// instance of type T. If the conversion fails, the closure should return
+    /// the input value, wrapped in an `Err` variant.
+    ///
+    /// # Example
+    /// ```
+    /// let mut type_registry = TypeRegistry::default();
+    /// type_registry.register::<i32>();
+    /// type_registry.register::<String>();
+    /// type_registry.register_type_conversion::<i32, String>(|n| Ok(n.into()));
+    /// ```
+    pub fn register_type_conversion<T, U>(&mut self, function: fn(T) -> Result<U, T>)
+    where
+        T: Reflect + TypePath,
+        U: Reflect + TypePath,
+    {
+        let data = self.get_mut(TypeId::of::<U>()).unwrap_or_else(|| {
+            panic!(
+                "attempted to call `TypeRegistry::register_type_conversion` for type `{U}` without registering `{U}` first",
+                U = U::type_path(),
+            )
+        });
+        if !data.contains::<ReflectConvert>() {
+            data.insert(ReflectConvert::new());
+        }
+        data.data_mut::<ReflectConvert>()
+            .unwrap()
+            .register_type_conversion(function);
+    }
+
     /// Whether the type with given [`TypeId`] has been registered in this registry.
     pub fn contains(&self, type_id: TypeId) -> bool {
         self.registrations.contains_key(&type_id)