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:
- 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.
- 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.
- 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.)
- 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:
- 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.
- Select the "Import From..." command from the right-mouse menu or the File menu.
- Locate the "Library" folder under the location where SGDK2 is installed.
- 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).
- Click "Next" in the wizard to see a list of the source code objects contained
in the selected file.
- 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.
- 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.
- 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.
- 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.)
- Open the Sprite Definitions folder and edit the Player sprite definition.
- On the Rules tab, select the "Continue music" rule.
- Notice that the first parameter to this rule is currently the Signal94 sample
music. Try changing it to TropicalFun.
- 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.
- Open the Maps folder, expand the Menu map, then the Layers folder, then
the Letters layer, and finally the Plans folder.
- Select the Plans folder and then select New Object from the context menu,
the File menu or the toolbar.
- When the Edit Plan window appears, enter the following name for the plan:
Menu Music
- Select "Add New Rule" from the Plan menu or the Edit Plan
toolbar.
- Enter the rule name "Continue menu music".
- Leave the rule type as "Do" and select
"CustomObjects.FMODBase.PlaySound" for the rule function.
- Select the TropicalFun sound for the first parameter.
- 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.
- Open the player sprite for editing again and go to the Rules tab.
- Add a new rule to the end of the list and name it "Stop menu
music"
- Leave the rule type as "Do" and select
"CustomObjects.FMODBase.StopSound" as the rule function.
- Select TropicalFun as the first parameter. This will cause TropicalFun
to be the sound that is stopped by this rule.
- Select the "Continue Music" rule above the last rule.
- Change the Sound parameter back to the Signal94 sound.
- 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.
- Add a new rule to the end of the rule list and name it Stop game music.
- Leave the rule type as "Do" and select
"CustomObjects.FMODBase.StopSound" as the rule function.
- 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.
- From the Sprite Definitions folder of the project tree, open the Player
sprite for editing, and switch to the Rules tab.
- 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.
- Un-check the "Suspend this rule" box, and delete the "*
Example - " from the beginning of the rule name.
- Change the rule function to CustomObjects.FMODBase.PlaySound.
- Select the Boing sound effect as the first parameter.
- 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.
- 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.
- In the project tree, open Maps->Level 1->Layers->Main->Plans
and open the Door Left plan for editing.
- 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).
- Select "Add New Rule" from the Plan menu, and name the new rule
"Play player 1 door sound".
- Leave the rule type as "Do" and change the rule function to
"CustomObjects.FMODBase.PlaySound".
- Select the river sound effect for the first parameter.
- 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:
- Expand SourceCode->fmodex.dll->fmod.cs->fmodbase.cs.
- Open any existing sound effect (we want to copy the code).
- 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.
- Right-click on fmodbase.cs in the project tree and select New.
- 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).
- Select the entire contents of the newly created code object and replace it
with the copied code (press Ctrl+V).
- 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.
- From the Embedded Data menu, select "Load From File..."
- 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.
- 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.
- Preview the sound using the "Play with FMOD" command from the
Embedded Data menu.
- 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.
- Expand Maps->Level 1->Layers->Main->Plans and open Door Left
for editing.
- Expand "If player 1 is active" and select "Play player 1 door
sound" (the rule added earlier in the tutorial).
- 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.