56bcbb0975
# Objective Resolves #3824. `unsafe` code should be the exception, not the norm in Rust. It's obviously needed for various use cases as it's interfacing with platforms and essentially running the borrow checker at runtime in the ECS, but the touted benefits of Bevy is that we are able to heavily leverage Rust's safety, and we should be holding ourselves accountable to that by minimizing our unsafe footprint. ## Solution Deny `unsafe_code` workspace wide. Add explicit exceptions for the following crates, and forbid it in almost all of the others. * bevy_ecs - Obvious given how much unsafe is needed to achieve performant results * bevy_ptr - Works with raw pointers, even more low level than bevy_ecs. * bevy_render - due to needing to integrate with wgpu * bevy_window - due to needing to integrate with raw_window_handle * bevy_utils - Several unsafe utilities used by bevy_ecs. Ideally moved into bevy_ecs instead of made publicly usable. * bevy_reflect - Required for the unsafe type casting it's doing. * bevy_transform - for the parallel transform propagation * bevy_gizmos - For the SystemParam impls it has. * bevy_assets - To support reflection. Might not be required, not 100% sure yet. * bevy_mikktspace - due to being a conversion from a C library. Pending safe rewrite. * bevy_dynamic_plugin - Inherently unsafe due to the dynamic loading nature. Several uses of unsafe were rewritten, as they did not need to be using them: * bevy_text - a case of `Option::unchecked` could be rewritten as a normal for loop and match instead of an iterator. * bevy_color - the Pod/Zeroable implementations were replaceable with bytemuck's derive macros.
101 lines
3.1 KiB
Rust
101 lines
3.1 KiB
Rust
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
|
|
#![forbid(unsafe_code)]
|
|
#![doc(
|
|
html_logo_url = "https://bevyengine.org/assets/icon.png",
|
|
html_favicon_url = "https://bevyengine.org/assets/icon.png"
|
|
)]
|
|
|
|
//! Parent-child relationships for Bevy entities.
|
|
//!
|
|
//! You should use the tools in this crate
|
|
//! whenever you want to organize your entities in a hierarchical fashion,
|
|
//! to make groups of entities more manageable,
|
|
//! or to propagate properties throughout the entity hierarchy.
|
|
//!
|
|
//! This crate introduces various tools, including a [plugin]
|
|
//! for managing parent-child relationships between entities.
|
|
//! It provides two components, [`Parent`] and [`Children`],
|
|
//! to store references to related entities.
|
|
//! It also provides [command] and [world] API extensions
|
|
//! to set and clear those relationships.
|
|
//!
|
|
//! More advanced users may also appreciate
|
|
//! [query extension methods] to traverse hierarchies,
|
|
//! and [events] to notify hierarchical changes.
|
|
//! There is also a [diagnostic plugin] to validate property propagation.
|
|
//!
|
|
//! # Hierarchy management
|
|
//!
|
|
//! The methods defined in this crate fully manage
|
|
//! the components responsible for defining the entity hierarchy.
|
|
//! Mutating these components manually may result in hierarchy invalidation.
|
|
//!
|
|
//! Hierarchical relationships are always managed symmetrically.
|
|
//! For example, assigning a child to an entity
|
|
//! will always set the parent in the other,
|
|
//! and vice versa.
|
|
//! Similarly, unassigning a child in the parent
|
|
//! will always unassign the parent in the child.
|
|
//!
|
|
//! ## Despawning entities
|
|
//!
|
|
//! The commands and methods provided by `bevy_ecs` to despawn entities
|
|
//! are not capable of automatically despawning hierarchies of entities.
|
|
//! In most cases, these operations will invalidate the hierarchy.
|
|
//! Instead, you should use the provided [hierarchical despawn extension methods].
|
|
//!
|
|
//! [command]: BuildChildren
|
|
//! [diagnostic plugin]: ValidParentCheckPlugin
|
|
//! [events]: HierarchyEvent
|
|
//! [hierarchical despawn extension methods]: DespawnRecursiveExt
|
|
//! [plugin]: HierarchyPlugin
|
|
//! [query extension methods]: HierarchyQueryExt
|
|
//! [world]: BuildWorldChildren
|
|
|
|
mod components;
|
|
pub use components::*;
|
|
|
|
mod hierarchy;
|
|
pub use hierarchy::*;
|
|
|
|
mod child_builder;
|
|
pub use child_builder::*;
|
|
|
|
mod events;
|
|
pub use events::*;
|
|
|
|
mod valid_parent_check_plugin;
|
|
pub use valid_parent_check_plugin::*;
|
|
|
|
mod query_extension;
|
|
pub use query_extension::*;
|
|
|
|
#[doc(hidden)]
|
|
pub mod prelude {
|
|
#[doc(hidden)]
|
|
pub use crate::{child_builder::*, components::*, hierarchy::*, query_extension::*};
|
|
|
|
#[doc(hidden)]
|
|
#[cfg(feature = "bevy_app")]
|
|
pub use crate::{HierarchyPlugin, ValidParentCheckPlugin};
|
|
}
|
|
|
|
#[cfg(feature = "bevy_app")]
|
|
use bevy_app::prelude::*;
|
|
|
|
/// Provides hierarchy functionality to a Bevy app.
|
|
///
|
|
/// Check the [crate-level documentation] for all the features.
|
|
///
|
|
/// [crate-level documentation]: crate
|
|
#[derive(Default)]
|
|
pub struct HierarchyPlugin;
|
|
|
|
impl Plugin for HierarchyPlugin {
|
|
fn build(&self, app: &mut App) {
|
|
app.register_type::<Children>()
|
|
.register_type::<Parent>()
|
|
.add_event::<HierarchyEvent>();
|
|
}
|
|
}
|