Suggested / related components

[alice-i-cecile]

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

Required components are great for explaining the relation between components when the relationship is mandatory, but aren't great when it's optional.

We've seen this come up in Bevy itself, with various texture atlas components being fully optional, but being intended to work with both UI images and sprites. Similarly, we could split a lot of fields off of Node (previously Style) by simply making them have no effect when they're missing. It would be really nice to have a standardized and tooling friendly way to explain these links.

To take an example from one of my crates: ActionState and InputMap are intended to work together, but you can use ActionState without an InputMap (great for AI). It would be nice to be able to document that edge in a structured and straightforward way.

What solution would you like?

A parallel Component annotation to the requires , called suggests. To start, this just generates documentation for the Component trait.

Afterwards, this should store runtime information for tooling. This will allow us to draw a graph of components and their relationships.

Downstream crates should be able to augment the list of suggested components for components they don't own, to show where they hook into existing primitives.

Primarily, this generates documentation using

What alternative(s) have you considered?

We could manually document these, but a) it's more tedious to remember to do b) this can't be automatically discovered by tooling.

Additional context

Raised on Discord and was broadly popular there!

[alice-i-cecile]

As @mockersf points out, this is loosely related to https://github.com/bevyengine/bevy/pull/16209, as it suggests another kind of edge between components.