Objective

Fix: #12359

Wanted to make it clear what happens when audio is being played, and the source is related to the PlaybackMode.
You're either playing sound effects that are temporary in lifetime, or constant repeated music.
Some sound effects related to existing entity while others are children of said entities.
I wanted the API to actually reflect that, instead of being split over two components.
It requires explicit input about PlaybackMode

This break existing code in two places:

• When AudioPlayer::new() is used it changes default mode to Remove, current default is Once.
• Tuple struct syntax requires as second argument.

Solution

• Changing the default PlaybackMode to PlaybackMode::Remove
• Adding PlaybackMode to AudioPlayer
• Adding convenience methods to AudioPlayer to create with different PlaybackModes

Testing

• Did you test these changes? If so, how?

• Ran each audio example.
• Ran tests

• Are there any parts that need more testing?

Performance? Since AudioPlayer now holds PlaybackMode there can have been a difference in internal optimizations that I might have missed.

• How can other people (reviewers) test your changes? Is there anything specific they need to know?

Run audio examples.

• If relevant, what platforms did you test these changes on, and are there any important ones you can't test?

Tested only on macOS, I don't think it's relevant for other platforms unless there are performance implications with the new default remove for PlaybackMode.

Migration Guide

Changed the default behaviour to be remove

    pub fn new(source: Handle<AudioSource>) -> Self {
        Self(source, PlaybackMode::default())
    }

Introducing new functions to create AudioPlayer

    /// Creates a new [`AudioPlayer`] that plays the sound once.
    pub fn with_once(source: Handle<AudioSource>) -> Self {
        Self(source, PlaybackMode::Once)
    }

    /// Creates a new [`AudioPlayer`] that loops the sound forever.
    pub fn with_loop(source: Handle<AudioSource>) -> Self {
        Self(source, PlaybackMode::Loop)
    }

    /// Creates a new [`AudioPlayer`] that despawns the entity when the sound finishes playing.
    pub fn with_despawn(source: Handle<AudioSource>) -> Self {
        Self(source, PlaybackMode::Despawn)
    }

    /// Creates a new [`AudioPlayer`] that removes the audio component from the entity when the sound finishes playing.
    pub fn with_remove(source: Handle<AudioSource>) -> Self {
        Self(source, PlaybackMode::Remove)
    }

Examples:

Old

    commands.spawn(AudioPlayer(
        asset_server.load("sounds/Windless Slopes.ogg"),
    ));

New

    commands.spawn(AudioPlayer::with_once(
        asset_server.load("sounds/Windless Slopes.ogg"),
    ));

Old

        commands.spawn((
            AudioPlayer(pitch_assets.add(Pitch::new(frequency.0, Duration::new(1, 0)))),
            PlaybackSettings::DESPAWN,
        ));

New

        commands.spawn(AudioPlayer(
            pitch_assets.add(Pitch::new(frequency.0, Duration::new(1, 0))),
            PlaybackMode::Despawn,
        ));