Moving PlaybackMode to AudioPlayer and defaulting to PlaybackMode::Remove

[seivan]

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,
        ));

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[rparrett]

Just noting that this would close #12359. I haven't looked closely at the PR yet.

[seivan]

Just noting that this would close #12359. I haven't looked closely at the PR yet.

I actually wanted to remove ::Once but wasn't sure if it had unintended consequences.

[rparrett]

For what it's worth, I have changed my opinion since writing up #12359 and I don't personally feel that automatic despawning ore removal by default is the right choice. The current behavior seems like what I would expect when I spawn any other entity.

I agree that PlaybackSettings is really clunky right now, but we should probably come to a consensus on a design if we're reworking it to minimize churn.