Add audio/play_sound_effect example (#23219)

Add `audio/play_sound_effect` example

# Objective

Add an example that demonstrates how to load an audio file and play it
multiple times on a specific event (pressing space).

## Solution

It is similar to the breakout example, but way shorter and focused. This
example loads a sound effect as a resource with the `FromWorld` trait,
and on a keyboard event spawns an `AudioPlayer` with `DESPAWN` mode.

## Testing

- Built on top of 0.18.1, and moved to master
- Tested by building the examples, and pressing the space a few times
(no overlapping audio)
- Tested also by pressing space as fast as I could do for about 1
minute. Lot of components are spawned, played at the same time, but I've
found no issues.

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Cargo.toml

@@ -2233,6 +2233,17 @@ description = "Shows how to directly play a simple pitch"
 category = "Audio"
 wasm = true
 
+[[example]]
+name = "play_sound_effect"
+path = "examples/audio/play_sound_effect.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.play_sound_effect]
+name = "Play Sound Effect"
+description = "Shows how to play a sound effect in response to an event"
+category = "Audio"
+wasm = true
+
 # Diagnostics
 [[example]]
 name = "log_diagnostics"

examples/README.md

@@ -287,6 +287,7 @@ Example | Description
 [Audio Control](../examples/audio/audio_control.rs) | Shows how to load and play an audio file, and control how it's played
 [Decodable](../examples/audio/decodable.rs) | Shows how to create and register a custom audio source by implementing the `Decodable` type.
 [Pitch](../examples/audio/pitch.rs) | Shows how to directly play a simple pitch
+[Play Sound Effect](../examples/audio/play_sound_effect.rs) | Shows how to play a sound effect in response to an event
 [Soundtrack](../examples/audio/soundtrack.rs) | Shows how to play different soundtracks based on game state
 [Spatial Audio 2D](../examples/audio/spatial_audio_2d.rs) | Shows how to play spatial audio, and moving the emitter in 2D
 [Spatial Audio 3D](../examples/audio/spatial_audio_3d.rs) | Shows how to play spatial audio, and moving the emitter in 3D

examples/audio/play_sound_effect.rs

@@ -0,0 +1,56 @@
+//! This example illustrates how to play a sound effect on an event.
+//! In this case, we will play a sound effect when the space key is pressed.
+use bevy::prelude::*;
+
+#[derive(Resource, Deref)]
+struct SoundEffect {
+    handle: Handle<AudioSource>,
+}
+
+// We can setup the logic for how to load our assets in the `FromWorld` trait.
+// This code is called via `init_resource`.
+impl FromWorld for SoundEffect {
+    fn from_world(world: &mut World) -> Self {
+        let asset_server = world.resource::<AssetServer>();
+        SoundEffect {
+            handle: asset_server.load("sounds/breakout_collision.ogg"),
+        }
+    }
+}
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .init_resource::<SoundEffect>()
+        .add_systems(Startup, setup)
+        .add_systems(Update, keyboard_event)
+        .run();
+}
+
+fn setup(mut commands: Commands) {
+    commands.spawn(Camera2d);
+    // example instruction
+    commands.spawn((
+        Text::new("Press Space to play the sound effect."),
+        Node {
+            position_type: PositionType::Absolute,
+            bottom: px(12),
+            left: px(12),
+            ..default()
+        },
+    ));
+}
+
+// spawn an audio player with the sound effect when the space key is pressed
+fn keyboard_event(
+    keyboard_input: Res<ButtonInput<KeyCode>>,
+    sound_effect: Res<SoundEffect>,
+    mut commands: Commands,
+) {
+    if keyboard_input.just_pressed(KeyCode::Space) {
+        commands.spawn((
+            AudioPlayer::new(sound_effect.clone()),
+            PlaybackSettings::DESPAWN,
+        ));
+    }
+}