# Bevy Skill Research: Hierarchy & Relationships

> **Bevy version**: 0.18, with 0.19 notes  
> **Date**: 2026-07-07

## ChildOf Replaces Parent (Bevy 0.16+)

- `Parent` renamed to **`ChildOf(pub Entity)`** — "entities with ChildOf are children, not parents"
- `Deref` removed; use **`child_of.parent()`** to get the parent Entity
- `ChildOf` implements `Relationship`; `Children` implements `RelationshipTarget` — they auto-sync via hooks
- Adding `ChildOf(parent)` to child auto-inserts `Children` on parent; removing it auto-updates parent
- Despawning a parent **auto-despawns all descendants** (was `despawn_recursive`, now just `despawn()`)

## Spawning Children

```rust
// Insert ChildOf directly
commands.spawn(ChildOf(parent));

// Inline child on parent
commands.entity(parent).with_child((SpriteBundle::default(), ChildOf(parent)));

// Multiple children via closure
commands.spawn_empty().with_children(|spawner: &mut ChildSpawnerCommands| {
    spawner.spawn(MyComponent(255));
    let parent = spawner.target_entity(); // was parent_entity()
});

// Add existing entities as children
commands.entity(parent).add_child(child);
commands.entity(parent).add_children(&[child1, child2]);
commands.entity(parent).insert_children(index, &[child1, child2]);
```

## Querying Hierarchy

- **`Children`** derefs to `[Entity]`, implements `IntoIterator`
- Correct iteration: **`for child in &children`** or **`children.into_iter()`**
- Wrong: ~~`children.iter().copied()`~~ — unnecessary, `IntoIterator` yields `Entity` directly
- Methods: `len()`, `is_empty()`, `contains()`, `first()`, `last()`, `sort_by()`
- Query extensions (0.16+): `query.related::<ChildOf>(entity)`, `query.relationship_sources::<Children>(entity)`

## Detaching vs Despawning (0.18 Renames)

| Old name (≤0.17) | New name (0.18+) | Effect |
|-------------------|------------------|--------|
| `remove_children` | **`detach_children`** | Detach only, do NOT despawn |
| `clear_children` | **`detach_all_children`** | Detach all, do NOT despawn |
| `remove_child` | **`detach_child`** | Detach one, do NOT despawn |

To actually despawn children: `despawn_related::<Children>()`

## Transform Propagation

- `GlobalTransform` is auto-propagated through `ChildOf` hierarchy
- Child `Transform` is relative to parent; `GlobalTransform` is computed world-space
- Propagation runs in **`PostUpdate`** — reading `GlobalTransform` in `Update` gives stale (last-frame) values

## Common Mistakes

| Mistake | Correct |
|---------|---------|
| `Parent` component | `ChildOf(entity)` |
| `children.iter().copied()` | `children.into_iter()` or `for child in &children` |
| `*child_of` (deref) | `child_of.parent()` |
| `despawn_recursive()` | `despawn()` (auto-recursive now) |
| `parent_entity()` in spawner | `target_entity()` |
| `clear_children()` | `detach_all_children()` (0.18+) |
| `remove_children()` | `detach_children()` (0.18+) |
| Reading GlobalTransform in Update | Read in PostUpdate, or accept one-frame lag |