bevyengine / bevyengine/bevy

Suggested / related components

Open
#16,246 1 comment 0 reactions 0 assignees View on GitHub
A-ECS C-Docs C-Feature D-Modest S-Ready-For-Implementation
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 22h
Merged PRs (30d)
161

Description

## 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](https://discord.com/channels/691052431525675048/743559241461399582/1301693168378712065) and was broadly popular there!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.