bevy_reflect/
remote.rs

1use crate::Reflect;
2
3/// Marks a type as a [reflectable] wrapper for a remote type.
4///
5/// This allows types from external libraries (remote types) to be included in reflection.
6///
7/// # Safety
8///
9/// It is highly recommended to avoid implementing this trait manually and instead use the
10/// [`#[reflect_remote]`](crate::reflect_remote) attribute macro.
11/// This is because the trait tends to rely on [`transmute`], which is [very unsafe].
12///
13/// The macro will ensure that the following safety requirements are met:
14/// - `Self` is a single-field tuple struct (i.e. a newtype) containing the remote type.
15/// - `Self` is `#[repr(transparent)]` over the remote type.
16///
17/// Additionally, the macro will automatically generate [`Reflect`] and [`FromReflect`] implementations,
18/// along with compile-time assertions to validate that the safety requirements have been met.
19///
20/// # Example
21///
22/// ```
23/// use bevy_reflect_derive::{reflect_remote, Reflect};
24///
25/// mod some_lib {
26///   pub struct TheirType {
27///     pub value: u32
28///   }
29/// }
30///
31/// #[reflect_remote(some_lib::TheirType)]
32/// struct MyType {
33///   pub value: u32
34/// }
35///
36/// #[derive(Reflect)]
37/// struct MyStruct {
38///   #[reflect(remote = MyType)]
39///   data: some_lib::TheirType,
40/// }
41/// ```
42///
43/// [reflectable]: Reflect
44/// [`transmute`]: std::mem::transmute
45/// [very unsafe]: https://doc.rust-lang.org/1.71.0/nomicon/transmutes.html
46/// [`FromReflect`]: crate::FromReflect
47pub trait ReflectRemote: Reflect {
48    /// The remote type this type represents via reflection.
49    type Remote;
50
51    /// Converts a reference of this wrapper to a reference of its remote type.
52    fn as_remote(&self) -> &Self::Remote;
53    /// Converts a mutable reference of this wrapper to a mutable reference of its remote type.
54    fn as_remote_mut(&mut self) -> &mut Self::Remote;
55    /// Converts this wrapper into its remote type.
56    fn into_remote(self) -> Self::Remote;
57
58    /// Converts a reference of the remote type to a reference of this wrapper.
59    fn as_wrapper(remote: &Self::Remote) -> &Self;
60    /// Converts a mutable reference of the remote type to a mutable reference of this wrapper.
61    fn as_wrapper_mut(remote: &mut Self::Remote) -> &mut Self;
62    /// Converts the remote type into this wrapper.
63    fn into_wrapper(remote: Self::Remote) -> Self;
64}
bevy_reflect/remote.rs

bevy_reflect/
remote.rs
