Struct BevyError 

pub struct BevyError { /* private fields */ }

The built in “universal” Bevy error type. This has a blanket From impl for any type that implements Rust’s Error, meaning it can be used as a “catch all” error.

Severity

Each BevyError carries a Severity value that indicates how serious the error is. While the levels within Severity correspond to traditional logging levels, these levels are fundamentally advisory metadata. The fallback error handler ultimately has discretion to respond to each of these errors according to its configuration. The error handler ultimately has discretion to respond to each of these errors according to its configuration. You can change the behavior of the fallback handler by modifying the FallbackErrorHandler resource.

By default, errors without an assigned severity use Severity::Panic, and will cause your application to panic. You can change the severity of an error by using with_severity, or map_severity on any Result type.

Backtraces

When used with the backtrace Cargo feature, it can capture a backtrace when the error is constructed (generally in the From impl).

To enable backtrace capture on supported platforms, set the RUST_BACKTRACE environment variable. See Backtrace::capture for details.

When the error is printed, the backtrace will be displayed. By default, the backtrace will be trimmed down to filter out noise. To see the full backtrace, set the BEVY_BACKTRACE=full environment variable.

Context

You can attach a context message to a Result or Option value to turn it into a Result with a BevyError using context or with_context. The resulting error will have the message passed to context added to it.

Usage

fn fallible_system() -> Result<(), BevyError> {
    // This will result in Rust's built-in ParseIntError, which will automatically
    // be converted into a BevyError with an additional message.
    let parsed: usize = "I am not a number".parse().context("failed to parse number")?;
    Ok(())
}

Implementations

impl BevyError

pub fn new<E>(severity: Severity, error: E) -> Self

where Box<dyn Error + Sync + Send>: From<E>,

Constructs a new BevyError with the given Severity.

The error will be stored as a Box<dyn Error + Send + Sync>.

The easiest way to use this is to pass in a string. This works because any type that can be converted into a Box<dyn Error + Send + Sync> can be used, and str is one such type.

Examples

fn some_function(val: i64) -> Result<(), BevyError> {
    if val < 0 {
        // Consider using the bevy_error! or even the bail! macro for format! support
        let error =
            BevyError::new(Severity::Panic, format!("Value can't be negative {val}"));
        return Err(error);
    }

    // ...
    Ok(())
}

pub fn new_with_backtrace<E>( severity: Severity, error: E, backtrace: Backtrace, ) -> Self

where Box<dyn Error + Sync + Send>: From<E>,

Constructs a new BevyError with the given Severity.

Like BevyError::new, but if the backtrace cargo feature is enabled it will use the supplied backtrace instead of capturing a new one.

pub fn ignore<E>(error: E) -> Self

where Box<dyn Error + Send + Sync>: From<E>,

Creates a new BevyError with the Severity::Ignore severity.

This is a shorthand for BevyError::new(Severity::Ignore, error).

pub fn trace<E>(error: E) -> Self

where Box<dyn Error + Send + Sync>: From<E>,

Creates a new BevyError with the Severity::Trace severity.

This is a shorthand for BevyError::new(Severity::Trace, error).

pub fn debug<E>(error: E) -> Self

where Box<dyn Error + Send + Sync>: From<E>,

Creates a new BevyError with the Severity::Debug severity.

This is a shorthand for BevyError::new(Severity::Debug, error).

pub fn info<E>(error: E) -> Self

where Box<dyn Error + Send + Sync>: From<E>,

Creates a new BevyError with the Severity::Info severity.

This is a shorthand for BevyError::new(Severity::Info, error).

pub fn warning<E>(error: E) -> Self

where Box<dyn Error + Send + Sync>: From<E>,

Creates a new BevyError with the Severity::Warning severity.

This is a shorthand for BevyError::new(Severity::Warning, error).

pub fn error<E>(error: E) -> Self

where Box<dyn Error + Send + Sync>: From<E>,

Creates a new BevyError with the Severity::Error severity.

This is a shorthand for BevyError::new(Severity::Error, error).

pub fn panic<E>(error: E, payload: Box<dyn Any + Send>) -> Self

where Box<dyn Error + Send + Sync>: From<E>,

Creates a new BevyError with the Severity::Panic severity.

This is a shorthand for BevyError::new(Severity::Panic, error).

pub fn is<E: Error + 'static>(&self) -> bool

Checks if the internal error is of the given type.

pub fn downcast_ref<E: Error + 'static>(&self) -> Option<&E>

Attempts to downcast the internal error to the given type.

impl BevyError

pub fn severity(&self) -> Severity

Returns the severity of this error.

pub fn with_severity(self, severity: Severity) -> Self

Returns this error with its severity overridden.

Note that this doesn’t change the underlying error value; only the Severity metadata used by the error handler.

pub fn with_payload(self, payload: Box<dyn Any + Send>) -> Self

Adds a panic payload to the error. This allows the panic to be resumed with Self::take_payload in the error handler.

pub fn take_payload(&mut self) -> Option<Box<dyn Any + Send>>

Use in an error handler to take the payload and use it to resume unwinding or add it to logging.

Trait Implementations

impl Debug for BevyError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for BevyError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E> From<E> for BevyError

where Box<dyn Error + Send + Sync + 'static>: From<E>,

fn from(error: E) -> Self

Converts to this type from the input type.