Added App::with_component_hooks

[pin3-free]

Objective

• Fixes make register_component_hooks method for App #16921
• Right now, to add component hooks, you either have to implement them in the Component trait implementation, or use app.world_mut().register_component_hooks(), which is somewhat clunky. This PR aims to introduce a more concise way to add component hooks directly from the app interface

Solution

• I could not find a good way to implement the interface proposed in the solution directly, since the user would need to not only pass the hook itself, but also specify which hook method (on_add, on_insert, etc.) they want to add the hook to. Plus there's the issue of fallible hook add methods.
• The proposed solution is similar to methods such as with_children on the EntityCommands, passing a closure that will mutate the target (in this case -- &mut ComponentHooks) and return the parent, allowing it to chain nicely into the multitude of calls usually associated with App.

Testing

• I tested this by creating a new example called with_component_hooks.rs in the ecs section of examples. It works identically to the component_hooks example, but uses the new API

---

Showcase

Here's a snipped from the component_hooks.rs example and the comparison to the with_component_hooks.rs example

While a showcase should aim to be brief and digestible, you can use a toggleable section to save space on longer showcases:

// === component_hooks.rs ===

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .add_systems(Update, trigger_hooks)
        .init_resource::<MyComponentIndex>()
        .add_event::<MyEvent>()
        .run();
}

fn setup(world: &mut World) {
    world
        .register_component_hooks::<MyComponent>()
        .on_add(|mut world, entity, component_id| {
            let value = world.get::<MyComponent>(entity).unwrap().0;
            println!("Component: {component_id:?} added to: {entity:?} with value {value:?}");
            world
                .resource_mut::<MyComponentIndex>()
                .insert(value, entity);
            world.send_event(MyEvent);
        })
        .on_insert(|world, _, _| {
            println!("Current Index: {:?}", world.resource::<MyComponentIndex>());
        })
        .on_replace(|mut world, entity, _| {
            let value = world.get::<MyComponent>(entity).unwrap().0;
            world.resource_mut::<MyComponentIndex>().remove(&value);
        })
        .on_remove(|mut world, entity, component_id| {
            let value = world.get::<MyComponent>(entity).unwrap().0;
            println!("Component: {component_id:?} removed from: {entity:?} with value {value:?}");
            world.commands().entity(entity).despawn();
        });
}

// === with_component_hooks.rs ===

// The setup function is no longer needed in this instance
fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Update, trigger_hooks)
        .with_component_hooks::<MyComponent>(|hooks| {
            hooks
                .on_add(|mut world, entity, component_id| {
                    let value = world.get::<MyComponent>(entity).unwrap().0;
                    println!(
                        "Component: {component_id:?} added to: {entity:?} with value {value:?}"
                    );
                    world
                        .resource_mut::<MyComponentIndex>()
                        .insert(value, entity);
                    world.send_event(MyEvent);
                })
                .on_insert(|world, _, _| {
                    println!("Current Index: {:?}", world.resource::<MyComponentIndex>());
                })
                .on_replace(|mut world, entity, _| {
                    let value = world.get::<MyComponent>(entity).unwrap().0;
                    world.resource_mut::<MyComponentIndex>().remove(&value);
                })
                .on_remove(|mut world, entity, component_id| {
                    let value = world.get::<MyComponent>(entity).unwrap().0;
                    println!(
                        "Component: {component_id:?} removed from: {entity:?} with value {value:?}"
                    );
                    world.commands().entity(entity).despawn();
                });
        })
        .init_resource::<MyComponentIndex>()
        .add_event::<MyEvent>()
        .run();
}

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[github-actions]

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[alice-i-cecile]

No complaints about the implementation, but I don't think we should do this. There's already too many methods on App and too much API duplication. Medium-term, I'd like to push folks towards the app.world_mut pattern in general, and this PR is going in the opposite direction.

[BenjaminBrienen]

Is there a compromise where we can allow for mutably "inspecting" the app's world from an App, which would allow for keeping the builder-like construction of an App without API duplication?

App::new()
    .add_plugins(DefaultPlugins)
    .add_systems(Update, trigger_hooks)
    .inspect_world_mut(|world| world.with_component_hooks(...))
    .init_resource::<MyComponentIndex>()
    .add_event::<MyEvent>()
    .run();

[alice-i-cecile]

It feels like that method would make sense as modify_world? Overall I think that the App <-> World duplication / API mess around multiple worlds needs a real design to solve, and we should be nervous about just adding a dozen little fixes.