From c661027d19f9c8f041f1bd80024c2049edea2186 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabor=20K=C3=B6rber?= Date: Tue, 7 Jul 2026 17:52:10 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20Flesh=20out=20bevy-0.19=20and=20?= =?UTF-8?q?bevy-upgrade=20skills=20from=20research?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- plugins/bevy/CLAUDE.md | 2 +- plugins/bevy/README.md | 2 +- plugins/bevy/skills/bevy-0.19/SKILL.md | 204 +++++++++++++++--- .../bevy-0.19/references/camera-rendering.md | 71 ++++++ .../bevy/skills/bevy-0.19/references/ecs.md | 87 ++++++++ .../bevy-0.19/references/events-observers.md | 105 +++++++++ .../skills/bevy-0.19/references/hierarchy.md | 65 ++++++ .../bevy/skills/bevy-0.19/references/input.md | 71 ++++++ .../bevy-0.19/references/plugins-and-app.md | 86 ++++++++ .../references/production-gotchas.md | 93 ++++++++ plugins/bevy/skills/bevy-upgrade/SKILL.md | 65 ++++-- .../bevy-upgrade/references/0.15-to-0.17.md | 36 ++++ .../bevy-upgrade/references/0.17-to-0.18.md | 57 +++++ .../bevy-upgrade/references/0.18-to-0.19.md | 36 ++++ 14 files changed, 927 insertions(+), 53 deletions(-) create mode 100644 plugins/bevy/skills/bevy-0.19/references/camera-rendering.md create mode 100644 plugins/bevy/skills/bevy-0.19/references/ecs.md create mode 100644 plugins/bevy/skills/bevy-0.19/references/events-observers.md create mode 100644 plugins/bevy/skills/bevy-0.19/references/hierarchy.md create mode 100644 plugins/bevy/skills/bevy-0.19/references/input.md create mode 100644 plugins/bevy/skills/bevy-0.19/references/plugins-and-app.md create mode 100644 plugins/bevy/skills/bevy-0.19/references/production-gotchas.md create mode 100644 plugins/bevy/skills/bevy-upgrade/references/0.15-to-0.17.md create mode 100644 plugins/bevy/skills/bevy-upgrade/references/0.17-to-0.18.md create mode 100644 plugins/bevy/skills/bevy-upgrade/references/0.18-to-0.19.md diff --git a/plugins/bevy/CLAUDE.md b/plugins/bevy/CLAUDE.md index 1112425..2965f6e 100644 --- a/plugins/bevy/CLAUDE.md +++ b/plugins/bevy/CLAUDE.md @@ -1 +1 @@ -Bevy game engine skills. The `bevy` skill is the primary implementation helper; `bevy-upgrade` handles version migrations and is invoked by `bevy` when upgrade work is detected. +Bevy game engine skills. The `bevy-0.19` skill is the primary implementation helper; `bevy-upgrade` handles version migrations and is invoked by `bevy-0.19` when upgrade work is detected. diff --git a/plugins/bevy/README.md b/plugins/bevy/README.md index 5ccad29..010a66e 100644 --- a/plugins/bevy/README.md +++ b/plugins/bevy/README.md @@ -7,7 +7,7 @@ Bevy's rapid release cycle (0.16 through 0.19 in ~18 months) introduces fundamen ## Skills - **bevy-0.19** — Implementation helper for writing correct, idiomatic Bevy 0.19 code. Covers plugins, ECS, hierarchy, events/observers, input, camera, and production gotchas. Triggers on Bevy 0.19 Rust code. Contains a compact always-loaded cheat sheet plus a `references/` folder for deeper topic dives. -- **bevy-upgrade** — Version migration guide for upgrading between Bevy releases. Covers the breaking-change chain (0.16 through 0.19+) with rename tables, semantic shifts, and step-by-step migration patterns. Invoked by the `bevy` skill when an upgrade task is detected, or directly when the user asks to migrate. +- **bevy-upgrade** — Version migration guide for upgrading between Bevy releases. Covers the breaking-change chain (0.16 through 0.19+) with rename tables, semantic shifts, and step-by-step migration patterns. Invoked by the `bevy-0.19` skill when an upgrade task is detected, or directly when the user asks to migrate. ## Research diff --git a/plugins/bevy/skills/bevy-0.19/SKILL.md b/plugins/bevy/skills/bevy-0.19/SKILL.md index 99a32ef..e9e40a2 100644 --- a/plugins/bevy/skills/bevy-0.19/SKILL.md +++ b/plugins/bevy/skills/bevy-0.19/SKILL.md @@ -1,38 +1,186 @@ --- name: bevy-0.19 -description: "TODO: Use the skill-creator skill to write this. See scaffolding goals below." +description: Write and navigate Bevy 0.19 (Rust game engine) code — ECS, plugins, systems, queries, events/messages, hierarchy, input, camera, rendering, assets. Use whenever editing Rust code that imports bevy, or the task involves Bevy components, systems, entity spawning, or game architecture. Pre-training knowledge of Bevy APIs is stale; consult this before writing Bevy code. For version migrations, defer to the bevy-upgrade skill. --- -# Bevy 0.19 — Implementation Helper +# Bevy 0.19 -> **This skill is a scaffold.** Use `/skill-creator` to create the full skill content from the research material. +Bevy's API changes fundamentally between minor versions. Code that looks correct from memory frequently targets 0.14–0.17 APIs and either fails to compile or — worse — compiles and silently misbehaves. This skill is ground truth for 0.19. -## Scaffolding Goals +## Step 0: Confirm the version -1. **Use the `skill-creator:skill-creator` skill** to create the full SKILL.md content -2. Feed it the research reports from [`docs/workpad/research/bevy-skill-research/`](../../../../docs/workpad/research/bevy-skill-research/00-index.md) -3. Follow **Approach A** from the [design sketch](../../../../docs/workpad/research/bevy-skill-research/08-landscape-and-design-sketch.md): compact always-loaded cheat sheet (~500 lines) plus `references/` folder for deep dives -4. The skill should trigger on Bevy 0.19 Rust code (`bevy = "0.19"` in Cargo.toml, `use bevy::prelude::*`, `App::new()`, `#[derive(Component)]`, etc.) -5. Core content priorities (ranked by LLM error frequency): - - Event/Message rename and split (0.18) - - ChildOf replacing Parent (0.16+) - - Fallible systems with `-> Result` (0.18) - - Coordinate system gotchas - - Transform propagation timing - - Resources-as-Components (0.19) -6. Populate `references/` with per-topic deep-dive files derived from research reports 01-07 -7. The skill should know about `bevy-upgrade` and invoke it when upgrade/migration work is detected +Check `Cargo.toml` for the `bevy` version before writing code. -## Reference Material +- **0.19** — this skill applies directly. +- **0.18** — most of this skill applies; 0.19-only notes are marked. Do not use 0.19-only APIs. +- **≤0.17, or the task is a version bump/migration** — use the **bevy-upgrade** skill. It owns rename tables and semantic shifts per version transition. Come back here for writing new idiomatic code once the target version is settled. -The research that feeds this skill lives in the workpad: +## Critical traps -- [00-index.md](../../../../docs/workpad/research/bevy-skill-research/00-index.md) — Research overview and design rationale -- [01-plugins.md](../../../../docs/workpad/research/bevy-skill-research/01-plugins.md) — Plugin lifecycle -- [02-ecs-core.md](../../../../docs/workpad/research/bevy-skill-research/02-ecs-core.md) — ECS fundamentals -- [03-hierarchy.md](../../../../docs/workpad/research/bevy-skill-research/03-hierarchy.md) — Hierarchy and ChildOf -- [04-events-observers.md](../../../../docs/workpad/research/bevy-skill-research/04-events-observers.md) — Events, messages, observers -- [05-input.md](../../../../docs/workpad/research/bevy-skill-research/05-input.md) — Input handling -- [06-camera-gotchas.md](../../../../docs/workpad/research/bevy-skill-research/06-camera-gotchas.md) — Camera and rendering -- [07-lessons-from-production.md](../../../../docs/workpad/research/bevy-skill-research/07-lessons-from-production.md) — Production gotchas -- [08-landscape-and-design-sketch.md](../../../../docs/workpad/research/bevy-skill-research/08-landscape-and-design-sketch.md) — Architecture options +The highest-frequency mistakes. When in doubt, trust this table over memory: + +| Trap | Wrong (stale) | Correct (0.18/0.19) | +|------|---------------|---------------------| +| Parent component | `Parent` | `ChildOf(entity)` | +| Get parent | `*child_of` (deref) | `child_of.parent()` | +| Child iteration | `children.iter().copied()` | `for child in &children` | +| Recursive despawn | `despawn_recursive()` | `despawn()` (recursive by default) | +| Buffered events | `EventWriter`/`EventReader` | `MessageWriter`/`MessageReader` | +| Run condition | `on_event::()` | `on_message::()` | +| Bundles | `#[derive(Bundle)]` | spawn tuples + `#[require(...)]` | +| System errors | infallible `fn(...)` everywhere | `fn(...) -> Result` where fallible | +| Forward direction | +Z | **-Z** (`Transform::forward()`) | +| GLTF model forward | -Z like Bevy | **+Z** — negate or use `transform.back()` | +| `GlobalTransform` in `Update` | assumed current | stale — propagation runs in `PostUpdate` | +| Material shader bind group | `@group(2)` | `@group(3)` (group 2 is mesh bindings) | +| Same-state `set()` | no-op | fires `OnExit`+`OnEnter`; use `set_if_neq()` | +| `AmbientLight` | one global type | `GlobalAmbientLight` resource vs `AmbientLight` camera component | +| `ShaderRef` import | `bevy::render::render_resource` | `bevy::shader::ShaderRef` | +| `WinitPlugin` | `WinitPlugin::` | `WinitPlugin` (not generic) | + +**0.19-specific:** + +| Trap | Detail | +|------|--------| +| Resources are components | Resources live on entities; `Query` matches them — filter broad queries with `Without`. Cannot derive both `Component` and `Resource` on one type. | +| Scene renamed | `Scene`/`SceneRoot` → `WorldAsset`/`WorldAssetRoot` | +| `Ref.clone()` | Returns `Ref`, not the inner value — use `ref.deref().clone()` | +| `Assets::get_mut` | Returns `AssetMut` (mutation-tracked), not `&mut A` | +| GLTF materials | Return `GltfMaterial`; use `#Material0/std` label for `StandardMaterial` | + +## ECS core + +### Components + +```rust +#[derive(Component)] +struct Health(f32); + +#[derive(Component)] +#[require(Transform, Visibility)] // auto-inserted when Player is added +struct Player; +``` + +- `#[require(B, C)]` replaces bundles: spawning the marker pulls in its dependencies. Constructors work: `#[require(Speed(5.0))]`, `#[require(Timer = default_timer())]`. +- `#[component(immutable)]` (0.18+) forbids `&mut T` access. +- `#[component(storage = "SparseSet")]` for frequently added/removed components. +- Lifecycle hooks: `#[component(on_add = f)]`, also `on_insert`, `on_replace`, `on_remove`, `on_despawn` — synchronous, inline with the ECS operation. + +### Systems + +Plain functions of `SystemParam`s. Make fallible systems return `Result` (0.18+) — errors log and the system retries next tick; `?` works with anything convertible to `BevyError`: + +```rust +fn apply_damage(mut q: Query<&mut Health>, mut reader: MessageReader) -> Result { + for msg in reader.read() { + q.get_mut(msg.target)?.0 -= msg.amount; + } + Ok(()) +} +``` + +Useful params beyond the obvious: `Single` (exactly one match or panic), `Populated` (skip system if empty), `Option>` (resource may not exist — required for render resources in headless contexts), `Local` (per-system persistent state), `RemovedComponents`. + +### Queries + +- Data: `&T`, `&mut T`, `Entity`, `Has`, tuples. +- Filters: `With`, `Without`, `Added`, `Changed`, `Spawned`, `Or<(A, B)>`. +- `.single()` panics unless exactly one match; prefer `Single` param or handle the `Result`. +- Derive `QueryData`/`QueryFilter` for reusable complex queries. + +### Commands + +`commands.spawn((CompA, CompB))` with tuples. `commands.entity(e).insert(..)` / `.insert_if_new(..)` / `.remove::()` / `.despawn()`. Commands are deferred — they apply at the next sync point, not immediately. + +### Ordering + +`(a, b).chain()`, `.before(x)` / `.after(x)`, `#[derive(SystemSet)]` + `configure_sets`. Unordered systems with overlapping mutable access run in nondeterministic order — order anything where it matters. + +## Hierarchy + +`ChildOf(parent)` on the child is the source of truth; `Children` on the parent is auto-synced. Despawning a parent despawns descendants. + +```rust +commands.spawn((Enemy, ChildOf(parent))); +commands.entity(parent).with_children(|s| { s.spawn(Turret); }); +commands.entity(parent).add_child(existing); +``` + +Detaching without despawning: `detach_child` / `detach_children` / `detach_all_children` (0.18 names). Despawn only the children: `despawn_related::()`. + +Details, custom relationships, transform propagation: `references/hierarchy.md`. + +## Events vs Messages — pick correctly + +0.18 split the old event system in two. Choosing wrong is the most common architectural error: + +| Mechanism | Model | Use for | +|-----------|-------|---------| +| `#[derive(Message)]` + `MessageWriter`/`MessageReader` | Pull, double-buffered, batch | Decoupled many-to-many data flow; multiple systems consuming the same stream | +| `#[derive(Event)]` + `commands.trigger()` + observers (`On`) | Push, immediate | React *now*: gameplay reactions, structural changes | +| `#[derive(EntityEvent)]` + `#[event_target]` | Push, per-entity, can `propagate` up `ChildOf` | Entity-targeted reactions (hit, clicked) | +| Component hooks | Synchronous, inline | Response must be atomic with the ECS operation | +| `Changed`/`Added` filters | Per-tick polling | Cheap frame-by-frame reaction in a normal system | + +Full API, lifecycle events (`Add`/`Insert`/`Replace`/`Remove`/`Despawn`), observer registration: `references/events-observers.md`. + +## Architecture + +How to structure a Bevy project — and how to navigate an unfamiliar one: + +- **One plugin per feature/domain** (`CombatPlugin`, `InventoryPlugin`, `UiPlugin`), each owning its components, systems, messages, and state. `main.rs` should be little more than `App::new().add_plugins(...)`. +- **Navigate by the plugin tree**: start at `App::new()`, follow `add_plugins` recursively; grep `add_systems` and `#[derive(SystemSet)]` to map execution order; grep `#[derive(Component)]`/`#[derive(Resource)]` per module to map data ownership. +- **Cross-plugin communication** goes through Messages or shared resources — not direct system coupling. A plugin's components are its internals; its messages are its API. +- **States** (`init_state`, `OnEnter`/`OnExit`, `in_state` run conditions) for game flow; `DespawnOnExit(state)` for scoped entities. Remember same-state `set()` re-fires transitions — one-time setup in `OnEnter` needs `set_if_neq` discipline from callers. +- **No formal plugin dependencies exist.** Guard with `is_plugin_added::()`, or do cross-plugin setup in `Plugin::finish()` (runs after all plugins are ready). +- **Headless-safe systems**: anything that may run in tests or dedicated servers must take render resources as `Option>`. +- **Spawn from standard schedules.** Entities spawned from exclusive/non-standard schedules (UI passes, custom schedules) can be invisible to plugins that hook the normal cycle — set a flag there, spawn in `Update`. + +Plugin trait lifecycle, plugin groups, states, run conditions: `references/plugins-and-app.md`. + +## Coordinates and transforms + +- Right-handed. **+Y up, -Z forward, +X right.** `Transform::forward()` is -Z. +- GLTF models face +Z visually — opposite Bevy. Orient with `look_to(-dir, Vec3::Y)` or treat `transform.back()` as the model's facing. +- Transform propagation runs in `PostUpdate`: reading `GlobalTransform` in `Update` gives last frame's value. Move the reader to `PostUpdate` after `TransformSystem::TransformPropagate`, or accept the one-frame lag deliberately. + +## Silent-failure checklist + +Bevy often succeeds silently when misconfigured. If something "doesn't show up" with no errors: + +1. **Mesh has no normals** → invisible. Use `.with_computed_flat_normals()` on programmatic meshes. +2. **GLTF spawned by raw handle** → nothing. Spawn scene labels: `"model.glb#Scene0"`. +3. **Parent lacks `Visibility`/`InheritedVisibility`** → children invisible. +4. **Object beyond default far plane (1000 units)** → culled. +5. **Asset cache poisoning**: `load_with_settings` with stripped meshes caches per *path*; a later plain `load()` of the same path returns the stripped version. Never mix stripped and rendered loads of one asset in one process. +6. **Assets aren't ready after `load()`** — gate on `AssetEvent::LoadedWithDependencies` or `is_loaded_with_dependencies()`. +7. **Raw `ButtonInput` fires through UI** — world click handlers need UI-consumption checks. + +More production gotchas (physics, multiplayer/shared-world, custom relationships): `references/production-gotchas.md`. + +## Code style + +Write pragmatic Rust, not defensive Rust: + +- Prefer `let Ok(x) = q.single() else { return; }` / `let Some(x) = ... else { return; }` over nested `if let` pyramids. +- Prefer fallible systems with `?` over `unwrap()` chains — a logged error beats a panic in a frame loop. +- Small, single-purpose components; marker components (`struct Player;`) are idiomatic and free. +- Don't hand-roll what the ECS gives you: relationship sync, recursive despawn, required components, run conditions. + +## References + +Load on demand — each is self-contained: + +| File | Read when working on | +|------|----------------------| +| `references/plugins-and-app.md` | Plugin trait/lifecycle, plugin groups, App builder, states, schedules, run conditions | +| `references/ecs.md` | Component/resource/system/query/command details beyond the summary above | +| `references/hierarchy.md` | ChildOf, Children, spawning/detaching, relationships, transform propagation | +| `references/events-observers.md` | Message vs Event APIs, observers, lifecycle events, hooks | +| `references/input.md` | Keyboard, mouse, gamepad, touch | +| `references/camera-rendering.md` | Cameras, coordinates, meshes, materials, shaders, assets, lighting | +| `references/production-gotchas.md` | Silent failures, physics-plugin traps, headless/server architecture | + +## Related skill + +**bevy-upgrade** — version migration (0.15→…→0.19): rename tables, semantic shifts, step-by-step upgrade workflow. Use it whenever the task is moving code *between* versions rather than writing code *for* one. It may in turn send you back here for post-migration idiomatic cleanup. diff --git a/plugins/bevy/skills/bevy-0.19/references/camera-rendering.md b/plugins/bevy/skills/bevy-0.19/references/camera-rendering.md new file mode 100644 index 0000000..7df0b7c --- /dev/null +++ b/plugins/bevy/skills/bevy-0.19/references/camera-rendering.md @@ -0,0 +1,71 @@ +# Camera, Rendering, Assets + +## Camera setup + +`Camera3d` is a marker with `#[require(...)]` pulling in `Camera`, `DebandDither`, `CameraRenderGraph`, `Projection`, `Tonemapping`, `ColorGrading`, `Exposure`. Spawning bare `Camera3d` yields a working 3D camera. + +- **0.18**: `RenderTarget` is a separate required component, no longer a `Camera` field. +- **0.19**: `Hdr` moved from `bevy_render` to `bevy_camera`; screen-space specular transmission fields moved into a `ScreenSpaceTransmission` component. + +### Multiple cameras / ordering + +- `Camera.order: isize` — higher renders later (on top). +- Every camera with `is_active: true` renders independently. +- Overlay cameras need `ClearColorConfig::None` or they wipe the layer below. + +### Camera gotchas + +- Default far plane is **1000 units** — anything beyond is silently culled. +- Forward is **-Z**. +- Viewport coordinates are **physical** pixels; cursor position is **logical**. + +## Coordinate system + +Right-handed: + +| Axis | Bevy | GLTF models | +|------|------|-------------| +| Forward | -Z (`Transform::forward()`) | +Z (`Transform::back()`) | +| Up | +Y | +Y | +| Right | +X | -X from camera perspective | + +GLTF fix: orient with `look_to(-direction, Vec3::Y)` or treat `transform.back()` as the model's visual forward. + +**0.18**: `GltfPlugin`'s `use_model_forward_direction` was replaced by `convert_coordinates` with `rotate_scene_entity` and `rotate_meshes` flags. + +## Meshes & materials + +- `StandardMaterial` needs **normals**; a mesh without them spawns fine and renders invisible. Programmatic meshes: `.with_computed_flat_normals()` (or insert `ATTRIBUTE_NORMAL`). +- Back-face culling is on by default — wrong winding = invisible faces. +- GLTF scenes spawn via **scene labels** (`"model.glb#Scene0"`), not the raw asset handle. +- Visibility inherits: parents without `Visibility`/`InheritedVisibility` make children invisible — common with hand-built hierarchies around loaded scenes. +- **0.18**: mesh accessors became `try_*` returning `Result<_, MeshAccessError>`; `MaterialPlugin` fields (`prepass_enabled`, `shadows_enabled`) became `Material` trait methods. +- **0.19**: GLTF material loading returns `GltfMaterial` — use the `#Material0/std` label for a `StandardMaterial`. `Assets::get_mut` returns mutation-tracked `AssetMut`. `Scene`/`SceneRoot` renamed to `WorldAsset`/`WorldAssetRoot`. + +## Custom material shaders — bind groups + +Material bindings are `@group(3)` (0.18+), not `@group(2)`: + +| Group | Contents | +|-------|----------| +| 0 | view | +| 1 | globals/lights | +| 2 | mesh (storage buffer) | +| 3 | material (`AsBindGroup`) | + +`@group(2)` for material uniforms produces the confusing `Storage class Storage doesn't match the shader Uniform` error — group 2 is the mesh storage buffer. + +Import: `use bevy::shader::ShaderRef;` (moved out of `bevy::render::render_resource` in 0.18). + +## Lighting + +`AmbientLight` split (0.18): +- `GlobalAmbientLight` — **resource**, all cameras. +- `AmbientLight` — **component** on a camera entity, per-camera. + +## Assets + +- Assets are not ready right after `asset_server.load()`. Gate on `AssetEvent::LoadedWithDependencies` or `AssetServer::is_loaded_with_dependencies()`. +- **Cache poisoning**: the server dedups by path. A `load_with_settings` that strips data (e.g. `load_meshes = RenderAssetUsages::empty()`) poisons the cache; a later `load()` of the same path returns the stripped asset — invisible models, zero errors. Never mix stripped and rendered loads of the same path in one process; stripped loads belong to headless tools only. +- **0.18**: `LoadContext::path()` returns `AssetPath`, not `Path`; image `reinterpret_*` return `Result`. +- **0.19**: `AssetPath::resolve()`/`resolve_embed()` take `&AssetPath`; the string-taking variants are `resolve_str()`/`resolve_embed_str()`. diff --git a/plugins/bevy/skills/bevy-0.19/references/ecs.md b/plugins/bevy/skills/bevy-0.19/references/ecs.md new file mode 100644 index 0000000..a8c35ac --- /dev/null +++ b/plugins/bevy/skills/bevy-0.19/references/ecs.md @@ -0,0 +1,87 @@ +# ECS Core Reference + +## Components + +`#[derive(Component)]` on structs/enums; requires `Send + Sync + 'static`. + +Storage: +- Table (default) — fast iteration. +- `#[component(storage = "SparseSet")]` — fast insert/remove; use for tag-like components that churn. + +Attributes: +- `#[component(immutable)]` (0.18+) — only `&T` access, never `&mut T`. Good for identity-like data. +- `#[require(B, C)]` — auto-insert `B` and `C` when this component is added. Constructor forms: `B(value)`, `C { field: val }`, function calls, `= expr`. This replaced `#[derive(Bundle)]` (removed 0.16+); spawn with tuples instead. +- Hooks: `#[component(on_add = f)]`, `on_insert`, `on_replace`, `on_remove`, `on_despawn`. Hook signature: `fn(DeferredWorld, HookContext)`. Hooks run synchronously inside the ECS operation. +- `#[component(clone_behavior = Ignore)]` — skip during entity clone. + +## Resources + +| Param | Access | +|-------|--------| +| `Res` | shared read | +| `ResMut` | exclusive write | +| `Option>` / `Option>` | may not exist (mandatory for render resources in headless-capable systems) | +| `Local` | per-system private state, default-initialized, persists across runs | +| `NonSend` / `NonSendMut` | `!Send` resources (main-thread only) | + +World/App: `init_resource::()`, `insert_resource(value)`, `remove_resource::()`. + +**0.19**: Resources implement `Component` and live on dedicated entities. Consequences: +- `Query` (and other very broad queries) match resource entities — filter with `Without`. +- A type cannot derive both `Component` and `Resource`. + +## Systems + +Any `fn(params...)` where every param is a `SystemParam`. + +- **Fallible** (0.18+): `fn system(...) -> Result` (alias for `Result<(), BevyError>`). Errors are logged; the system runs again next tick. `?` converts anything convertible to `BevyError`. Prefer this over `unwrap()`. +- **Exclusive**: `fn system(world: &mut World)` — full access, blocks parallelism; use sparingly. + +Valid `SystemParam` types include: `Query`, `Res`, `ResMut`, `Commands`, `Local`, `MessageReader`, `MessageWriter`, `ParamSet`, `Single`, `Populated`, `SystemName`, `SystemChangeTick`, `RemovedComponents`, `DeferredWorld`, `&World`, `Option

`, `Result`. + +- `Single` — resolves to exactly one entity or the system doesn't run correctly (panics); the param-level version of `query.single()`. +- `Populated` — the system is skipped when the query is empty. Cheap way to avoid per-frame no-op runs. + +## Queries + +`Query` — `D: QueryData`, `F: QueryFilter` (default `()`). + +Data: `&T`, `&mut T`, `Entity`, `Has`, tuples. + +Filters: + +| Filter | Matches | +|--------|---------| +| `With` / `Without` | presence / absence | +| `Added` | first tick after the component was added | +| `Changed` | first tick after add or mutable deref | +| `Spawned` | first tick after entity spawn | +| `Or<(A, B)>` | either | + +Note `Changed` triggers on `&mut` deref even without an actual value change — deref only when writing. + +Methods: `.iter()` / `.iter_mut()`, `.get(entity)` / `.get_mut(entity)`, `.single()` (Result-returning; panicking use is a bug magnet), `.par_iter()` / `.par_iter_mut()`. + +Reusable shapes: `#[derive(QueryData)]`, `#[derive(QueryFilter)]`. + +## Commands + +| Call | Effect | +|------|--------| +| `commands.spawn((A, B))` | spawn with component tuple, returns `EntityCommands` | +| `commands.spawn_empty()` | empty entity, chain `.insert(...)` | +| `commands.spawn_batch(iter)` | batch spawn | +| `commands.entity(e).insert(c)` | add/replace component | +| `commands.entity(e).insert_if_new(c)` | add only if absent | +| `commands.entity(e).remove::()` | remove component | +| `commands.entity(e).despawn()` | despawn entity **and descendants** | +| `commands.queue(cmd)` | custom `Command` impl | + +Commands are deferred to the next sync point — a spawn is not queryable in the same system. + +## Ordering + +- `(a, b).chain()` — sequential. +- `.before(x)` / `.after(x)` — explicit constraints against systems or sets. +- `#[derive(SystemSet)]` + `app.configure_sets(Update, SetA.before(SetB))` — named groups; the scalable way to order across plugins. +- Systems with overlapping mutable access and no ordering run nondeterministically; Bevy warns about ambiguities. Order anything where results depend on it. diff --git a/plugins/bevy/skills/bevy-0.19/references/events-observers.md b/plugins/bevy/skills/bevy-0.19/references/events-observers.md new file mode 100644 index 0000000..5db7c4b --- /dev/null +++ b/plugins/bevy/skills/bevy-0.19/references/events-observers.md @@ -0,0 +1,105 @@ +# Events, Messages, Observers & Hooks + +0.18 split the old single event system into **Messages** (pull, buffered) and **Events** (push, observed). They are different traits with different derives — using the wrong one won't compile, and porting old code mechanically to the wrong side is an architecture bug. + +## Messages — pull-based, double-buffered + +The renamed successor of `EventWriter`/`EventReader`. Use for decoupled many-to-many data flow where several systems batch-process the same stream. + +```rust +#[derive(Message)] +struct Collision { a: Entity, b: Entity } + +fn produce(mut writer: MessageWriter) { + writer.write(Collision { a, b }); // also: write_batch(iter), write_default() +} + +fn consume(mut reader: MessageReader) { + for c in reader.read() { /* each reader has its own cursor */ } +} +``` + +- Double-buffered: a message survives one `update()` cycle and is dropped on the next. A reader that runs before the writer in the same frame sees it next frame. +- Multiple readers run concurrently; multiple writers of the same type cannot. +- Reader extras: `len()`, `is_empty()`, `clear()`. +- Run condition: `on_message::()`. + +## Events — push-based, immediate, observed + +```rust +#[derive(Event)] +struct Speak { text: String } + +// Global observer +app.add_observer(|on: On| println!("{}", on.text)); + +// Entity-scoped observer — fires only for this entity +commands.entity(id).observe(|on: On| { /* ... */ }); + +// Trigger +commands.trigger(Speak { text: "hi".into() }); +world.trigger_ref(&mut event); // inspect the event after observers mutate it +``` + +Observer param `On<'w, 't, E, B>` (`B: Bundle` filters by component): +- `event()` / `event_mut()` — event data (also `Deref` for direct field access) +- `trigger()` / `trigger_mut()` — trigger context +- `observer()` — the observer entity + +Observers run immediately during the trigger, not at a schedule point. + +## EntityEvent — entity-targeted + +```rust +#[derive(EntityEvent)] +struct Hit { + #[event_target] + entity: Entity, + damage: f32, +} +``` + +`#[entity_event(propagate)]` makes the event bubble up the `ChildOf` chain — useful for UI-like hit forwarding. + +**0.19**: `EntityComponentsTrigger` gained archetype fields — destructure with `..`: +`let EntityComponentsTrigger { components, .. } = e.trigger();` + +## Lifecycle events + +Built-in events observers can watch per component: + +| Event | Fires | Order | +|-------|-------|-------| +| `Add` | component added where absent | first | +| `Insert` | any insert (add or replace) | after `Add` | +| `Replace` | component removed, regardless of replacement | before `Remove` | +| `Remove` | component removed | after `Replace` | +| `Despawn` | entity despawned (per component) | last | + +```rust +world.add_observer(|on: On| { /* entity just gained Health */ }); +``` + +## Component hooks — synchronous, inline + +For callbacks that must be atomic with the ECS operation itself (not deferred, not scheduled): + +```rust +#[derive(Component)] +#[component(on_add = init_health_bar)] +struct Health(f32); + +fn init_health_bar(world: DeferredWorld, ctx: HookContext) { /* ... */ } +``` + +Available: `on_add`, `on_insert`, `on_replace`, `on_remove`, `on_despawn`. + +## Choosing the mechanism + +| Mechanism | Model | Reach for it when | +|-----------|-------|-------------------| +| Messages | pull, buffered, scheduled | several systems independently process a stream; frame-batched work | +| Event + observer | push, immediate | something must react *now* (gameplay reactions, structural responses) | +| EntityEvent | push, targeted, can propagate | the reaction belongs to a specific entity | +| Component hook | synchronous, inline | the response must not be separable from the ECS operation | +| `Changed` / `Added` | per-tick polling | cheap frame-wise checks inside a normal system | diff --git a/plugins/bevy/skills/bevy-0.19/references/hierarchy.md b/plugins/bevy/skills/bevy-0.19/references/hierarchy.md new file mode 100644 index 0000000..042d2e9 --- /dev/null +++ b/plugins/bevy/skills/bevy-0.19/references/hierarchy.md @@ -0,0 +1,65 @@ +# Hierarchy & Relationships + +## ChildOf / Children (0.16+ model) + +- `ChildOf(pub Entity)` lives on the **child** and points at the parent. (`Parent` no longer exists.) +- Get the parent via `child_of.parent()` — the old `Deref` was removed. +- `ChildOf` implements `Relationship`; `Children` implements `RelationshipTarget`. They auto-sync via hooks: adding `ChildOf(p)` to a child inserts/updates `Children` on `p`; removing it updates the parent. Never maintain `Children` manually. +- Despawning a parent despawns all descendants — `despawn()` is recursive by default (`despawn_recursive` is gone). + +## Spawning children + +```rust +// Direct: ChildOf in the spawn tuple +commands.spawn((Turret, ChildOf(ship))); + +// Closure for several children +commands.entity(ship).with_children(|spawner| { + spawner.spawn(Turret); + let ship = spawner.target_entity(); // was parent_entity() +}); + +// Attach existing entities +commands.entity(ship).add_child(turret); +commands.entity(ship).add_children(&[a, b]); +commands.entity(ship).insert_children(index, &[a, b]); +``` + +## Querying + +- `Children` derefs to `[Entity]` and implements `IntoIterator` yielding `Entity`. +- Iterate: `for child in &children` — not `children.iter().copied()`. +- Methods: `len()`, `is_empty()`, `contains()`, `first()`, `last()`, `sort_by()`. +- Relationship-generic query extensions: `query.related::(entity)`, `query.relationship_sources::(entity)`. + +## Detach vs despawn (0.18 names) + +| Method | Effect | +|--------|--------| +| `detach_child(e)` | unparent one child, keep it alive | +| `detach_children(&[..])` | unparent several | +| `detach_all_children()` | unparent all | +| `despawn_related::()` | despawn the children themselves | + +The pre-0.18 names (`remove_child`, `remove_children`, `clear_children`) are gone. + +## Custom relationships + +`#[relationship]` / `#[relationship_target]` derive pairs get the same auto-sync as `ChildOf`/`Children`. Do **not** write observers that manually push/remove entities in the target collection — the hooks already do it, and manual sync causes duplicates or desync. + +## Transform propagation + +- Child `Transform` is parent-relative; `GlobalTransform` is computed world-space through the `ChildOf` chain. +- Propagation runs in **`PostUpdate`** (`TransformSystem::TransformPropagate`). A system in `Update` reading `GlobalTransform` sees last frame's value. +- Options: schedule the reader in `PostUpdate` after propagation; accept the one-frame lag (often fine); or (rarely) walk the `Transform` chain manually. + +## Quick corrections + +| Stale | Correct | +|-------|---------| +| `Parent` | `ChildOf(entity)` | +| `*child_of` | `child_of.parent()` | +| `children.iter().copied()` | `for child in &children` | +| `despawn_recursive()` | `despawn()` | +| `parent_entity()` (in spawner) | `target_entity()` | +| `remove_children` / `clear_children` | `detach_children` / `detach_all_children` | diff --git a/plugins/bevy/skills/bevy-0.19/references/input.md b/plugins/bevy/skills/bevy-0.19/references/input.md new file mode 100644 index 0000000..08f1c9b --- /dev/null +++ b/plugins/bevy/skills/bevy-0.19/references/input.md @@ -0,0 +1,71 @@ +# Input + +## Keyboard — `Res>` + +| Method | Purpose | +|--------|---------| +| `pressed(k)` | held this frame | +| `just_pressed(k)` / `just_released(k)` | edge detection | +| `any_pressed(iter)` / `any_just_pressed(iter)` / `all_pressed(iter)` | multi-key checks | +| `get_pressed()` / `get_just_pressed()` | iterate held / newly pressed | +| `clear_just_pressed(k)` | consume the press | + +`ButtonInput` exists for logical/locale-aware keys (text-ish input); `KeyCode` is physical layout. + +## Mouse + +Buttons: `Res>` — same API. Variants: `Left`, `Right`, `Middle`, `Back`, `Forward`, `Other(u16)`. + +Motion and scroll: + +| Type | Kind | Purpose | +|------|------|---------| +| `MouseMotion` | Message | raw per-event `delta: Vec2` — read with `MessageReader` | +| `AccumulatedMouseMotion` | Resource | frame total, reset each frame — usually what you want | +| `MouseWheel` | Message | scroll with `MouseScrollUnit` (Line/Pixel) | +| `AccumulatedMouseScroll` | Resource | frame total scroll | + +Cursor position — from the `Window` component, logical pixels, origin top-left: + +```rust +fn cursor(windows: Query<&Window>) -> Result { + if let Some(pos) = windows.single()?.cursor_position() { /* ... */ } + Ok(()) +} +``` + +**UI click-through trap**: `ButtonInput` is raw winit input — it fires even when the click landed on a UI panel. World-click handlers must verify the click wasn't consumed by UI (e.g. a full-screen background `Interaction` node that only receives clicks passing through all UI). + +## Gamepad + +- Buttons: `Res>` — same pressed/just_pressed API; analog buttons also map to `[0.0, 1.0]`. +- Axes: `Res>` → `get(axis) -> Option` in `[-1.0, 1.0]`. +- Messages: `GamepadButtonStateChangedEvent`, `GamepadButtonChangedEvent`, `GamepadAxisChangedEvent`, `GamepadConnectionEvent`. +- Deadzones/thresholds: `GamepadSettings` component. + +## Touch + +- `TouchInput` message with `TouchPhase` (Began/Moved/Ended). +- `Touches` resource — active-touch queries, analogous to `ButtonInput`. +- `ForceTouch` for pressure-capable devices. +- Requires the `touch` feature flag. + +## Feature gating (0.18+) + +Input sources (`mouse`, `keyboard`, `gamepad`, `touch`, `gestures`) are feature-gated. They're on by default via `bevy_window`/`bevy_gilrs`, but with `default-features = false` they must be listed explicitly — missing input with no errors usually means a missing feature. + +## Action mapping + +Bevy has no built-in action-mapping layer. The community standard is `leafwing-input-manager`; check the project's `Cargo.toml` before hand-rolling bindings. + +## Pattern + +```rust +fn movement(keys: Res>) { + let mut dir = Vec3::ZERO; + if keys.pressed(KeyCode::KeyW) { dir.z -= 1.0; } // forward is -Z + if keys.pressed(KeyCode::KeyS) { dir.z += 1.0; } + if keys.pressed(KeyCode::KeyA) { dir.x -= 1.0; } + if keys.pressed(KeyCode::KeyD) { dir.x += 1.0; } +} +``` diff --git a/plugins/bevy/skills/bevy-0.19/references/plugins-and-app.md b/plugins/bevy/skills/bevy-0.19/references/plugins-and-app.md new file mode 100644 index 0000000..84b1cb4 --- /dev/null +++ b/plugins/bevy/skills/bevy-0.19/references/plugins-and-app.md @@ -0,0 +1,86 @@ +# Plugins, App, States, Schedules + +## Plugin trait (`bevy::app::Plugin`) + +Required: +- `fn build(&self, app: &mut App)` — runs immediately on `add_plugins`. + +Optional (defaults provided): +- `fn ready(&self, _: &App) -> bool` — default `true`; override for async init. +- `fn finish(&self, _: &mut App)` — runs after all plugins report `ready()`, before the first schedule tick. The idiomatic place for cross-plugin setup that needs another plugin's resources to exist. +- `fn cleanup(&self, _: &mut App)` — runs after `finish()`; remove temp resources. +- `fn name(&self) -> &str` — defaults to type name; used for the uniqueness check. +- `fn is_unique(&self) -> bool` — default `true`; return `false` for multi-instance plugins. + +Any `fn(&mut App)` auto-implements `Plugin`. + +## Plugin dependencies + +There is no formal depends-on declaration. Patterns: + +- `app.is_plugin_added::()` to guard or panic early with a clear message. +- Sub-plugins: call `app.add_plugins(ChildPlugin)` inside `build()`. Bevy deduplicates by name; unique plugins panic on double-add. +- Cross-plugin wiring that needs the other plugin's resources → `finish()`. + +## Plugin groups + +`DefaultPlugins` / `MinimalPlugins` implement `PluginGroup`. Customize via the builder: + +```rust +DefaultPlugins + .disable::() + .set(WindowPlugin { /* config */ }) + .add_before::(MyPlugin) +``` + +`.disable::()`, `.enable::()`, `.set(plugin)`, `.add_before::(p)`, `.add_after::(p)`. + +## App builder key methods + +| Method | Purpose | +|--------|---------| +| `add_plugins(P)` | Plugin, plugin group, or tuple of either | +| `insert_resource(R)` | Insert, overwriting existing | +| `init_resource::()` | Insert via `Default`/`FromWorld` if absent | +| `add_systems(schedule, systems)` | Add to a schedule | +| `configure_sets(schedule, sets)` | Order system sets | +| `register_type::()` | Reflection registry | +| `is_plugin_added::()` | Plugin presence check | +| `register_required_components::()` | Runtime component requirements | + +## States + +Three flavors: + +- **FreelyMutableState** — changed via the `NextState` resource. +- **SubStates** — exist only while the parent state is in a required variant. +- **ComputedStates** — derived: `fn compute(sources) -> Option`. + +Registration: `app.init_state::()` (default initial) or `app.insert_state(value)`. + +Transition schedules: `OnEnter(S)`, `OnExit(S)`, `OnTransition(S)`. +Entity scoping: `DespawnOnEnter(S)`, `DespawnOnExit(S)` (replaced `StateScoped`, 0.16+). +Run condition: `in_state(S)`. + +**0.18 behavior change**: `NextState::set()` fires `OnExit`+`OnEnter` even when setting the current state. Use `set_if_neq()` for no-op-on-same. One-time setup in `OnEnter` systems will re-run if any caller `set()`s the active state. + +## Schedules + +| Phase | Schedules | +|-------|-----------| +| Startup (once) | `PreStartup`, `Startup`, `PostStartup` | +| Per-frame | `First`, `PreUpdate`, `Update`, `PostUpdate`, `Last` | +| Fixed timestep | `FixedFirst`, `FixedPreUpdate`, `FixedUpdate`, `FixedPostUpdate`, `FixedLast` (inside `FixedMain`, driven by `RunFixedMainLoop`) | +| Other | `Main`, `SpawnScene` | + +Gameplay simulation that must be framerate-independent goes in `FixedUpdate`. Transform propagation and most engine bookkeeping run in `PostUpdate`. + +## Run conditions (`common_conditions`) + +- `in_state(s)` +- `resource_exists::()`, `resource_added::()`, `resource_changed::()`, `resource_equals(val)` +- `any_with_component::()`, `any_component_removed::()` +- `on_message::()` (renamed from `on_event`, 0.18) +- `run_once()`, `not(cond)`, `condition_changed(cond)`, `condition_changed_to(cond)` + +Combine with `.and(cond)` / `.or(cond)`. diff --git a/plugins/bevy/skills/bevy-0.19/references/production-gotchas.md b/plugins/bevy/skills/bevy-0.19/references/production-gotchas.md new file mode 100644 index 0000000..232ed6c --- /dev/null +++ b/plugins/bevy/skills/bevy-0.19/references/production-gotchas.md @@ -0,0 +1,93 @@ +# Production Gotchas + +Battle-tested traps from shipped Bevy code. Most are silent — no error, no warning, wrong behavior. Grouped by category; scan the headers when debugging "it just doesn't work". + +## Silent failures + +### Asset cache poisoning via `load_with_settings` + +`AssetServer` dedups by path. Loading a GLTF with stripped settings (e.g. `load_meshes = RenderAssetUsages::empty()` for hierarchy extraction) caches the stripped version; a later plain `load("model.glb#Scene0")` returns it — invisible models, zero errors, order-dependent. + +Rule: a process that renders an asset must never also `load_with_settings`-strip that asset. Stripped loads are for headless servers/tools only. + +### Mesh without normals + +Spawns successfully, renders invisible. Use `.with_computed_flat_normals()` or insert `ATTRIBUTE_NORMAL` on programmatic meshes. + +### Visibility hierarchy + +Parents lacking `Visibility`/`InheritedVisibility` make all children invisible regardless of the children's settings. Sneaky in hand-assembled hierarchies around loaded scenes. + +### Spawning from non-standard schedules + +Plugins (particles, audio, …) often hook the standard `Update`/`Startup` cycle. Entities spawned from exclusive or custom schedules (e.g. a UI pass) can exist in queries yet be ignored by the plugin — all components present, no errors, nothing happens. + +Fix: set a flag in the odd schedule, do the actual spawn in `Update`: + +```rust +fn ui_system(mut state: ResMut) { + if clicked { state.spawn_requested = true; } +} +fn handle_spawns(mut state: ResMut, mut commands: Commands) { + if std::mem::take(&mut state.spawn_requested) { + commands.spawn(/* ... */); + } +} +``` + +## Scheduling & state + +### `GlobalTransform` stale in `Update` + +Propagation runs in `PostUpdate`; `Update` readers see last frame. Move the reader to `PostUpdate` after `TransformSystem::TransformPropagate`, or accept the lag deliberately. + +### `State::set()` re-fires same-state transitions (0.18) + +`next_state.set(Playing)` while already `Playing` fires `OnExit(Playing)` + `OnEnter(Playing)`. One-time setup in `OnEnter` (cameras, level loads) re-runs. Use `set_if_neq()` when re-firing isn't wanted. + +## Headless / server contexts + +### Render resources must be `Option` + +`ResMut>` panics in headless runs (tests, dedicated servers) — the resource doesn't exist without `RenderPlugin`: + +```rust +fn my_system(materials: Option>>) { + let Some(mut materials) = materials else { return; }; + // ... +} +``` + +Any system that can run both rendered and headless needs this. + +## UI interaction + +### Raw mouse input fires through UI + +`Res>` is winit-level; it fires for clicks consumed by UI panels. World-click handlers need a UI-consumption check (e.g. a full-screen low-z `Interaction` node that receives only clicks passing through all UI). + +### `RelativeCursorPosition.normalized` is center-origin + +`(0, 0)` is the node's **center**; range is `(-0.5, -0.5)`–`(0.5, 0.5)`. For `[0, 1]` UV: `normalized + Vec2::splat(0.5)`. + +## Relationships + +Custom `#[relationship]` / `#[relationship_target]` pairs auto-sync via hooks. Do not write observers that manually push/remove entities in the target `Vec` — that duplicates what the macro does and desyncs. + +## Physics plugins (Avian / Rapier pattern) + +- **`CollidingEntities` is not auto-inserted** with `Collider` (Avian3D 0.5). Without adding `CollidingEntities::default()`, collision queries return nothing while the simulation runs fine internally. +- **Removing `RigidBody` from a parent with `Collider` children** can panic with stale internal-tree indices. Despawn collider children first. + +## Shared-world multiplayer (server + client in one process) + +- **Server entities carry no visual components.** `SceneRoot`/`Mesh3d`/`Sprite` belong on client-spawned entities only; mixing causes host-vs-remote visual drift and double maintenance. +- **`run_if(is_server)` gates the system, not the query.** In a shared world, server systems still match client replica entities — queries must filter client markers explicitly. +- **Shared components race.** Server and client systems in one World share component instances; a client system resetting a timer changes what the server system reads the same frame. Use `Local` for server-side state that must stay independent. + +## Debugging heuristics + +1. Invisible things: check normals, visibility hierarchy, far plane (1000), asset cache poisoning, scene-label spawning. +2. Empty query results: check the component is actually inserted (physics markers), spawn schedule, `Without` on broad queries (0.19). +3. Behavior fires unexpectedly / twice: same-state transitions, raw input through UI, ambiguous system order. +4. Compiles-but-wrong after touching old code: stale API from a previous Bevy version — cross-check the bevy-upgrade skill's rename tables. diff --git a/plugins/bevy/skills/bevy-upgrade/SKILL.md b/plugins/bevy/skills/bevy-upgrade/SKILL.md index e0f20bc..ee8cb10 100644 --- a/plugins/bevy/skills/bevy-upgrade/SKILL.md +++ b/plugins/bevy/skills/bevy-upgrade/SKILL.md @@ -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/-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` 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` 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. diff --git a/plugins/bevy/skills/bevy-upgrade/references/0.15-to-0.17.md b/plugins/bevy/skills/bevy-upgrade/references/0.15-to-0.17.md new file mode 100644 index 0000000..a05426c --- /dev/null +++ b/plugins/bevy/skills/bevy-upgrade/references/0.15-to-0.17.md @@ -0,0 +1,36 @@ +# 0.15 → 0.16 → 0.17 + +The 0.16 transition restructured hierarchy and spawning; 0.17 was comparatively quiet. Both are covered here. For changes not listed, consult the official guides: `https://bevy.org/learn/migration-guides/0-15-to-0-16/` and `.../0-16-to-0-17/`. + +## Renames & removals (mechanical) + +| Old (≤0.15) | New (0.16+) | Notes | +|-------------|-------------|-------| +| `Parent` component | `ChildOf(pub Entity)` | Lives on the child; entities *with* `ChildOf` are children | +| `*parent` (Deref to Entity) | `child_of.parent()` | Deref removed | +| `despawn_recursive()` | `despawn()` | `despawn()` is now recursive by default | +| `despawn_descendants()` | `despawn_related::()` | | +| `#[derive(Bundle)]` | spawn tuples + `#[require(...)]` | Bundles removed as a user-facing pattern | +| `StateScoped(state)` | `DespawnOnExit(state)` / `DespawnOnEnter(state)` | | +| `parent_entity()` (child spawner) | `target_entity()` | | + +## API shape changes + +- **Hierarchy is relationship-based**: `ChildOf` implements `Relationship`, `Children` implements `RelationshipTarget`; they sync automatically via hooks. Delete any manual `Children` bookkeeping — it now fights the engine. +- **Spawning children**: `commands.spawn((Comp, ChildOf(parent)))` works directly; `with_children(|spawner| ...)` remains. `add_child` / `add_children` / `insert_children` attach existing entities. +- **`Children` iteration** yields `Entity` via `IntoIterator`: `for child in &children`. Ports of `children.iter().copied()` compile but are noise — simplify during cleanup. +- **Required components** replace bundles: `#[require(Transform, Visibility)]` on a marker pulls in dependencies at spawn. When porting a `Bundle` struct, its fields usually become either a spawn tuple at call sites or `#[require(...)]` on the primary component. +- Query relationship extensions appear: `query.related::(entity)`, `query.relationship_sources::(entity)`. + +## Semantic shifts (audit, don't just compile) + +- **`despawn()` is recursive.** Code that relied on `despawn()` orphaning children (intentionally detaching them) now destroys them. If detach-then-despawn was the intent, `detach_all_children()` first (name as of 0.18; `clear_children()` in 0.16–0.17). +- **Adding `ChildOf` has side effects**: parent's `Children` updates immediately via hooks, and lifecycle observers on `Children` fire. Ordering assumptions around manual parent updates are void. + +## Porting checklist + +1. `grep -rn "Parent\b"` — replace with `ChildOf`, fix accessors to `.parent()`. +2. `grep -rn "despawn_recursive\|despawn_descendants"` — rename; then audit remaining plain `despawn()` calls for the orphaning assumption. +3. `grep -rn "derive(Bundle)"` — convert to tuples/`#[require]`. +4. `grep -rn "StateScoped"` — replace with `DespawnOnExit`/`DespawnOnEnter`. +5. Remove manual child-list maintenance (observers/systems pushing into `Children`). diff --git a/plugins/bevy/skills/bevy-upgrade/references/0.17-to-0.18.md b/plugins/bevy/skills/bevy-upgrade/references/0.17-to-0.18.md new file mode 100644 index 0000000..2b67708 --- /dev/null +++ b/plugins/bevy/skills/bevy-upgrade/references/0.17-to-0.18.md @@ -0,0 +1,57 @@ +# 0.17 → 0.18 + +The largest recent transition. Its centerpiece — the Event/Message split — is architectural, not just a rename. Official guide for the long tail: `https://bevy.org/learn/migration-guides/0-17-to-0-18/`. + +## The Event/Message split + +The old buffered event system was split in two: + +| Old (≤0.17) | New (0.18) | +|-------------|-----------| +| `#[derive(Event)]` (buffered use) | `#[derive(Message)]` | +| `EventWriter` / `.send(e)` | `MessageWriter` / `.write(m)` | +| `EventReader` | `MessageReader` | +| `Events` | `Messages` | +| `on_event::()` run condition | `on_message::()` | + +`Event` still exists but now means **observer-events only** (`commands.trigger()` + `On` observers, immediate push). This is the transition's biggest trap: a type ported to `#[derive(Event)]` and written with a `MessageWriter` won't compile, but a type left as `Event` with a forgotten reader silently does nothing. + +Port rule: every buffered event → `Message`. Only convert to `Event`+observer deliberately, during post-migration cleanup, where immediate reaction is actually wanted. + +New in 0.18: `#[derive(EntityEvent)]` with `#[event_target]` for entity-targeted events, optionally `#[entity_event(propagate)]` to bubble up `ChildOf`. + +## Renames & moves (mechanical) + +| Old | New | +|-----|-----| +| `remove_child` / `remove_children` / `clear_children` | `detach_child` / `detach_children` / `detach_all_children` | +| `bevy::render::render_resource::ShaderRef` | `bevy::shader::ShaderRef` | +| `WinitPlugin::` | `WinitPlugin` (no longer generic) | +| `AmbientLight` (single type) | `GlobalAmbientLight` **resource** + `AmbientLight` **camera component** | +| `Camera.target` field | `RenderTarget` required component | +| `GltfPlugin` `use_model_forward_direction` | `convert_coordinates` + `rotate_scene_entity` / `rotate_meshes` flags | + +## API shape changes + +- **Fallible systems**: systems may return `Result` (= `Result<(), BevyError>`); errors log and the system retries next tick. Adopt during the bump wherever it deletes `unwrap()`s cheaply; systematically during cleanup. +- **Mesh accessors** became `try_*` returning `Result<_, MeshAccessError>`. +- **`MaterialPlugin` fields** `prepass_enabled` / `shadows_enabled` became `Material` trait methods. +- **`LoadContext::path()`** returns `AssetPath`, not `Path`; image `reinterpret_*` methods return `Result`. +- **Immutable components**: `#[component(immutable)]` available. +- **Input feature gates**: `mouse`, `keyboard`, `gamepad`, `touch`, `gestures` are now cargo features. Default-on, but builds with `default-features = false` must list them — otherwise input silently stops arriving. + +## Semantic shifts (audit, don't just compile) + +- **`NextState::set()` same-state transitions fire.** `set(Playing)` while in `Playing` now triggers `OnExit(Playing)` + `OnEnter(Playing)` (previously a no-op). One-time setup in `OnEnter` (spawn camera, load level) re-runs. Audit every `next_state.set(...)` reachable while already in that state; use `set_if_neq()` where the old behavior is wanted. +- **Material shader bind groups**: material bindings are `@group(3)`; `@group(2)` is the mesh storage buffer. Old custom shaders using `@group(2)` fail with `Storage class Storage doesn't match the shader Uniform`. Update all `.wgsl` material shaders. +- **`MouseMotion`, `MouseWheel` and other input streams are Messages now** — readers must be `MessageReader`. + +## Porting checklist + +1. `grep -rn "EventWriter\|EventReader\|on_event\|Events<"` — rename to Message equivalents; `.send(` → `.write(`. +2. `grep -rn "derive(Event)"` — decide per type: buffered (→ `Message`) or observed (stays `Event`, needs a trigger + observer). +3. `grep -rn "remove_child\|clear_children"` — rename to `detach_*`. +4. `grep -rn "next_state.set\|NextState"` — audit same-state re-fire. +5. `grep -rn "@group(2)" --include=*.wgsl` — move material bindings to group 3. +6. `grep -rn "AmbientLight"` — split into resource vs camera component usage. +7. Check `Cargo.toml` for `default-features = false` on bevy → add input features. diff --git a/plugins/bevy/skills/bevy-upgrade/references/0.18-to-0.19.md b/plugins/bevy/skills/bevy-upgrade/references/0.18-to-0.19.md new file mode 100644 index 0000000..09b983c --- /dev/null +++ b/plugins/bevy/skills/bevy-upgrade/references/0.18-to-0.19.md @@ -0,0 +1,36 @@ +# 0.18 → 0.19 + +Smaller than 0.17→0.18 but with one deep semantic change: resources became components. Official guide for the long tail: `https://bevy.org/learn/migration-guides/0-18-to-0-19/`. + +## Renames & moves (mechanical) + +| Old (0.18) | New (0.19) | +|------------|-----------| +| `Scene` / `SceneRoot` | `WorldAsset` / `WorldAssetRoot` | +| `AssetPath::resolve(&str)` / `resolve_embed(&str)` | `resolve_str()` / `resolve_embed_str()` (`resolve()`/`resolve_embed()` now take `&AssetPath`) | +| `Hdr` in `bevy_render` | `bevy_camera` | +| `Camera` screen-space specular transmission fields | `ScreenSpaceTransmission` component | + +## API shape changes + +- **`Assets::get_mut`** returns `AssetMut` (mutation-tracked), not `&mut A`. Deref for access; code storing the `&mut A` needs restructuring. +- **`Ref.clone()`** returns `Ref`, not the inner value. Old code relying on clone-through must use `ref.deref().clone()`. +- **GLTF material loading** returns `GltfMaterial`; request a `StandardMaterial` with the `#Material0/std` label suffix. +- **`EntityComponentsTrigger`** gained archetype fields — exhaustive destructuring breaks; add `..`: + `let EntityComponentsTrigger { components, .. } = e.trigger();` + +## Semantic shifts (audit, don't just compile) + +- **Resources are components on abstract entities.** Consequences: + - `Query` and other very broad queries now match resource entities. Any "iterate all entities" logic (cleanup sweeps, entity counts, serialization, debug overlays) silently includes resources — filter with `Without`. + - A type can no longer derive both `Component` and `Resource`. Split such types or pick one role. +- **Scene rename is semantic-adjacent**: `WorldAsset` naming reflects the same data model, but grep for the old names in strings/reflection paths, not just types. + +## Porting checklist + +1. `grep -rn "SceneRoot\|Scene>" ` — rename to `WorldAssetRoot`/`WorldAsset`. +2. `grep -rn "Query]"` and other broad queries — add `Without` where resources must not appear. +3. `grep -rn "derive(Component" | grep "Resource"` — find dual-derive types; split them. +4. `grep -rn "get_mut" ` on `Assets<...>` — adapt to `AssetMut`. +5. `grep -rn "EntityComponentsTrigger {"` — add `..` to destructuring. +6. GLTF material handles — append `/std` labels where `StandardMaterial` is expected.