Implement Bundle for every component and simplify API

[alice-i-cecile]

What problem does this solve or what need does it fill?

The distinction between components and bundles is often lost on new users, and we end up with a lot of redundant, nearly-duplicated APIs.

What solution would you like?

Implement Bundle for every Component, representing the one element bundle containing only that component.

Remove all duplicated API surfaces, keeping the Component names but accepting bundles:

• insert and insert_bundle -> insert
• remove and remove_bundle -> remove
• remove spawn_bundle; there's now less boilerplate and the design of this routinely confuses the mental model for new users

There are some additional benefits:

• we can remove the #[bundle] annotation in the #[derive(Bundle)] crate
• spawn_batch becomes much easier to work with for simple 0 and 1 component cases
• users cannot accidentally derive component on a standard bundle, as conflicting impls will exist

What alternative(s) have you considered?

Just leave it as is.

Additional context

Design credit to @BoxyUwU, @TheRawMeatball and @Frizi. Originally described here: https://hackmd.io/EvBrYLQeQbCjE2eycBlo3w

Made possible by #2254!

[cart]

I don't think we should move forward on this until we resolve the "how do Bundles relate to scenes and editor experiences" conversation (ex: #3833 (comment) and the various discussions we've had on discord). Bundles might be promoted to "metadata that exists on entities" and might expand to include "prefab-like" contexts.

I'm also personally against this because it further blurs the lines between components and bundles, which our users constantly mess up in their mental models and in their code. #[derive(Component)] has helped in that regard.

Pulling in @bevyengine/ecs-team as this is pretty fundamental stuff.

[alice-i-cecile]

I'm also personally against this because it further blurs the lines between components and bundles, which our users constantly mess up in their mental models and in their code

I agree with this: but I actually think that this change will help.

Fundamentally, this user confusion is driven by the fact that bundles are treated as a distinct concept by our APIs: particularly spawn_bundle and insert_bundle.

I think we should:

1. Go forward with this change.
2. Change the name of the Bundle trait to ComponentBundle and use "bundle of components" in our docs.
3. Eliminate insert_bundle and spawn_bundle (plus any minor uses, like remove_bundle).

The type signature of .insert() becomes

fn insert(&mut EntityCommands, components: impl ComponentBundle) -> &mut EntityCommands

This removes the concept of "bundles" from our API calls, and reinforces that #[derive(ComponentBundle)] results in a bundle of components, rather than this nebulous disconnected concept.

Bundles might be promoted to "metadata that exists on entities" and might expand to include "prefab-like" contexts.

IMO if this exists, it should not use Bundles: it should be a separate concept that stores a bundle internally. A "collection of components" is a foundational idea: there's no need to overload it when we can just wrap it.

[alice-i-cecile]

Bundles might be promoted to "metadata that exists on entities" and might expand to include "prefab-like" contexts.

IMO if this exists, it should not use Bundles: it should be a separate concept that stores a bundle internally. A "collection of components" is a foundational idea: there's no need to overload it when we can just wrap it.

#3877 is a solid vision of what this would look like in practice. The needs appear to be quite divergent, and I suspect they will only diverge further as we explore more.

[DJMcNab]

My thinking around this is that behaviour only makes sense in relation to a combinations of components on the entity.
And so Bundles are helpers to get a useful combination of components, and thus have no meaning beyond their constituent components.
This seems to me to be the only way to maintain coherent behaviour with the underlying systems operating on components.
Which encapsulates how multiple bundles of the same 'kind' (e.g. rendering: SpriteBundle, PBRBundle, camera: OrthographicCameraBundle, PerspectiveCameraBundle) don't compose.

With this view, unifying the apis which deal with Bundles and Components is natural.

[djeedai]

All agreeing with the above from @alice-i-cecile and @DJMcNab, but I thought this feature was further along / already implemented, so let me present another use case that is blocked until this is implemented: fluent-style component construction. In bevy_tweening (but the concept is more general, applies to any library) we have an Animator component which animates another component. Although this can be added manually, a much nicer way to do this in other libraries / languages is to do something like this (pseudo-code):

my_component.move_to(Vec3(1,2,3))

For Bevy, this could be implemented with a trait:

pub trait TransformAnimation {
  fn move_to(self, dst: Vec3) -> (Transform, Animator);
}

impl TransformAnimation for Transform {
  pub fn move_to(self, dst: Vec3) -> (Transform, Animator) {
    // create the Animator
    // [...]
    (self, animator)
  }
}

commands.spawn(Transform::default().move_to(Vec3::new(1., 2., 3.));

However this is blocked by the fact the API for adding a single component is different from the one for adding 2+ components, which means users would have to change all call sites where they want to animate a component on insertion.

[DJMcNab]

Which impl do you think will cause (C1, C2) to be Component? This issue only suggests adding new implementations of Bundle.

[urben1680]

Oh then I misunderstood this proposal! Thanks for making this clear to me.