1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

use std::marker::PhantomData;

use bevy_app::{App, CoreStage, Plugin};
use bevy_core::Name;
use bevy_ecs::{prelude::*, schedule::ShouldRun};
use bevy_log::warn;
use bevy_utils::{get_short_name, HashSet};

use crate::Parent;

/// When enabled, runs [`check_hierarchy_component_has_valid_parent<T>`].
///
/// This resource is added by [`ValidParentCheckPlugin<T>`].
/// It is enabled on debug builds and disabled in release builds by default,
/// you can update this resource at runtime to change the default behavior.
#[derive(Resource)]
pub struct ReportHierarchyIssue<T> {
    /// Whether to run [`check_hierarchy_component_has_valid_parent<T>`].
    pub enabled: bool,
    _comp: PhantomData<fn(T)>,
}
impl<T> Default for ReportHierarchyIssue<T> {
    fn default() -> Self {
        Self {
            enabled: cfg!(debug_assertions),
            _comp: PhantomData,
        }
    }
}

/// System to print a warning for each `Entity` with a `T` component
/// which parent hasn't a `T` component.
///
/// Hierarchy propagations are top-down, and limited only to entities
/// with a specific component (such as `ComputedVisibility` and `GlobalTransform`).
/// This means that entities with one of those component
/// and a parent without the same component is probably a programming error.
/// (See B0004 explanation linked in warning message)
pub fn check_hierarchy_component_has_valid_parent<T: Component>(
    parent_query: Query<
        (Entity, &Parent, Option<&Name>),
        (With<T>, Or<(Changed<Parent>, Added<T>)>),
    >,
    component_query: Query<(), With<T>>,
    mut already_diagnosed: Local<HashSet<Entity>>,
) {
    for (entity, parent, name) in &parent_query {
        let parent = parent.get();
        if !component_query.contains(parent) && !already_diagnosed.contains(&entity) {
            already_diagnosed.insert(entity);
            warn!(
                "warning[B0004]: {name} with the {ty_name} component has a parent without {ty_name}.\n\
                This will cause inconsistent behaviors! See https://bevyengine.org/learn/errors/#B0004",
                ty_name = get_short_name(std::any::type_name::<T>()),
                name = name.map_or("An entity".to_owned(), |s| format!("The {s} entity")),
            );
        }
    }
}

/// Run criteria that only allows running when [`ReportHierarchyIssue<T>`] is enabled.
pub fn on_hierarchy_reports_enabled<T>(report: Res<ReportHierarchyIssue<T>>) -> ShouldRun
where
    T: Component,
{
    report.enabled.into()
}

/// Print a warning for each `Entity` with a `T` component
/// whose parent doesn't have a `T` component.
///
/// See [`check_hierarchy_component_has_valid_parent`] for details.
pub struct ValidParentCheckPlugin<T: Component>(PhantomData<fn() -> T>);
impl<T: Component> Default for ValidParentCheckPlugin<T> {
    fn default() -> Self {
        Self(PhantomData)
    }
}

impl<T: Component> Plugin for ValidParentCheckPlugin<T> {
    fn build(&self, app: &mut App) {
        app.init_resource::<ReportHierarchyIssue<T>>()
            .add_system_to_stage(
                CoreStage::Last,
                check_hierarchy_component_has_valid_parent::<T>
                    .with_run_criteria(on_hierarchy_reports_enabled::<T>),
            );
    }
}