bevy/crates/bevy_internal/src/lib.rs

215 lines
4.8 KiB
Rust
Raw Normal View History

#![cfg_attr(docsrs, feature(doc_auto_cfg))]
Forbid unsafe in most crates in the engine (#12684) # 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.
2024-03-27 03:30:08 +00:00
#![forbid(unsafe_code)]
#![doc(
html_logo_url = "https://bevyengine.org/assets/icon.png",
html_favicon_url = "https://bevyengine.org/assets/icon.png"
)]
//! This module is separated into its own crate to enable simple dynamic linking for Bevy, and should not be used directly
/// `use bevy::prelude::*;` to import common components, bundles, and plugins.
pub mod prelude;
mod default_plugins;
pub use default_plugins::*;
/// Integrate with platform accessibility APIs.
pub mod a11y {
pub use bevy_a11y::*;
}
/// Build bevy apps, create plugins, and read events.
pub mod app {
pub use bevy_app::*;
}
/// Load and store assets and resources for Apps.
#[cfg(feature = "bevy_asset")]
pub mod asset {
pub use bevy_asset::*;
}
/// Contains core plugins.
pub mod core {
pub use bevy_core::*;
}
/// Shared color types and operations.
#[cfg(feature = "bevy_color")]
pub mod color {
pub use bevy_color::*;
}
/// Useful diagnostic plugins and types for bevy apps.
pub mod diagnostic {
pub use bevy_diagnostic::*;
}
/// Bevy's entity-component-system.
pub mod ecs {
pub use bevy_ecs::*;
}
/// Resources and events for inputs, e.g. mouse/keyboard, touch, gamepads, etc.
pub mod input {
pub use bevy_input::*;
}
/// Logging capabilities
2020-11-13 01:23:57 +00:00
pub mod log {
pub use bevy_log::*;
}
/// Math types (Vec3, Mat4, Quat, etc) and helpers.
pub mod math {
pub use bevy_math::*;
}
/// Utilities for working with untyped pointers in a more safe way.
pub mod ptr {
pub use bevy_ptr::*;
}
/// Type reflection used for dynamically interacting with rust types.
2020-11-28 00:39:59 +00:00
pub mod reflect {
pub use bevy_reflect::*;
}
/// Save/load collections of entities and components to/from file.
#[cfg(feature = "bevy_scene")]
pub mod scene {
pub use bevy_scene::*;
}
/// Pools for async, IO, and compute tasks.
pub mod tasks {
pub use bevy_tasks::*;
}
/// Contains time utilities.
pub mod time {
pub use bevy_time::*;
}
/// Entity hierarchies and property inheritance
Split bevy_hierarchy out from bevy_transform (#4168) # Objective - Hierarchy tools are not just used for `Transform`: they are also used for scenes. - In the future there's interest in using them for other features, such as visiibility inheritance. - The fact that these tools are found in `bevy_transform` causes a great deal of user and developer confusion - Fixes #2758. ## Solution - Split `bevy_transform` into two! - Make everything work again. Note that this is a very tightly scoped PR: I *know* there are code quality and docs issues that existed in bevy_transform that I've just moved around. We should fix those in a seperate PR and try to merge this ASAP to reduce the bitrot involved in splitting an entire crate. ## Frustrations The API around `GlobalTransform` is a mess: we have massive code and docs duplication, no link between the two types and no clear way to extend this to other forms of inheritance. In the medium-term, I feel pretty strongly that `GlobalTransform` should be replaced by something like `Inherited<Transform>`, which lives in `bevy_hierarchy`: - avoids code duplication - makes the inheritance pattern extensible - links the types at the type-level - allows us to remove all references to inheritance from `bevy_transform`, making it more useful as a standalone crate and cleaning up its docs ## Additional context - double-blessed by @cart in https://github.com/bevyengine/bevy/issues/4141#issuecomment-1063592414 and https://github.com/bevyengine/bevy/issues/2758#issuecomment-913810963 - preparation for more advanced / cleaner hierarchy tools: go read https://github.com/bevyengine/rfcs/pull/53 ! - originally attempted by @finegeometer in #2789. It was a great idea, just needed more discussion! Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-03-15 01:54:05 +00:00
pub mod hierarchy {
pub use bevy_hierarchy::*;
}
/// Local and global transforms (e.g. translation, scale, rotation).
pub mod transform {
pub use bevy_transform::*;
}
/// Various miscellaneous utilities for easing development
pub mod utils {
pub use bevy_utils::*;
}
/// Configuration, creation, and management of one or more windows.
pub mod window {
pub use bevy_window::*;
}
/// Provides types and plugins for animations.
#[cfg(feature = "bevy_animation")]
pub mod animation {
pub use bevy_animation::*;
}
/// Provides types and plugins for audio playback.
#[cfg(feature = "bevy_audio")]
pub mod audio {
pub use bevy_audio::*;
}
/// Core render pipeline.
#[cfg(feature = "bevy_core_pipeline")]
pub mod core_pipeline {
pub use bevy_core_pipeline::*;
}
/// Bevy interface with `GilRs` - "Game Input Library for Rust" - to handle gamepad inputs.
#[cfg(feature = "bevy_gilrs")]
pub mod gilrs {
pub use bevy_gilrs::*;
}
/// Support for GLTF file loading.
#[cfg(feature = "bevy_gltf")]
pub mod gltf {
pub use bevy_gltf::*;
}
/// Physically based rendering.
#[cfg(feature = "bevy_pbr")]
pub mod pbr {
pub use bevy_pbr::*;
}
/// Cameras, meshes, textures, shaders, and pipelines.
/// Use [`RenderDevice::features`](renderer::RenderDevice::features),
/// [`RenderDevice::limits`](renderer::RenderDevice::limits), and the
/// [`RenderAdapterInfo`](renderer::RenderAdapterInfo) resource to
/// get runtime information about the actual adapter, backend, features, and limits.
#[cfg(feature = "bevy_render")]
pub mod render {
pub use bevy_render::*;
}
/// Items for sprites, rects, texture atlases, etc.
#[cfg(feature = "bevy_sprite")]
pub mod sprite {
pub use bevy_sprite::*;
}
/// Text drawing, styling, and font assets.
#[cfg(feature = "bevy_text")]
pub mod text {
pub use bevy_text::*;
}
/// User interface components and widgets.
#[cfg(feature = "bevy_ui")]
pub mod ui {
pub use bevy_ui::*;
}
/// Window creation, configuration, and handling
#[cfg(feature = "bevy_winit")]
pub mod winit {
pub use bevy_winit::*;
}
/// Immediate mode drawing api for visual debugging.
///
/// # Example
/// ```
/// # use bevy_gizmos::prelude::*;
/// # use bevy_render::prelude::*;
/// # use bevy_math::prelude::*;
/// # use bevy_color::palettes::basic::GREEN;
/// fn system(mut gizmos: Gizmos) {
/// gizmos.line(Vec3::ZERO, Vec3::X, GREEN);
/// }
/// # bevy_ecs::system::assert_is_system(system);
/// ```
///
/// See the documentation on [`Gizmos`](gizmos::Gizmos) for more examples.
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
#[cfg(feature = "bevy_gizmos")]
pub mod gizmos {
pub use bevy_gizmos::*;
}
/// Dynamic linking of plugins
#[cfg(feature = "bevy_dynamic_plugin")]
pub mod dynamic_plugin {
pub use bevy_dynamic_plugin::*;
}
/// Collection of developer tools
#[cfg(feature = "bevy_dev_tools")]
pub mod dev_tools {
pub use bevy_dev_tools::*;
}