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//! [`match_severity`] error handler function is used, which defers to an error's [`Severity`].
9//!
10//! You can change the default behavior by registering a custom error handler:
11//! Use [`FallbackErrorHandler`] 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//! - [`match_severity`] defers to an error's [`Severity`], using one of the handlers listed below.
19//! - [`panic`] – panics with the system error
20//! - [`error`] – logs the system error at the `error` level
21//! - [`warn`] – logs the system error at the `warn` level
22//! - [`info`] – logs the system error at the `info` level
23//! - [`debug`] – logs the system error at the `debug` level
24//! - [`trace`] – logs the system error at the `trace` level
25//! - [`ignore`] – ignores the system error
26//!
27//! However, you can use any custom error handler logic by providing your own function (or
28//! non-capturing closure that coerces to the function signature) as long as it matches the
29//! signature:
30//!
31//! ```rust,ignore
32//! fn(BevyError, ErrorContext)
33//! ```
34//!
35//! The [`ErrorContext`] allows you to access additional details relevant to providing
36//! context surrounding the error – such as the system's [`name`] – in your error messages.
37//!
38//! ```rust, ignore
39//! use bevy_ecs::error::{BevyError, ErrorContext, FallbackErrorHandler};
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//!     let mut world = World::new();
52//!     world.insert_resource(FallbackErrorHandler(my_error_handler));
53//!     // Use your world here
54//! }
55//! ```
56//!
57//! If you need special handling of individual fallible systems, you can use Bevy's [`system piping
58//! feature`] to capture the [`Result`] output of the system and handle it accordingly.
59//!
60//! When working with commands, you can handle the result of each command separately
61//! using the [`Command::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//! [`Command::handle_error_with`]: crate::system::Command::handle_error_with
70
71mod bevy_error;
72mod command_handling;
73mod handler;
74
75pub use bevy_error::*;
76pub use command_handling::*;
77pub use handler::*;
78
79/// A result type for use in fallible systems, commands and observers.
80///
81/// The [`BevyError`] type is a type-erased error type with optional Bevy-specific diagnostics.
82pub type Result<T = (), E = BevyError> = core::result::Result<T, E>;
bevy_ecs/error/mod.rs

bevy_ecs/error/
mod.rs
