Add on_insert hook to Node to warn if parent has Text

[bytemunch]

Objective

Add a warning when adding a Node as a child of an entity with a Text component, and some information in Text docs.

Closes #18015
Would close #17551 if it weren't already

Solution

Use an on_insert component hook on Node to check the node's parent and emit a warning.

Testing

Click to view test code

use bevy::{input::common_conditions::input_just_pressed, prelude::*};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, (setup, setup_insert))
        .add_systems(
            Update,
            insert_test.run_if(input_just_pressed(MouseButton::Left)),
        )
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
    commands
        .spawn(Text::new("Hello, bevy!"))
        .with_children(|cb| {
            cb.spawn(Node::default()); // Warning triggers here.
        });
}

fn setup_insert(mut commands: Commands) {
    commands
        .spawn(Text::new("Hello, bevy!"))
        .with_children(|cb| {
            cb.spawn_empty();
        });
}

fn insert_test(mut commands: Commands, q: Query<Entity, With<ChildOf>>) {
    for e in &q {
        commands.entity(e).insert(Node::default()); // Warning triggers here.
    }
}

---

[alice-i-cecile]

I'm a little nervous about this pattern (warning due to non-local invariant violation), but I don't have a strong argument for either why it's dangerous or what we should do instead.

[bytemunch]

I've also noticed that inserting a ChildOf doesn't trigger the warning, so this code wouldn't be covered.

    let text = commands.spawn(Text::new("Hello, bevy!")).id();

    commands
        .spawn(Node::default())
        .insert(ChildOf { parent: text });

Which would point to running the check on the ChildOf component, but that feels like overreach for such a specific case. Maybe a system looking for Query<&Node, Added<ChildOf>>, but that could have performance impacts on dense UI scenes.

The pattern was inspired by bevy_ecs::hierarchy::validate_parent_has_component, which outputs a similar warning when the parent is expected to have a certain component.

Would a better approach perhaps be to define a LeafNode marker component that refuses to have children, and warn/forbid when using that specifically?

[alice-i-cecile]

Would a better approach perhaps be to define a LeafNode marker component that refuses to have children, and warn/forbid when using that specifically?

Honestly, I like that design a lot better. That's much more clear, and more discoverable.

[bytemunch]

Cool, I'll close this and see how well I can get leaf nodes to work :)