Fallible systems

Cargo.toml

@@ -2020,6 +2020,17 @@ description = "Systems are skipped if their parameters cannot be acquired"
 category = "ECS (Entity Component System)"
 wasm = false
 
+[[example]]
+name = "fallible_systems"
+path = "examples/ecs/fallible_systems.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.fallible_systems]
+name = "Fallible Systems"
+description = "Systems that return results to handle errors"
+category = "ECS (Entity Component System)"
+wasm = false
+
 [[example]]
 name = "startup_system"
 path = "examples/ecs/startup_system.rs"

examples/README.md

@@ -299,6 +299,7 @@ Example | Description
 [ECS Guide](../examples/ecs/ecs_guide.rs) | Full guide to Bevy's ECS
 [Event](../examples/ecs/event.rs) | Illustrates event creation, activation, and reception
 [Fallible System Parameters](../examples/ecs/fallible_params.rs) | Systems are skipped if their parameters cannot be acquired
+[Fallible Systems](../examples/ecs/fallible_systems.rs) | Systems that return results to handle errors
 [Fixed Timestep](../examples/ecs/fixed_timestep.rs) | Shows how to create systems that run every fixed timestep, rather than every tick
 [Generic System](../examples/ecs/generic_system.rs) | Shows how to create systems that can be reused with different types
 [Hierarchy](../examples/ecs/hierarchy.rs) | Creates a hierarchy of parents and children entities

examples/ecs/fallible_systems.rs

@@ -0,0 +1,77 @@
+use bevy::math::sampling::UniformMeshSampler;
+use bevy::prelude::*;
+
+use rand::distributions::Distribution;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_systems(Startup, setup)
+        .run();
+}
+
+/// An example of a system that calls several fallible functions with the questionmark operator.
+fn setup(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+) -> Result {
+    let mut rng = rand::thread_rng();
+
+    // Make a plane for establishing space.
+    commands.spawn((
+        Mesh3d(meshes.add(Plane3d::default().mesh().size(12.0, 12.0))),
+        MeshMaterial3d(materials.add(Color::srgb(0.3, 0.5, 0.3))),
+        Transform::from_xyz(0.0, -2.5, 0.0),
+    ));
+
+    // Spawn a light:
+    commands.spawn((
+        PointLight {
+            shadows_enabled: true,
+            ..default()
+        },
+        Transform::from_xyz(4.0, 8.0, 4.0),
+    ));
+
+    // Spawn a camera:
+    commands.spawn((
+        Camera3d::default(),
+        Transform::from_xyz(-2.0, 3.0, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
+    ));
+
+    // Create a new sphere mesh:
+    let mut sphere_mesh = Sphere::new(1.0).mesh().ico(7)?;
+    sphere_mesh.generate_tangents()?;
+
+    // Spawn the mesh into the scene:
+    let mut sphere = commands.spawn((
+        Mesh3d(meshes.add(sphere_mesh.clone())),
+        MeshMaterial3d(materials.add(StandardMaterial::default())),
+        Transform::from_xyz(-1.0, 1.0, 0.0),
+    ));
+
+    // Generate random sample points:
+    let triangles = sphere_mesh.triangles()?;
+    let distribution = UniformMeshSampler::try_new(triangles)?;
+
+    // Setup sample points:
+    let point_mesh = meshes.add(Sphere::new(0.01).mesh().ico(3)?);
+    let point_material = materials.add(StandardMaterial {
+        base_color: Srgba::RED.into(),
+        emissive: LinearRgba::rgb(1.0, 0.0, 0.0),
+        ..default()
+    });
+
+    /// Add sample points as children of the sphere:
+    for point in distribution.sample_iter(&mut rng).take(10000) {
+        sphere.with_child((
+            Mesh3d(point_mesh.clone()),
+            MeshMaterial3d(point_material.clone()),
+            Transform::from_translation(point),
+        ));
+    }
+
+    /// Indicate the system completed sucsessfully:
+    Ok(())
+}