---
name: bevy-upgrade
description: Migrate Bevy (Rust game engine) projects between versions, 0.15 through 0.19. Rename tables, semantic behavior shifts, and a per-bump migration workflow. Use when the task bumps the bevy version in Cargo.toml, fixes compile errors after an upgrade, or modernizes code using removed APIs (Parent, EventWriter/EventReader, despawn_recursive, derive(Bundle), StateScoped). For writing new code on the current version, defer to the bevy-0.19 skill.
---

# Bevy Upgrade

Bevy ships breaking changes every minor release. Upgrades are tractable if run as a disciplined loop — one minor version at a time, mechanical renames before semantic fixes, behavior shifts verified by running the game, not just compiling it.

## Workflow

1. **Establish current and target versions.** Read `Cargo.toml` (`bevy` plus ecosystem crates — each is pinned to a Bevy minor and must be bumped in lockstep).
2. **Upgrade one minor version at a time.** Skipping versions compounds renames and makes errors unattributable. For each bump:
   1. Bump `bevy` and every Bevy-ecosystem crate to versions compatible with the target. If an ecosystem crate has no compatible release, stop and surface it — that blocks the bump.
   2. `cargo check`, then apply the **rename table** for the transition (see references) across all errors. These are mechanical.
   3. Fix remaining compile errors using the transition's **API shape changes** (signatures, moved modules, new required destructuring).
   4. Audit for the transition's **semantic shifts** — changes that compile clean but behave differently. Grep for the listed patterns; these do not announce themselves.
   5. `cargo check` clean → run the game / test suite and smoke-test the areas the semantic shifts touch.
3. **Anything not covered by the references**: fetch the official migration guide at `https://bevy.org/learn/migration-guides/<from>-to-<to>/` and work through it — the references cover the high-frequency changes, not every niche API.
4. **Post-migration cleanup**: once on the target version, use the **bevy-0.19** skill to rewrite awkward mechanically-ported code into current idioms (e.g. old buffered events that should now be observers, manual child bookkeeping that relationships handle).

## Transition references

Load only the transitions on your path:

| File | Covers |
|------|--------|
| `references/0.15-to-0.17.md` | 0.15→0.16 and 0.16→0.17: `Parent`→`ChildOf`, recursive `despawn`, bundle removal, `StateScoped` replacement |
| `references/0.17-to-0.18.md` | The largest transition: Event/Message split, fallible systems, state-transition semantics, renames across hierarchy/render/input |
| `references/0.18-to-0.19.md` | Resources-as-components, `Scene`→`WorldAsset`, asset API changes |

## Detecting the source version from code

When `Cargo.toml` is ambiguous (workspace inheritance, git deps), the code itself dates the project:

| You see | Version is |
|---------|-----------|
| `Parent`, `despawn_recursive()`, `#[derive(Bundle)]`, `StateScoped` | ≤0.15 |
| `ChildOf` but `EventWriter`/`EventReader`/`on_event` | 0.16–0.17 |
| `MessageWriter`/`MessageReader`, `-> Result` systems | 0.18+ |
| `WorldAsset`/`WorldAssetRoot`, `Without<IsResource>` filters | 0.19 |

## The traps of upgrading

- **Renames that compile but misbehave**: some old names still exist with new meaning. `Event` compiles in 0.18+ but means observer-events, not buffered messages — a mechanical `EventWriter → MessageWriter` port is right, but a type left as `#[derive(Event)]` and "written" nowhere fires no observers silently.
- **Behavior shifts need runtime verification**: `NextState::set()` same-state re-firing (0.18), transform-propagation reads, `Query<Entity>` matching resource entities (0.19). `cargo check` proves nothing here — run it.
- **Ecosystem crates lag.** A Bevy bump is only as ready as its slowest dependency. Check compatibility before starting, not after.
- **Don't modernize mid-bump.** During a bump, make the minimal change that satisfies the new API; idiomatic rewrites happen after the chain is complete (with the bevy-0.19 skill). Mixing the two makes regressions unattributable.

## Related skill

**bevy-0.19** — writing correct, idiomatic code on the current version. Use it after the migration chain completes, and whenever the task turns from porting into feature work.