Struct AudioSource 

pub struct AudioSource {
    pub audio: AssetHandle<AudioAsset>,
    pub audio_path: Option<String>,
    pub playing: bool,
    pub looping: bool,
    pub volume: f32,
    pub pitch: f32,
    pub channel: AudioChannel,
    pub auto_play: bool,
    pub spatial: bool,
    pub max_distance: f32,
    pub attenuation: AttenuationModel,
    /* private fields */
}

AudioSource component for spatial audio playback.

Attach this component to an entity to enable audio playback. The audio system will automatically handle playback, looping, volume, pitch, and spatial audio based on the component’s configuration.

Fields

• audio: Reference to the audio asset to play
• playing: Whether the audio is currently playing
• looping: Whether the audio should loop when it finishes
• volume: Volume multiplier (0.0 = silent, 1.0 = full volume)
• pitch: Pitch multiplier (0.5 = half speed, 2.0 = double speed)
• channel: Audio channel for grouping and mixing
• auto_play: Whether to start playing automatically when spawned
• spatial: Whether to apply spatial audio (requires Transform)
• max_distance: Maximum distance for spatial audio attenuation
• attenuation: Distance-based volume falloff model
• sink_id: Internal audio sink ID (managed by audio system)

Examples

See module-level documentation for usage examples.

Fields

audio: AssetHandle<AudioAsset>

Reference to the audio asset to play

audio_path: Option<String>

Optional path to the audio asset for serialization.

The handle cannot survive serialization, but this path string can. A higher-level system resolves it back to an AssetHandle after deserialization.

playing: bool

Whether the audio is currently playing

looping: bool

Whether the audio should loop when it finishes

volume: f32

Volume multiplier (0.0 = silent, 1.0 = full volume)

pitch: f32

Pitch multiplier (0.5 = half speed, 2.0 = double speed)

channel: AudioChannel

Audio channel for grouping and mixing

auto_play: bool

Whether to start playing automatically when spawned

spatial: bool

Whether to apply spatial audio (requires Transform)

max_distance: f32

Maximum distance for spatial audio attenuation

attenuation: AttenuationModel

Distance-based volume falloff model

Implementations

impl AudioSource

pub fn new(audio: AssetHandle<AudioAsset>) -> AudioSource

Creates a new AudioSource with default settings.

Arguments

• audio: Reference to the audio asset to play

Default Values

• playing: false (stopped)
• looping: false (one-shot)
• volume: 1.0 (full volume)
• pitch: 1.0 (normal speed)
• channel: SFX
• auto_play: false
• spatial: false (non-spatial)
• max_distance: 100.0
• attenuation: InverseDistance
• sink_id: None

Examples

use goud_engine::ecs::components::AudioSource;
use goud_engine::assets::AssetHandle;
use goud_engine::assets::loaders::audio::AudioAsset;

let audio_handle: AssetHandle<AudioAsset> = AssetHandle::default();
let source = AudioSource::new(audio_handle);

assert_eq!(source.playing, false);
assert_eq!(source.volume, 1.0);
assert_eq!(source.pitch, 1.0);

pub fn with_volume(self, volume: f32) -> AudioSource

Sets the volume (0.0-1.0, clamped).

Examples

use goud_engine::ecs::components::AudioSource;
use goud_engine::assets::AssetHandle;
use goud_engine::assets::loaders::audio::AudioAsset;

let audio_handle: AssetHandle<AudioAsset> = AssetHandle::default();
let source = AudioSource::new(audio_handle).with_volume(0.5);
assert_eq!(source.volume, 0.5);

pub fn with_pitch(self, pitch: f32) -> AudioSource

Sets the pitch (0.5-2.0, clamped).

Examples

use goud_engine::ecs::components::AudioSource;
use goud_engine::assets::AssetHandle;
use goud_engine::assets::loaders::audio::AudioAsset;

let audio_handle: AssetHandle<AudioAsset> = AssetHandle::default();
let source = AudioSource::new(audio_handle).with_pitch(1.5);
assert_eq!(source.pitch, 1.5);

pub fn with_looping(self, looping: bool) -> AudioSource

Sets whether the audio should loop.

pub fn with_channel(self, channel: AudioChannel) -> AudioSource

Sets the audio channel.

pub fn with_auto_play(self, auto_play: bool) -> AudioSource

Sets whether to start playing automatically when spawned.

pub fn with_audio_path(self, path: impl Into<String>) -> AudioSource

Sets the audio asset path for serialization.

The path is stored alongside the source so it survives serialization. A higher-level system resolves it back to an AssetHandle after deserialization.

pub fn with_spatial(self, spatial: bool) -> AudioSource

Sets whether to apply spatial audio (requires Transform component).

pub fn with_max_distance(self, max_distance: f32) -> AudioSource

Sets the maximum distance for spatial audio attenuation.

pub fn with_attenuation(self, attenuation: AttenuationModel) -> AudioSource

Sets the attenuation model for spatial audio.

pub fn play(&mut self)

Starts playing the audio.

pub fn pause(&mut self)

Pauses the audio (retains playback position).

pub fn stop(&mut self)

Stops the audio (resets playback position).

pub fn is_playing(&self) -> bool

Returns whether the audio is currently playing.

pub fn is_spatial(&self) -> bool

Returns whether the audio is spatial.

pub fn has_sink(&self) -> bool

Returns whether the audio has an active sink.

Trait Implementations

impl Clone for AudioSource

fn clone(&self) -> AudioSource

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AudioSource

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for AudioSource

fn default() -> AudioSource

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AudioSource

fn deserialize<__D>( __deserializer: __D, ) -> Result<AudioSource, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for AudioSource

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Serialize for AudioSource

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Component for AudioSource