Mutually Exclusive Components

[ickk]

What problem does this solve or what need does it fill?

Provide a way to declare two or more components as "mutually exclusive". That is if ComponentA and ComponentB are mutually exclusive, only one of ComponentA or ComponentB may exist on an Entity at a given time.

What solution would you like?

1. An annotation or derive macro that marks two or more components as xor, or another way to register the relationship with the application.

2. When a ComponentA is added to an Entity that already has a ComponentB, then ComponentB will be automatically & atomically removed, thus upholding the invariant.

3. Queries could be made aware of mutually exclusive components, and add implicit Without filters as appropriate. That is Query<.., With<ComponentA>> is equivalent to Query<.., (With<ComponentA>, Without<ComponentB>)>.

   This works to allow a system to have both Query<&mut T, With<ComponentA>> and Query<&mut T, With<ComponentB>>, without the user needing to explicitly write the Without filters.

4. It should be possible for the user to add a ComponentC to an existing set of mutually exclusive components defined by a 3rd party.

What alternative(s) have you considered?

Enum Components provide similar xor behaviour, however the entire enum must be queried and then branched on inside systems. Additionally, it is not possible to add variants to an existing enum (point 4 of the previous section).

Additional context

This is kinda sorta the inverse of "Required Components", but it provides a stronger invariant (xor-ness should always be maintained) and can integrate more meaningfully into queries & systems, rather than acting only at bundle insertion time.

I'm sure I've seen this idea floating around before, so this is an attempt to formalise the feature request. (Maybe it should be an rfc?)

[tbillington]

Thanks for raising this, something like it would be a nice ergonomic win.

I'm not sold on automatically resolving conflicts though. Would it also remove components that were added by required components? To me it feels much more like a logic error, eg I've accidentally added Player to an entity with NPC and I'd rather it fail, not make any changes, and log an error.

[HackerFoo]

This would be useful to me. I'm using typed transforms in my app, so this could help make queries more succinct.

I think I'd prefer to manually remove conflicting components, though, so maybe inserting them should be an error. Maintaining mutual exclusivity could allow the ECS to store sets of mutually exclusive components as an enum, or make other optimizations.

Maybe a minimal implementation could just handle mutually exclusive markers (ZSTs), which would be very useful.

[alice-i-cecile]

This is a duplicate / subset of #1481. Please collect discussion there.