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//! Use [`DefaultErrorHandler`] to set a custom error handler function for a world,
12//! or `App::set_error_handler` for a whole app.
13//! In practice, this is generally feature-flagged: panicking or loudly logging errors in development,
14//! and quietly logging or ignoring them in production to avoid crashing the app.
15//!
16//! Bevy provides a number of pre-built error-handlers for you to use:
17//!
18//! - [`panic`] – panics with the system error
19//! - [`error`] – logs the system error at the `error` level
20//! - [`warn`] – logs the system error at the `warn` level
21//! - [`info`] – logs the system error at the `info` level
22//! - [`debug`] – logs the system error at the `debug` level
23//! - [`trace`] – logs the system error at the `trace` level
24//! - [`ignore`] – ignores the system error
25//!
26//! However, you can use any custom error handler logic by providing your own function (or
27//! non-capturing closure that coerces to the function signature) as long as it matches the
28//! signature:
29//!
30//! ```rust,ignore
31//! fn(BevyError, ErrorContext)
32//! ```
33//!
34//! The [`ErrorContext`] allows you to access additional details relevant to providing
35//! context surrounding the error – such as the system's [`name`] – in your error messages.
36//!
37//! ```rust, ignore
38//! use bevy_ecs::error::{BevyError, ErrorContext, DefaultErrorHandler};
39//! use log::trace;
40//!
41//! fn my_error_handler(error: BevyError, ctx: ErrorContext) {
42//!    if ctx.name().ends_with("plz_ignore") {
43//!       trace!("Nothing to see here, move along.");
44//!       return;
45//!   }
46//!   bevy_ecs::error::error(error, ctx);
47//! }
48//!
49//! fn main() {
50//!     let mut world = World::new();
51//!     world.insert_resource(DefaultErrorHandler(my_error_handler));
52//!     // Use your world here
53//! }
54//! ```
55//!
56//! If you need special handling of individual fallible systems, you can use Bevy's [`system piping
57//! feature`] to capture the [`Result`] output of the system and handle it accordingly.
58//!
59//! When working with commands, you can handle the result of each command separately using the [`HandleError::handle_error_with`] method.
60//!
61//! [`Schedule`]: crate::schedule::Schedule
62//! [`panic`]: panic()
63//! [`World`]: crate::world::World
64//! [`System`]: crate::system::System
65//! [`name`]: crate::system::System::name
66//! [`system piping feature`]: crate::system::In
67
68mod bevy_error;
69mod command_handling;
70mod handler;
71
72pub use bevy_error::*;
73pub use command_handling::*;
74pub use handler::*;
75
76/// A result type for use in fallible systems, commands and observers.
77///
78/// The [`BevyError`] type is a type-erased error type with optional Bevy-specific diagnostics.
79pub type Result<T = (), E = BevyError> = core::result::Result<T, E>;
bevy_ecs/error/mod.rs

bevy_ecs/error/
mod.rs
