Archetype Invariants

[alice-i-cecile]

Introduced in #1312. The complete design will be found at RFC #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 (Ambiguous system ordering #1312)
2. Assumption checking for safety
3. More granular overlapping queries (to expand on Less permissive component conflict allowance in system queries #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

[alice-i-cecile]

A new thing that I want: element_of(bundle), which allows for "any one of the underlying components" and can be dropped in anywhere you could put a component. This enables enum-like component groups in a really nice way.

For context, I want this for overriding behavior in a checked and elegant way.

[alice-i-cecile]

As an interesting twist: a user asked in #1635 to enforce that a resource must always exist. In theory, because #1525 stores resources as components on a singleton entity, we could provide a wrapper to ensure that, by tying it to a Resource marker component or the like.

While I think that archetype invariants are the right tool for ultimately solving the other requests in #1635, I'm much less convinced on this use case. It feels like it's exploiting a quirk of the implementation details, and that systems panicking when they request a resource that doesn't exist gets us the desired behavior already.