Skip to content

Commit

Permalink
Improve SpatialBundle docs (bevyengine#9673)
Browse files Browse the repository at this point in the history
# 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 bevyengine#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>
  • Loading branch information
2 people authored and Ray Redondo committed Jan 9, 2024
1 parent f5e6819 commit 7575747
Showing 1 changed file with 11 additions and 9 deletions.
20 changes: 11 additions & 9 deletions crates/bevy_render/src/spatial_bundle.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 7575747

Please sign in to comment.