Bevy design doc

bevy_tdd_template.md

Bevy Design Document / RFC Template

Metadata

• Feature name: snake_case_name
• Status: Draft | In review | Accepted | Rejected
• Target Bevy version: e.g. 0.18
• Author(s):
• Related issues / PRs / discussions: links only

---

Quality bar (delete this block before submitting)

A reviewer must be able to accept or reject this document from the core sections alone, without reading the appendix.

• Length: core sections ≤ 250 lines total. If you need more, the design is probably too big for one doc — split it, or push detail to the Appendix.
• No padding: omit sections that don't apply rather than filling them.
• No repetition: state each point once. Don't restate the summary in the motivation, or the motivation in the implementation.
• Show, don't narrate: prefer a short code block over a paragraph describing what the code would look like. One good example beats three sentences.
• No pedantry: skip obvious justifications and background a Bevy contributor already knows. Assume the reader knows the ECS, schedules, plugins, and App.
• Concrete over abstract: name the actual types, systems, and crates involved, not "a component" or "the relevant system".

---

Summary [Core]

One paragraph: what this proposes and the outcome a Bevy user gets. No implementation detail. A teammate should understand the gist from this alone.

Motivation [Core]

What problem does this solve, framed from the perspective of someone using Bevy? What use cases does it unblock, and what is bad or missing today? State the requirements a solution must meet — the what, not the how. Frame these so that if this proposal is rejected, the constraints still stand for an alternative.

Non-goals [If relevant]

What this explicitly does not cover. Often the fastest way to bound scope.

Assumptions [If relevant]

What must be true for this to work (e.g. a dependency on an unmerged RFC, an existing engine capability, a feature flag). List only load-bearing assumptions.

User-facing explanation [Core]

Explain the feature as if it already shipped and you're teaching a Bevy user:

• Introduce new named concepts and how they fit the existing mental model (components, systems, resources, events, schedules, plugins, queries, assets, reflection, etc.).
• Show the API through small, concrete examples — spawning, querying, the system signature, the plugin/App setup. Code blocks, not prose.
• If applicable, show sample error messages, panics, deprecation warnings, or migration snippets.
• If it resembles an existing feature, say when a user would reach for each.

Implementation strategy [Core]

Enough detail that two contributors would build roughly the same thing:

• Where it lives: which crate/module/plugin; new vs. modified types.
• How it interacts with the rest of the engine: schedule/system ordering, the render graph, asset pipeline, reflection, App builder, etc.
• Data layout and ECS fit: components vs. resources, archetype impact, queries, SystemParams, exclusive vs. parallel systems.
• Corner cases, dissected by example (return to the examples above).
• Feature-flag gating and optional dependencies, if any.

Performance & memory considerations [If relevant]

Frame-time and allocation impact: parallelism, archetype fragmentation, per-frame allocations, cache behavior, scaling with entity/system count. Note any benchmarks you'll add. Quantify where you can; flag where you're guessing.

Safety, soundness & determinism [If relevant]

unsafe introduced and why it's sound; panic conditions; thread-safety (Send/Sync) implications; and determinism if it touches networking, replays, or fixed-timestep simulation.

Migration & compatibility [If relevant]

Is this a breaking change? Sketch the migration guide entry, deprecation path, and whether old and new APIs can coexist behind a flag for a release.

Testing & validation [If relevant]

How this is tested: unit tests, a new examples/ entry, benchmarks, CI. What "working" looks like and how a reviewer or implementer would verify it.

Alternatives considered [Core]

What else was considered and why it was discarded — including relevant prior art from other engines or Bevy plugins. Be brief; link out for detail but always give an inline summary. Note the cost of doing nothing. If an alternative is wrong now but plausible later, mention the migration path.

Risks & unresolved questions [Core]

Open questions that affect the design and how you'll resolve them; what you expect to settle during the RFC vs. during implementation; one-way doors; external/away-team dependencies.

Work required [If relevant]

High-level breakdown with t-shirt sizes (S / M / XL). Call out work that needs another team or an upstream dependency.

Future possibilities [If relevant]

Natural extensions, kept short. Note: anything here is not a reason to accept this proposal — if it's load-bearing, move it to Motivation or Alternatives.

References & Appendix [If relevant]

Links, and any supplementary material (full benchmarks, long code listings, prototype branches). Nothing the accept/reject decision depends on belongs here.

---

Reviewer self-check (delete before submitting)

• Core sections decide accept/reject without the appendix.
• Core sections ≤ 250 lines.
• No "N/A" sections — irrelevant ones deleted.
• No point made more than once.
• Examples are code, not descriptions of code.
• Every new term defined at first use; actual types/crates named.