Note: this is in the process of being split up, consider reviewing the individual PRs unless you're looking for the whole context

Objective

• Fixes Bundles with optional components #2157 by implementing Bundle for Option<T: Bundle>
• Fixes Better tools for working with dynamic collections of components #3227 by implement Bundle for Box<dyn Bundle> and Vec<Box<dyn Bundle>>
• Supersedes Add Self: Sized bounds to Bundle trait methods #14879
• Don't regress the performance for current static bundles
• have Option bundles be faster than calling insert a second time
• Bonus: fix a bug where multiple #[bundle(ignore)] fields were handled in the wrong way

Solution

• Introduce a StaticBundle (name bikesheddable) for usecases where the set of components of a bundle must be knowable without an instance of the bundle and switch functions that needed this aspect of Bundle;
• Add &self parameters to Bundle's methods to allow them to depend on self's value;
• (Optimization): add a way to distinguish different types of Bundles:
  • static bundles have all components statically known, like current bundles, and can be cached by their type id;
  • bounded bundles may have some optional components, but overall the set of components they can contain is bounded, allowing to distinguish different subsets by a cache key (in addition to the bundle type id);
  • dynamic bundles have no way to be cached other than looking at their ComponentIds
  • overall this is implemented through the new is_static, is_bounded and cache_key methods on Bundle.
• Implement Bundle for Option<T: Bundle> as a bounded bundle (i.e. with is_static = false, is_bounded = true and a cache key depending on whether it is Some or None);
• Make Bundle dyn-compatible and implement Bundle for Box<dyn Bundle>
  • this was done by marking non-dyn compatible methods as where Self: Sized and by introducing a couple of new dyn-compatible automatically-implemented supertraits, BundleDyn and BundleEffectDyn.
• Add a #[bundle(dynamic)] attribute for the Bundle derive macro to opt-out of deriving StaticBundle and BundleFromComponents
  • BundleFromComponents could theoretically be implemented for bounded but non-static bundles, but it seems tricky and I decided to leave it out from this PR

Testing

• each new implementation of Bundle comes with its own tests in crates/bevy_ecs/src/bundle.rs
• benchmarks have been added to validate the performance advantages of the cache key mechanism, see this and this comments

Showcase

fn enemy_bundle(name: String, attack_power: u32, is_boss: bool) -> impl Bundle {
    (
        EnemyMarker,
        Name::new(name),
        AttackPower(attack_power),
        // You can now conditionally insert components or other bundles!
        if is_boss { Some(BossMarker) } else { None }
    )
}

// You can now convert reflected components and bundles into an actual `Bundle` you can insert
fn bundle_from_reflected_data(components: Vec<Box<dyn Reflect>>, registry: &TypeRegistry) -> impl Bundle {
    components
        .into_iter()
        .map(|data| {
            let Some(reflect_bundle) = registry.get_type_data::<ReflectBundle>(data.type_id()) else { todo!() };
            let Ok(bundle_box) = reflect_bundle.get_boxed(data) else { todo!() };
            bundle_box
        })
        .collect::<Vec<Box<dyn Bundle>>>()
}