ecs.AudioSource

Spec for the AudioSource component, which maps to the native AudioSource. Plays a .soundClip asset from an entity, with optional 3D spatial attenuation. Spatial sources are heard relative to the scene's AudioListener.

Fields

• clip — the .soundClip asset to play, referenced by guid.
• bytesHandle — the staging handle the mixer takes the clip's audio bytes from.
• streaming — stream the compressed payload vs decode it fully on load.
• sourceType — an AudioSourceType variant name.
• volume, pitch — playback gain and pitch.
• looping — repeat playback.
• spatial — enable 3D distance attenuation.
• maxDistance — the distance a spatial source fades to silence at, in world units. It is at full volume within one unit of the listener.
• rolloff — exponent of that fade: the amplitude is (1 - t)^rolloff for a source t of the way through the window, so 1 fades linearly, higher drops off sooner, and 0 holds full volume to the edge.
• state — a PlaybackState variant name.
• stopRequested — a stop asked for on the source, taken up by the mixer.
• autoplay — start playing on add.
• channel — the mixer channel name.
• pitchValue, volumeValue: the names of named values (values.set) the voice follows: it plays at pitch times the value and volume times the value, read from the source's entity or its nearest ancestor holding one, every frame. Empty follows nothing.

Usage

The Audio script component owns this one. It resolves the clip, stages the clip's bytes under bytesHandle so the mixer has something to play, installs the source, and keeps the source in step with its own fields as they change. Adding Audio is how a clip sounds from an entity.

entity(id).component.add("Audio", { clip = themeClip, looping = true, autoplay = true })

A playback setting written on that component reaches the source it installed, including one that is already sounding:

local music = entity(id).component.get("Audio")
music.volume = 0.5