Introduction

What a player hears in game can be just as important as what he sees! This tutorial will show you how to add ambient (background) music with looping. Also covered is how to integrate non-looping sound effects to your game. The tutorial is aimed at beginner level users of TGB.

Getting Started

First, we are going to load an existing project that came with TGB. In the File menu, select Open Project...


Figure 1.1

Choose FishDemo from the list and then click on the Open Project button. If you've never opened the fish demo project before, you should see a screen like in Figure 1.2.


Figure 1.2

The FishDemo project has many levels already created. Go again to the File menu and this time choose Open...

From the list seen in Figure 1.3 below, choose the first level and click Open.


Figure 1.3

There should now be a level loaded up for you, as seen below:


Figure 1.4

Click on the fish in the middle of the screen. With it selected, click on the Edit Tab and open the Scripting rollout. You should see that the fish already has a name and class.


Figure 1.5

Now with everything set up for us, exit out of TGB. Setting up audio is largely a function of scripting in version 1.1 of TGB. Before you start scripting though, download the following zip file and extract the Oceanwhales.wav sound file. Put it in your games\Fish\data\audio folder.

Image:Oceanwhales.zip

The AudioDatablock

To start off, create a new script file in your games\FishDemo\gameScripts\ folder and call it audioDatablocks.cs. An audio datablock is composed of two sections: AudioDescriptions and AudioProfiles. The first to be added will be AudioDescriptions. Open the audioDatablocks script file and add this to the top:

new AudioDescription(AudioLooping)
{
   volume   = 1.0;
   isLooping= true;
   is3D     = false;
   type     = $GuiAudioType;
};

Let's quickly go over what we have here. We are calling this description AudioLooping. Volume has a range from 0.0 to 1.0, with 1.0 being full volume and the default. isLooping defines whether or not you want the file to repeat. Since our description is AudioLooping, it makes sense to have this as true. The is3D variable defines whether or not the position of something in the world affects how the audio sounds. $GuiAudioType is a predefined audio type within Torque.

Add the second AudioDescription, AudioNonLooping, right below the one you just typed (or copy/pasted) in:

new AudioDescription(AudioNonLooping)
{
   volume   = 1.0;
   isLooping= false;
   is3D     = false;
   type     = $GuiAudioType;
};

Very similar to our first AudioDescription, except that isLooping is now false.

The next section of your audioDatablocks.cs file is for the AudioProfiles. These contain the actual path to your audio file, the description used (from AudioDescription), plus a variable for preloading the file or not. Add this below the AudioNonLooping description:

new AudioProfile(ambient1Audio)
{
	filename = "~/data/audio/oceanwhales.wav";
	description = "AudioLooping";
	preload = true;
};

Your entire audioDatablocks.cs file should now look like this:

new AudioDescription(AudioLooping)
{
   volume   = 1.0;
   isLooping= true;
   is3D     = false;
   type     = $GuiAudioType;
};

new AudioDescription(AudioNonLooping)
{
   volume   = 1.0;
   isLooping= false;
   is3D     = false;
   type     = $GuiAudioType;
};

new AudioProfile(ambient1Audio)
{
	filename = "~/data/audio/oceanwhales.wav";
	description = "AudioLooping";
	preload = true;
};

Save your audioDatablocks.cs file and open up main.cs, found in the games\Fish folder. Find this line:

   // Exec game scripts.
   exec("./gameScripts/game.cs");

and add this just below it:

exec("./gameScripts/audioDatablocks.cs");

Save and close the main.cs file.

Singing Fish

Now we have to find an appropriate location to turn the music on. In the FishDemo\gameScripts\tutorialScriptSamples folder, open up FishTutorial1.cs. We will edit the onLevelLoaded function. Here is how it currently looks:

function FishClass::onLevelLoaded(%this, %sceneGraph)
{
   %this.setLinearVelocityX(-20);

   %worldLimit = %this.getWorldLimit();

   %limit0 = getWord(%worldLimit, 1);
   %limit1 = getWord(%worldLimit, 2);
   %limit2 = getWord(%worldLimit, 3);
   %limit3 = getWord(%worldLimit, 4);

   %this.setWorldLimit("NULL", %limit0, %limit1, %limit2, %limit3 , true);
}

Now, change it to look like this:

function FishClass::onLevelLoaded(%this, %sceneGraph)
{
   // play ambient music
   $fishMusic = alxPlay(ambient1Audio);
   
   %this.setLinearVelocityX(-20);

   %worldLimit = %this.getWorldLimit();

   %limit0 = getWord(%worldLimit, 1);
   %limit1 = getWord(%worldLimit, 2);
   %limit2 = getWord(%worldLimit, 3);
   %limit3 = getWord(%worldLimit, 4);

   %this.setWorldLimit("NULL", %limit0, %limit1, %limit2, %limit3 , true);
}

To start a sound file, we use the alxPlay() function with a reference in the quotes to our only AudioProfile.

Now save the script file, close it, and open up the Level Builder again. Press the play button and make sure your speakers are turned on!

Turn it off!

If for whatever reason you wish to stop the background music (while the game is paused, for example), it is also quite easy to accomplish in TGB.

Let's keep it simple and make the whales stop singing when you press the stop button inside the level builder. Here is the endGame function found in the FishDemo\gameScripts\game.cs file as it is by default:

function endGame()
{
   sceneWindow2D.endLevel();
   moveMap.pop();
}

Change it to this:

function endGame()
{
   alxStop($fishMusic);
   sceneWindow2D.endLevel();
   moveMap.pop();
}

Easy? You bet. Non looping sounds work the same way, use alxPlay() inside your game specific functions, remembering that timing is key. To test it out you can simply change our existing AudioProfile for the ocean whales to:

new AudioProfile(ambient1Audio)
{
	filename = "~/data/audio/oceanwhales.wav";
	description = "AudioNonLooping";
	preload = true;
};

or create a new AudioProfile with a much shorter duration sound effect. Examples in this area can be seen in the scrollerDemo. The audioDatablocks.cs file can be found in games\scrollerDemo\data\audio\. Check it out and make your games sound great!