Quick know-how > Adding sounds to your game

Starting from the version 0.0.47, Cubzh has implemented a sound system to help you improve the ambience of your games. You can now pick from a library of built-in musics and sound effects to bring your worlds to life!

In a nutshell, the sound system works as follows:

- First, you have to place a listener somewhere in your scene: this is basically a microphone-like object that captures the sounds from all the sources around it and outputs the result to your speakers. It is unique and readily available using the AudioListener variable.
- Then, to add a new sound source in the game, you have to create a new instance of the AudioSource class, assign it a reference to a sound file (among the list of built-in ones, see below) and parent it somewhere in the world's hierarchy.

All this can be done via a code snippet like this one:

Client.OnStart = function()
    -- add the AudioListener to the player's head
    -- to "glue the microphone" to this object
    Player.Head:AddChild(AudioListener)

    -- create a new source
    as = AudioSource()
    as.Sound = "death_scream_guy_1"
    as:SetParent(Player.Head)
end

You can create as many sources as you want, keeping in mind that one source can only play one sound at a time. And since both the AudioListener and AudioSource classes inherit from the Object base, you can set their transform and parent-dependencies like you're used to :)

Once initialized like this, your AudioSource instance can be turned on by calling its Play method, and off by calling its Stop method:

gameOver = function()
    as:Play()

    Timer(2, false, function()
        as:Stop()
    end)
end

The whole trick is then to properly choose your sounds and musics, and to tweak their parameters to better integrate them to the context! Let's see some additional tricks!

Changing the volume of your AudioSource

The most commonly used option is the Volume. This value goes from 0 (full silence) to 1 (full volume) and makes it easy to level the various sources according to one another.

as = AudioSource()
as.Sound = "gun_shot_1"
as:SetParent(gun)

as.Volume = 0.3

Taking an excerpt of the sound

Our most creative contributors have already managed to go above and beyond and make their own sounds by playing around with the existing ones and chopping them up in clever ways! If you too want to try and remix the raw material, have some fun with the StartAt and StopAt properties of your AudioSource (both expressed in milliseconds):

as = AudioSource()
as.Sound = "waterdrop_1"
as:SetParent(gun)

as.StartAt = 200
as.StopAt = 1000

Playing around with the pitch

To expand the audio library, you can also tweak the pitch of the sound file, i.e. how "high" or "low" it is perceived. This property works like this:

- 1.0 keeps the normal frequency, meaning the sound is as-is
- 0.5 halves the frequency, so the audio will sound lower
- 2.0 doubles the frequency, so the audio will sound higher

The pitch cannot be 0, but it can technically go up to +infinity. To change it, just set the Pitch option of the source:

as = AudioSource()
as.Sound = "waterdrop_1"
as:SetParent(gun)

as.Pitch = 0.5 -- lower the sound

Tweaking or disabling spatialization

Another interesting features of the sounds in Cubzh is that, by default, they are spatialized. This means that you won't hear your AudioSource the same depending on where the listener is. For example, the sound will be louder when the listener is closer to it, and you will get a left/right pan effect as the angle between the source and the listener changes. This is a great way to make really believable positional sound source in your world in a flash!

But of course, sometimes, you might want one of your AudioSource instances to be just some ambient sound, or a background music. In that case, the sound should not be spatialized, because it is independent of the position of the listener. This is easy to setup: just turn the Spatialized property off like this:

as = AudioSource()
as.Sound = "gun_shot_1"
as:SetParent(gun)

as.Spatialized = False

If you want to keep the spatialization but customize it in more details, you can force its pan to be more in the left or the right ear using the Pan setting.

The Pan value goes from -1 (left ear only) to 1 (right ear only), with a default of 0 (equal in both ears):

as = AudioSource()
as.Sound = "gun_shot_1"
as:SetParent(gun)

as.Pan = -0.5 -- "move the sound" slightly on the left

List of available sounds

Here is a list of all the sounds currently available in Cubzh (they should be pretty self-explanatory, but don't hesitate to try out some "surprising" effects to give a unique style to your world!):