diff --git a/plugins/bevy/skills/bevy-0.19/SKILL.md b/plugins/bevy/skills/bevy-0.19/SKILL.md index e9e40a2..8d88c67 100644 --- a/plugins/bevy/skills/bevy-0.19/SKILL.md +++ b/plugins/bevy/skills/bevy-0.19/SKILL.md @@ -44,7 +44,7 @@ The highest-frequency mistakes. When in doubt, trust this table over memory: |------|--------| | 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()` | +| `Ref.clone()` | Returns `Ref`, not the inner value — use `my_ref.deref().clone()` | | `Assets::get_mut` | Returns `AssetMut` (mutation-tracked), not `&mut A` | | GLTF materials | Return `GltfMaterial`; use `#Material0/std` label for `StandardMaterial` | @@ -68,7 +68,7 @@ struct Player; ### 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`: +Plain functions of `SystemParam`s. Make fallible systems return `Result` (0.18+) — errors are logged via `BevyError` and the system continues running on its normal schedule; `?` works with anything convertible to `BevyError`: ```rust fn apply_damage(mut q: Query<&mut Health>, mut reader: MessageReader) -> Result { @@ -156,7 +156,7 @@ Bevy often succeeds silently when misconfigured. If something "doesn't show up" 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`. +More production gotchas (custom relationships, debugging heuristics): `references/production-gotchas.md`. ## Code style @@ -179,7 +179,7 @@ Load on demand — each is self-contained: | `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 | +| `references/production-gotchas.md` | Silent failures, headless contexts, debugging heuristics | ## Related skill diff --git a/plugins/bevy/skills/bevy-0.19/references/events-observers.md b/plugins/bevy/skills/bevy-0.19/references/events-observers.md index 5db7c4b..a7c66a0 100644 --- a/plugins/bevy/skills/bevy-0.19/references/events-observers.md +++ b/plugins/bevy/skills/bevy-0.19/references/events-observers.md @@ -72,7 +72,7 @@ Built-in events observers can watch per component: |-------|-------|-------| | `Add` | component added where absent | first | | `Insert` | any insert (add or replace) | after `Add` | -| `Replace` | component removed, regardless of replacement | before `Remove` | +| `Replace` | component value overwritten by a new insert over an existing value | before `Remove` | | `Remove` | component removed | after `Replace` | | `Despawn` | entity despawned (per component) | last | diff --git a/plugins/bevy/skills/bevy-0.19/references/production-gotchas.md b/plugins/bevy/skills/bevy-0.19/references/production-gotchas.md index 232ed6c..425b861 100644 --- a/plugins/bevy/skills/bevy-0.19/references/production-gotchas.md +++ b/plugins/bevy/skills/bevy-0.19/references/production-gotchas.md @@ -74,17 +74,6 @@ Any system that can run both rendered and headless needs this. 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. diff --git a/plugins/bevy/skills/bevy-upgrade/SKILL.md b/plugins/bevy/skills/bevy-upgrade/SKILL.md index ee8cb10..7c30ee5 100644 --- a/plugins/bevy/skills/bevy-upgrade/SKILL.md +++ b/plugins/bevy/skills/bevy-upgrade/SKILL.md @@ -9,7 +9,7 @@ Bevy ships breaking changes every minor release. Upgrades are tractable if run a ## Workflow -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). +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. @@ -43,7 +43,7 @@ When `Cargo.toml` is ambiguous (workspace inheritance, git deps), the code itsel ## 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. +- **Behavior shifts need runtime verification**: `NextState::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. 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 index 2b67708..acad966 100644 --- 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 @@ -33,7 +33,7 @@ New in 0.18: `#[derive(EntityEvent)]` with `#[event_target]` for entity-targeted ## 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. +- **Fallible systems**: systems may return `Result` (= `Result<(), BevyError>`); errors are logged and the system continues running on its normal schedule. 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`. @@ -52,6 +52,6 @@ New in 0.18: `#[derive(EntityEvent)]` with `#[event_target]` for entity-targeted 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. +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 index 09b983c..21f3630 100644 --- 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 @@ -14,7 +14,7 @@ Smaller than 0.17→0.18 but with one deep semantic change: resources became com ## 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()`. +- **`Ref.clone()`** returns `Ref`, not the inner value. Old code relying on clone-through must use `val.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();` @@ -28,9 +28,9 @@ Smaller than 0.17→0.18 but with one deep semantic change: resources became com ## Porting checklist -1. `grep -rn "SceneRoot\|Scene>" ` — rename to `WorldAssetRoot`/`WorldAsset`. +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`. +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.