reliquary/plugins/bevy/skills/bevy-upgrade/SKILL.md

name, description

name

description

bevy-upgrade

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.