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 dialog offers these options:

  • Stream: decode the sound as it plays, instead of holding the whole sound in memory. A sound longer than 10 seconds or larger than 2 MB streams even with this off, which suits music.
  • Force mono: mix it down to one channel, which halves its size and suits sounds placed in the world.
  • Loop: loop it by default when it plays. A WAV file’s own loop points are found when it is imported, and take precedence.
  • Trim trailing silence: drop the silent tail.
  • Normalize: raise the loudest point to just under full volume (-1 dB).

Double-click a clip to open its page, which shows its waveform and plays it. Its settings repeat those options and add:

  • Keep Compressed: for a clip held in memory, decode it each time it plays rather than once when it loads.
  • Loop Start Frame and Loop End Frame, shown while Loop is on, to loop part of the sound. An end of 0 is the end of the clip.
  • 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 (in the Assets panel, New > Audio > Sound Cue) holds up to eight Variants, each a clip, and picks one each time it plays. Its Picks setting says how:

  • At random, never twice running (the default).
  • At random, where the same clip can come twice in a row.
  • In order, each clip in turn.

Each variant has a Weight (1), so one can come up more often than another. The cue can also vary the pitch and volume each time, between Pitch Min and Pitch Max and between Volume Min and Volume Max. The cue’s page plays it and shows which clip it picked. An Audio Source and the script calls below can play a cue as well as a clip.

A Sound Cue page with three variants, and its pitch and volume varied

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 (off) starts it when the game starts. Otherwise a script starts it (below).
  • Loop (off) repeats it, for an engine hum or a waterfall. A clip whose own Loop is on repeats either way.
  • Volume (1) and Pitch (1): pitch 2 is an octave up, and twice as fast.
  • Bus (Effects): which part of the mix it belongs to (below). Bus Name sends it to a bus of your own instead.
  • Priority (128): when too many sounds play at once, the lower priorities go first.
  • Reverb Send (0): how much of it, from 0 to 1, also feeds a separate reverb that plays wherever the listener is. The reverb zones set that reverb’s room size and damping.

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 (4000) 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 (1) 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, and beyond the outer angle at Cone Outer Gain. The default angles, 360 degrees, send it every way.

These settings are hidden while Spatial is off.

The listener

Section titled “The listener”

Sound is heard from the entity with an Audio Listener component, usually the camera or the player. If several are active, the first one is used. With no listener in the scene, the first enabled 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 (New > Audio > Audio Bus Layout) sets up the mix. Its page lists the buses as a tree; select one to set:

  • Volume (from 0 to 2) and Muted;
  • Lowpass (Hz) and Highpass (Hz) filters, for a muffled underwater mix or a tinny radio;
  • an echo: Delay (s), and Decay, how much of each echo comes back;
  • reverb: Wet, Room Size and Damping.

An Audio Bus Layout page, with a Voices bus of its own under Effects

Each effect is off at 0. Add Bus adds a bus of your own, up to eight, under Master at first. Give it a Name and a Parent: a fixed bus or another of your own, such as a Voices bus under Effects. A sound goes to it when its Bus Name is the bus’s name. Removing a bus moves the buses under it to Master.

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

Reverb zones

Section titled “Reverb zones”

A Reverb Zone component 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 sounds on the Effects bus get reverb with the zone’s Room Size (0.6), Damping (0.4) and Wet Level (0.5). Edge Fade (0.25) is the outer part of the sphere, as a fraction of the radius, over which the reverb blends in, so walking in is gradual. Where zones overlap, the wettest wins. Zones need an Audio Listener component in the scene; a camera standing in for a missing listener does not count.

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. playOneShot(clip, bus) picks the bus, and two more arguments set the volume and the pitch. playOneShot3D(clip, position) plays it at a place in the world.
  • playCue(cue), playCue(cue, bus) and playCue3D(cue, position) do the same with a cue.
  • playMusic(clip, crossFadeSeconds) starts music on the Music bus, cross-fading from what played before (over 1 second when you leave the time out); a third argument sets its volume. stopMusic(fadeSeconds) fades it out, and musicVoice() returns the music playing.
  • playOneShotPath(path), playOneShot3DPath(path, x, y, z), playCuePath(path) and playMusicPath(path, fadeSeconds) take the sound’s path in the Assets panel instead of its ID, such as "Audio/Coin". They return whether a sound started.
  • setBusVolume(bus, volume) and busVolume(bus) set and read one of the four buses, for a volume menu. setNamedBusVolume(name, volume) and namedBusVolume(name) reach your own buses by name, and setBusMuted(name, muted) and busMuted(name) take any bus by name.

The calls that take an ID return a handle to the playing sound. Pass it to isVoicePlaying(handle), stopVoice(handle, fadeSeconds), setVoicePaused(handle, paused), setVoiceVolume(handle, volume, seconds) and setVoicePitch(handle, pitch, seconds). The volume and pitch glide over the given seconds, or change at once when you leave the seconds out.

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

SceneAudio also has stop(entity), pause(entity, paused) (false resumes), isPlaying(entity), setPitch(entity, pitch, seconds) and setClip(entity, clipId).

Limits

Section titled “Limits”

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