bevy/crates
Carter Anderson 9cdb915809
Required Components (#14791)
## Introduction

This is the first step in my [Next Generation Scene / UI
Proposal](https://github.com/bevyengine/bevy/discussions/14437).

Fixes https://github.com/bevyengine/bevy/issues/7272 #14800.

Bevy's current Bundles as the "unit of construction" hamstring the UI
user experience and have been a pain point in the Bevy ecosystem
generally when composing scenes:

* They are an additional _object defining_ concept, which must be
learned separately from components. Notably, Bundles _are not present at
runtime_, which is confusing and limiting.
* They can completely erase the _defining component_ during Bundle init.
For example, `ButtonBundle { style: Style::default(), ..default() }`
_makes no mention_ of the `Button` component symbol, which is what makes
the Entity a "button"!
* They are not capable of representing "dependency inheritance" without
completely non-viable / ergonomically crushing nested bundles. This
limitation is especially painful in UI scenarios, but it applies to
everything across the board.
* They introduce a bunch of additional nesting when defining scenes,
making them ugly to look at
* They introduce component name "stutter": `SomeBundle { component_name:
ComponentName::new() }`
* They require copious sprinklings of `..default()` when spawning them
in Rust code, due to the additional layer of nesting

**Required Components** solve this by allowing you to define which
components a given component needs, and how to construct those
components when they aren't explicitly provided.

This is what a `ButtonBundle` looks like with Bundles (the current
approach):

```rust
#[derive(Component, Default)]
struct Button;

#[derive(Bundle, Default)]
struct ButtonBundle {
    pub button: Button,
    pub node: Node,
    pub style: Style,
    pub interaction: Interaction,
    pub focus_policy: FocusPolicy,
    pub border_color: BorderColor,
    pub border_radius: BorderRadius,
    pub image: UiImage,
    pub transform: Transform,
    pub global_transform: GlobalTransform,
    pub visibility: Visibility,
    pub inherited_visibility: InheritedVisibility,
    pub view_visibility: ViewVisibility,
    pub z_index: ZIndex,
}

commands.spawn(ButtonBundle {
    style: Style {
        width: Val::Px(100.0),
        height: Val::Px(50.0),
        ..default()
    },
    focus_policy: FocusPolicy::Block,
    ..default()
})
```

And this is what it looks like with Required Components:

```rust
#[derive(Component)]
#[require(Node, UiImage)]
struct Button;

commands.spawn((
    Button,
    Style { 
        width: Val::Px(100.0),
        height: Val::Px(50.0),
        ..default()
    },
    FocusPolicy::Block,
));
```

With Required Components, we mention only the most relevant components.
Every component required by `Node` (ex: `Style`, `FocusPolicy`, etc) is
automatically brought in!

### Efficiency

1. At insertion/spawn time, Required Components (including recursive
required components) are initialized and inserted _as if they were
manually inserted alongside the given components_. This means that this
is maximally efficient: there are no archetype or table moves.
2. Required components are only initialized and inserted if they were
not manually provided by the developer. For the code example in the
previous section, because `Style` and `FocusPolicy` are inserted
manually, they _will not_ be initialized and inserted as part of the
required components system. Efficient!
3. The "missing required components _and_ constructors needed for an
insertion" are cached in the "archetype graph edge", meaning they aren't
computed per-insertion. When a component is inserted, the "missing
required components" list is iterated (and that graph edge (AddBundle)
is actually already looked up for us during insertion, because we need
that for "normal" insert logic too).

### IDE Integration

The `#[require(SomeComponent)]` macro has been written in such a way
that Rust Analyzer can provide type-inspection-on-hover and `F12` /
go-to-definition for required components.

### Custom Constructors

The `require` syntax expects a `Default` constructor by default, but it
can be overridden with a custom constructor:

```rust
#[derive(Component)]
#[require(
    Node,
    Style(button_style),
    UiImage
)]
struct Button;

fn button_style() -> Style {
    Style {
        width: Val::Px(100.0),
        ..default()
    }
}
```

### Multiple Inheritance

You may have noticed by now that this behaves a bit like "multiple
inheritance". One of the problems that this presents is that it is
possible to have duplicate requires for a given type at different levels
of the inheritance tree:

```rust
#[derive(Component)
struct X(usize);

#[derive(Component)]
#[require(X(x1))
struct Y;

fn x1() -> X {
    X(1)
}

#[derive(Component)]
#[require(
    Y,
    X(x2),
)]
struct Z;

fn x2() -> X {
    X(2)
}

// What version of X is inserted for Z?
commands.spawn(Z);
```

This is allowed (and encouraged), although this doesn't appear to occur
much in practice. First: only one version of `X` is initialized and
inserted for `Z`. In the case above, I think we can all probably agree
that it makes the most sense to use the `x2` constructor for `X`,
because `Y`'s `x1` constructor exists "beneath" `Z` in the inheritance
hierarchy; `Z`'s constructor is "more specific".

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 Depth First Search). When a constructor is found, it will only be
used if one has not already been found.

From a user perspective, just think about this as the following:

1. Specifying a required component constructor for `Foo` directly on a
spawned component `Bar` will result in that constructor being used (and
overriding existing constructors lower in the inheritance tree). This is
the classic "inheritance override" behavior people expect.
2. For cases where "multiple inheritance" results in constructor
clashes, Components should be listed in "importance order". List a
component earlier in the requirement list to initialize its inheritance
tree earlier.

Required Components _does_ generally result in a model where component
values are decoupled from each other at construction time. Notably, some
existing Bundle patterns use bundle constructors to initialize multiple
components with shared state. I think (in general) moving away from this
is necessary:

1. It allows Required Components (and the Scene system more generally)
to operate according to simple rules
2. The "do arbitrary init value sharing in Bundle constructors" approach
_already_ causes data consistency problems, and those problems would be
exacerbated in the context of a Scene/UI system. For cases where shared
state is truly necessary, I think we are better served by observers /
hooks.
3. If a situation _truly_ needs shared state constructors (which should
be rare / generally discouraged), Bundles are still there if they are
needed.

## Next Steps

* **Require Construct-ed Components**: I have already implemented this
(as defined in the [Next Generation Scene / UI
Proposal](https://github.com/bevyengine/bevy/discussions/14437). However
I've removed `Construct` support from this PR, as that has not landed
yet. Adding this back in requires relatively minimal changes to the
current impl, and can be done as part of a future Construct pr.
* **Port Built-in Bundles to Required Components**: This isn't something
we should do right away. It will require rethinking our public
interfaces, which IMO should be done holistically after the rest of Next
Generation Scene / UI lands. I think we should merge this PR first and
let people experiment _inside their own code with their own Components_
while we wait for the rest of the new scene system to land.
* **_Consider_ Automatic Required Component Removal**: We should
evaluate _if_ automatic Required Component removal should be done. Ex:
if all components that explicitly require a component are removed,
automatically remove that component. This issue has been explicitly
deferred in this PR, as I consider the insertion behavior to be
desirable on its own (and viable on its own). I am also doubtful that we
can find a design that has behavior we actually want. Aka: can we
_really_ distinguish between a component that is "only there because it
was automatically inserted" and "a component that was necessary / should
be kept". See my [discussion response
here](https://github.com/bevyengine/bevy/discussions/14437#discussioncomment-10268668)
for more details.

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com>
Co-authored-by: Pascal Hertleif <killercup@gmail.com>
2024-08-27 20:22:23 +00:00
..
bevy_a11y Add Reflect derive to bevy_a11y::Focus (#14763) 2024-08-15 17:33:20 +00:00
bevy_animation Add AnimationGraph::from_clips and simplify animated_fox example (#14853) 2024-08-25 14:16:04 +00:00
bevy_app Added on_unimplemented Diagnostic for IntoObserverSystem (#14840) 2024-08-25 14:15:49 +00:00
bevy_asset drop pending asset loads (#14808) 2024-08-27 00:16:44 +00:00
bevy_audio Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_color Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_core Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_core_pipeline Have EntityCommands methods consume self for easier chaining (#14897) 2024-08-26 18:24:59 +00:00
bevy_derive Remove deprecated bevy_dynamic_plugin (#14534) 2024-07-30 15:31:08 +00:00
bevy_dev_tools Rewrite screenshots. (#14833) 2024-08-25 14:14:32 +00:00
bevy_diagnostic Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_dylib Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_ecs Required Components (#14791) 2024-08-27 20:22:23 +00:00
bevy_encase_derive Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_gilrs Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_gizmos Fix arc_2d Gizmos (#14731) 2024-08-26 17:57:57 +00:00
bevy_gltf Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_hierarchy Add link to with_children in with_child doc (#14604) 2024-08-04 13:36:52 +00:00
bevy_input Fix common capitalization errors in documentation (#14562) 2024-07-31 21:16:05 +00:00
bevy_internal Add bevy_picking sprite backend (#14757) 2024-08-26 18:01:32 +00:00
bevy_log Fix common capitalization errors in documentation (#14562) 2024-07-31 21:16:05 +00:00
bevy_macro_utils Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_math Fixing Curve trait not being object safe. (#14939) 2024-08-27 13:29:02 +00:00
bevy_mikktspace Fix underflow panic in InitTriInfo (#14893) 2024-08-25 14:13:23 +00:00
bevy_pbr Have EntityCommands methods consume self for easier chaining (#14897) 2024-08-26 18:24:59 +00:00
bevy_picking rename Drop to bevy::picking::events::DragDrop to unclash std::ops:Drop (#14926) 2024-08-26 18:38:56 +00:00
bevy_ptr Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_reflect Split GenericTypeCell::get_or_insert into smaller pieces (#14865) 2024-08-26 18:20:01 +00:00
bevy_render Fix Adreno 642L crash (#14937) 2024-08-27 17:35:01 +00:00
bevy_scene reflect: implement the unique reflect rfc (#7207) 2024-08-12 17:01:41 +00:00
bevy_sprite Have EntityCommands methods consume self for easier chaining (#14897) 2024-08-26 18:24:59 +00:00
bevy_state Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_tasks Fix common capitalization errors in documentation (#14562) 2024-07-31 21:16:05 +00:00
bevy_text Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_time Allow ordering variable timesteps around fixed timesteps (#14881) 2024-08-23 16:19:42 +00:00
bevy_transform Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_ui Refactor AsBindGroup to use a associated SystemParam. (#14909) 2024-08-25 20:16:34 +00:00
bevy_utils Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_window Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_winit Have EntityCommands methods consume self for easier chaining (#14897) 2024-08-26 18:24:59 +00:00