bevy_reflect/type_registry.rs
1use crate::{serde::Serializable, FromReflect, Reflect, TypeInfo, TypePath, Typed};
2use alloc::{boxed::Box, string::String};
3use bevy_platform::{
4 collections::{HashMap, HashSet},
5 sync::{Arc, PoisonError, RwLock, RwLockReadGuard, RwLockWriteGuard},
6};
7use bevy_ptr::{Ptr, PtrMut};
8use bevy_utils::TypeIdMap;
9use core::{
10 any::TypeId,
11 fmt::Debug,
12 ops::{Deref, DerefMut},
13};
14use downcast_rs::{impl_downcast, Downcast};
15use serde::{Deserialize, Serialize};
16
17/// A registry of [reflected] types.
18///
19/// This struct is used as the central store for type information.
20/// [Registering] a type will generate a new [`TypeRegistration`] entry in this store
21/// using a type's [`GetTypeRegistration`] implementation
22/// (which is automatically implemented when using [`#[derive(Reflect)]`](derive@crate::Reflect)).
23///
24/// See the [crate-level documentation] for more information.
25///
26/// [reflected]: crate
27/// [Registering]: TypeRegistry::register
28/// [crate-level documentation]: crate
29pub struct TypeRegistry {
30 registrations: TypeIdMap<TypeRegistration>,
31 short_path_to_id: HashMap<&'static str, TypeId>,
32 type_path_to_id: HashMap<&'static str, TypeId>,
33 ambiguous_names: HashSet<&'static str>,
34}
35
36// TODO: remove this wrapper once we migrate to Atelier Assets and the Scene AssetLoader doesn't
37// need a TypeRegistry ref
38/// A synchronized wrapper around a [`TypeRegistry`].
39#[derive(Clone, Default)]
40pub struct TypeRegistryArc {
41 /// The wrapped [`TypeRegistry`].
42 pub internal: Arc<RwLock<TypeRegistry>>,
43}
44
45impl Debug for TypeRegistryArc {
46 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
47 self.internal
48 .read()
49 .unwrap_or_else(PoisonError::into_inner)
50 .type_path_to_id
51 .keys()
52 .fmt(f)
53 }
54}
55
56/// A trait which allows a type to generate its [`TypeRegistration`]
57/// for registration into the [`TypeRegistry`].
58///
59/// This trait is automatically implemented for items using [`#[derive(Reflect)]`](derive@crate::Reflect).
60/// The macro also allows [`TypeData`] to be more easily registered.
61///
62/// If you need to use this trait as a generic bound along with other reflection traits,
63/// for your convenience, consider using [`Reflectable`] instead.
64///
65/// See the [crate-level documentation] for more information on type registration.
66///
67/// [`Reflectable`]: crate::Reflectable
68/// [crate-level documentation]: crate
69#[diagnostic::on_unimplemented(
70 message = "`{Self}` does not implement `GetTypeRegistration` so cannot provide type registration information",
71 note = "consider annotating `{Self}` with `#[derive(Reflect)]`"
72)]
73pub trait GetTypeRegistration: 'static {
74 /// Returns the default [`TypeRegistration`] for this type.
75 fn get_type_registration() -> TypeRegistration;
76 /// Registers other types needed by this type.
77 ///
78 /// This method is called by [`TypeRegistry::register`] to register any other required types.
79 /// Often, this is done for fields of structs and enum variants to ensure all types are properly registered.
80 fn register_type_dependencies(_registry: &mut TypeRegistry) {}
81}
82
83impl Default for TypeRegistry {
84 fn default() -> Self {
85 Self::new()
86 }
87}
88
89impl TypeRegistry {
90 /// Create a type registry with *no* registered types.
91 pub fn empty() -> Self {
92 Self {
93 registrations: Default::default(),
94 short_path_to_id: Default::default(),
95 type_path_to_id: Default::default(),
96 ambiguous_names: Default::default(),
97 }
98 }
99
100 /// Create a type registry with default registrations for primitive types.
101 pub fn new() -> Self {
102 let mut registry = Self::empty();
103 registry.register::<()>();
104 registry.register::<bool>();
105 registry.register::<char>();
106 registry.register::<u8>();
107 registry.register::<u16>();
108 registry.register::<u32>();
109 registry.register::<u64>();
110 registry.register::<u128>();
111 registry.register::<usize>();
112 registry.register::<i8>();
113 registry.register::<i16>();
114 registry.register::<i32>();
115 registry.register::<i64>();
116 registry.register::<i128>();
117 registry.register::<isize>();
118 registry.register::<f32>();
119 registry.register::<f64>();
120 registry.register::<String>();
121 registry
122 }
123
124 /// Register all non-generic types annotated with `#[derive(Reflect)]`.
125 ///
126 /// Calling this method is equivalent to calling [`register`](Self::register) on all types without generic parameters
127 /// that derived [`Reflect`] trait.
128 ///
129 /// This method is supported on Linux, macOS, Windows, iOS, Android, and Web via the `inventory` crate.
130 /// It does nothing on platforms not supported by either of those crates.
131 ///
132 /// # Example
133 ///
134 /// ```
135 /// # use std::any::TypeId;
136 /// # use bevy_reflect::{Reflect, TypeRegistry, std_traits::ReflectDefault};
137 /// #[derive(Reflect, Default)]
138 /// #[reflect(Default)]
139 /// struct Foo {
140 /// name: Option<String>,
141 /// value: i32
142 /// }
143 ///
144 /// let mut type_registry = TypeRegistry::empty();
145 /// type_registry.register_derived_types();
146 ///
147 /// // The main type
148 /// assert!(type_registry.contains(TypeId::of::<Foo>()));
149 ///
150 /// // Its type dependencies
151 /// assert!(type_registry.contains(TypeId::of::<Option<String>>()));
152 /// assert!(type_registry.contains(TypeId::of::<i32>()));
153 ///
154 /// // Its type data
155 /// assert!(type_registry.get_type_data::<ReflectDefault>(TypeId::of::<Foo>()).is_some());
156 /// ```
157 #[cfg(feature = "auto_register")]
158 pub fn register_derived_types(&mut self) {
159 crate::__macro_exports::auto_register::register_types(self);
160 }
161
162 /// Attempts to register the type `T` if it has not yet been registered already.
163 ///
164 /// This will also recursively register any type dependencies as specified by [`GetTypeRegistration::register_type_dependencies`].
165 /// When deriving `Reflect`, this will generally be all the fields of the struct or enum variant.
166 /// As with any type registration, these type dependencies will not be registered more than once.
167 ///
168 /// If the registration for type `T` already exists, it will not be registered again and neither will its type dependencies.
169 /// To register the type, overwriting any existing registration, use [register](Self::overwrite_registration) instead.
170 ///
171 /// Additionally, this will add any reflect [type data](TypeData) as specified in the [`Reflect`] derive.
172 ///
173 /// # Example
174 ///
175 /// ```
176 /// # use core::any::TypeId;
177 /// # use bevy_reflect::{Reflect, TypeRegistry, std_traits::ReflectDefault};
178 /// #[derive(Reflect, Default)]
179 /// #[reflect(Default)]
180 /// struct Foo {
181 /// name: Option<String>,
182 /// value: i32
183 /// }
184 ///
185 /// let mut type_registry = TypeRegistry::default();
186 ///
187 /// type_registry.register::<Foo>();
188 ///
189 /// // The main type
190 /// assert!(type_registry.contains(TypeId::of::<Foo>()));
191 ///
192 /// // Its type dependencies
193 /// assert!(type_registry.contains(TypeId::of::<Option<String>>()));
194 /// assert!(type_registry.contains(TypeId::of::<i32>()));
195 ///
196 /// // Its type data
197 /// assert!(type_registry.get_type_data::<ReflectDefault>(TypeId::of::<Foo>()).is_some());
198 /// ```
199 pub fn register<T>(&mut self)
200 where
201 T: GetTypeRegistration,
202 {
203 if self.register_internal(TypeId::of::<T>(), T::get_type_registration) {
204 T::register_type_dependencies(self);
205 }
206 }
207
208 /// Attempts to register the referenced type `T` if it has not yet been registered.
209 ///
210 /// See [`register`] for more details.
211 ///
212 /// # Example
213 ///
214 /// ```
215 /// # use bevy_reflect::{Reflect, TypeRegistry};
216 /// # use core::any::TypeId;
217 /// #
218 /// # let mut type_registry = TypeRegistry::default();
219 /// #
220 /// #[derive(Reflect)]
221 /// struct Foo {
222 /// bar: Bar,
223 /// }
224 ///
225 /// #[derive(Reflect)]
226 /// struct Bar;
227 ///
228 /// let foo = Foo { bar: Bar };
229 ///
230 /// // Equivalent to `type_registry.register::<Foo>()`
231 /// type_registry.register_by_val(&foo);
232 ///
233 /// assert!(type_registry.contains(TypeId::of::<Foo>()));
234 /// assert!(type_registry.contains(TypeId::of::<Bar>()));
235 /// ```
236 ///
237 /// [`register`]: Self::register
238 pub fn register_by_val<T>(&mut self, _: &T)
239 where
240 T: GetTypeRegistration,
241 {
242 self.register::<T>();
243 }
244
245 /// Attempts to register the type described by `registration`.
246 ///
247 /// If the registration for the type already exists, it will not be registered again.
248 ///
249 /// To forcibly register the type, overwriting any existing registration, use the
250 /// [`overwrite_registration`](Self::overwrite_registration) method instead.
251 ///
252 /// This method will _not_ register type dependencies.
253 /// Use [`register`](Self::register) to register a type with its dependencies.
254 ///
255 /// Returns `true` if the registration was added and `false` if it already exists.
256 pub fn add_registration(&mut self, registration: TypeRegistration) -> bool {
257 let type_id = registration.type_id();
258 self.register_internal(type_id, || registration)
259 }
260
261 /// Registers the type described by `registration`.
262 ///
263 /// If the registration for the type already exists, it will be overwritten.
264 ///
265 /// To avoid overwriting existing registrations, it's recommended to use the
266 /// [`register`](Self::register) or [`add_registration`](Self::add_registration) methods instead.
267 ///
268 /// This method will _not_ register type dependencies.
269 /// Use [`register`](Self::register) to register a type with its dependencies.
270 pub fn overwrite_registration(&mut self, registration: TypeRegistration) {
271 Self::update_registration_indices(
272 ®istration,
273 &mut self.short_path_to_id,
274 &mut self.type_path_to_id,
275 &mut self.ambiguous_names,
276 );
277 self.registrations
278 .insert(registration.type_id(), registration);
279 }
280
281 /// Internal method to register a type with a given [`TypeId`] and [`TypeRegistration`].
282 ///
283 /// By using this method, we are able to reduce the number of `TypeId` hashes and lookups needed
284 /// to register a type.
285 ///
286 /// This method is internal to prevent users from accidentally registering a type with a `TypeId`
287 /// that does not match the type in the `TypeRegistration`.
288 fn register_internal(
289 &mut self,
290 type_id: TypeId,
291 get_registration: impl FnOnce() -> TypeRegistration,
292 ) -> bool {
293 use bevy_platform::collections::hash_map::Entry;
294
295 match self.registrations.entry(type_id) {
296 Entry::Occupied(_) => false,
297 Entry::Vacant(entry) => {
298 let registration = get_registration();
299 Self::update_registration_indices(
300 ®istration,
301 &mut self.short_path_to_id,
302 &mut self.type_path_to_id,
303 &mut self.ambiguous_names,
304 );
305 entry.insert(registration);
306 true
307 }
308 }
309 }
310
311 /// Internal method to register additional lookups for a given [`TypeRegistration`].
312 fn update_registration_indices(
313 registration: &TypeRegistration,
314 short_path_to_id: &mut HashMap<&'static str, TypeId>,
315 type_path_to_id: &mut HashMap<&'static str, TypeId>,
316 ambiguous_names: &mut HashSet<&'static str>,
317 ) {
318 let short_name = registration.type_info().type_path_table().short_path();
319 if short_path_to_id.contains_key(short_name) || ambiguous_names.contains(short_name) {
320 // name is ambiguous. fall back to long names for all ambiguous types
321 short_path_to_id.remove(short_name);
322 ambiguous_names.insert(short_name);
323 } else {
324 short_path_to_id.insert(short_name, registration.type_id());
325 }
326 type_path_to_id.insert(registration.type_info().type_path(), registration.type_id());
327 }
328
329 /// Registers the type data `D` for type `T`.
330 ///
331 /// Most of the time [`TypeRegistry::register`] can be used instead to register a type you derived [`Reflect`] for.
332 /// However, in cases where you want to add a piece of type data that was not included in the list of `#[reflect(...)]` type data in the derive,
333 /// or where the type is generic and cannot register e.g. [`ReflectSerialize`] unconditionally without knowing the specific type parameters,
334 /// this method can be used to insert additional type data.
335 ///
336 /// # Example
337 /// ```
338 /// use bevy_reflect::{TypeRegistry, ReflectSerialize, ReflectDeserialize};
339 ///
340 /// let mut type_registry = TypeRegistry::default();
341 /// type_registry.register::<Option<String>>();
342 /// type_registry.register_type_data::<Option<String>, ReflectSerialize>();
343 /// type_registry.register_type_data::<Option<String>, ReflectDeserialize>();
344 /// ```
345 pub fn register_type_data<T: Reflect + TypePath, D: TypeData + FromType<T>>(&mut self) {
346 let data = self.get_mut(TypeId::of::<T>()).unwrap_or_else(|| {
347 panic!(
348 "attempted to call `TypeRegistry::register_type_data` for type `{T}` with data `{D}` without registering `{T}` first",
349 T = T::type_path(),
350 D = core::any::type_name::<D>(),
351 )
352 });
353 data.insert(D::from_type());
354 }
355
356 /// Whether the type with given [`TypeId`] has been registered in this registry.
357 pub fn contains(&self, type_id: TypeId) -> bool {
358 self.registrations.contains_key(&type_id)
359 }
360
361 /// Returns a reference to the [`TypeRegistration`] of the type with the
362 /// given [`TypeId`].
363 ///
364 /// If the specified type has not been registered, returns `None`.
365 #[inline]
366 pub fn get(&self, type_id: TypeId) -> Option<&TypeRegistration> {
367 self.registrations.get(&type_id)
368 }
369
370 /// Returns a mutable reference to the [`TypeRegistration`] of the type with
371 /// the given [`TypeId`].
372 ///
373 /// If the specified type has not been registered, returns `None`.
374 pub fn get_mut(&mut self, type_id: TypeId) -> Option<&mut TypeRegistration> {
375 self.registrations.get_mut(&type_id)
376 }
377
378 /// Returns a reference to the [`TypeRegistration`] of the type with the
379 /// given [type path].
380 ///
381 /// If no type with the given path has been registered, returns `None`.
382 ///
383 /// [type path]: TypePath::type_path
384 pub fn get_with_type_path(&self, type_path: &str) -> Option<&TypeRegistration> {
385 self.type_path_to_id
386 .get(type_path)
387 .and_then(|id| self.get(*id))
388 }
389
390 /// Returns a mutable reference to the [`TypeRegistration`] of the type with
391 /// the given [type path].
392 ///
393 /// If no type with the given type path has been registered, returns `None`.
394 ///
395 /// [type path]: TypePath::type_path
396 pub fn get_with_type_path_mut(&mut self, type_path: &str) -> Option<&mut TypeRegistration> {
397 self.type_path_to_id
398 .get(type_path)
399 .cloned()
400 .and_then(move |id| self.get_mut(id))
401 }
402
403 /// Returns a reference to the [`TypeRegistration`] of the type with
404 /// the given [short type path].
405 ///
406 /// If the short type path is ambiguous, or if no type with the given path
407 /// has been registered, returns `None`.
408 ///
409 /// [short type path]: TypePath::short_type_path
410 pub fn get_with_short_type_path(&self, short_type_path: &str) -> Option<&TypeRegistration> {
411 self.short_path_to_id
412 .get(short_type_path)
413 .and_then(|id| self.registrations.get(id))
414 }
415
416 /// Returns a mutable reference to the [`TypeRegistration`] of the type with
417 /// the given [short type path].
418 ///
419 /// If the short type path is ambiguous, or if no type with the given path
420 /// has been registered, returns `None`.
421 ///
422 /// [short type path]: TypePath::short_type_path
423 pub fn get_with_short_type_path_mut(
424 &mut self,
425 short_type_path: &str,
426 ) -> Option<&mut TypeRegistration> {
427 self.short_path_to_id
428 .get(short_type_path)
429 .and_then(|id| self.registrations.get_mut(id))
430 }
431
432 /// Returns `true` if the given [short type path] is ambiguous, that is, it matches multiple registered types.
433 ///
434 /// # Example
435 /// ```
436 /// # use bevy_reflect::TypeRegistry;
437 /// # mod foo {
438 /// # use bevy_reflect::Reflect;
439 /// # #[derive(Reflect)]
440 /// # pub struct MyType;
441 /// # }
442 /// # mod bar {
443 /// # use bevy_reflect::Reflect;
444 /// # #[derive(Reflect)]
445 /// # pub struct MyType;
446 /// # }
447 /// let mut type_registry = TypeRegistry::default();
448 /// type_registry.register::<foo::MyType>();
449 /// type_registry.register::<bar::MyType>();
450 /// assert_eq!(type_registry.is_ambiguous("MyType"), true);
451 /// ```
452 ///
453 /// [short type path]: TypePath::short_type_path
454 pub fn is_ambiguous(&self, short_type_path: &str) -> bool {
455 self.ambiguous_names.contains(short_type_path)
456 }
457
458 /// Returns a reference to the [`TypeData`] of type `T` associated with the given [`TypeId`].
459 ///
460 /// The returned value may be used to downcast [`Reflect`] trait objects to
461 /// trait objects of the trait used to generate `T`, provided that the
462 /// underlying reflected type has the proper `#[reflect(DoThing)]`
463 /// attribute.
464 ///
465 /// If the specified type has not been registered, or if `T` is not present
466 /// in its type registration, returns `None`.
467 pub fn get_type_data<T: TypeData>(&self, type_id: TypeId) -> Option<&T> {
468 self.get(type_id)
469 .and_then(|registration| registration.data::<T>())
470 }
471
472 /// Returns a mutable reference to the [`TypeData`] of type `T` associated with the given [`TypeId`].
473 ///
474 /// If the specified type has not been registered, or if `T` is not present
475 /// in its type registration, returns `None`.
476 pub fn get_type_data_mut<T: TypeData>(&mut self, type_id: TypeId) -> Option<&mut T> {
477 self.get_mut(type_id)
478 .and_then(|registration| registration.data_mut::<T>())
479 }
480
481 /// Returns the [`TypeInfo`] associated with the given [`TypeId`].
482 ///
483 /// If the specified type has not been registered, returns `None`.
484 pub fn get_type_info(&self, type_id: TypeId) -> Option<&'static TypeInfo> {
485 self.get(type_id).map(TypeRegistration::type_info)
486 }
487
488 /// Returns an iterator over the [`TypeRegistration`]s of the registered
489 /// types.
490 pub fn iter(&self) -> impl Iterator<Item = &TypeRegistration> {
491 self.registrations.values()
492 }
493
494 /// Returns a mutable iterator over the [`TypeRegistration`]s of the registered
495 /// types.
496 pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut TypeRegistration> {
497 self.registrations.values_mut()
498 }
499
500 /// Checks to see if the [`TypeData`] of type `T` is associated with each registered type,
501 /// returning a ([`TypeRegistration`], [`TypeData`]) iterator for all entries where data of that type was found.
502 pub fn iter_with_data<T: TypeData>(&self) -> impl Iterator<Item = (&TypeRegistration, &T)> {
503 self.registrations.values().filter_map(|item| {
504 let type_data = item.data::<T>();
505 type_data.map(|data| (item, data))
506 })
507 }
508}
509
510impl TypeRegistryArc {
511 /// Takes a read lock on the underlying [`TypeRegistry`].
512 pub fn read(&self) -> RwLockReadGuard<'_, TypeRegistry> {
513 self.internal.read().unwrap_or_else(PoisonError::into_inner)
514 }
515
516 /// Takes a write lock on the underlying [`TypeRegistry`].
517 pub fn write(&self) -> RwLockWriteGuard<'_, TypeRegistry> {
518 self.internal
519 .write()
520 .unwrap_or_else(PoisonError::into_inner)
521 }
522}
523
524/// Runtime storage for type metadata, registered into the [`TypeRegistry`].
525///
526/// An instance of `TypeRegistration` can be created using the [`TypeRegistration::of`] method,
527/// but is more often automatically generated using [`#[derive(Reflect)]`](derive@crate::Reflect) which itself generates
528/// an implementation of the [`GetTypeRegistration`] trait.
529///
530/// Along with the type's [`TypeInfo`],
531/// this struct also contains a type's registered [`TypeData`].
532///
533/// See the [crate-level documentation] for more information on type registration.
534///
535/// # Example
536///
537/// ```
538/// # use bevy_reflect::{TypeRegistration, std_traits::ReflectDefault, FromType};
539/// let mut registration = TypeRegistration::of::<Option<String>>();
540///
541/// assert_eq!("core::option::Option<alloc::string::String>", registration.type_info().type_path());
542/// assert_eq!("Option<String>", registration.type_info().type_path_table().short_path());
543///
544/// registration.insert::<ReflectDefault>(FromType::<Option<String>>::from_type());
545/// assert!(registration.data::<ReflectDefault>().is_some())
546/// ```
547///
548/// [crate-level documentation]: crate
549pub struct TypeRegistration {
550 data: TypeIdMap<Box<dyn TypeData>>,
551 type_info: &'static TypeInfo,
552}
553
554impl Debug for TypeRegistration {
555 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
556 f.debug_struct("TypeRegistration")
557 .field("type_info", &self.type_info)
558 .finish()
559 }
560}
561
562impl TypeRegistration {
563 /// Creates type registration information for `T`.
564 pub fn of<T: Reflect + Typed + TypePath>() -> Self {
565 Self {
566 data: Default::default(),
567 type_info: T::type_info(),
568 }
569 }
570
571 /// Returns the [`TypeId`] of the type.
572 #[inline]
573 pub fn type_id(&self) -> TypeId {
574 self.type_info.type_id()
575 }
576
577 /// Returns a reference to the registration's [`TypeInfo`]
578 pub fn type_info(&self) -> &'static TypeInfo {
579 self.type_info
580 }
581
582 /// Inserts an instance of `T` into this registration's [type data].
583 ///
584 /// If another instance of `T` was previously inserted, it is replaced.
585 ///
586 /// [type data]: TypeData
587 pub fn insert<T: TypeData>(&mut self, data: T) {
588 self.data.insert(TypeId::of::<T>(), Box::new(data));
589 }
590
591 /// Inserts the [`TypeData`] instance of `T` created for `V`, and inserts any
592 /// [`TypeData`] dependencies for that combination of `T` and `V`.
593 #[inline]
594 pub fn register_type_data<T: TypeData + FromType<V>, V>(&mut self) {
595 self.insert(T::from_type());
596 T::insert_dependencies(self);
597 }
598
599 /// Returns a reference to the value of type `T` in this registration's
600 /// [type data].
601 ///
602 /// Returns `None` if no such value exists.
603 ///
604 /// For a dynamic version of this method, see [`data_by_id`].
605 ///
606 /// [type data]: TypeData
607 /// [`data_by_id`]: Self::data_by_id
608 pub fn data<T: TypeData>(&self) -> Option<&T> {
609 self.data
610 .get(&TypeId::of::<T>())
611 .and_then(|value| value.downcast_ref())
612 }
613
614 /// Returns a reference to the value with the given [`TypeId`] in this registration's
615 /// [type data].
616 ///
617 /// Returns `None` if no such value exists.
618 ///
619 /// For a static version of this method, see [`data`].
620 ///
621 /// [type data]: TypeData
622 /// [`data`]: Self::data
623 pub fn data_by_id(&self, type_id: TypeId) -> Option<&dyn TypeData> {
624 self.data.get(&type_id).map(Deref::deref)
625 }
626
627 /// Returns a mutable reference to the value of type `T` in this registration's
628 /// [type data].
629 ///
630 /// Returns `None` if no such value exists.
631 ///
632 /// For a dynamic version of this method, see [`data_mut_by_id`].
633 ///
634 /// [type data]: TypeData
635 /// [`data_mut_by_id`]: Self::data_mut_by_id
636 pub fn data_mut<T: TypeData>(&mut self) -> Option<&mut T> {
637 self.data
638 .get_mut(&TypeId::of::<T>())
639 .and_then(|value| value.downcast_mut())
640 }
641
642 /// Returns a mutable reference to the value with the given [`TypeId`] in this registration's
643 /// [type data].
644 ///
645 /// Returns `None` if no such value exists.
646 ///
647 /// For a static version of this method, see [`data_mut`].
648 ///
649 /// [type data]: TypeData
650 /// [`data_mut`]: Self::data_mut
651 pub fn data_mut_by_id(&mut self, type_id: TypeId) -> Option<&mut dyn TypeData> {
652 self.data.get_mut(&type_id).map(DerefMut::deref_mut)
653 }
654
655 /// Returns true if this registration contains the given [type data].
656 ///
657 /// For a dynamic version of this method, see [`contains_by_id`].
658 ///
659 /// [type data]: TypeData
660 /// [`contains_by_id`]: Self::contains_by_id
661 pub fn contains<T: TypeData>(&self) -> bool {
662 self.data.contains_key(&TypeId::of::<T>())
663 }
664
665 /// Returns true if this registration contains the given [type data] with [`TypeId`].
666 ///
667 /// For a static version of this method, see [`contains`].
668 ///
669 /// [type data]: TypeData
670 /// [`contains`]: Self::contains
671 pub fn contains_by_id(&self, type_id: TypeId) -> bool {
672 self.data.contains_key(&type_id)
673 }
674
675 /// The total count of [type data] in this registration.
676 ///
677 /// [type data]: TypeData
678 pub fn len(&self) -> usize {
679 self.data.len()
680 }
681
682 /// Returns true if this registration has no [type data].
683 ///
684 /// [type data]: TypeData
685 pub fn is_empty(&self) -> bool {
686 self.data.is_empty()
687 }
688
689 /// Returns an iterator over all [type data] in this registration.
690 ///
691 /// The iterator yields a tuple of the [`TypeId`] and its corresponding type data.
692 ///
693 /// [type data]: TypeData
694 pub fn iter(&self) -> impl ExactSizeIterator<Item = (TypeId, &dyn TypeData)> {
695 self.data.iter().map(|(id, data)| (*id, data.deref()))
696 }
697
698 /// Returns a mutable iterator over all [type data] in this registration.
699 ///
700 /// The iterator yields a tuple of the [`TypeId`] and its corresponding type data.
701 ///
702 /// [type data]: TypeData
703 pub fn iter_mut(&mut self) -> impl ExactSizeIterator<Item = (TypeId, &mut dyn TypeData)> {
704 self.data
705 .iter_mut()
706 .map(|(id, data)| (*id, data.deref_mut()))
707 }
708}
709
710impl Clone for TypeRegistration {
711 fn clone(&self) -> Self {
712 let mut data = TypeIdMap::default();
713 for (id, type_data) in &self.data {
714 data.insert(*id, (*type_data).clone_type_data());
715 }
716
717 TypeRegistration {
718 data,
719 type_info: self.type_info,
720 }
721 }
722}
723
724/// A trait used to type-erase type metadata.
725///
726/// Type data can be registered to the [`TypeRegistry`] and stored on a type's [`TypeRegistration`].
727///
728/// While type data is often generated using the [`#[reflect_trait]`](crate::reflect_trait) macro,
729/// almost any type that implements [`Clone`] can be considered "type data".
730/// This is because it has a blanket implementation over all `T` where `T: Clone + Send + Sync + 'static`.
731///
732/// See the [crate-level documentation] for more information on type data and type registration.
733///
734/// [crate-level documentation]: crate
735pub trait TypeData: Downcast + Send + Sync {
736 /// Creates a type-erased clone of this value.
737 fn clone_type_data(&self) -> Box<dyn TypeData>;
738}
739
740impl_downcast!(TypeData);
741
742impl<T: 'static + Send + Sync> TypeData for T
743where
744 T: Clone,
745{
746 fn clone_type_data(&self) -> Box<dyn TypeData> {
747 Box::new(self.clone())
748 }
749}
750
751/// Trait used to generate [`TypeData`] for trait reflection.
752///
753/// This is used by the `#[derive(Reflect)]` macro to generate an implementation
754/// of [`TypeData`] to pass to [`TypeRegistration::insert`].
755pub trait FromType<T> {
756 /// Creates an instance of `Self` for type `T`.
757 fn from_type() -> Self;
758 /// Inserts [`TypeData`] dependencies of this [`TypeData`].
759 /// This is especially useful for trait [`TypeData`] that has a supertrait (ex: `A: B`).
760 /// When the [`TypeData`] for `A` is inserted, the `B` [`TypeData`] will also be inserted.
761 fn insert_dependencies(_type_registration: &mut TypeRegistration) {}
762}
763
764/// A struct used to serialize reflected instances of a type.
765///
766/// A `ReflectSerialize` for type `T` can be obtained via
767/// [`FromType::from_type`].
768#[derive(Clone)]
769pub struct ReflectSerialize {
770 get_serializable: fn(value: &dyn Reflect) -> Serializable,
771}
772
773impl<T: TypePath + FromReflect + erased_serde::Serialize> FromType<T> for ReflectSerialize {
774 fn from_type() -> Self {
775 ReflectSerialize {
776 get_serializable: |value| {
777 value
778 .downcast_ref::<T>()
779 .map(|value| Serializable::Borrowed(value))
780 .or_else(|| T::from_reflect(value.as_partial_reflect()).map(|value| Serializable::Owned(Box::new(value))))
781 .unwrap_or_else(|| {
782 panic!(
783 "FromReflect::from_reflect failed when called on type `{}` with this value: {value:?}",
784 T::type_path(),
785 );
786 })
787 },
788 }
789 }
790}
791
792impl ReflectSerialize {
793 /// Turn the value into a serializable representation
794 pub fn get_serializable<'a>(&self, value: &'a dyn Reflect) -> Serializable<'a> {
795 (self.get_serializable)(value)
796 }
797
798 /// Serializes a reflected value.
799 pub fn serialize<S>(&self, value: &dyn Reflect, serializer: S) -> Result<S::Ok, S::Error>
800 where
801 S: serde::Serializer,
802 {
803 (self.get_serializable)(value).serialize(serializer)
804 }
805}
806
807/// A struct used to deserialize reflected instances of a type.
808///
809/// A `ReflectDeserialize` for type `T` can be obtained via
810/// [`FromType::from_type`].
811#[derive(Clone)]
812pub struct ReflectDeserialize {
813 /// Function used by [`ReflectDeserialize::deserialize`] to
814 /// perform deserialization.
815 pub func: fn(
816 deserializer: &mut dyn erased_serde::Deserializer,
817 ) -> Result<Box<dyn Reflect>, erased_serde::Error>,
818}
819
820impl ReflectDeserialize {
821 /// Deserializes a reflected value.
822 ///
823 /// The underlying type of the reflected value, and thus the expected
824 /// structure of the serialized data, is determined by the type used to
825 /// construct this `ReflectDeserialize` value.
826 pub fn deserialize<'de, D>(&self, deserializer: D) -> Result<Box<dyn Reflect>, D::Error>
827 where
828 D: serde::Deserializer<'de>,
829 {
830 let mut erased = <dyn erased_serde::Deserializer>::erase(deserializer);
831 (self.func)(&mut erased)
832 .map_err(<<D as serde::Deserializer<'de>>::Error as serde::de::Error>::custom)
833 }
834}
835
836impl<T: for<'a> Deserialize<'a> + Reflect> FromType<T> for ReflectDeserialize {
837 fn from_type() -> Self {
838 ReflectDeserialize {
839 func: |deserializer| Ok(Box::new(T::deserialize(deserializer)?)),
840 }
841 }
842}
843
844/// [`Reflect`] values are commonly used in situations where the actual types of values
845/// are not known at runtime. In such situations you might have access to a `*const ()` pointer
846/// that you know implements [`Reflect`], but have no way of turning it into a `&dyn Reflect`.
847///
848/// This is where [`ReflectFromPtr`] comes in, when creating a [`ReflectFromPtr`] for a given type `T: Reflect`.
849/// Internally, this saves a concrete function `*const T -> const dyn Reflect` which lets you create a trait object of [`Reflect`]
850/// from a pointer.
851///
852/// # Example
853/// ```
854/// use bevy_reflect::{TypeRegistry, Reflect, ReflectFromPtr};
855/// use bevy_ptr::Ptr;
856/// use core::ptr::NonNull;
857///
858/// #[derive(Reflect)]
859/// struct Reflected(String);
860///
861/// let mut type_registry = TypeRegistry::default();
862/// type_registry.register::<Reflected>();
863///
864/// let mut value = Reflected("Hello world!".to_string());
865/// let value = Ptr::from(&value);
866///
867/// let reflect_data = type_registry.get(core::any::TypeId::of::<Reflected>()).unwrap();
868/// let reflect_from_ptr = reflect_data.data::<ReflectFromPtr>().unwrap();
869/// // SAFE: `value` is of type `Reflected`, which the `ReflectFromPtr` was created for
870/// let value = unsafe { reflect_from_ptr.as_reflect(value) };
871///
872/// assert_eq!(value.downcast_ref::<Reflected>().unwrap().0, "Hello world!");
873/// ```
874#[derive(Clone)]
875pub struct ReflectFromPtr {
876 type_id: TypeId,
877 from_ptr: unsafe fn(Ptr) -> &dyn Reflect,
878 from_ptr_mut: unsafe fn(PtrMut) -> &mut dyn Reflect,
879}
880
881#[expect(
882 unsafe_code,
883 reason = "We must interact with pointers here, which are inherently unsafe."
884)]
885impl ReflectFromPtr {
886 /// Returns the [`TypeId`] that the [`ReflectFromPtr`] was constructed for.
887 pub fn type_id(&self) -> TypeId {
888 self.type_id
889 }
890
891 /// Convert `Ptr` into `&dyn Reflect`.
892 ///
893 /// # Safety
894 ///
895 /// `val` must be a pointer to value of the type that the [`ReflectFromPtr`] was constructed for.
896 /// This can be verified by checking that the type id returned by [`ReflectFromPtr::type_id`] is the expected one.
897 pub unsafe fn as_reflect<'a>(&self, val: Ptr<'a>) -> &'a dyn Reflect {
898 // SAFETY: contract uphold by the caller.
899 unsafe { (self.from_ptr)(val) }
900 }
901
902 /// Convert `PtrMut` into `&mut dyn Reflect`.
903 ///
904 /// # Safety
905 ///
906 /// `val` must be a pointer to a value of the type that the [`ReflectFromPtr`] was constructed for
907 /// This can be verified by checking that the type id returned by [`ReflectFromPtr::type_id`] is the expected one.
908 pub unsafe fn as_reflect_mut<'a>(&self, val: PtrMut<'a>) -> &'a mut dyn Reflect {
909 // SAFETY: contract uphold by the caller.
910 unsafe { (self.from_ptr_mut)(val) }
911 }
912 /// Get a function pointer to turn a `Ptr` into `&dyn Reflect` for
913 /// the type this [`ReflectFromPtr`] was constructed for.
914 ///
915 /// # Safety
916 ///
917 /// When calling the unsafe function returned by this method you must ensure that:
918 /// - The input `Ptr` points to the `Reflect` type this `ReflectFromPtr`
919 /// was constructed for.
920 pub fn from_ptr(&self) -> unsafe fn(Ptr) -> &dyn Reflect {
921 self.from_ptr
922 }
923 /// Get a function pointer to turn a `PtrMut` into `&mut dyn Reflect` for
924 /// the type this [`ReflectFromPtr`] was constructed for.
925 ///
926 /// # Safety
927 ///
928 /// When calling the unsafe function returned by this method you must ensure that:
929 /// - The input `PtrMut` points to the `Reflect` type this `ReflectFromPtr`
930 /// was constructed for.
931 pub fn from_ptr_mut(&self) -> unsafe fn(PtrMut) -> &mut dyn Reflect {
932 self.from_ptr_mut
933 }
934}
935
936#[expect(
937 unsafe_code,
938 reason = "We must interact with pointers here, which are inherently unsafe."
939)]
940impl<T: Reflect> FromType<T> for ReflectFromPtr {
941 fn from_type() -> Self {
942 ReflectFromPtr {
943 type_id: TypeId::of::<T>(),
944 from_ptr: |ptr| {
945 // SAFETY: `from_ptr_mut` is either called in `ReflectFromPtr::as_reflect`
946 // or returned by `ReflectFromPtr::from_ptr`, both lay out the invariants
947 // required by `deref`
948 unsafe { ptr.deref::<T>() as &dyn Reflect }
949 },
950 from_ptr_mut: |ptr| {
951 // SAFETY: same as above, but for `as_reflect_mut`, `from_ptr_mut` and `deref_mut`.
952 unsafe { ptr.deref_mut::<T>() as &mut dyn Reflect }
953 },
954 }
955 }
956}
957
958#[cfg(test)]
959#[expect(
960 unsafe_code,
961 reason = "We must interact with pointers here, which are inherently unsafe."
962)]
963mod test {
964 use super::*;
965
966 #[test]
967 fn test_reflect_from_ptr() {
968 #[derive(Reflect)]
969 struct Foo {
970 a: f32,
971 }
972
973 let foo_registration = <Foo as GetTypeRegistration>::get_type_registration();
974 let reflect_from_ptr = foo_registration.data::<ReflectFromPtr>().unwrap();
975
976 // not required in this situation because we no nobody messed with the TypeRegistry,
977 // but in the general case somebody could have replaced the ReflectFromPtr with an
978 // instance for another type, so then we'd need to check that the type is the expected one
979 assert_eq!(reflect_from_ptr.type_id(), TypeId::of::<Foo>());
980
981 let mut value = Foo { a: 1.0 };
982 {
983 let value = PtrMut::from(&mut value);
984 // SAFETY: reflect_from_ptr was constructed for the correct type
985 let dyn_reflect = unsafe { reflect_from_ptr.as_reflect_mut(value) };
986 match dyn_reflect.reflect_mut() {
987 bevy_reflect::ReflectMut::Struct(strukt) => {
988 strukt.field_mut("a").unwrap().apply(&2.0f32);
989 }
990 _ => panic!("invalid reflection"),
991 }
992 }
993
994 {
995 // SAFETY: reflect_from_ptr was constructed for the correct type
996 let dyn_reflect = unsafe { reflect_from_ptr.as_reflect(Ptr::from(&value)) };
997 match dyn_reflect.reflect_ref() {
998 bevy_reflect::ReflectRef::Struct(strukt) => {
999 let a = strukt
1000 .field("a")
1001 .unwrap()
1002 .try_downcast_ref::<f32>()
1003 .unwrap();
1004 assert_eq!(*a, 2.0);
1005 }
1006 _ => panic!("invalid reflection"),
1007 }
1008 }
1009 }
1010
1011 #[test]
1012 fn type_data_iter() {
1013 #[derive(Reflect)]
1014 struct Foo;
1015
1016 #[derive(Clone)]
1017 struct DataA(i32);
1018
1019 let mut registration = TypeRegistration::of::<Foo>();
1020 registration.insert(DataA(123));
1021
1022 let mut iter = registration.iter();
1023
1024 let (id, data) = iter.next().unwrap();
1025 assert_eq!(id, TypeId::of::<DataA>());
1026 assert_eq!(data.downcast_ref::<DataA>().unwrap().0, 123);
1027
1028 assert!(iter.next().is_none());
1029 }
1030
1031 #[test]
1032 fn type_data_iter_mut() {
1033 #[derive(Reflect)]
1034 struct Foo;
1035
1036 #[derive(Clone)]
1037 struct DataA(i32);
1038
1039 let mut registration = TypeRegistration::of::<Foo>();
1040 registration.insert(DataA(123));
1041
1042 {
1043 let mut iter = registration.iter_mut();
1044
1045 let (_, data) = iter.next().unwrap();
1046 data.downcast_mut::<DataA>().unwrap().0 = 456;
1047
1048 assert!(iter.next().is_none());
1049 }
1050
1051 let data = registration.data::<DataA>().unwrap();
1052 assert_eq!(data.0, 456);
1053 }
1054}