Suggested components

[alice-i-cecile]

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

Some components tend to be useful together, but don't always belong together. A prime example of this is found in how we handle spritesheets, where you can add a TextureAtlas component to make it animatable. Similar things occur with cameras.

This can be quite difficult to discover!

What solution would you like?

Following #14791, it would be nice to have a way to note sibling components as "suggested" complements, using the same style of macro annotations.

What alternative(s) have you considered?

Just add these to the docs. This is less structured, making it harder to read and less usable for tooling.

Additional context

This is not an original idea: this has come up multiple times over the course of the BSN working group.

[ItsDoot]

Additionally, if we add this as part of Component rather than just additional documentation, we could eventually hook it up to the editor so it can recommend components whenever a user is building an entity. The more general version of this is component traits (not rust traits).

[iiYese]

Some centralized place with tables of component combinations would be nice so this doesn't turn into doc spaghetti & chasing links upon links to get the full picture.

[MiniaczQ]

If this isn't going to be enforced by anything I rather not have this.
Docs are already the place to document interesting behavior, such as interaction with non-bundled components.
Adding an attribute that does essentially nothing will be confusing and overlap with what docs already do.

There are very few cases where this would be required in the first place:

1. component A extends behavior of component B
2. components A and B are unrelated, but have a synergy

First one is obvious, A should require B, it serves no other purpose.
Second one can be solved the same way, it just isn't as pretty.
We can introduce a component C that requires both A and B and represents their synergy.
The downside is that we require an additional ZST component on the entity.
The upside is that we can use this marker to control whether the synergy is used or not.
(I assume that whatever system is adding this, will filter queries using C)

Introducing a 1-way relation should be enough to make discoverability tools.
I don't consider this a full solution by any means, but definitely something to think about.

[bushrat011899]

Second one can be solved the same way, it just isn't as pretty. We can introduce a component C that requires both A and B and represents their synergy. The downside is that we require an additional ZST component on the entity.

Further to this, we already have a system for recommending that components be used together, Bundles. This solves the issue of linking unrelated components in an optional manner without adding extra ZST's to the final entities. Within the context of an editor, registered Bundles could be used to prompt users for suggested components. The benefit to this approach is anyone can create these bundles and add documentation to them explaining why the combination should be considered.

Outside of an editor, it would be really nice if (somehow) components could be scraped into a docs.rs style page, providing documentation and then using bundles as a way of linking to related components. I have no idea how you'd even go about such a task, but it sure would be nice.

[ManevilleF]

Can't we automatically discover this through required components in the opposite direction ?
TextureAtlas would probably require Handle<Image> so we should be able to find that Handle<Image> can be extenderd through TextureAtlas

[MiniaczQ]

Further to this, we already have a system for recommending that components be used together, Bundles.

The point of required components is to supersede bundles

[alice-i-cecile]

The reverse dependency search should work quite well in general. I think I'm happy with that as a solution, in concert with manual docs.

Note that there will still be rare cases where that's not possible: TextureAtlas works with both UI and sprites, and so won't be able to add a required components on the other. I think that's a worthwhile sacrifice for the reduced complexity though.