Bundles with optional components

[botiapa]

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

Currently if a bundle has components which are wrapped in an Option<>, they are treated literally. However in my opinion it would be a good addition if we had the option to mark optional components, and they would be treated as such.

What solution would you like?

Unfortunately I don't understand the inner workings of bevy enough to propose an exact solution, but after having a small conversation on discord, it has come to my attention, that there had been a similar feature like this in the old ECS called DynamicBundle. An example might look like this:

#[derive(Bundle)]
struct BundleA {
    component_a: f32,
    #[optional]
    component_b: Option<i32>
}

// In a system
let bundle = BundleA { component_a: 0f32, component_b: None };
commands.spawn_bundle(bundle) // --> Only component_a is added to the entity;

What alternative(s) have you considered?

Manually checking every optional component and adding it manually.

Additional context

I hadn't used DynamicBundle when it was still in, so I don't know if what I'm proposing makes sense.

[JonahPlusPlus]

Hmm, maybe a builder pattern would be better for this? If you have a big bundle that has a lot of optionals, then it would mean that you would have to set a lot of then to None, when perhaps you only need a few. With a builder pattern, you could just add the ones you need, then spawn all of them together. However, I only see it being useful for when you don't want to spawn something right away. I don't know what scenario it would be used for, maybe you have something in mind?

Anyways, you can already spawn custom bundles by using tuples. The Bevy Docs cover it. You can use it like commands.spawn_bundle((Component1, Component2));. But maybe I am misunderstanding something?

[botiapa]

Okay so imagine the following scenario:

You want to synchronize an entity over the network, so you create a query like this on the server side:
Query<(&NetID, Option<&ComponentA>, Option<&ComponentB>, Option<&ComponentC>)> you could easily convert this to a custom bundle which then you could serialize and send through the network, and adding it on the client side could be as easy as: commands.spawn_bundle(deserialized_bundle);

I hope that clears it up.

[Nilirad]

If I understand correctly, when you put in a query an Option<T>, the ECS will return the components of entities that may or may not include a component T.

If that's the case, I wonder if a Component that is of type Option<T> is actually queryable. If not, there should be no need to put an #[optional] attribute, since an Option cannot be returned from a query.

I'm 99% sure that I'm missing something though... 🤔

[botiapa]

I'm pretty sure that it's queryable, you just have to switch where you put the &: Query<&Option<ComponentA>> instead of Query<Option<&ComponentA>>

I don't know if anyones uses it like this, but it is possible AFAIK.

[mockersf]

Thinking more about this, I actually think we shouldn't insert optional components from a bundle:

• if the component is None, do not insert it
• if the component is Some(v), insert v

The Option from Rust translate nicely into a component present or not on an entity in Bevy

Downside is that a bundle may not have the same components based on its value, but seems OK to me

[StarArawn]

I ran into this when wanting to allow users to pass in a custom bundle for tiles. I'm not sure how I can let them have tags in bundles currently. Example:

struct TileBundle {
  tile: Tile,
  visible: VisibleTile, // < If this is Option<VisibleTile> that doesn't make sense for a tag, yet there is no way for a user to not include the tag in the bundle.
}

This type of code is useful for deferred spawning of entities. Where you want to build out all of your entity data first and then mass spawn all of them.

[cart]

This would likely require some major changes to how we handle Bundles internally and would likely result in more expensive archetype changes. Right now, we assume a Bundle's composition is static. This allows us to make bundle add/remove operations faster by pre-computing archetype transitions in the Archetype Graph and indexing them via the BundleId (which correlates 1:1 to a Bundle's TypeId).

If we want to support this pattern, we'll probably need to find a way to treat permutations of "optional bundle components" as different BundleIds.

There might be a way to reconcile this pattern with the "Bundle Builder" abstraction we've discussed in a couple of places:

#2061 (comment)
#792

// TileBundle includes all possible TileBundle components 
commands.spawn().insert_bundle(
    TileBundle::default()
        .without::<VisibleTile>()
)

[bjorn3]

Nope, the get_type_info method doesn't take &self and as such must return the same type infos independent of the actual value of the bundle. I do see value in changing this though. (especially in the context of (currently not yet supported) dynamic components)