Manual

Manual

Sounds and audio sources

Abyss plays sound through Kira, mixing it through the buses of your game's mix. This page covers sound files and their import settings, the Audio Source component that plays a clip from an entity, the Audio Listener that hears it, how sound in the world pans and falls off with distance, and how your code plays and controls sounds. The buses themselves are on Buses and effects.

Sound files

A sound clip is a WAV, OGG Vorbis, MP3 or FLAC file in your assets. Drag one into the Project panel to add it, and drop it on an Audio Source's Clip slot, or load it from code by its key.

Import settings

Pick a sound in the Project panel to see its import settings in the Inspector:

SettingWhat it does
Force To MonoMixes its channels into one as it is imported: half as big, and heard the same from both sides.
Load TypeHow it is kept once loaded. Decompress On Load, the default, decodes it whole, so it plays at once and as often as asked, at the most memory. Compressed In Memory keeps the file's bytes and decodes each sound of it as it plays: less memory, more work. Streaming reads it from its file or its pack as it plays and keeps none of it, for music and anything else long.
Compression FormatAs Encoded, the default, plays and packs the file as it is. Vorbis, ADPCM and PCM encode it into the project's cache as it is imported, and a build packs that.
QualityFor Vorbis: from 1, the smallest, to 100, the nearest the file. It starts at 70.
Sample Rate SettingPreserve Sample Rate keeps the file's rate. Override Sample Rate resamples it as it is imported to the Sample Rate you pick, from 8,000 to 48,000 Hz.

A line under the settings says how big the sound is before and after its import. Click Apply to write the settings, or Revert to put them back. A sound to be encoded is imported again in the background: it shows a spinner meanwhile, and its file plays until the import is done.

In a game built for the web, every clip is decoded whole, whatever its Load Type says, because a browser game has one thread.

Listen in the Inspector

Under its settings, the Inspector says what the file holds and draws its waveform, a row for each channel. Play plays it from its start, and becomes Stop while it plays. The loop button plays it round and round, and the time at the row's end says where it is and how long it is. Click the waveform to play from that point.

Audio Source

An Audio Source plays a clip from the entity it is on. Make one with Entity ▸ Audio ▸ Audio Source, or add one to any entity with Add Component.

FieldWhat it does
ClipThe sound clip it plays. Drop one from the Project panel on it, or pick one with its button.
OutputThe bus of the mix it plays on, Master to begin with (see Buses and effects).
MutePlays silently, going on all the same, so it is heard again where it got to when you lift the mute.
Play On AwakePlays as the game starts playing, or as the entity is spawned while it plays. On to begin with.
LoopingPlays again from its start each time it ends, until it is stopped.
VolumeFrom 0, silent, to 1, the clip as it is.
PitchHow fast, and so how high: 1 is the clip as it is, 2 an octave up and twice as fast. From 0.05 to 3.
Stereo PanWhere between the speakers, from -1, the left, to 1, the right.
Spatial BlendHow much of a 3D sound it is: 0 is a 2D sound, heard the same anywhere, and 1 pans and falls off with its distance from the listener. It starts at 0.
Volume RolloffHow its volume falls between its two distances: Logarithmic or Linear (see Sound in the world).
Min DistanceWithin this distance it is heard at its whole volume. It starts at 1.
Max DistancePast this distance it falls off no further. It starts at 500.

An Audio Source reads its fields again as they change, so a sound it is playing gets louder, higher, looped or panned at once, while the game plays as well. One with no clip plays nothing. A scene keeps the clip by its file's identity, so you can move or rename the file.

When an Audio Source is picked, the Scene panel draws its Min Distance and Max Distance as two light blue spheres around it. Drag the dots on them to change the distances.

Audio Listener

Sound is heard from the first entity with an Audio Listener, the way it faces: what is to its right is heard on the right. The Audio Listener has no fields. Where no entity has one, sound is heard from the game's first camera.

The Main Camera of a scene made from the Basic or 2D template carries an Audio Listener, as does the camera in a scene made from the Project panel. Put the Audio Listener on the player's character instead to hear the world from where the character stands.

Sound in the world

A 3D sound pans by which side of the listener it is on, and its volume falls with its distance from the listener:

RolloffHow the volume falls
LogarithmicThe minimum distance over the distance: loud near the sound and falling fast, then slowly, to what it is at the maximum distance, where it stays.
LinearIn a straight line, from the whole of it at the minimum distance to nothing at the maximum.

How much of this a sound does is its spatial blend, from 0, none of it, a 2D sound, to 1, all of it.

An Audio Source starts as a 2D sound, its Spatial Blend at 0. Raise it to place the sound in the world. A sound your code plays at a point or on an entity starts fully 3D instead, its spatial blend at 1.

Play sounds from code

Sounds are played and controlled through world.Audio. A flow reaches it as flow.World.Audio, and a plugin's systems through the world the plugin was built with, schedule.World.

Load a clip

Load a sound by its key once it is Addressable (see Keys in code). The load returns at once, and a flow can wait for the clip to land:

AudioClipId hit = flow.Assets.LoadAudioClip(Addresses.Audio.Hit);   // audio/hit.wavawait flow.Loaded(hit);

A sound asked for while its clip is still loading starts once the clip has landed, so you don't have to wait. Loads are counted, as other assets' are, and Release gives one back.

Play a sound

Each of these plays a clip, and returns the Sound it is at once:

Sound music = world.Audio.Play(theme, new PlayOptions { Loop = true, Volume = 0.5f, FadeIn = 2f, Bus = "Music" });Sound boom = world.Audio.PlayAt(explosion, position, new PlayOptions { MaxDistance = 60f });Sound hum = world.Audio.PlayOn(car, motor, new PlayOptions { Loop = true });
MethodPlays the clip
Play(clip, options)As a 2D sound, heard the same wherever the listener is
PlayAt(clip, position, options)At a point in the world
PlayOn(entity, clip, options)On an entity, following it as it moves, and stopping if the entity goes

PlayOptions says how. Leave it out for the clip as it is, once, on Master:

OptionWhat it doesStarts at
VolumeHow loud, from 0, silent, to 1, the clip as it is1
PitchHow fast, and so how high1
PanWhere between the speakers, from -1, the left, to 1, the right0
LoopPlays again from its start each time it ends, until it is stoppedfalse
FadeInHow many seconds it takes to come up from silence0
StartHow many seconds into the clip it starts0
BusThe bus it plays on, by its name; null for Masternull
SpatialBlendPlayed in the world, how much of a 3D sound it is1
MinDistance, MaxDistancePlayed in the world, within what it is heard whole, and past what it falls off no further1, 500
RolloffPlayed in the world, Rolloff.Logarithmic or Rolloff.LinearLogarithmic

A sound asked for in the same frame as another starts with it. A bus the mix doesn't have plays the sound on Master, and the log says so.

Control a sound

A Sound is plain data, so a component or a resource can keep one. Ask the world to change it while it plays:

world.Audio.SetVolume(music, 0.2f, fade: 1f);     // from 0 to 1, over a secondworld.Audio.SetPitch(hum, 1.4f, fade: 0.5f);world.Audio.Pause(music, fadeOut: 0.3f);world.Audio.Resume(music, fadeIn: 0.3f);world.Audio.Stop(music, fadeOut: 3f);
bool playing = world.Audio.IsPlaying(hum);        // playing, or waiting for its clipdouble at = world.Audio.PositionOf(music);        // seconds into its clip

StateOf(sound) says whether it is Waiting for its clip, Playing, Paused or Stopped, and SetLooping makes it loop or end where its clip does. A sound that is over is asked nothing.

Play an Audio Source from code

Play(entity) plays the Audio Source on an entity as its fields say, stopping what it played before, so an Audio Source with Play On Awake off plays only when your code asks. SoundOf(entity) is the sound it plays, or played last, to control as any other:

Sound opened = world.Audio.Play(door);           // the door's Audio Sourceworld.Audio.Stop(world.Audio.SoundOf(radio), fadeOut: 0.5f);

From Rust

A game's Rust systems play sound through the GameAudio system parameter, which takes a clip by its path. Here Struck is a component of the game's own:

use abyss_ffi::{GameAudio, PlayOptions};
use bevy_ecs::prelude::*;
use bevy_transform::components::GlobalTransform;

fn chime(audio: GameAudio, struck: Query<&GlobalTransform, Added<Struck>>) {
    for at in &struck {
        audio.play_at("audio/chime.ogg", at.translation(), PlayOptions { pitch: 1.2, ..PlayOptions::default() });
    }
}

GameAudio also has play, play_on, play_source, stop, pause, resume, set_volume, set_pitch and is_playing. A clip played by its path must still reach the build, by being Addressable or used in a scene. See Rust in a game.

Sound, pause and the game's time

In the editor, the game's sounds pause while its play is paused and resume with it, and every one of them stops when you press Stop. Mute Audio, in the Game panel's row, silences the game while it goes on playing; your code does the same with world.Audio.SetMuted(true).

Sounds play at their own speed whatever the game's time scale says, unless their bus follows it (see Follow the time scale). That way a game's sound effects can slow down with slow motion while its music and its menus' sounds go on.

In the Scripting API