Archetype Invariants
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 22h
- Merged PRs (30d)
- 161
Description
Introduced in [#1312](https://github.com/bevyengine/bevy/discussions/1312#discussioncomment-347678). The complete design will be found at [RFC #5](https://github.com/bevyengine/rfcs/pull/5).
# The Basics
An *archetype* is the set of components that are found together on a single entity. The set of *archetypes* present in our `World` is the union of the archetypes of every entity in the world.
**Archetype invariants** are rules that limit which components can coexist, limiting the possible archetypes that can co-occur. Because of the flexible power of `commands.spawn` and `commands.insert`, the components that an entity could have is unknowable at compile time, preventing us from .
We can use this information to allow for more granular component access in ways that would otherwise result in inconsistent runtime behavior, or verify that certain logical rules are followed during execution.
Due to the overhead of verifying these rules against the `World`'s archetypes, this is likely best done only during debug mode, or perhaps by post-hoc inspection of logs.
# Use Cases
1. Reducing false positives in system scheduling ambiguity detection (#1312)
2. Assumption checking for safety
3. More granular overlapping queries (to expand on #1320)
# API for specifying archetype invariants
**Primitives:**
- `forbidden(my_bundle)`: an entities archetype cannot have have the specific combination of components listed in the bundle as a subset
- 'A.always_with(B)': entities that have component A always also have component B
- `A.only_with(my_bundle)': component A never occurs with components other than those in the bundle
**Derived:**
- `inseparable(my_bundle)`: entities that have either component A or B never occur without each other. Equivalent to combining `A.always_with(B)` with the reverse for every pairwise combination
- `disjoint(my_bundle)`: entities can only have at most one component in the bundle. Equivalent to creating a `forbidden` archetype invariant for each pairwise combination
- bundle versions of all of the primitives, where A and B can be replaced by tuples of components (bundles) instead
Contributor guide
Assessment
This issue has not been assessed yet.