SceneSpawner needs more explanation of how it works.
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 171
Description
The [`SceneSpawner`](http://dev-docs.bevyengine.org/bevy/prelude/struct.SceneSpawner.html) docs provide rudimentary explanation of how to use the spawning/despawning API, but don't go into more detail. For instance, what does it mean to `spawn_as_child`? What, exactly, is made into a child of the parent entity?
Looking at the source explains that every scene has a root entity, but this property is not explained anywhere in the docs. It's also not clear what happens if tat invariant does not hold.
There are more questions: what makes an entity considered part of a scene, such that it will be affected by despawning? Is it applicable to only those entities directly created by the spawner? Or does it follow the hierarchy? Is there a way to insert new children of that root node that represents the entire scene?
Given how nontrivial the implementation actually is, relying on hierarchy relationships among the scene's entities, more docs are sorely needed.
See also [this Discord thread](https://discord.com/channels/691052431525675048/1203684702007861258).
Contributor guide
Research direction
Start with the SceneSpawner API documentation linked in the issue, then inspect the SceneSpawner implementation and the referenced Discord discussion to verify the spawning and despawning behavior. Document what spawn_as_child means, how the scene root and hierarchy determine membership, what happens when the root invariant is absent, and whether new children can be added. Done means these behaviors are explained in the API docs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100