Vendor dependencies for 0.3.0 release

vendor/bevy_ecs/src/error/bevy_error.rs

@@ -0,0 +1,249 @@
+use alloc::boxed::Box;
+use core::{
+    error::Error,
+    fmt::{Debug, Display},
+};
+
+/// 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.
+///
+/// # Backtraces
+///
+/// When used with the `backtrace` Cargo feature, it will capture a backtrace when the error is constructed (generally in the [`From`] impl]).
+/// When 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.
+///
+/// # Usage
+///
+/// ```
+/// # use bevy_ecs::prelude::*;
+///
+/// fn fallible_system() -> Result<(), BevyError> {
+///     // This will result in Rust's built-in ParseIntError, which will automatically
+///     // be converted into a BevyError.
+///     let parsed: usize = "I am not a number".parse()?;
+///     Ok(())
+/// }
+/// ```
+pub struct BevyError {
+    inner: Box<InnerBevyError>,
+}
+
+impl BevyError {
+    /// Attempts to downcast the internal error to the given type.
+    pub fn downcast_ref<E: Error + 'static>(&self) -> Option<&E> {
+        self.inner.error.downcast_ref::<E>()
+    }
+
+    fn format_backtrace(&self, _f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        #[cfg(feature = "backtrace")]
+        {
+            let f = _f;
+            let backtrace = &self.inner.backtrace;
+            if let std::backtrace::BacktraceStatus::Captured = backtrace.status() {
+                let full_backtrace = std::env::var("BEVY_BACKTRACE").is_ok_and(|val| val == "full");
+
+                let backtrace_str = alloc::string::ToString::to_string(backtrace);
+                let mut skip_next_location_line = false;
+                for line in backtrace_str.split('\n') {
+                    if !full_backtrace {
+                        if skip_next_location_line {
+                            if line.starts_with("             at") {
+                                continue;
+                            }
+                            skip_next_location_line = false;
+                        }
+                        if line.contains("std::backtrace_rs::backtrace::") {
+                            skip_next_location_line = true;
+                            continue;
+                        }
+                        if line.contains("std::backtrace::Backtrace::") {
+                            skip_next_location_line = true;
+                            continue;
+                        }
+                        if line.contains("<bevy_ecs::error::bevy_error::BevyError as core::convert::From<E>>::from") {
+                            skip_next_location_line = true;
+                            continue;
+                        }
+                        if line.contains("<core::result::Result<T,F> as core::ops::try_trait::FromResidual<core::result::Result<core::convert::Infallible,E>>>::from_residual") {
+                            skip_next_location_line = true;
+                            continue;
+                        }
+                        if line.contains("__rust_begin_short_backtrace") {
+                            break;
+                        }
+                        if line.contains("bevy_ecs::observer::Observers::invoke::{{closure}}") {
+                            break;
+                        }
+                    }
+                    writeln!(f, "{}", line)?;
+                }
+                if !full_backtrace {
+                    if std::thread::panicking() {
+                        SKIP_NORMAL_BACKTRACE.set(true);
+                    }
+                    writeln!(f, "{FILTER_MESSAGE}")?;
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
+/// This type exists (rather than having a `BevyError(Box<dyn InnerBevyError)`) to make [`BevyError`] use a "thin pointer" instead of
+/// a "fat pointer", which reduces the size of our Result by a usize. This does introduce an extra indirection, but error handling is a "cold path".
+/// We don't need to optimize it to that degree.
+/// PERF: We could probably have the best of both worlds with a "custom vtable" impl, but thats not a huge priority right now and the code simplicity
+/// of the current impl is nice.
+struct InnerBevyError {
+    error: Box<dyn Error + Send + Sync + 'static>,
+    #[cfg(feature = "backtrace")]
+    backtrace: std::backtrace::Backtrace,
+}
+
+// NOTE: writing the impl this way gives us From<&str> ... nice!
+impl<E> From<E> for BevyError
+where
+    Box<dyn Error + Send + Sync + 'static>: From<E>,
+{
+    #[cold]
+    fn from(error: E) -> Self {
+        BevyError {
+            inner: Box::new(InnerBevyError {
+                error: error.into(),
+                #[cfg(feature = "backtrace")]
+                backtrace: std::backtrace::Backtrace::capture(),
+            }),
+        }
+    }
+}
+
+impl Display for BevyError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        writeln!(f, "{}", self.inner.error)?;
+        self.format_backtrace(f)?;
+        Ok(())
+    }
+}
+
+impl Debug for BevyError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        writeln!(f, "{:?}", self.inner.error)?;
+        self.format_backtrace(f)?;
+        Ok(())
+    }
+}
+
+#[cfg(feature = "backtrace")]
+const FILTER_MESSAGE: &str = "note: Some \"noisy\" backtrace lines have been filtered out. Run with `BEVY_BACKTRACE=full` for a verbose backtrace.";
+
+#[cfg(feature = "backtrace")]
+std::thread_local! {
+    static SKIP_NORMAL_BACKTRACE: core::cell::Cell<bool> =
+        const { core::cell::Cell::new(false) };
+}
+
+/// When called, this will skip the currently configured panic hook when a [`BevyError`] backtrace has already been printed.
+#[cfg(feature = "backtrace")]
+#[expect(clippy::print_stdout, reason = "Allowed behind `std` feature gate.")]
+pub fn bevy_error_panic_hook(
+    current_hook: impl Fn(&std::panic::PanicHookInfo),
+) -> impl Fn(&std::panic::PanicHookInfo) {
+    move |info| {
+        if SKIP_NORMAL_BACKTRACE.replace(false) {
+            if let Some(payload) = info.payload().downcast_ref::<&str>() {
+                std::println!("{payload}");
+            } else if let Some(payload) = info.payload().downcast_ref::<alloc::string::String>() {
+                std::println!("{payload}");
+            }
+            return;
+        }
+
+        current_hook(info);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+
+    #[test]
+    #[cfg(not(miri))] // miri backtraces are weird
+    #[cfg(not(windows))] // the windows backtrace in this context is ... unhelpful and not worth testing
+    fn filtered_backtrace_test() {
+        fn i_fail() -> crate::error::Result {
+            let _: usize = "I am not a number".parse()?;
+            Ok(())
+        }
+
+        // SAFETY: this is not safe ...  this test could run in parallel with another test
+        // that writes the environment variable. We either accept that so we can write this test,
+        // or we don't.
+
+        unsafe { std::env::set_var("RUST_BACKTRACE", "1") };
+
+        let error = i_fail().err().unwrap();
+        let debug_message = alloc::format!("{error:?}");
+        let mut lines = debug_message.lines().peekable();
+        assert_eq!(
+            "ParseIntError { kind: InvalidDigit }",
+            lines.next().unwrap()
+        );
+
+        // On mac backtraces can start with Backtrace::create
+        let mut skip = false;
+        if let Some(line) = lines.peek() {
+            if &line[6..] == "std::backtrace::Backtrace::create" {
+                skip = true;
+            }
+        }
+
+        if skip {
+            lines.next().unwrap();
+        }
+
+        let expected_lines = alloc::vec![
+            "bevy_ecs::error::bevy_error::tests::filtered_backtrace_test::i_fail",
+            "bevy_ecs::error::bevy_error::tests::filtered_backtrace_test",
+            "bevy_ecs::error::bevy_error::tests::filtered_backtrace_test::{{closure}}",
+            "core::ops::function::FnOnce::call_once",
+        ];
+
+        for expected in expected_lines {
+            let line = lines.next().unwrap();
+            assert_eq!(&line[6..], expected);
+            let mut skip = false;
+            if let Some(line) = lines.peek() {
+                if line.starts_with("             at") {
+                    skip = true;
+                }
+            }
+
+            if skip {
+                lines.next().unwrap();
+            }
+        }
+
+        // on linux there is a second call_once
+        let mut skip = false;
+        if let Some(line) = lines.peek() {
+            if &line[6..] == "core::ops::function::FnOnce::call_once" {
+                skip = true;
+            }
+        }
+        if skip {
+            lines.next().unwrap();
+        }
+        let mut skip = false;
+        if let Some(line) = lines.peek() {
+            if line.starts_with("             at") {
+                skip = true;
+            }
+        }
+
+        if skip {
+            lines.next().unwrap();
+        }
+        assert_eq!(super::FILTER_MESSAGE, lines.next().unwrap());
+        assert!(lines.next().is_none());
+    }
+}

vendor/bevy_ecs/src/error/command_handling.rs

@@ -0,0 +1,120 @@
+use core::{any::type_name, fmt};
+
+use crate::{
+    entity::Entity,
+    never::Never,
+    system::{entity_command::EntityCommandError, Command, EntityCommand},
+    world::{error::EntityMutableFetchError, World},
+};
+
+use super::{default_error_handler, BevyError, ErrorContext};
+
+/// Takes a [`Command`] that returns a Result and uses a given error handler function to convert it into
+/// a [`Command`] that internally handles an error if it occurs and returns `()`.
+pub trait HandleError<Out = ()> {
+    /// Takes a [`Command`] that returns a Result and uses a given error handler function to convert it into
+    /// a [`Command`] that internally handles an error if it occurs and returns `()`.
+    fn handle_error_with(self, error_handler: fn(BevyError, ErrorContext)) -> impl Command;
+    /// Takes a [`Command`] that returns a Result and uses the default error handler function to convert it into
+    /// a [`Command`] that internally handles an error if it occurs and returns `()`.
+    fn handle_error(self) -> impl Command
+    where
+        Self: Sized,
+    {
+        self.handle_error_with(default_error_handler())
+    }
+}
+
+impl<C, T, E> HandleError<Result<T, E>> for C
+where
+    C: Command<Result<T, E>>,
+    E: Into<BevyError>,
+{
+    fn handle_error_with(self, error_handler: fn(BevyError, ErrorContext)) -> impl Command {
+        move |world: &mut World| match self.apply(world) {
+            Ok(_) => {}
+            Err(err) => (error_handler)(
+                err.into(),
+                ErrorContext::Command {
+                    name: type_name::<C>().into(),
+                },
+            ),
+        }
+    }
+}
+
+impl<C> HandleError<Never> for C
+where
+    C: Command<Never>,
+{
+    fn handle_error_with(self, _error_handler: fn(BevyError, ErrorContext)) -> impl Command {
+        move |world: &mut World| {
+            self.apply(world);
+        }
+    }
+}
+
+impl<C> HandleError for C
+where
+    C: Command,
+{
+    #[inline]
+    fn handle_error_with(self, _error_handler: fn(BevyError, ErrorContext)) -> impl Command {
+        self
+    }
+    #[inline]
+    fn handle_error(self) -> impl Command
+    where
+        Self: Sized,
+    {
+        self
+    }
+}
+
+/// Passes in a specific entity to an [`EntityCommand`], resulting in a [`Command`] that
+/// internally runs the [`EntityCommand`] on that entity.
+///
+// NOTE: This is a separate trait from `EntityCommand` because "result-returning entity commands" and
+// "non-result returning entity commands" require different implementations, so they cannot be automatically
+// implemented. And this isn't the type of implementation that we want to thrust on people implementing
+// EntityCommand.
+pub trait CommandWithEntity<Out> {
+    /// Passes in a specific entity to an [`EntityCommand`], resulting in a [`Command`] that
+    /// internally runs the [`EntityCommand`] on that entity.
+    fn with_entity(self, entity: Entity) -> impl Command<Out> + HandleError<Out>;
+}
+
+impl<C> CommandWithEntity<Result<(), EntityMutableFetchError>> for C
+where
+    C: EntityCommand,
+{
+    fn with_entity(
+        self,
+        entity: Entity,
+    ) -> impl Command<Result<(), EntityMutableFetchError>>
+           + HandleError<Result<(), EntityMutableFetchError>> {
+        move |world: &mut World| -> Result<(), EntityMutableFetchError> {
+            let entity = world.get_entity_mut(entity)?;
+            self.apply(entity);
+            Ok(())
+        }
+    }
+}
+
+impl<C, T, Err> CommandWithEntity<Result<T, EntityCommandError<Err>>> for C
+where
+    C: EntityCommand<Result<T, Err>>,
+    Err: fmt::Debug + fmt::Display + Send + Sync + 'static,
+{
+    fn with_entity(
+        self,
+        entity: Entity,
+    ) -> impl Command<Result<T, EntityCommandError<Err>>> + HandleError<Result<T, EntityCommandError<Err>>>
+    {
+        move |world: &mut World| {
+            let entity = world.get_entity_mut(entity)?;
+            self.apply(entity)
+                .map_err(EntityCommandError::CommandFailed)
+        }
+    }
+}

vendor/bevy_ecs/src/error/handler.rs

@@ -0,0 +1,183 @@
+#[cfg(feature = "configurable_error_handler")]
+use bevy_platform::sync::OnceLock;
+use core::fmt::Display;
+
+use crate::{component::Tick, error::BevyError};
+use alloc::borrow::Cow;
+
+/// Context for a [`BevyError`] to aid in debugging.
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub enum ErrorContext {
+    /// The error occurred in a system.
+    System {
+        /// The name of the system that failed.
+        name: Cow<'static, str>,
+        /// The last tick that the system was run.
+        last_run: Tick,
+    },
+    /// The error occurred in a run condition.
+    RunCondition {
+        /// The name of the run condition that failed.
+        name: Cow<'static, str>,
+        /// The last tick that the run condition was evaluated.
+        last_run: Tick,
+    },
+    /// The error occurred in a command.
+    Command {
+        /// The name of the command that failed.
+        name: Cow<'static, str>,
+    },
+    /// The error occurred in an observer.
+    Observer {
+        /// The name of the observer that failed.
+        name: Cow<'static, str>,
+        /// The last tick that the observer was run.
+        last_run: Tick,
+    },
+}
+
+impl Display for ErrorContext {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            Self::System { name, .. } => {
+                write!(f, "System `{}` failed", name)
+            }
+            Self::Command { name } => write!(f, "Command `{}` failed", name),
+            Self::Observer { name, .. } => {
+                write!(f, "Observer `{}` failed", name)
+            }
+            Self::RunCondition { name, .. } => {
+                write!(f, "Run condition `{}` failed", name)
+            }
+        }
+    }
+}
+
+impl ErrorContext {
+    /// The name of the ECS construct that failed.
+    pub fn name(&self) -> &str {
+        match self {
+            Self::System { name, .. }
+            | Self::Command { name, .. }
+            | Self::Observer { name, .. }
+            | Self::RunCondition { name, .. } => name,
+        }
+    }
+
+    /// A string representation of the kind of ECS construct that failed.
+    ///
+    /// This is a simpler helper used for logging.
+    pub fn kind(&self) -> &str {
+        match self {
+            Self::System { .. } => "system",
+            Self::Command { .. } => "command",
+            Self::Observer { .. } => "observer",
+            Self::RunCondition { .. } => "run condition",
+        }
+    }
+}
+
+/// A global error handler. This can be set at startup, as long as it is set before
+/// any uses. This should generally be configured _before_ initializing the app.
+///
+/// This should be set inside of your `main` function, before initializing the Bevy app.
+/// The value of this error handler can be accessed using the [`default_error_handler`] function,
+/// which calls [`OnceLock::get_or_init`] to get the value.
+///
+/// **Note:** this is only available when the `configurable_error_handler` feature of `bevy_ecs` (or `bevy`) is enabled!
+///
+/// # Example
+///
+/// ```
+/// # use bevy_ecs::error::{GLOBAL_ERROR_HANDLER, warn};
+/// GLOBAL_ERROR_HANDLER.set(warn).expect("The error handler can only be set once, globally.");
+/// // initialize Bevy App here
+/// ```
+///
+/// To use this error handler in your app for custom error handling logic:
+///
+/// ```rust
+/// use bevy_ecs::error::{default_error_handler, GLOBAL_ERROR_HANDLER, BevyError, ErrorContext, panic};
+///
+/// fn handle_errors(error: BevyError, ctx: ErrorContext) {
+///    let error_handler = default_error_handler();
+///    error_handler(error, ctx);        
+/// }
+/// ```
+///
+/// # Warning
+///
+/// As this can *never* be overwritten, library code should never set this value.
+#[cfg(feature = "configurable_error_handler")]
+pub static GLOBAL_ERROR_HANDLER: OnceLock<fn(BevyError, ErrorContext)> = OnceLock::new();
+
+/// The default error handler. This defaults to [`panic()`],
+/// but if set, the [`GLOBAL_ERROR_HANDLER`] will be used instead, enabling error handler customization.
+/// The `configurable_error_handler` feature must be enabled to change this from the panicking default behavior,
+/// as there may be runtime overhead.
+#[inline]
+pub fn default_error_handler() -> fn(BevyError, ErrorContext) {
+    #[cfg(not(feature = "configurable_error_handler"))]
+    return panic;
+
+    #[cfg(feature = "configurable_error_handler")]
+    return *GLOBAL_ERROR_HANDLER.get_or_init(|| panic);
+}
+
+macro_rules! inner {
+    ($call:path, $e:ident, $c:ident) => {
+        $call!(
+            "Encountered an error in {} `{}`: {}",
+            $c.kind(),
+            $c.name(),
+            $e
+        );
+    };
+}
+
+/// Error handler that panics with the system error.
+#[track_caller]
+#[inline]
+pub fn panic(error: BevyError, ctx: ErrorContext) {
+    inner!(panic, error, ctx);
+}
+
+/// Error handler that logs the system error at the `error` level.
+#[track_caller]
+#[inline]
+pub fn error(error: BevyError, ctx: ErrorContext) {
+    inner!(log::error, error, ctx);
+}
+
+/// Error handler that logs the system error at the `warn` level.
+#[track_caller]
+#[inline]
+pub fn warn(error: BevyError, ctx: ErrorContext) {
+    inner!(log::warn, error, ctx);
+}
+
+/// Error handler that logs the system error at the `info` level.
+#[track_caller]
+#[inline]
+pub fn info(error: BevyError, ctx: ErrorContext) {
+    inner!(log::info, error, ctx);
+}
+
+/// Error handler that logs the system error at the `debug` level.
+#[track_caller]
+#[inline]
+pub fn debug(error: BevyError, ctx: ErrorContext) {
+    inner!(log::debug, error, ctx);
+}
+
+/// Error handler that logs the system error at the `trace` level.
+#[track_caller]
+#[inline]
+pub fn trace(error: BevyError, ctx: ErrorContext) {
+    inner!(log::trace, error, ctx);
+}
+
+/// Error handler that ignores the system error.
+#[track_caller]
+#[inline]
+pub fn ignore(_: BevyError, _: ErrorContext) {}

vendor/bevy_ecs/src/error/mod.rs

@@ -0,0 +1,81 @@
+//! 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.
+//! Modify the [`GLOBAL_ERROR_HANDLER`] value to set a custom error handler function for your entire 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 error
+//! - [`error`] – logs the system error at the `error` level
+//! - [`warn`] – logs the system error at the `warn` level
+//! - [`info`] – logs the system error at the `info` level
+//! - [`debug`] – logs the system error at the `debug` level
+//! - [`trace`] – logs the system error at the `trace` level
+//! - [`ignore`] – 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:
+//!
+//! ```rust,ignore
+//! 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.
+//!
+//! Remember to turn on the `configurable_error_handler` feature to set a global error handler!
+//!
+//! ```rust, ignore
+//! use bevy_ecs::error::{GLOBAL_ERROR_HANDLER, BevyError, ErrorContext};
+//! 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() {
+//!     // This requires the "configurable_error_handler" feature to be enabled to be in scope.
+//!     GLOBAL_ERROR_HANDLER.set(my_error_handler).expect("The error handler can only be set once.");
+//!     
+//!     // Initialize your Bevy App 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.
+//!
+//! [`Schedule`]: crate::schedule::Schedule
+//! [`panic`]: panic()
+//! [`World`]: crate::world::World
+//! [`System`]: crate::system::System
+//! [`name`]: crate::system::System::name
+//! [`system piping feature`]: crate::system::In
+
+mod bevy_error;
+mod command_handling;
+mod handler;
+
+pub use bevy_error::*;
+pub use command_handling::*;
+pub use handler::*;
+
+/// A result type for use in fallible systems, commands and observers.
+///
+/// The [`BevyError`] type is a type-erased error type with optional Bevy-specific diagnostics.
+pub type Result<T = (), E = BevyError> = core::result::Result<T, E>;