Mutually Exclusive Components

[eugineerd]

Goal Description

Certain components in an ECS can be used to define variants of some behavior and shouldn't exist on the same entity (like RigidBody and StaticBody in a physics engine). Bevy should have an ergonomic way to represent these types of components while taking advantage of the parallel execution of systems with components that are mutually exclusive.

Goal Status

This is a potential Bevy Project Goal. Its state on the Project Goals Board determines if it is Proposed, Postponed, Blocked (Approved), Inactive (Approved), Active (Approved), Completed, or Declined.

• Staffing SMEs: Not yet staffed
• Working Group Link: Working Group not yet formed
• Design Documents: Design documents not yet written

[eugineerd]

Currently there are two main ways to represent this behavior in Bevy: an enum component or OnInsert hooks, both of which have problems.

An enum logically represents mutual exclusivity at the type level, however a specific variant can't be queried for since it's not a component by itself, requiring filtering inside the system and reducing parallelism. Even if we make enums queryable by utilizing fragmenting value components,enums are closed set and variants can't be added without source code modification, which makes it inconvenient for users who want to extend the behaviors with their own variants.

OnInsert hooks allow to represent mutually exclusive components as separate types, which makes it easy to query for them and unlocks parallel execution of systems, but they aren't very ergonomic. The logic required for mutual exclusivity lives inside the hooks and must be implemented manually. Since different libraries might implement it in slightly different ways, this creates additional friction to users. The non-declarative nature of this approach also makes it impossible to take advantage of the fact that mutually exclusive components can't exist on the same archetype, which can unlock additional inter-system parallelism and allow queries with mutually exclusive components inside the same system to assert that they aren't overlapping without requiring additional Without filters.

[Jondolf]

For additional motivation, this is desired by Avian, as we would like to replace the RigidBody enum with mutually exclusive marker components that can be queried and observed separately (as suggested in the goal description). This would also allow us to have different component requirements for different body types, for example dynamic bodies require storing mass and velocity, while static bodies don't. With an enum, specifying different requirements like this is not possible without manually inserting components at spawn, which would involve archetype moves and be less robust.

[alice-i-cecile]

I would be interested in helping shepherd this goal as an SME, but don't currently have bandwidth to do so.