Misleading docs on duplicate required component constructors
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 171
Description
The [required components documentation](https://dev-docs.bevyengine.org/bevy/ecs/component/trait.Component.html#required-components) describes the algorithm for resolving multiple constructors for the same component in a required components tree as follows:
> In general, this shouldn’t happen often, but when it does the algorithm is simple and predictable:
>
> 1. Use all of the constructors (including default constructors) directly defined in the spawned component’s require list
> 2. In the order the requires are defined in #[require()], recursively visit the require list of each of the components in the list (this is a Depth First Search). When a constructor is found, it will only be used if one has not already been found.
However, this is not what actually happens. For example, consider this case:
```rust
#[derive(Component)]
#[require(B)]
struct A;
#[derive(Component, Default)]
#[require(C, D(|| D(1)))]
struct B;
#[derive(Component, Default)]
#[require(D(|| D(2)))]
struct C;
#[derive(Component)]
struct D(u8);
```
Now suppose we spawn `A`. Following the steps described in the docs to determine which constructor will be used for `D`:
1. The "spawned component" is `A`, which does not have a constructor for `D`, so go to step 2.
2. A DFS will visit the components in the order `A B C D(2) D(1)`. So when `D(2)` is visited, it will be used because `D` hasn't been found yet; and when `D(1)` is visited, it will not be used because `D` has been found already.
This suggests that `D(2)` will be used as the constructor. But that's incorrect: `D(1)` is actually used.
Contributor guide
Research direction
Start with the required components documentation linked in the issue and compare its stated traversal order with the provided A–D example. Update the explanation so it matches the actual constructor-selection behavior, including which D constructor is used, and verify that the example and algorithm agree.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100