Allow components to be "explicitly required".

[andriyDev]

Objective

• Fixes Require components that can't be defaulted #16194.

Solution

• Add an "explicit" tag to required components to allow them to check (at runtime) that a component is present (or inserted at the same time).

Testing

• Unit tests are sufficient.

---

Showcase

#[derive(Component)]
#[require(EnemyTarget(explicit))]
struct Enemy {
  health: f32,
}

#[derive(Component)]
struct EnemyTarget(Entity);

fn main() {
  App::new()
    .add_plugins(DefaultPlugins)
    .run()
}

fn setup(mut commands: Commands) {
  let target = commands.spawn(Transform::default()).id();
  // Panics if we don't add the EnemyTarget.
  commands.spawn((Enemy{ health: 10.0 }, EnemyTarget(target)));
}

Migration Guide

• Required component constructors named explicit must be renamed to anything else.

Risks

Required components so far are safe - they should not cause a panic. Explicitly required components can cause panics now whenever you spawn or insert a component that names an explicitly required component. For example, in the example above, if you spawn the Enemy + EnemyTarget components, then remove the EnemyTarget component, then insert the Enemy component again, you get a panic! This can make the panics more non-deterministic.

[MrGVSV]

This could be surprising behavior to users who name their constructor explicit (for whatever reason). Could we make sure this is at least documented?

Alternatively we could do #[requires(explicit = true)] and peeking for = could be used to disambiguate the two. Not sure that's totally worth the ergonomics hit though.

[mockersf]

Would it be possible to find different words for require as in "automatically added if not present when adding this component" and require as in "must be present when adding this component"

Maybe "dependent" for the current require?

[andriyDev]

Closed as per the discussion in #16194.