bevyengine / bevyengine/bevy

Misleading docs on duplicate required component constructors

Open
#16,494 3 comments 0 reactions 0 assignees View on GitHub
A-ECS C-Docs S-Ready-For-Implementation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.