bevy_ecs/error/
mod.rs

1//! Error handling for Bevy systems, commands, and observers.
2//!
3//! When a system is added to a [`Schedule`], and its return type is that of [`Result`], then Bevy
4//! considers those systems to be "fallible", and the ECS scheduler will special-case the [`Err`]
5//! variant of the returned `Result`.
6//!
7//! All [`BevyError`]s returned by a system, observer or command are handled by an "error handler". By default, the
8//! [`panic`] error handler function is used, resulting in a panic with the error message attached.
9//!
10//! You can change the default behavior by registering a custom error handler.
11//! Modify the [`GLOBAL_ERROR_HANDLER`] value to set a custom error handler function for your entire app.
12//! In practice, this is generally feature-flagged: panicking or loudly logging errors in development,
13//! and quietly logging or ignoring them in production to avoid crashing the app.
14//!
15//! Bevy provides a number of pre-built error-handlers for you to use:
16//!
17//! - [`panic`] – panics with the system error
18//! - [`error`] – logs the system error at the `error` level
19//! - [`warn`] – logs the system error at the `warn` level
20//! - [`info`] – logs the system error at the `info` level
21//! - [`debug`] – logs the system error at the `debug` level
22//! - [`trace`] – logs the system error at the `trace` level
23//! - [`ignore`] – ignores the system error
24//!
25//! However, you can use any custom error handler logic by providing your own function (or
26//! non-capturing closure that coerces to the function signature) as long as it matches the
27//! signature:
28//!
29//! ```rust,ignore
30//! fn(BevyError, ErrorContext)
31//! ```
32//!
33//! The [`ErrorContext`] allows you to access additional details relevant to providing
34//! context surrounding the error – such as the system's [`name`] – in your error messages.
35//!
36//! Remember to turn on the `configurable_error_handler` feature to set a global error handler!
37//!
38//! ```rust, ignore
39//! use bevy_ecs::error::{GLOBAL_ERROR_HANDLER, BevyError, ErrorContext};
40//! use log::trace;
41//!
42//! fn my_error_handler(error: BevyError, ctx: ErrorContext) {
43//!    if ctx.name().ends_with("plz_ignore") {
44//!       trace!("Nothing to see here, move along.");
45//!       return;
46//!   }
47//!   bevy_ecs::error::error(error, ctx);
48//! }
49//!
50//! fn main() {
51//!     // This requires the "configurable_error_handler" feature to be enabled to be in scope.
52//!     GLOBAL_ERROR_HANDLER.set(my_error_handler).expect("The error handler can only be set once.");
53//!     
54//!     // Initialize your Bevy App here
55//! }
56//! ```
57//!
58//! If you need special handling of individual fallible systems, you can use Bevy's [`system piping
59//! feature`] to capture the [`Result`] output of the system and handle it accordingly.
60//!
61//! When working with commands, you can handle the result of each command separately using the [`HandleError::handle_error_with`] method.
62//!
63//! [`Schedule`]: crate::schedule::Schedule
64//! [`panic`]: panic()
65//! [`World`]: crate::world::World
66//! [`System`]: crate::system::System
67//! [`name`]: crate::system::System::name
68//! [`system piping feature`]: crate::system::In
69
70mod bevy_error;
71mod command_handling;
72mod handler;
73
74pub use bevy_error::*;
75pub use command_handling::*;
76pub use handler::*;
77
78/// A result type for use in fallible systems, commands and observers.
79///
80/// The [`BevyError`] type is a type-erased error type with optional Bevy-specific diagnostics.
81pub type Result<T = (), E = BevyError> = core::result::Result<T, E>;
bevy_ecs/error/mod.rs

bevy_ecs/error/
mod.rs
