dirigence/reliquary
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

🤖 Flesh out bevy-0.19 and bevy-upgrade skills from research

Browse Source 
Replace scaffold placeholders with full skill content:
- bevy-0.19: ECS cheat sheet, critical traps table, architecture guide, and 7 reference files
- bevy-upgrade: version migration workflow, transition references for 0.15→0.19, and 3 per-bump reference files
This commit is contained in:
Gabor Körber
2026-07-07 17:52:10 +02:00
parent 325e278af1
commit c661027d19
14 changed files with 927 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/bevy/skills/bevy-upgrade/SKILL.md
+42 -23
View File
@@ -1,33 +1,52 @@
---
name: bevy-upgrade
description: "TODO: Use the skill-creator skill to write this. See scaffolding goals below."
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 — Version Migration Guide
# Bevy Upgrade
> **This skill is a scaffold.** Use `/skill-creator` to create the full skill content from the research material.
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.
## Scaffolding Goals
## Workflow
1. **Use the `skill-creator:skill-creator` skill** to create the full SKILL.md content
2. Feed it the version-change annotations from research reports 01-06 in [`docs/workpad/research/bevy-skill-research/`](../../../../docs/workpad/research/bevy-skill-research/00-index.md)
3. The skill should trigger when the user asks to upgrade/migrate Bevy versions, or when the `bevy` skill detects upgrade work
4. Core content:
- Breaking-change chain from 0.16 through 0.19+
- Rename tables (old name -> new name, which version)
- Semantic shifts (behavior changes, not just renames)
- Step-by-step migration patterns for each version bump
- Common upgrade pitfalls and their fixes
5. Populate `references/` with per-version-transition files (e.g., `0.17-to-0.18.md`, `0.18-to-0.19.md`)
6. The skill should be invocable both directly and from the `bevy` skill
1. **Establish current and target versions.** Read `Cargo.toml` (`bevy` plus ecosystem crates: physics, UI, networking — 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).
## Reference Material
## Transition references
Same research as the `bevy` skill — version-change annotations are woven into each report:
Load only the transitions on your path:
- [01-plugins.md](../../../../docs/workpad/research/bevy-skill-research/01-plugins.md) — Plugin API changes across versions
- [02-ecs-core.md](../../../../docs/workpad/research/bevy-skill-research/02-ecs-core.md) — ECS API renames and new patterns
- [03-hierarchy.md](../../../../docs/workpad/research/bevy-skill-research/03-hierarchy.md) — Parent->ChildOf transition
- [04-events-observers.md](../../../../docs/workpad/research/bevy-skill-research/04-events-observers.md) — Event/Message split
- [05-input.md](../../../../docs/workpad/research/bevy-skill-research/05-input.md) — Input API changes
- [06-camera-gotchas.md](../../../../docs/workpad/research/bevy-skill-research/06-camera-gotchas.md) — Camera API changes
| 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**: `State::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.