Expand description
Error handling for Bevy systems, commands, and observers.
When a system is added to a Schedule
, and its return type is that of Result
, then Bevy
considers those systems to be “fallible”, and the ECS scheduler will special-case the Err
variant of the returned Result
.
All BevyError
s returned by a system, observer or command are handled by an “error handler”. By default, the
panic
error handler function is used, resulting in a panic with the error message attached.
You can change the default behavior by registering a custom error handler:
Use DefaultErrorHandler
to set a custom error handler function for a world,
or App::set_error_handler
for a whole app.
In practice, this is generally feature-flagged: panicking or loudly logging errors in development,
and quietly logging or ignoring them in production to avoid crashing the app.
Bevy provides a number of pre-built error-handlers for you to use:
panic
– panics with the system errorerror
– logs the system error at theerror
levelwarn
– logs the system error at thewarn
levelinfo
– logs the system error at theinfo
leveldebug
– logs the system error at thedebug
leveltrace
– logs the system error at thetrace
levelignore
– ignores the system error
However, you can use any custom error handler logic by providing your own function (or non-capturing closure that coerces to the function signature) as long as it matches the signature:
fn(BevyError, ErrorContext)
The ErrorContext
allows you to access additional details relevant to providing
context surrounding the error – such as the system’s name
– in your error messages.
use bevy_ecs::error::{BevyError, ErrorContext, DefaultErrorHandler};
use log::trace;
fn my_error_handler(error: BevyError, ctx: ErrorContext) {
if ctx.name().ends_with("plz_ignore") {
trace!("Nothing to see here, move along.");
return;
}
bevy_ecs::error::error(error, ctx);
}
fn main() {
let mut world = World::new();
world.insert_resource(DefaultErrorHandler(my_error_handler));
// Use your world here
}
If you need special handling of individual fallible systems, you can use Bevy’s system piping feature
to capture the Result
output of the system and handle it accordingly.
When working with commands, you can handle the result of each command separately using the HandleError::handle_error_with
method.
Structs§
- Bevy
Error - The built in “universal” Bevy error type. This has a blanket
From
impl for any type that implements Rust’sError
, meaning it can be used as a “catch all” error. - Default
Error Handler - Error handler to call when an error is not handled otherwise.
Defaults to
panic()
.
Enums§
- Error
Context - Context for a
BevyError
to aid in debugging.
Traits§
- Command
With Entity - Passes in a specific entity to an
EntityCommand
, resulting in aCommand
that internally runs theEntityCommand
on that entity. - Handle
Error - Takes a
Command
that potentially returns a Result and uses a given error handler function to convert it into aCommand
that internally handles an error if it occurs and returns()
.
Functions§
- bevy_
error_ panic_ hook - When called, this will skip the currently configured panic hook when a
BevyError
backtrace has already been printed. - debug
- Error handler that logs the system error at the
debug
level. - error
- Error handler that logs the system error at the
error
level. - ignore
- Error handler that ignores the system error.
- info
- Error handler that logs the system error at the
info
level. - panic
- Error handler that panics with the system error.
- trace
- Error handler that logs the system error at the
trace
level. - warn
- Error handler that logs the system error at the
warn
level.
Type Aliases§
- Error
Handler - Defines how Bevy reacts to errors.
- Result
- A result type for use in fallible systems, commands and observers.