Error handling
Return Result from systems, observers and commands, use the ? operator, set error severity, and choose what the app does with errors through error handlers.
On this page
Systems, observers and commands can fail: a resource isn't there yet, an entity was despawned, a mesh can't be built. Instead of unwrap, a system can return Result and use ?. The engine passes any error to an error handler, which decides whether to panic, log it or ignore it.
Fallible systems#
Return Result (the engine's alias for Result<(), NeoError>, in the prelude):
use neo::prelude::*;
fn setup(
mut commands: Commands,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<StandardMaterial>>,
) -> Result {
let mut sphere = Sphere::new(1.0).mesh().ico(7)?; // fails for too many subdivisions
sphere.generate_tangents()?;
commands.spawn((
Mesh3d(meshes.add(sphere)),
MeshMaterial3d(materials.add(StandardMaterial::default())),
));
Ok(())
}NeoError converts from any error type and from &str, so ? works on most things, and option.ok_or("message")? turns a missing value into an error. Observers can return Result the same way, and so can commands.
Severity#
Every error carries a Severity, which the default handler uses to decide what to do. Errors are Severity::Panic unless you say otherwise.
| Severity | The default handler |
|---|---|
Ignore | Does nothing. |
Trace, Debug, Info | Logs at that level. |
Warning | Logs a warning. |
Error | Logs an error and carries on. |
Panic | Panics. |
Set it where the error happens:
fn read_settings(world: &mut World) -> Result {
world
.get_resource::<Settings>()
.ok_or("settings not loaded yet")
.with_severity(Severity::Debug)?; // expected during loading: don't panic
Ok(())
}
#[derive(Resource)]
struct Settings;map_severity(|e| ..) picks a severity from the error value.
Error handlers#
The handler applies to every system, observer and command in the app that doesn't handle its own errors. The default, match_severity, follows each error's severity. Replace it for the whole app:
use neo::ecs::error::warn;
fn main() {
App::new()
.set_error_handler(warn) // log every unhandled error as a warning
.add_plugins(DefaultPlugins)
.run();
}Built-in handlers, in neo::ecs::error: match_severity, panic, error, warn, info, debug, trace and ignore. A handler is any fn(NeoError, ErrorContext); the ErrorContext names the system, observer or command that failed:
use neo::ecs::error::{ErrorContext, NeoError};
fn my_handler(error: NeoError, context: ErrorContext) {
if context.name().ends_with("optional_effects") {
return; // never mind
}
neo::ecs::error::error(error, context);
}Missing system parameters#
When a system's parameters can't be fetched, for example a Res<T> whose resource doesn't exist, that's an error too, and it goes to the same handler. Parameters such as Single, Populated and If skip the system instead; see System parameters.
Handling one system's errors yourself#
Pipe the system's result into another system to handle it there instead of in the global handler:
app.add_systems(
Update,
setup_level.pipe(|In(result): In<Result>| {
if let Err(error) = result {
warn!("level setup failed: {error}");
}
}),
);For commands, commands.queue_handled(command, handler) gives one command its own handler, and the try_ command variants (try_insert, try_despawn) do nothing when the entity is gone.
Examples#
Run these from the engine core's workspace:
| Example | What it shows |
|---|---|
cargo run --example error_handling | Fallible systems, observers and commands, severities and a custom handler. |
cargo run --example fallible_params | Parameters that skip a system instead of failing. |