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

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
2026-07-07 17:52:10 +02:00
parent 325e278af1
commit c661027d19
14 changed files with 927 additions and 53 deletions
@@ -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::<ChildOf>(entity)`, `query.relationship_sources::<Children>(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::<Children>()` | 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` |