AudioSource

Namespace:

namespace Lenga\Engine\Audio;

class AudioSource

AudioSource plays an assigned AudioClip from a GameObject.

Use it for background music, UI sounds, pickup sounds, impacts, jump sounds, and other one-shot or looping audio. In the editor, add an Audio Source component, assign an audio asset to Clip, then tune Play On Awake, Loop, Volume, Pitch, and mixer routing.

Properties

clip

public ?AudioClip $clip

The audio clip currently assigned to this source.

Assign clips through the Inspector for authored defaults. Scripts can also swap between serialized AudioClip references exposed on a Behaviour.

playOnAwake

public bool $playOnAwake

When true, the source starts playing automatically when the component starts. When false, the clip only plays when you call play() from code.

loop

public bool $loop

When true, the source restarts after the clip finishes. Use this for background music and ambience.

volume

public float $volume

Playback volume from 0.0 to 1.0.

pitch

public float $pitch

Playback pitch. 1.0 is the normal pitch. Values above 1.0 play higher and faster. Values below 1.0 play lower and slower.

outputAudioMixer

public ?AudioMixer $outputAudioMixer

Mixer asset that receives this source's output. Leave this null to play through the default output.

outputChannelId

public string $outputChannelId

Channel id inside the assigned mixer. New mixer assets start with master. Additional channels receive generated ids when you add them to the mixer asset.

isPlaying

public bool $isPlaying

Returns whether this source is currently playing and not paused.

isPaused

public bool $isPaused

Returns true when this source is currently paused.

This includes script-level pauses made with pause(). It also reports true while an active source is paused by the engine-wide application pause state.

isStopped

public bool $isStopped

Returns true when this source is stopped and not paused. This includes sources that have never played, sources that have finished playing and are not set to loop, and sources that have been stopped with stop().

Methods

play

public function play(): bool

Starts the assigned clip. Returns false if the clip cannot be played.

Calling play() starts from the beginning of the clip. If the source was paused with pause(), play() clears that paused state and restarts playback.

pause

public function pause(): bool

Pauses playback without resetting the clip position. Returns false if there is no active clip playback to pause.

Use this when you want to temporarily hold a music track, ambience loop, or long sound effect and later continue from the same position.

resume

public function resume(): bool

Resumes playback after pause(). Returns false if the source cannot resume because the clip is no longer available.

If the engine is globally paused, resume() clears the source-level pause but the sound remains silent until the engine resumes.

stop

public function stop(): bool

Stops playback and resets the source. Use pause() instead when you need to continue from the current clip position later.

isPlaying

public function isPlaying(): bool

Deprecated compatibility method. Use the isPlaying property instead:

if ($audio->isPlaying) {
    $audio->pause();
}

setOutput

public function setOutput(?AudioMixer $mixer, string $channelId = 'master'): bool

Routes the source to a mixer channel in one call. Returns false if Lenga cannot apply the change at runtime.

The source volume and pitch are multiplied by the resolved mixer channel path. For example, lowering the assigned channel volume affects every AudioSource routed through that channel.

Example: Choose a Sound from Script

use Lenga\Engine\Audio\AudioClip;
use Lenga\Engine\Audio\AudioMixer;
use Lenga\Engine\Audio\AudioSource;
use Lenga\Engine\Core\Behaviour;

final class ImpactAudio extends Behaviour
{
    public ?AudioClip $softHit = null;
    public ?AudioClip $hardHit = null;
    public ?AudioMixer $mixer = null;

    private ?AudioSource $audio = null;

    public function start(): void
    {
        $this->audio = $this->gameObject->getComponent(AudioSource::class);
        $this->audio?->setOutput($this->mixer, 'channel-1');
    }

    public function playImpact(bool $hard): void
    {
        $clip = $hard ? $this->hardHit : $this->softHit;
        if ($clip === null || $this->audio === null) {
            return;
        }

        $this->audio->clip = $clip;
        $this->audio->play();
    }
}

Assign Soft Hit and Hard Hit in the Inspector, then choose which one to play from gameplay code.

Notes

  • Play On Awake only controls automatic playback. A script can still call play() explicitly.
  • Active audio sources pause and resume with the engine-wide pause state.
  • Source-level pause() is separate from engine pause. If a script pauses a source, resuming the engine does not automatically resume that source.
  • Use looping sources for music and ambience. Use explicit play() calls for short gameplay sounds.
  • Use AudioClip references instead of hand-written paths in gameplay code.
  • Use AudioMixer routing when several sources should share music, SFX, UI, or ambience controls.