Skip to content
AssiduousEngine

Audio

Sound files

Section titled “Sound files”

Import .wav, .ogg, .mp3 or .flac files; each becomes an Audio Clip. The import options, which the clip’s page also has, are:

  • Stream: play from the file as it goes, instead of holding the whole sound in memory. A sound longer than 10 seconds or larger than 2 MB streams on its own; music should.
  • Force Mono: mix it down to one channel, half the size.
  • Loop, with Loop Start Frame and Loop End Frame to loop part of it. A WAV file’s own loop points are found when it is imported.
  • Trim Trailing Silence, and Normalize to bring the loudest point to just under full volume.
  • Gain: louder or quieter, from 0 to 4 times.

Cues: a sound with variety

Section titled “Cues: a sound with variety”

A footstep that plays the same file every time soon sounds mechanical. A Sound Cue (Create > Audio > Sound Cue) holds up to eight clips and picks one each time it plays:

  • RandomNoRepeat (the default): at random, never the same one twice in a row.
  • Random: at random.
  • Sequential: each in turn.

Each clip has a Weight, so one can come up more often than another, and the cue can vary the pitch and volume each time, between a minimum and a maximum. Anywhere a clip can play, a cue can play.

Audio Source

Section titled “Audio Source”

To play a sound from an entity, give it Add Component > Audio Source. Choose Source Type Clip or Cue, and set the clip or cue.

  • Auto Play starts it when the game starts; otherwise a script starts it (below).
  • Loop repeats it, for an engine hum or a waterfall.
  • Volume and Pitch: pitch 2 is an octave up, and twice as fast.
  • Bus: which part of the mix it belongs to (below).
  • Priority (128): when too many sounds play at once, the lower priorities go first.
  • Reverb Send: how much of it goes to the bus’s reverb.

In the world

Section titled “In the world”

With Spatial on, the default, the sound comes from the entity: it pans as the listener turns, fades with distance, and shifts in pitch as it passes. Turn it off for sounds that are not anywhere, such as an engine heard from the driver’s seat.

  • Min Distance (1) is how close you must be to hear it at full volume, and Max Distance (100) where the fade stops.
  • Attenuation Model is how it fades between them: Inverse (the default, like real sound), Linear, Exponential, or None (it does not fade, but still pans). Rolloff makes the fade steeper or gentler.
  • Distance Lowpass Hz muffles it with distance, as air does: open at the minimum distance, down to this frequency at the maximum. 0 turns it off.
  • Doppler Factor scales the pitch shift of a moving sound; 0 turns it off.
  • The three Cone settings make it louder in front: within the inner angle it plays at full volume, beyond the outer angle at Cone Outer Gain. The defaults, 360 degrees, send it every way.

The listener

Section titled “The listener”

Sound is heard from the entity with an Audio Listener component, usually the camera or the player. With no listener in the scene, the first camera hears it.

Buses

Section titled “Buses”

Every sound plays through a bus, and the buses mix together: Master, with Effects, Music and UI under it. Turning a bus down turns down everything on it, which is how a game’s volume settings work.

An Audio Bus Layout asset (Create > Audio) sets each bus’s volume, and can give it effects:

  • a low-pass and a high-pass filter (a muffled underwater mix, a tinny radio);
  • an echo, its delay and how quickly it dies;
  • reverb, with a room size and damping.

A layout can also add up to eight buses of your own, each under another, such as a Voices bus under Effects. A sound goes to one by setting its Bus Name to the new bus’s name.

Choose the layout in Project > Project Settings…, on the Audio tab, as Default bus layout. Without one, the four buses play at full volume with no effects.

Reverb zones

Section titled “Reverb zones”

An Audio Reverb Zone gives a place its echo: a cave, a hall, a tunnel. It is a sphere of Radius (8 m); while the listener is inside, the scene’s sound gets reverb of that Room Size, Damping and Wet Level. Edge Fade blends it in over the outer part of the sphere, so walking in is gradual. Where zones overlap, the wettest wins.

Sound from scripts

Section titled “Sound from scripts”
local Coin = Guid.new("6d963695-67f8-4b7f-9cf4-d234f8034116") -- a clip's ID
local Theme = Guid.new("1b0f1e9c-2a8e-4c7a-9a0d-3c8e5f6a7b21")


function Player:collect()
    Audio.playOneShot(Coin, AudioBus.Effects, 0.7)
    Audio.playOneShot3D(Coin, self.entity:worldPosition())
end


function Player:onStart()
    Audio.playMusic(Theme, 2.0) -- cross-fade from any music over 2 seconds
    Audio.setBusVolume(AudioBus.Music, 0.5)
end

Copy a clip’s ID with Copy GUID in its right-click menu in the Assets panel.

  • playOneShot(clip) plays a sound once, on the Effects bus unless you give another, with an optional volume and pitch. playOneShot3D(clip, position) plays it at a place in the world.
  • playCue and playCue3D do the same with a cue.
  • playMusic(clip, fadeSeconds) starts music, fading out what played before; stopMusic(seconds) fades it out.
  • Each has a Path form that takes the sound’s path in the Assets panel instead of its ID, such as playOneShotPath("Audio/Coin").
  • setBusVolume(bus, volume) and setBusMuted(name, muted) set the mix, for a volume menu; setNamedBusVolume(name, volume) reaches your own buses.

The play calls return a handle to the playing sound: stopVoice(handle, fadeSeconds), setVoicePaused, and setVoiceVolume and setVoicePitch, which can glide over a number of seconds.

An entity’s own Audio Source is played through SceneAudio:

local audio = SceneAudio.of(self.entity.scene)
audio:play(self.entity)
audio:setVolume(self.entity, 0.2, 1.5) -- down to 0.2 over 1.5 seconds

stop, pause, isPlaying, setPitch and setClip are there too.

Limits

Section titled “Limits”

Up to 64 sounds play at once, and up to 8 streamed ones. Beyond that, the lowest priority sounds make way.