diff --git a/rfcs/archetype-invariants.md b/rfcs/archetype-invariants.md new file mode 100644 index 00000000..bca4fcd8 --- /dev/null +++ b/rfcs/archetype-invariants.md @@ -0,0 +1,78 @@ +# Feature Name: `archetype-invariants` + +## Summary + +**Archetype invariants** are global rules about which archetypes can exist in a Bevy app's ECS. +By defining which components must or cannot coexist, we can enforce domain-specific rules to ensure correctness. +Once these rules are encoded into our ECS, we can leverage them to improve performance in a large variety of ways. + +## Motivation + +TODO: Complete. + +Why are we doing this? What use cases does it support? + +## Guide-level explanation + +TODO: Complete. + +Explain the proposal as if it was already included in the engine and you were teaching it to another Bevy user. That generally means: + +- Introducing new named concepts. +- Explaining the feature, ideally through simple examples of solutions to concrete problems. +- Explaining how Bevy users should *think* about the feature, and how it should impact the way they use Bevy. It should explain the impact as concretely as possible. +- If applicable, provide sample error messages, deprecation warnings, or migration guidance. +- If applicable, explain how this feature compares to similar existing features, and in what situations the user would use each one. + +## Reference-level explanation + +TODO: Complete. + + +This is the technical portion of the RFC. Explain the design in sufficient detail that: + +- Its interaction with other features is clear. +- It is reasonably clear how the feature would be implemented. +- Corner cases are dissected by example. + +The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work. + +## Drawbacks + +TODO: Complete. + +Why should we *not* do this? + +## Rationale and alternatives + +TODO: Complete. + +- Why is this design the best in the space of possible designs? +- What other designs have been considered and what is the rationale for not choosing them? +- What is the impact of not doing this? +- Why is this important to implement as a feature of Bevy itself, rather than an ecosystem crate? + +## Unresolved questions + +TODO: Complete. + +- What parts of the design do you expect to resolve through the RFC process before this gets merged? +- What parts of the design do you expect to resolve through the implementation of this feature before the feature PR is merged? +- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? + +## \[Optional\] Future possibilities + +TODO: Complete. + +Think about what the natural extension and evolution of your proposal would +be and how it would affect Bevy as a whole in a holistic way. +Try to use this section as a tool to more fully consider other possible +interactions with the engine in your proposal. + +This is also a good place to "dump ideas", if they are out of scope for the +RFC you are writing but otherwise related. + +Note that having something written down in the future-possibilities section +is not a reason to accept the current or a future RFC; such notes should be +in the section on motivation or rationale in this or subsequent RFCs. +If a feature or change has no direct value on its own, expand your RFC to include the first valuable feature that would build on it.