Click or drag to resize
Sound and Music Tutorial

Because of the flexibility of Scrolling Game Development Kit 2, it is possible to implement sound and music without using any built-in features of the kit. That means games are not confined to using a particular sound library, and are free to implement sound however the project designer chooses to. However, with the less rigid system for implementing sound, many users may be left wondering what the easiest way of implementing sound in SGDK2 is. So for convenience, a few samples, a sound library and this tutorial have been pre-packaged with the kit as a sort of default sound solution. This page will describe how to import some sample sounds into a project, play them as part of the game execution, and how to create additional sounds, all based on the included sound library (FMOD Ex).

Using the Included Sound Library

All sample sounds delivered with SGDK2 rely on the included FMOD Ex sound library, which also provides some source code to access the functions provided in the DLL. There are 4 layers of code to be aware of when dealing with the sample sounds or other sounds using the included sound library:

  1. Fmodex.dll - This is the sound library binary itself. This DLL is delivered with SGDK2 as a suggested solution for playing sounds. Normally when importing a sound, a reference to this DLL will be at the root of the SourceCode folder as an indication to the SGDK2 environment that the DLL should be included in the project's output files when the project is compiled.
  2. Fmod.cs - This is a relatively large source code file that contains a bunch of the C# source code that was delivered with the FMOD Ex library, and is designed to be used to access it from C# programs such as the games created with SGDK2. Because this file is so large, the sample sound files refer to it using ~import "fmod.cs" instead of actually including the content of the while file in each SGDK2 sound template file. This causes the fmod.cs file to be loaded into the project at the time the sample is being imported. The actual fmod.cs file exists as a separate file in the Library\Sound directory for the purpose of allowing all the sample sounds in the library to share the same code. The fmod.cs file is normally listed as a "child" of the fmodex.dll file in the SourceCode tree, indicating that this code depends on the existence of fmodex.dll in the output folder in order to function.
  3. Fmodbase.cs - This relatively small piece of code wraps the functionality of FMOD Ex in another layer of functions specifically designed for SGDK2. It implements rules that are visible in the plan and sprite editors that can be called directly by plan rules and sprite rules to play sounds. Notice in this file that there functions and descriptions that show up in the rule editors for sprites and plans. This code is listed as a "child" of the fmod.cs file in the SourceCode tree indicating that it relies on the code in fmod.cs in order to function. All the sample sounds use this same set of code as a foundation for playing sounds. (This defines the "FMODBase" class from which all the sample sound effects derive.)
  4. Finally the fourth layer of code defines individual sound effects. The code at this layer (for the sample sounds) depends on fmodbase.cs, and is very small. The intention is to minimize the amount of code that needs to be copied for each individual sound, and since one of these files will exist for every sound, most of the code is implemented in the fmodbase.cs file and only a minimum amount of code will exist in the individual sound files at this level. It's also important to note that this is where the actual sound data is stored in binary form. When one of these files is loaded in the code editor, you can select commands in the "Embedded Data" menu and see that there is binary data associated with the code, and can manipulate it with these menu items.
Importing a Sound From the Library

The simplest way of adding a piece of sound or music to your project is to import a sound from the library. Even if you don't want to use a particular sound from the library, importing a sound is an easy way to get the proper code and framework imported into your project. Then you can rename the sound and supply new data if you want to change the sound. The steps for importing a sound are:

  1. Select the "SourceCode" folder in the Project Tree for your project. Note that sound effects go in the SourceCode folder because they are completely user-defined objects.
  2. Select the "Import From..." command from the right-mouse menu or the File menu.
  3. Locate the "Library" folder under the location where SGDK2 is installed.
  4. In the Library folder, browse to the "Sound" folder and select an SGDK2 file from within the Sound folder (or any other SGDK2 file that you know contains sounds).
  5. Click "Next" in the wizard to see a list of the source code objects contained in the selected file.
  6. Select one or more sounds to import. Note that fmodex.dll, fmod.cs and fmodbase.cs will automatically be checked for inclusion as soon as any sound effect is selected because every sound effect depends on fmodbase.cs, which depends on fmod.cs, which depends on fmodex.dll. If you only want to import the framework code and no sound in particular, you could just select the 3 FMOD files, but selecting a specific sound object provides a convenient starting point for a new sound at least. Just make sure that the file selected doesn't already exist in the project because if the file already exists, it will be ignored or overwrite during import rather than adding a new object.
  7. After clicking "Next" again, if your project already contains sounds that rely on the FMOD files, you will be prompted to specify whether the FMOD framework files should be replaced or ignored. If you check the box to replace a file, it will be re-imported from the template (which might be useful if you have corrupted the version in your project, or the sound effect you are importing includes an enhanced version of one of the FMOD files to support a customized feature of the sound). Leaving the boxes unchecked is usually the easiest thing to do, and will ensure that your existing sounds will continue to function as before.
  8. Click "Next" and then "Finish" to complete the wizard. The sound is now available to your project and can be triggered by sprite rules or plan rules.
Playing a Sound

There are two primary uses for sounds: effects and background music. Effects generally play once and are over quickly (until triggered again) while background music starts when the level loads (or when the game starts) and loops until the game or level is over (or some other event changes the music).

This portion of the tutorial will walk through the steps of adding more music and sound effects to the sample project. To begin, create a new project based on the sample project by selecting "Scrolling Game Development Kit Sample Project" from the File->New Project menu.

Playing Background Music

The sample game already has some groovy background music, but we can take a look at how it gets played as well as change the music or make the music change as the player is playing.

  1. Follow the instructions above to import a sample piece of music from the file Ben.sgdk2 into the sample project; try importing TropicalFun.cs. (Leave the boxes for overwriting unchecked when going through the wizard.)
  2. Open the Sprite Definitions folder and edit the Player sprite definition.
  3. On the Rules tab, select the "Continue music" rule.
  4. Notice that the first parameter to this rule is currently the Signal94 sample music. Try changing it to TropicalFun.
  5. Save the project (this is necessary in order to be able to run it) and run it to hear the new music.

Note that, although the sample project uses the player sprite to trigger the music, it could be triggered from any rule. Also note that, although the rule is called Continue music, it also causes the music to start playing, and the Continue option in the second parameter causes it to check the music every frame and loop to the beginning and play again when necessary. Other options in the second parameter are:

  • StartNew - Play another copy of this sound at the same time. Make sure that this is not used with a function that triggers the sound on every frame because playing 1000 copies of a sound at the same time really is not very nice. This may, however, be useful for a jumping sound effect that just plays once every time the the sound is triggered. Using this option will allow the existing jump sound effect to finish up while playing a new copy at the same time.
  • Restart - Restart the existing sound if one is already playing (or play a new sound if it's not playing). This is useful if you don't want to risk too many copies of the sound playing at once. For example, if the player can get lodged beneath a solid block and trigger a constant stream of jump sound effects, you might be better off using this option to prevent 100 copies of that sound effect from playing at once. It will just play the most recently triggered sound from the beginning. The difference between this option and Continue is that contine will allow the sound to keep playing from where it left off whereas this will force it to restart when the sound is re-triggered.

Next we will try triggering the music from somewhere else. Since the menu screen doesn't have any music, we could add some music there.

  1. Open the Maps folder, expand the Menu map, then the Layers folder, then the Letters layer, and finally the Plans folder.
  2. Select the Plans folder and then select New Object from the context menu, the File menu or the toolbar.
  3. When the Edit Plan window appears, enter the following name for the plan: Menu Music
  4. Select "Add New Rule" from the Plan menu or the Edit Plan toolbar.
  5. Enter the rule name "Continue menu music".
  6. Leave the rule type as "Do" and select "CustomObjects.FMODBase.PlaySound" for the rule function.
  7. Select the TropicalFun sound for the first parameter.
  8. Select the Continue option for the second parameter.

If you play the game at this point, you'll notice that the music starts when the menu appears now, and continues when you start playing the game. Next we will try to play different music on level 1 than we had on the menu map.

  1. Open the player sprite for editing again and go to the Rules tab.
  2. Add a new rule to the end of the list and name it "Stop menu music"
  3. Leave the rule type as "Do" and select "CustomObjects.FMODBase.StopSound" as the rule function.
  4. Select TropicalFun as the first parameter. This will cause TropicalFun to be the sound that is stopped by this rule.
  5. Select the "Continue Music" rule above the last rule.
  6. Change the Sound parameter back to the Signal94 sound.
  7. Now we must also make sure the level 1 music stops when switching back to the menu. Open the Menu map, and find the Menu Music rule again and edit it.
  8. Add a new rule to the end of the rule list and name it Stop game music.
  9. Leave the rule type as "Do" and select "CustomObjects.FMODBase.StopSound" as the rule function.
  10. Select the Signal94 music for the first parameter.

Finally you're ready to run the project. Now you should observe that the TropicalFun music is always the only music playing on the menu screen and the Signal94 music is always the only music playing during the game (when the player sprite is active).

Playing Sound Effects

The main differences between a sound effect and background music are that sound effect is generally shorter than a piece of music and does not loop. For this phase, we will add two sound effects, one to demonstrate a sound triggered by a sprite rule, and one to demostrate a sound triggered by a plan rule. Since there is no sound effect for when the player sprite jumps, this will be the sprite action. Then another sound will be added when the sprite goes through the door. Since a bouncing sound effect already exists in the sample game, we begin by triggering it when the player jumps instead of only when bouncing on the spring.

  1. From the Sprite Definitions folder of the project tree, open the Player sprite for editing, and switch to the Rules tab.
  2. Expand the "If climbing" rule, then in there, expand "Else (not climbing) if trying to climb up", then "Else (not trying to climb) if standing on solid". In there, you will see a rule called "* Example - play jump sound effect". Select it.
  3. Un-check the "Suspend this rule" box, and delete the "* Example - " from the beginning of the rule name.
  4. Change the rule function to CustomObjects.FMODBase.PlaySound.
  5. Select the Boing sound effect as the first parameter.
  6. Select Restart as the option for the second parameter.

Now the player sprite will play the boing sound effect every time it jumps. That was relatively easy because the sample rule was already there. Next a slightly more interesting trick will be to create and play a sound when going through a door.

  1. Follow the process described at the beginning of the tutorial to import a new sound effect. Import a sound effect from the Effects.sgdk2 file called River.cs.
  2. In the project tree, open Maps->Level 1->Layers->Main->Plans and open the Door Left plan for editing.
  3. Expand "If player 1 is active" and select "Ensure up is now seen as an old keypress for player 1" (the second-to-last rule in the group).
  4. Select "Add New Rule" from the Plan menu, and name the new rule "Play player 1 door sound".
  5. Leave the rule type as "Do" and change the rule function to "CustomObjects.FMODBase.PlaySound".
  6. Select the river sound effect for the first parameter.
  7. Select the Restart option for the second parameter.

Now you should be able to observe both the jumping sound effect when the player jumps, and the river sound effect when the player enters the left-hand door on the map. Adding the same sound effect for entering the right-hand door is left as an exercise for the reader :). You may also wish to attempt to make the plan-related sound effects function for player 2. The sprite-related sound effects should already work for either player because both players are instances of the same player sprite definition.

That wraps up sound effects for plan rules. You may also want to look at the player sprite rule "Play player 1 grape sound" and similar rules to see how sound effects can be triggered when the player interacts with tiles.

Defining New Sounds

With the limited selection of sounds available in the library, you will probably want to create your own sound effects and music. Try this:

  1. Expand SourceCode->fmodex.dll->fmod.cs->fmodbase.cs.
  2. Open any existing sound effect (we want to copy the code).
  3. Select the entire contents of the file and press Ctrl+C to copy the code. The code could also be copied from the help file by pressing F1 in the code editor and locating the section named Sound Effects Sample.
  4. Right-click on fmodbase.cs in the project tree and select New.
  5. Enter a name for the sound effect. It must not contain any spaces or punctuation, and should be unique from all the other items in the SourceCode tree (.cs will be appended automatically).
  6. Select the entire contents of the newly created code object and replace it with the copied code (press Ctrl+V).
  7. Find and replace all occurrences of the original sound effect name with your new name. There should be 5. You can use the find and replace feature for this.
  8. From the Embedded Data menu, select "Load From File..."
  9. Select any sound file you want to import into your project. Suggested formats are OGG, MP3, MOD and MID, but any format supported by FMOD will work. WAV is supported, but often times will not compress as well as other formats. You cannot import sounds from other SGDK2 files with this command.
  10. If the code you copied has a "Volume" property implemented in it, you can easily adjust the volume at which the sound will play by changing the value returned to any value between 0 and 1.
  11. Preview the sound using the "Play with FMOD" command from the Embedded Data menu.
  12. To ensure that your new sound becomes available in the rule editors, close all windows and re-compile the project with the F7 key.

After performing these steps, your sound should be available as a selection for any rule function that expects a sound. Try triggering your new sound when the player enters the left door and is transported to the right door.

  1. Expand Maps->Level 1->Layers->Main->Plans and open Door Left for editing.
  2. Expand "If player 1 is active" and select "Play player 1 door sound" (the rule added earlier in the tutorial).
  3. Change the sound in the first parameter to your new sound. (This should be available if the plan window was opened after you re-compiled the project with F7 in step 12 above.)

Now you should hear your custom sound effect whenever the player enters the door.