forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve SpatialBundle docs (#9673)

Browse Source 
# Objective

This PR aims to fix a handful of problems with the `SpatialBundle` docs:

The docs describe the role of the single components of the bundle,
overshadowing the purpose of `SpatialBundle` itself. Also, those items
may be added, removed or changed over time, as it happened with #9497,
requiring a higher maintenance effort, which will often result in
errors, as it happened.

## Solution

Just describe the role of `SpatialBundle` and of the transform and
visibility concepts, without mentioning the specific component types.
Since the bundle has public fields, the reader can easily click them and
read the documentation if they need to know more. I removed the mention
of numbers of components since they were four, now they are five, and
who knows how many they will be in the future. In this process, I
removed the bullet points, which are no longer needed, and were
contextually wrong in the first place, since they were meant to list the
components, but ended up describing use-cases and requirements for
hierarchies.

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
This commit is contained in:
Federico Rinaldi 2023-09-03 01:44:12 +02:00 committed by GitHub
parent 58f7dac689
commit 532f3cb603
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 11 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
crates/bevy_render/src/spatial_bundle.rs
View File

@ -3,16 +3,18 @@ use bevy_transform::prelude::{GlobalTransform, Transform};
use crate::view::{InheritedVisibility, ViewVisibility, Visibility};
/// A [`Bundle`] with the following [`Component`](bevy_ecs::component::Component)s:
/// * [`Visibility`], and [`InheritedVisibility`], which describe the visibility of an entity
/// * [`Transform`] and [`GlobalTransform`], which describe the position of an entity
/// A [`Bundle`] that allows the correct positional rendering of an entity.
///
/// * To show or hide an entity, you should set its [`Visibility`].
/// * To get the computed visibility of an entity, you should get its [`InheritedVisibility`] or [`ViewVisibility`] components.
/// * To place or move an entity, you should set its [`Transform`].
/// * To get the global transform of an entity, you should get its [`GlobalTransform`].
/// * For hierarchies to work correctly, you must have all four components.
/// * You may use the [`SpatialBundle`] to guarantee this.
/// It consists of transform components,
/// controlling position, rotation and scale of the entity,
/// but also visibility components,
/// which determine whether the entity is visible or not.
///
/// Parent-child hierarchies of entities must contain
/// all the [`Component`]s in this `Bundle`
/// to be rendered correctly.
///
/// [`Component`]: bevy_ecs::component::Component
#[derive(Bundle, Debug, Default)]
pub struct SpatialBundle {
/// The visibility of the entity.