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

✨ Scaffold bevy plugin with bevy-0.19 and bevy-upgrade skills

Browse Source 
Add plugin skeleton with versioned skill directories, TODO SKILL.md
scaffolds with goals for skill-creator, and copy over bevy-skill-research
reports from spacecraft into docs/workpad/research/.
This commit is contained in:
Gabor Körber
2026-07-07 17:52:00 +02:00
parent 8545738a05
commit 325e278af1
13 changed files with 1211 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workpad/research/bevy-skill-research/00-index.md
+105
View File
@@ -0,0 +1,105 @@
# Bevy Skill Research — Index
> **Date**: 2026-07-07
## What We Want to Create
A **Claude Code skill for Bevy game engine development** — primarily an **implementation helper** that teaches how to correctly write Bevy code: how to structure plugins, compose systems, define components, handle events, manage hierarchy, process input, and avoid the silent failures that Bevy's flexible ECS makes easy to walk into.
The skill is NOT a migration guide or changelog. Its primary job is: **when an agent is writing or modifying Bevy code, it should produce correct, idiomatic code for the current version.**
However, because Bevy's rapid release cycle (0.16→0.17→0.18→0.19 in ~18 months) introduces fundamental renames and semantic shifts, the skill also needs **version-aware reference material** for situations like upgrades. An agent asked to migrate from 0.18 to 0.19 needs to know what changed and why — not just what the current API looks like. So the migration chain knowledge is retained as reference, not thrown away.
## How This Research Evolved
### Initial idea: upgrade-focused
The research started when we saw an agent fetch Bevy's 0.18→0.19 migration guide during an upgrade task. The question was: should a Bevy skill hold the migration chain as its core content, so agents don't have to fetch and parse migration guides at runtime?
### The pivot: implementation-focused
We quickly realized the migration chain is a **secondary use case**. The primary problem — confirmed by blog posts, community discussions, and this project's 1500+ lines of errata — is that LLMs confidently generate Bevy code against **outdated or incorrect patterns** during normal day-to-day implementation work. The skill's core content should teach **how to write correct Bevy code**, organized by topic (plugins, ECS, events, hierarchy, input, camera), not by version transition.
### What we researched
Two complementary knowledge sources, reflecting the two purposes:
1. **Official API truth** (reports 01–06) — how Bevy's subsystems actually work in 0.18/0.19, with version-change annotations where LLMs are most likely to use stale patterns. This is the **implementation helper** core.
2. **Production battle scars** (report 07) — gotchas extracted from a production Bevy 0.18 multiplayer game's errata, neutralized into generic examples. These are the "not in any docs" patterns that cost real debugging time. Also **implementation helper** material.
3. **Landscape survey and design options** (report 08) — ecosystem survey confirming no adequate skill exists, plus three architectural approaches with tradeoffs. This informs **how to build the skill**, not what goes in it.
The migration chain knowledge (0.16→0.17→0.18→0.19 breaking changes) is woven into reports 01–06 as annotations rather than being a standalone topic — because the skill's primary audience is an agent writing code today, not an agent performing a version migration. But the annotations are there, and a reference folder can hold the full migration details for when that situation arises.
## Why We Did This Research
1. **No adequate public skill exists.** We surveyed the ecosystem (see report 08) and found nothing usable for Bevy 0.18+. The best candidate (bfollington/terma, 154 installs) covers only up to 0.17 and would actively mislead on current APIs.
2. **This project already has better Bevy knowledge than any public skill** — but it's locked in project-specific errata and CLAUDE.md files. A skill would extract and generalize that knowledge for reuse.
3. **The skill needs to serve two modes**: day-to-day implementation (always-loaded, compact) and version migration (on-demand, detailed). The research captures content for both.
4. **The skill design has multiple viable approaches** with real tradeoffs around size, scope, and maintenance burden (report 08). This research captures the options before committing.
## Reports
### API Ground Truth (from official docs and migration guides)
| # | File | Topic |
|---|------|-------|
| 1 | [01-plugins.md](01-plugins.md) | Plugin trait lifecycle, dependencies, states, schedules, run conditions |
| 2 | [02-ecs-core.md](02-ecs-core.md) | Components, resources, systems, queries, commands, ordering |
| 3 | [03-hierarchy.md](03-hierarchy.md) | ChildOf relationships, spawning/querying children, transform propagation |
| 4 | [04-events-observers.md](04-events-observers.md) | Message/Event split (0.18), observers, lifecycle triggers, hooks |
| 5 | [05-input.md](05-input.md) | Keyboard, mouse, gamepad, touch input patterns |
| 6 | [06-camera-gotchas.md](06-camera-gotchas.md) | Camera setup, rendering, coordinates, full LLM-trap table |
### Production Knowledge and Design
| # | File | Topic |
|---|------|-------|
| 7 | [07-lessons-from-production.md](07-lessons-from-production.md) | 15 neutralized gotchas from a production Bevy 0.18 multiplayer game |
| 8 | [08-landscape-and-design-sketch.md](08-landscape-and-design-sketch.md) | Ecosystem survey, skill architecture options, content priorities |
## Skill Design Approaches Under Consideration
### Approach A: Single Compact Skill + Reference Folder
One `bevy` skill file (~500 lines) with the critical "don't get this wrong" content always loaded. Deeper reference docs in a `references/bevy/` folder that the LLM can read on demand.
- **Pro**: Low per-trigger context cost, deep knowledge available when needed
- **Con**: Two things to maintain (skill + references)
### Approach B: Single Comprehensive Skill
Everything in one skill file (~1500 lines). Always loaded, always complete.
- **Pro**: Simple, no secondary lookups needed
- **Con**: Heavy context cost every trigger (~3-4k tokens), may crowd out project-specific context
### Approach C: Multiple Topic Skills
Split into `bevy-ecs`, `bevy-events`, `bevy-rendering` etc. Each triggers independently based on what code is being touched.
- **Pro**: Granular — only loads what's relevant
- **Con**: More files, more trigger descriptions to maintain, fragmented knowledge for cross-cutting concerns
### Current Recommendation
**Approach A** — compact always-loaded cheat sheet with reference folder. The skill triggers broadly on any Bevy work, loads the critical renames/gotchas/decision guides (~500 lines), and points to reference docs for deeper dives on specific topics.
## Content Priority (What LLMs Get Wrong Most)
Ranked by frequency of incorrect generation:
1. Event → Message rename and the Event/Message split (0.18)
2. ChildOf replacing Parent (0.16+), children iteration patterns
3. `-> Result` fallible systems (0.18)
4. Coordinate system (+Y up, -Z forward) vs GLTF (+Z forward)
5. Transform propagation timing (PostUpdate, not Update)
6. Resources-as-Components in 0.19
7. Material bind groups — group 3, not group 2
8. State::set() same-state transitions now fire (0.18)
9. Asset cache poisoning via load_with_settings
10. Schedule-dependent spawning breaking plugin expectations