Implementing FMOD

From Valve Developer Community
Jump to: navigation, search
Note:FMOD EX is no longer available to download directly from FMOD's website. Another source is hosted below.


Implementing FMOD into the Source engine is incredibly easy and the benefits speak for themselves, however you will need to know how FMOD works in order to get anything out of adding it to your modification.

What is FMOD?

Essentially, FMOD is a sound system that can run in a different instance while your modification is running. This means you can have music playing while a player is connecting to a server or loading a new map, not to mention play files in formats that Miles, the default sound system of the Source engine, can't. The possibilities are endless, and because it is relatively easy to implement, there's really no reason not to add it to your modification.

FMOD operates under a free for non-profit license. As long as you don't plan to ever sell your modification, you may continue using FMOD for free, otherwise you'll need to pay for a license.

The Installation

You will need to download a version of FMOD Ex. You can do this by visiting this website. Once downloaded, make sure the files are installed to a directory in your source code. It's easier if you just made an "fmod" folder in your /src folder and put everything in there.

In addition to the files FMOD provides you, you will need to download the following files and add them to your client project:

These files were originally created by User:£cho and are free for non-profit use. Please do not attempt to edit these files unless you know what you're doing.

NOTE: FMOD will not operate under the server project at this time. The primary reason for this is because the server does not store the path to a client's mod folder. It does store the mod folder's name (i.e hl2, hl2dm, etc), however not the directory tree, which means sounds cannot be found relative to a client's modification folder. However, a way around this is to build console commands that trigger FMODManager's internal functions, then fired from the server. It's not a perfect solution but it will work for server-side code.

Oh, and before you forget, navigate to your fmod/api folder (assuming you followed the suggested folder structure mentioned above) and copy the fmodex.dll into your modification's /bin folder.

The Setup

Now that the installation is done, it's time to setup our system. There's not a whole lot to do here, but these are necessary steps you'll have to take in order to begin using FMOD.

To start, right-click on your client project in the Solution Explorer and go to "Properties". Expand "Configuration Properties" on the left of the new window that appears and click on "C++". Edit "Additional Include Directories" to include FMOD's /api/inc folder. For example, if you made a new "fmod" folder in your /src folder of your source code files as suggested, you would add this to your list of include directories: ..\..\fmod\api\inc

Stay in the same window and click on "Linker", which is the option under "C++". Edit "Additional Library Directories" to include FMOD's /api/lib folder. Again, if you made a new "fmod" folder in your /src folder of your source code files, add this: ..\..\fmod\api\lib

Note:If you get "unresolved external symbol" errors on compile, right-click the "Link Libraries" folder in your client solution and select "Add Existing". Go into the "fmod\api\lib" folder and choose "fmodex_vc.lib" to add to the solution. If a window comes up at this point, click "No".

All that needs to be done now is to start the FMOD sound system when the modification launches. To do this, open up cdll_client_int.cpp, add #include "fmod_manager.h" to the list of includes and add the following in the Init function under g_pClientMode->Enable();

// FMOD - Start 'er up!
FMODManager()->InitFMOD();

Similarly, in the same file in the Shutdown method, add the following below g_pClientMode->Shutdown();

// FMOD - Shut us down
FMODManager()->ExitFMOD();

To get fading to work, the client must be able to think every frame. The hacky way to go about doing this is to add the following somewhere in the View_Render method:

// S:O - Think about fading ambient sounds if necessary
FMODManager()->FadeThink();

Also, we want to be absolutely sure sounds stop playing whenever we exit to the main menu from having just been playing the mod. Do to this, add the following at the end of the LevelShutdown method:

// S:O - Stop all FMOD sounds when exiting to the main menu
FMODManager()->StopAmbientSound( false );

Usage

The installation and setup are both complete! Assuming you followed this little tutorial step-by-step, you now have successfully implemented the FMOD sound system into your modification. Now it's time to learn how to use it, otherwise this would all have been for nothing.

Whenever you want to use the FMOD system, you will need to add the following to your list of includes at the top of the cpp you are editing;

#include "fmod_manager.h"

After this is done, you can proceed to call any one of CFMODManager's public functions and methods using FMODManager()->. Here's an example:

FMODManager()->TransitionAmbientSounds( "ambient/so-ambience1.mp3" );

The above transitions between a sound that is playing via FMOD by slowly fading it out, then playing the new sound. If a sound isn't playing via FMOD when this is called, don't worry, it'll just start playing the new sound. In most cases, you'll want to use this instead of the PlayAmbientSound method to prevent two sounds from playing simultaneously.

To stop all sounds playing via FMOD using a fade, you can use the following:

FMODManager()->StopAmbientSound( true );

Sometimes you'll probably want to see if a sound is already playing before playing it again or playing a new sound. For this, you can use the following:

FMODManager()->IsSoundPlaying( "relative path to sound file to check here" );

The IsSoundPlaying function will return true if the sound is already playing and false if it is not or if no sound is currently playing.