1use alloc::{format, vec::Vec};
2use bevy_platform::{hash::FixedHasher, sync::Arc};
3use bevy_ptr::OwningPtr;
4use core::fmt::Debug;
5use indexmap::{IndexMap, IndexSet};
6use thiserror::Error;
7
8use crate::{
9 bundle::BundleInfo,
10 change_detection::MaybeLocation,
11 component::{Component, ComponentId, Components, ComponentsRegistrator, Tick},
12 entity::Entity,
13 query::DebugCheckedUnwrap as _,
14 storage::{SparseSets, Table, TableRow},
15};
16
17#[derive(Clone)]
19pub struct RequiredComponent {
20 pub constructor: RequiredComponentConstructor,
22}
23
24#[derive(Clone)]
26pub struct RequiredComponentConstructor(
27 Arc<dyn Fn(&mut Table, &mut SparseSets, Tick, TableRow, Entity, MaybeLocation)>,
29);
30
31impl RequiredComponentConstructor {
32 pub unsafe fn new<C: Component>(component_id: ComponentId, constructor: fn() -> C) -> Self {
38 RequiredComponentConstructor({
39 #[cfg(not(target_has_atomic = "ptr"))]
46 use alloc::boxed::Box;
47
48 type Constructor = dyn for<'a, 'b> Fn(
49 &'a mut Table,
50 &'b mut SparseSets,
51 Tick,
52 TableRow,
53 Entity,
54 MaybeLocation,
55 );
56
57 #[cfg(not(target_has_atomic = "ptr"))]
58 type Intermediate<T> = Box<T>;
59
60 #[cfg(target_has_atomic = "ptr")]
61 type Intermediate<T> = Arc<T>;
62
63 let boxed: Intermediate<Constructor> = Intermediate::new(
64 move |table, sparse_sets, change_tick, table_row, entity, caller| {
65 OwningPtr::make(constructor(), |ptr| {
66 unsafe {
71 BundleInfo::initialize_required_component(
72 table,
73 sparse_sets,
74 change_tick,
75 table_row,
76 entity,
77 component_id,
78 C::STORAGE_TYPE,
79 ptr,
80 caller,
81 );
82 }
83 });
84 },
85 );
86
87 Arc::from(boxed)
88 })
89 }
90
91 pub(crate) unsafe fn initialize(
101 &self,
102 table: &mut Table,
103 sparse_sets: &mut SparseSets,
104 change_tick: Tick,
105 table_row: TableRow,
106 entity: Entity,
107 caller: MaybeLocation,
108 ) {
109 (self.0)(table, sparse_sets, change_tick, table_row, entity, caller);
110 }
111}
112
113#[derive(Default, Clone)]
117pub struct RequiredComponents {
118 pub(crate) direct: IndexMap<ComponentId, RequiredComponent, FixedHasher>,
123 pub(crate) all: IndexMap<ComponentId, RequiredComponent, FixedHasher>,
132}
133
134impl Debug for RequiredComponents {
135 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
136 f.debug_struct("RequiredComponents")
137 .field("direct", &self.direct.keys())
138 .field("all", &self.all.keys())
139 .finish()
140 }
141}
142
143impl RequiredComponents {
144 unsafe fn register<C: Component>(
153 &mut self,
154 components: &mut ComponentsRegistrator<'_>,
155 constructor: fn() -> C,
156 ) {
157 let id = components.register_component::<C>();
158 unsafe { self.register_by_id::<C>(id, components, constructor) };
162 }
163
164 unsafe fn register_by_id<C: Component>(
174 &mut self,
175 component_id: ComponentId,
176 components: &Components,
177 constructor: fn() -> C,
178 ) {
179 let constructor =
181 || unsafe { RequiredComponentConstructor::new(component_id, constructor) };
182
183 unsafe { self.register_dynamic_with(component_id, components, constructor) };
188 }
189
190 unsafe fn register_dynamic_with(
202 &mut self,
203 component_id: ComponentId,
204 components: &Components,
205 constructor: impl FnOnce() -> RequiredComponentConstructor,
206 ) {
207 let entry = match self.direct.entry(component_id) {
209 indexmap::map::Entry::Vacant(entry) => entry,
210 indexmap::map::Entry::Occupied(_) =>
211 panic!("Error while registering required component {component_id:?}: already directly required"),
212 };
213
214 let constructor = constructor();
216 let required_component = RequiredComponent { constructor };
217 entry.insert(required_component.clone());
218
219 unsafe {
224 Self::register_inherited_required_components_unchecked(
225 &mut self.all,
226 component_id,
227 required_component,
228 components,
229 );
230 }
231 }
232
233 unsafe fn rebuild_inherited_required_components(&mut self, components: &Components) {
239 self.all.clear();
241
242 for (&required_id, required_component) in &self.direct {
244 unsafe {
249 Self::register_inherited_required_components_unchecked(
250 &mut self.all,
251 required_id,
252 required_component.clone(),
253 components,
254 );
255 }
256 }
257 }
258
259 unsafe fn register_inherited_required_components_unchecked(
267 all: &mut IndexMap<ComponentId, RequiredComponent, FixedHasher>,
268 required_id: ComponentId,
269 required_component: RequiredComponent,
270 components: &Components,
271 ) {
272 let info = unsafe { components.get_info(required_id).debug_checked_unwrap() };
274
275 if !all.contains_key(&required_id) {
280 for (&inherited_id, inherited_required) in &info.required_components().all {
281 all.entry(inherited_id)
289 .or_insert_with(|| inherited_required.clone());
290 }
291 }
292
293 all.insert(required_id, required_component);
301 }
302
303 pub fn iter_ids(&self) -> impl Iterator<Item = ComponentId> + '_ {
305 self.all.keys().copied()
306 }
307}
308
309impl Components {
310 pub(crate) unsafe fn register_required_by(
318 &mut self,
319 requiree: ComponentId,
320 required_components: &RequiredComponents,
321 ) {
322 for &required in required_components.all.keys() {
323 let required_by = unsafe { self.get_required_by_mut(required).debug_checked_unwrap() };
325 required_by.insert(requiree);
330 }
331 }
332
333 pub(crate) unsafe fn register_required_components<R: Component>(
354 &mut self,
355 requiree: ComponentId,
356 required: ComponentId,
357 constructor: fn() -> R,
358 ) -> Result<(), RequiredComponentsError> {
359 let required_required_components = unsafe {
363 self.get_required_components(required)
364 .debug_checked_unwrap()
365 };
366
367 if required_required_components.all.contains_key(&requiree) {
369 return Err(RequiredComponentsError::CyclicRequirement(
370 requiree, required,
371 ));
372 }
373
374 let required_components = unsafe {
376 self.get_required_components_mut(requiree)
377 .debug_checked_unwrap()
378 };
379
380 if required_components.direct.contains_key(&required) {
382 return Err(RequiredComponentsError::DuplicateRegistration(
383 requiree, required,
384 ));
385 }
386
387 let old_required_count = required_components.all.len();
391
392 self.required_components_scope(requiree, |this, required_components| {
394 unsafe { required_components.register_by_id(required, this, constructor) };
396 });
397
398 let required_components = unsafe {
403 self.get_required_components_mut(requiree)
404 .debug_checked_unwrap()
405 };
406
407 let new_required_components = required_components.all[old_required_count..]
413 .keys()
414 .copied()
415 .collect::<Vec<_>>();
416
417 let requiree_required_by = unsafe { self.get_required_by(requiree).debug_checked_unwrap() };
420 let new_requiree_components = [requiree]
421 .into_iter()
422 .chain(requiree_required_by.iter().copied())
423 .collect::<IndexSet<_, FixedHasher>>();
424
425 for &indirect_requiree in &new_requiree_components[1..] {
437 self.required_components_scope(indirect_requiree, |this, required_components| {
439 unsafe { required_components.rebuild_inherited_required_components(this) };
442 });
443 }
444
445 for &indirect_required in &new_required_components {
447 let required_by = unsafe {
449 self.get_required_by_mut(indirect_required)
450 .debug_checked_unwrap()
451 };
452
453 required_by.retain(|id| !new_requiree_components.contains(id));
459 required_by.extend(&new_requiree_components);
460 }
461
462 Ok(())
463 }
464
465 unsafe fn required_components_scope<R>(
472 &mut self,
473 component_id: ComponentId,
474 f: impl FnOnce(&mut Self, &mut RequiredComponents) -> R,
475 ) -> R {
476 struct DropGuard<'a> {
477 components: &'a mut Components,
478 component_id: ComponentId,
479 required_components: RequiredComponents,
480 }
481
482 impl Drop for DropGuard<'_> {
483 fn drop(&mut self) {
484 let required_components = unsafe {
486 self.components
487 .get_required_components_mut(self.component_id)
488 .debug_checked_unwrap()
489 };
490
491 debug_assert!(required_components.direct.is_empty());
492 debug_assert!(required_components.all.is_empty());
493
494 *required_components = core::mem::take(&mut self.required_components);
495 }
496 }
497
498 let mut guard = DropGuard {
499 component_id,
500 required_components: core::mem::take(unsafe {
502 self.get_required_components_mut(component_id)
503 .debug_checked_unwrap()
504 }),
505 components: self,
506 };
507
508 f(guard.components, &mut guard.required_components)
509 }
510}
511
512#[derive(Error, Debug)]
514#[non_exhaustive]
515pub enum RequiredComponentsError {
516 #[error("Component {0:?} already directly requires component {1:?}")]
518 DuplicateRegistration(ComponentId, ComponentId),
519 #[error("Cyclic requirement found: the requiree component {0:?} is required by the required component {1:?}")]
521 CyclicRequirement(ComponentId, ComponentId),
522 #[error("An archetype with the component {0:?} that requires other components already exists")]
524 ArchetypeExists(ComponentId),
525}
526
527pub(super) fn enforce_no_required_components_recursion(
528 components: &Components,
529 recursion_check_stack: &[ComponentId],
530 required: ComponentId,
531) {
532 if let Some(direct_recursion) = recursion_check_stack
533 .iter()
534 .position(|&id| id == required)
535 .map(|index| index == recursion_check_stack.len() - 1)
536 {
537 panic!(
538 "Recursive required components detected: {}\nhelp: {}",
539 recursion_check_stack
540 .iter()
541 .map(|id| format!("{}", components.get_name(*id).unwrap().shortname()))
542 .collect::<Vec<_>>()
543 .join(" → "),
544 if direct_recursion {
545 format!(
546 "Remove require({}).",
547 components.get_name(required).unwrap().shortname()
548 )
549 } else {
550 "If this is intentional, consider merging the components.".into()
551 }
552 );
553 }
554}
555
556pub struct RequiredComponentsRegistrator<'a, 'w> {
558 components: &'a mut ComponentsRegistrator<'w>,
559 required_components: &'a mut RequiredComponents,
560}
561
562impl<'a, 'w> RequiredComponentsRegistrator<'a, 'w> {
563 pub(super) unsafe fn new(
567 components: &'a mut ComponentsRegistrator<'w>,
568 required_components: &'a mut RequiredComponents,
569 ) -> Self {
570 Self {
571 components,
572 required_components,
573 }
574 }
575
576 pub fn register_required<C: Component>(&mut self, constructor: fn() -> C) {
581 unsafe {
584 self.required_components
585 .register(self.components, constructor);
586 }
587 }
588
589 pub unsafe fn register_required_by_id<C: Component>(
598 &mut self,
599 component_id: ComponentId,
600 constructor: fn() -> C,
601 ) {
602 unsafe {
606 self.required_components.register_by_id::<C>(
607 component_id,
608 self.components,
609 constructor,
610 );
611 }
612 }
613
614 pub unsafe fn register_required_dynamic_with(
625 &mut self,
626 component_id: ComponentId,
627 constructor: impl FnOnce() -> RequiredComponentConstructor,
628 ) {
629 unsafe {
634 self.required_components.register_dynamic_with(
635 component_id,
636 self.components,
637 constructor,
638 );
639 }
640 }
641}
642
643#[cfg(test)]
644mod tests {
645 use alloc::string::{String, ToString};
646
647 use crate::{
648 bundle::Bundle,
649 component::{Component, RequiredComponentsError},
650 prelude::Resource,
651 world::World,
652 };
653
654 #[test]
655 fn required_components() {
656 #[derive(Component)]
657 #[require(Y)]
658 struct X;
659
660 #[derive(Component)]
661 #[require(Z = new_z())]
662 struct Y {
663 value: String,
664 }
665
666 #[derive(Component)]
667 struct Z(u32);
668
669 impl Default for Y {
670 fn default() -> Self {
671 Self {
672 value: "hello".to_string(),
673 }
674 }
675 }
676
677 fn new_z() -> Z {
678 Z(7)
679 }
680
681 let mut world = World::new();
682 let id = world.spawn(X).id();
683 assert_eq!(
684 "hello",
685 world.entity(id).get::<Y>().unwrap().value,
686 "Y should have the default value"
687 );
688 assert_eq!(
689 7,
690 world.entity(id).get::<Z>().unwrap().0,
691 "Z should have the value provided by the constructor defined in Y"
692 );
693
694 let id = world
695 .spawn((
696 X,
697 Y {
698 value: "foo".to_string(),
699 },
700 ))
701 .id();
702 assert_eq!(
703 "foo",
704 world.entity(id).get::<Y>().unwrap().value,
705 "Y should have the manually provided value"
706 );
707 assert_eq!(
708 7,
709 world.entity(id).get::<Z>().unwrap().0,
710 "Z should have the value provided by the constructor defined in Y"
711 );
712
713 let id = world.spawn((X, Z(8))).id();
714 assert_eq!(
715 "hello",
716 world.entity(id).get::<Y>().unwrap().value,
717 "Y should have the default value"
718 );
719 assert_eq!(
720 8,
721 world.entity(id).get::<Z>().unwrap().0,
722 "Z should have the manually provided value"
723 );
724 }
725
726 #[test]
727 fn generic_required_components() {
728 #[derive(Component)]
729 #[require(Y<usize>)]
730 struct X;
731
732 #[derive(Component, Default)]
733 struct Y<T> {
734 value: T,
735 }
736
737 let mut world = World::new();
738 let id = world.spawn(X).id();
739 assert_eq!(
740 0,
741 world.entity(id).get::<Y<usize>>().unwrap().value,
742 "Y should have the default value"
743 );
744 }
745
746 #[test]
747 fn required_components_spawn_nonexistent_hooks() {
748 #[derive(Component)]
749 #[require(Y)]
750 struct X;
751
752 #[derive(Component, Default)]
753 struct Y;
754
755 #[derive(Resource)]
756 struct A(usize);
757
758 #[derive(Resource)]
759 struct I(usize);
760
761 let mut world = World::new();
762 world.insert_resource(A(0));
763 world.insert_resource(I(0));
764 world
765 .register_component_hooks::<Y>()
766 .on_add(|mut world, _| world.resource_mut::<A>().0 += 1)
767 .on_insert(|mut world, _| world.resource_mut::<I>().0 += 1);
768
769 assert!(world.spawn(X).contains::<Y>());
771
772 assert_eq!(world.resource::<A>().0, 1);
773 assert_eq!(world.resource::<I>().0, 1);
774 }
775
776 #[test]
777 fn required_components_insert_existing_hooks() {
778 #[derive(Component)]
779 #[require(Y)]
780 struct X;
781
782 #[derive(Component, Default)]
783 struct Y;
784
785 #[derive(Resource)]
786 struct A(usize);
787
788 #[derive(Resource)]
789 struct I(usize);
790
791 let mut world = World::new();
792 world.insert_resource(A(0));
793 world.insert_resource(I(0));
794 world
795 .register_component_hooks::<Y>()
796 .on_add(|mut world, _| world.resource_mut::<A>().0 += 1)
797 .on_insert(|mut world, _| world.resource_mut::<I>().0 += 1);
798
799 assert!(world.spawn_empty().insert(X).contains::<Y>());
801
802 assert_eq!(world.resource::<A>().0, 1);
803 assert_eq!(world.resource::<I>().0, 1);
804 }
805
806 #[test]
807 fn required_components_take_leaves_required() {
808 #[derive(Component)]
809 #[require(Y)]
810 struct X;
811
812 #[derive(Component, Default)]
813 struct Y;
814
815 let mut world = World::new();
816 let e = world.spawn(X).id();
817 let _ = world.entity_mut(e).take::<X>().unwrap();
818 assert!(world.entity_mut(e).contains::<Y>());
819 }
820
821 #[test]
822 fn required_components_retain_keeps_required() {
823 #[derive(Component)]
824 #[require(Y)]
825 struct X;
826
827 #[derive(Component, Default)]
828 struct Y;
829
830 #[derive(Component, Default)]
831 struct Z;
832
833 let mut world = World::new();
834 let e = world.spawn((X, Z)).id();
835 world.entity_mut(e).retain::<X>();
836 assert!(world.entity_mut(e).contains::<X>());
837 assert!(world.entity_mut(e).contains::<Y>());
838 assert!(!world.entity_mut(e).contains::<Z>());
839 }
840
841 #[test]
842 fn required_components_spawn_then_insert_no_overwrite() {
843 #[derive(Component)]
844 #[require(Y)]
845 struct X;
846
847 #[derive(Component, Default)]
848 struct Y(usize);
849
850 let mut world = World::new();
851 let id = world.spawn((X, Y(10))).id();
852 world.entity_mut(id).insert(X);
853
854 assert_eq!(
855 10,
856 world.entity(id).get::<Y>().unwrap().0,
857 "Y should still have the manually provided value"
858 );
859 }
860
861 #[test]
862 fn dynamic_required_components() {
863 #[derive(Component)]
864 #[require(Y)]
865 struct X;
866
867 #[derive(Component, Default)]
868 struct Y;
869
870 let mut world = World::new();
871 let x_id = world.register_component::<X>();
872
873 let mut e = world.spawn_empty();
874
875 bevy_ptr::OwningPtr::make(X, |ptr| unsafe {
877 e.insert_by_id(x_id, ptr);
878 });
879
880 assert!(e.contains::<Y>());
881 }
882
883 #[test]
884 fn remove_component_and_its_runtime_required_components() {
885 #[derive(Component)]
886 struct X;
887
888 #[derive(Component, Default)]
889 struct Y;
890
891 #[derive(Component, Default)]
892 struct Z;
893
894 #[derive(Component)]
895 struct V;
896
897 let mut world = World::new();
898 world.register_required_components::<X, Y>();
899 world.register_required_components::<Y, Z>();
900
901 let e = world.spawn((X, V)).id();
902 assert!(world.entity(e).contains::<X>());
903 assert!(world.entity(e).contains::<Y>());
904 assert!(world.entity(e).contains::<Z>());
905 assert!(world.entity(e).contains::<V>());
906
907 world.entity_mut(e).remove::<X>();
909 assert!(!world.entity(e).contains::<X>());
910 assert!(world.entity(e).contains::<Y>());
911 assert!(world.entity(e).contains::<Z>());
912 assert!(world.entity(e).contains::<V>());
913
914 world.entity_mut(e).insert(X);
915 assert!(world.entity(e).contains::<X>());
916 assert!(world.entity(e).contains::<Y>());
917 assert!(world.entity(e).contains::<Z>());
918 assert!(world.entity(e).contains::<V>());
919
920 world.entity_mut(e).remove_with_requires::<X>();
922 assert!(!world.entity(e).contains::<X>());
923 assert!(!world.entity(e).contains::<Y>());
924 assert!(!world.entity(e).contains::<Z>());
925 assert!(world.entity(e).contains::<V>());
926 }
927
928 #[test]
929 fn remove_component_and_its_required_components() {
930 #[derive(Component)]
931 #[require(Y)]
932 struct X;
933
934 #[derive(Component, Default)]
935 #[require(Z)]
936 struct Y;
937
938 #[derive(Component, Default)]
939 struct Z;
940
941 #[derive(Component)]
942 struct V;
943
944 let mut world = World::new();
945
946 let e = world.spawn((X, V)).id();
947 assert!(world.entity(e).contains::<X>());
948 assert!(world.entity(e).contains::<Y>());
949 assert!(world.entity(e).contains::<Z>());
950 assert!(world.entity(e).contains::<V>());
951
952 world.entity_mut(e).remove::<X>();
954 assert!(!world.entity(e).contains::<X>());
955 assert!(world.entity(e).contains::<Y>());
956 assert!(world.entity(e).contains::<Z>());
957 assert!(world.entity(e).contains::<V>());
958
959 world.entity_mut(e).insert(X);
960 assert!(world.entity(e).contains::<X>());
961 assert!(world.entity(e).contains::<Y>());
962 assert!(world.entity(e).contains::<Z>());
963 assert!(world.entity(e).contains::<V>());
964
965 world.entity_mut(e).remove_with_requires::<X>();
967 assert!(!world.entity(e).contains::<X>());
968 assert!(!world.entity(e).contains::<Y>());
969 assert!(!world.entity(e).contains::<Z>());
970 assert!(world.entity(e).contains::<V>());
971 }
972
973 #[test]
974 fn remove_bundle_and_his_required_components() {
975 #[derive(Component, Default)]
976 #[require(Y)]
977 struct X;
978
979 #[derive(Component, Default)]
980 struct Y;
981
982 #[derive(Component, Default)]
983 #[require(W)]
984 struct Z;
985
986 #[derive(Component, Default)]
987 struct W;
988
989 #[derive(Component)]
990 struct V;
991
992 #[derive(Bundle, Default)]
993 struct TestBundle {
994 x: X,
995 z: Z,
996 }
997
998 let mut world = World::new();
999 let e = world.spawn((TestBundle::default(), V)).id();
1000
1001 assert!(world.entity(e).contains::<X>());
1002 assert!(world.entity(e).contains::<Y>());
1003 assert!(world.entity(e).contains::<Z>());
1004 assert!(world.entity(e).contains::<W>());
1005 assert!(world.entity(e).contains::<V>());
1006
1007 world.entity_mut(e).remove_with_requires::<TestBundle>();
1008 assert!(!world.entity(e).contains::<X>());
1009 assert!(!world.entity(e).contains::<Y>());
1010 assert!(!world.entity(e).contains::<Z>());
1011 assert!(!world.entity(e).contains::<W>());
1012 assert!(world.entity(e).contains::<V>());
1013 }
1014
1015 #[test]
1016 fn runtime_required_components() {
1017 #[derive(Component)]
1020 struct X;
1021
1022 #[derive(Component)]
1023 struct Y {
1024 value: String,
1025 }
1026
1027 #[derive(Component)]
1028 struct Z(u32);
1029
1030 impl Default for Y {
1031 fn default() -> Self {
1032 Self {
1033 value: "hello".to_string(),
1034 }
1035 }
1036 }
1037
1038 let mut world = World::new();
1039
1040 world.register_required_components::<X, Y>();
1041 world.register_required_components_with::<Y, Z>(|| Z(7));
1042
1043 let id = world.spawn(X).id();
1044
1045 assert_eq!(
1046 "hello",
1047 world.entity(id).get::<Y>().unwrap().value,
1048 "Y should have the default value"
1049 );
1050 assert_eq!(
1051 7,
1052 world.entity(id).get::<Z>().unwrap().0,
1053 "Z should have the value provided by the constructor defined in Y"
1054 );
1055
1056 let id = world
1057 .spawn((
1058 X,
1059 Y {
1060 value: "foo".to_string(),
1061 },
1062 ))
1063 .id();
1064 assert_eq!(
1065 "foo",
1066 world.entity(id).get::<Y>().unwrap().value,
1067 "Y should have the manually provided value"
1068 );
1069 assert_eq!(
1070 7,
1071 world.entity(id).get::<Z>().unwrap().0,
1072 "Z should have the value provided by the constructor defined in Y"
1073 );
1074
1075 let id = world.spawn((X, Z(8))).id();
1076 assert_eq!(
1077 "hello",
1078 world.entity(id).get::<Y>().unwrap().value,
1079 "Y should have the default value"
1080 );
1081 assert_eq!(
1082 8,
1083 world.entity(id).get::<Z>().unwrap().0,
1084 "Z should have the manually provided value"
1085 );
1086 }
1087
1088 #[test]
1089 fn runtime_required_components_override_1() {
1090 #[derive(Component)]
1091 struct X;
1092
1093 #[derive(Component, Default)]
1094 struct Y;
1095
1096 #[derive(Component)]
1097 struct Z(u32);
1098
1099 let mut world = World::new();
1100
1101 world.register_required_components::<X, Y>();
1105 world.register_required_components_with::<Y, Z>(|| Z(5));
1106 world.register_required_components_with::<X, Z>(|| Z(7));
1107
1108 let id = world.spawn(X).id();
1109
1110 assert_eq!(
1111 7,
1112 world.entity(id).get::<Z>().unwrap().0,
1113 "Z should have the value provided by the constructor defined in X"
1114 );
1115 }
1116
1117 #[test]
1118 fn runtime_required_components_override_2() {
1119 #[derive(Component)]
1122 struct X;
1123
1124 #[derive(Component, Default)]
1125 struct Y;
1126
1127 #[derive(Component)]
1128 struct Z(u32);
1129
1130 let mut world = World::new();
1131
1132 world.register_required_components::<X, Y>();
1136 world.register_required_components_with::<X, Z>(|| Z(7));
1137 world.register_required_components_with::<Y, Z>(|| Z(5));
1138
1139 let id = world.spawn(X).id();
1140
1141 assert_eq!(
1142 7,
1143 world.entity(id).get::<Z>().unwrap().0,
1144 "Z should have the value provided by the constructor defined in X"
1145 );
1146 }
1147
1148 #[test]
1149 fn runtime_required_components_propagate_up() {
1150 #[derive(Component)]
1152 #[require(B)]
1153 struct A;
1154
1155 #[derive(Component, Default)]
1156 struct B;
1157
1158 #[derive(Component, Default)]
1159 struct C;
1160
1161 let mut world = World::new();
1162
1163 world.register_required_components::<B, C>();
1166
1167 let id = world.spawn(A).id();
1168
1169 assert!(world.entity(id).get::<C>().is_some());
1170 }
1171
1172 #[test]
1173 fn runtime_required_components_propagate_up_even_more() {
1174 #[derive(Component)]
1175 struct A;
1176
1177 #[derive(Component, Default)]
1178 struct B;
1179
1180 #[derive(Component, Default)]
1181 struct C;
1182
1183 #[derive(Component, Default)]
1184 struct D;
1185
1186 let mut world = World::new();
1187
1188 world.register_required_components::<A, B>();
1189 world.register_required_components::<B, C>();
1190 world.register_required_components::<C, D>();
1191
1192 let id = world.spawn(A).id();
1193
1194 assert!(world.entity(id).get::<D>().is_some());
1195 }
1196
1197 #[test]
1198 fn runtime_required_components_deep_require_does_not_override_shallow_require() {
1199 #[derive(Component)]
1200 struct A;
1201 #[derive(Component, Default)]
1202 struct B;
1203 #[derive(Component, Default)]
1204 struct C;
1205 #[derive(Component)]
1206 struct Counter(i32);
1207 #[derive(Component, Default)]
1208 struct D;
1209
1210 let mut world = World::new();
1211
1212 world.register_required_components::<A, B>();
1213 world.register_required_components::<B, C>();
1214 world.register_required_components::<C, D>();
1215 world.register_required_components_with::<D, Counter>(|| Counter(2));
1216 world.register_required_components_with::<C, Counter>(|| Counter(1));
1219
1220 let id = world.spawn(A).id();
1221
1222 assert_eq!(world.entity(id).get::<Counter>().unwrap().0, 1);
1224 }
1225
1226 #[test]
1227 fn runtime_required_components_deep_require_does_not_override_shallow_require_deep_subtree_after_shallow(
1228 ) {
1229 #[derive(Component)]
1230 struct A;
1231 #[derive(Component, Default)]
1232 struct B;
1233 #[derive(Component, Default)]
1234 struct C;
1235 #[derive(Component, Default)]
1236 struct D;
1237 #[derive(Component, Default)]
1238 struct E;
1239 #[derive(Component)]
1240 struct Counter(i32);
1241 #[derive(Component, Default)]
1242 struct F;
1243
1244 let mut world = World::new();
1245
1246 world.register_required_components::<A, B>();
1247 world.register_required_components::<B, C>();
1248 world.register_required_components::<C, D>();
1249 world.register_required_components::<D, E>();
1250 world.register_required_components_with::<E, Counter>(|| Counter(1));
1251 world.register_required_components_with::<F, Counter>(|| Counter(2));
1252 world.register_required_components::<E, F>();
1253
1254 let id = world.spawn(A).id();
1255
1256 assert_eq!(world.entity(id).get::<Counter>().unwrap().0, 1);
1258 }
1259
1260 #[test]
1261 fn runtime_required_components_existing_archetype() {
1262 #[derive(Component)]
1263 struct X;
1264
1265 #[derive(Component, Default)]
1266 struct Y;
1267
1268 let mut world = World::new();
1269
1270 world.spawn(X);
1273 assert!(matches!(
1274 world.try_register_required_components::<X, Y>(),
1275 Err(RequiredComponentsError::ArchetypeExists(_))
1276 ));
1277 }
1278
1279 #[test]
1280 fn runtime_required_components_fail_with_duplicate() {
1281 #[derive(Component)]
1282 #[require(Y)]
1283 struct X;
1284
1285 #[derive(Component, Default)]
1286 struct Y;
1287
1288 let mut world = World::new();
1289
1290 assert!(matches!(
1292 world.try_register_required_components::<X, Y>(),
1293 Err(RequiredComponentsError::DuplicateRegistration(_, _))
1294 ));
1295 }
1296
1297 #[test]
1298 fn required_components_bundle_priority() {
1299 #[derive(Component, PartialEq, Eq, Clone, Copy, Debug)]
1300 struct MyRequired(bool);
1301
1302 #[derive(Component, Default)]
1303 #[require(MyRequired(false))]
1304 struct MiddleMan;
1305
1306 #[derive(Component, Default)]
1307 #[require(MiddleMan)]
1308 struct ConflictingRequire;
1309
1310 #[derive(Component, Default)]
1311 #[require(MyRequired(true))]
1312 struct MyComponent;
1313
1314 let mut world = World::new();
1315 let order_a = world
1316 .spawn((ConflictingRequire, MyComponent))
1317 .get::<MyRequired>()
1318 .cloned();
1319 let order_b = world
1320 .spawn((MyComponent, ConflictingRequire))
1321 .get::<MyRequired>()
1322 .cloned();
1323
1324 assert_eq!(order_a, Some(MyRequired(false)));
1325 assert_eq!(order_b, Some(MyRequired(true)));
1326 }
1327
1328 #[test]
1329 #[should_panic]
1330 fn required_components_recursion_errors() {
1331 #[derive(Component, Default)]
1332 #[require(B)]
1333 struct A;
1334
1335 #[derive(Component, Default)]
1336 #[require(C)]
1337 struct B;
1338
1339 #[derive(Component, Default)]
1340 #[require(B)]
1341 struct C;
1342
1343 World::new().register_component::<A>();
1344 }
1345
1346 #[test]
1347 #[should_panic]
1348 fn required_components_self_errors() {
1349 #[derive(Component, Default)]
1350 #[require(A)]
1351 struct A;
1352
1353 World::new().register_component::<A>();
1354 }
1355
1356 #[test]
1357 fn regression_19333() {
1358 #[derive(Component)]
1359 struct X(usize);
1360
1361 #[derive(Default, Component)]
1362 #[require(X(0))]
1363 struct Base;
1364
1365 #[derive(Default, Component)]
1366 #[require(X(1), Base)]
1367 struct A;
1368
1369 #[derive(Default, Component)]
1370 #[require(A, Base)]
1371 struct B;
1372
1373 #[derive(Default, Component)]
1374 #[require(B, Base)]
1375 struct C;
1376
1377 let mut w = World::new();
1378
1379 assert_eq!(w.spawn(B).get::<X>().unwrap().0, 1);
1380 assert_eq!(w.spawn(C).get::<X>().unwrap().0, 1);
1381 }
1382
1383 #[test]
1384 fn required_components_depth_first_2v1() {
1385 #[derive(Component)]
1386 struct X(usize);
1387
1388 #[derive(Component)]
1389 #[require(Left, Right)]
1390 struct Root;
1391
1392 #[derive(Component, Default)]
1393 #[require(LeftLeft)]
1394 struct Left;
1395
1396 #[derive(Component, Default)]
1397 #[require(X(0))] struct LeftLeft;
1399
1400 #[derive(Component, Default)]
1401 #[require(X(1))] struct Right;
1403
1404 let mut world = World::new();
1405
1406 assert_eq!(world.spawn(Root).get::<X>().unwrap().0, 0);
1408 }
1409
1410 #[test]
1411 fn required_components_depth_first_3v1() {
1412 #[derive(Component)]
1413 struct X(usize);
1414
1415 #[derive(Component)]
1416 #[require(Left, Right)]
1417 struct Root;
1418
1419 #[derive(Component, Default)]
1420 #[require(LeftLeft)]
1421 struct Left;
1422
1423 #[derive(Component, Default)]
1424 #[require(LeftLeftLeft)]
1425 struct LeftLeft;
1426
1427 #[derive(Component, Default)]
1428 #[require(X(0))] struct LeftLeftLeft;
1430
1431 #[derive(Component, Default)]
1432 #[require(X(1))] struct Right;
1434
1435 let mut world = World::new();
1436
1437 assert_eq!(world.spawn(Root).get::<X>().unwrap().0, 0);
1439 }
1440
1441 #[test]
1442 fn runtime_required_components_depth_first_2v1() {
1443 #[derive(Component)]
1444 struct X(usize);
1445
1446 #[derive(Component)]
1447 struct Root;
1448
1449 #[derive(Component, Default)]
1450 struct Left;
1451
1452 #[derive(Component, Default)]
1453 struct LeftLeft;
1454
1455 #[derive(Component, Default)]
1456 struct Right;
1457
1458 let mut world = World::new();
1460 world.register_required_components_with::<LeftLeft, X>(|| X(0));
1461 world.register_required_components_with::<Right, X>(|| X(1));
1462 world.register_required_components::<Left, LeftLeft>();
1463 world.register_required_components::<Root, Left>();
1464 world.register_required_components::<Root, Right>();
1465 assert_eq!(world.spawn(Root).get::<X>().unwrap().0, 0);
1466
1467 let mut world = World::new();
1469 world.register_required_components::<Root, Left>(); world.register_required_components::<Root, Right>();
1471 world.register_required_components::<Left, LeftLeft>();
1472 world.register_required_components_with::<Right, X>(|| X(1));
1473 world.register_required_components_with::<LeftLeft, X>(|| X(0));
1474 assert_eq!(world.spawn(Root).get::<X>().unwrap().0, 0);
1475
1476 let mut world = World::new();
1478 world.register_required_components::<Root, Left>();
1479 world.register_required_components::<Root, Right>();
1480 world.register_required_components::<Left, LeftLeft>();
1481 world.register_required_components_with::<LeftLeft, X>(|| X(0));
1482 world.register_required_components_with::<Right, X>(|| X(1));
1483 assert_eq!(world.spawn(Root).get::<X>().unwrap().0, 0);
1484 }
1485
1486 #[test]
1487 fn runtime_required_components_propagate_metadata_alternate() {
1488 #[derive(Component, Default)]
1489 #[require(L1)]
1490 struct L0;
1491
1492 #[derive(Component, Default)]
1493 struct L1;
1494
1495 #[derive(Component, Default)]
1496 #[require(L3)]
1497 struct L2;
1498
1499 #[derive(Component, Default)]
1500 struct L3;
1501
1502 #[derive(Component, Default)]
1503 #[require(L5)]
1504 struct L4;
1505
1506 #[derive(Component, Default)]
1507 struct L5;
1508
1509 let mut world = World::new();
1511 world.register_required_components::<L1, L2>();
1512 world.register_required_components::<L3, L4>();
1513 let e = world.spawn(L0).id();
1514 assert!(world
1515 .query::<(&L0, &L1, &L2, &L3, &L4, &L5)>()
1516 .get(&world, e)
1517 .is_ok());
1518
1519 let mut world = World::new();
1521 world.register_required_components::<L3, L4>();
1522 world.register_required_components::<L1, L2>();
1523 let e = world.spawn(L0).id();
1524 assert!(world
1525 .query::<(&L0, &L1, &L2, &L3, &L4, &L5)>()
1526 .get(&world, e)
1527 .is_ok());
1528 }
1529
1530 #[test]
1531 fn runtime_required_components_propagate_metadata_chain() {
1532 #[derive(Component, Default)]
1533 #[require(L1)]
1534 struct L0;
1535
1536 #[derive(Component, Default)]
1537 struct L1;
1538
1539 #[derive(Component, Default)]
1540 struct L2;
1541
1542 #[derive(Component, Default)]
1543 #[require(L4)]
1544 struct L3;
1545
1546 #[derive(Component, Default)]
1547 struct L4;
1548
1549 let mut world = World::new();
1551 world.register_required_components::<L1, L2>();
1552 world.register_required_components::<L2, L3>();
1553 let e = world.spawn(L0).id();
1554 assert!(world
1555 .query::<(&L0, &L1, &L2, &L3, &L4)>()
1556 .get(&world, e)
1557 .is_ok());
1558
1559 let mut world = World::new();
1561 world.register_required_components::<L2, L3>();
1562 world.register_required_components::<L1, L2>();
1563 let e = world.spawn(L0).id();
1564 assert!(world
1565 .query::<(&L0, &L1, &L2, &L3, &L4)>()
1566 .get(&world, e)
1567 .is_ok());
1568 }
1569
1570 #[test]
1571 fn runtime_required_components_cyclic() {
1572 #[derive(Component, Default)]
1573 #[require(B)]
1574 struct A;
1575
1576 #[derive(Component, Default)]
1577 struct B;
1578
1579 #[derive(Component, Default)]
1580 struct C;
1581
1582 let mut world = World::new();
1583
1584 assert!(world.try_register_required_components::<B, C>().is_ok());
1585 assert!(matches!(
1586 world.try_register_required_components::<C, A>(),
1587 Err(RequiredComponentsError::CyclicRequirement(_, _))
1588 ));
1589 }
1590}