3. Integration Tutorial

This guide will show you how to get started with FMOD for Unity. You will take an existing Unity project, install FMOD for Unity and integrate adaptive audio created with FMOD Studio. Follow along step by step and hear the results. When you have completed the tutorial, you should know enough to integrate FMOD content to any Unity project.

The Unity project you will be using is the Karting Microgame Template, a 3D kart racing game developed specifically for learning. To keep things simple, you will be using audio content from the FMOD examples project.

Let’s get started!

3.1 Setting up the Unity project

1. Visit the Unity website and install Unity Hub using the download link appropriate for your operating system.

2. Log in to the Unity website or create an account, and add the Karting Microgame to your assets from the Asset Store.

3. Run the Unity Hub and log in again.
   To allow the following steps to work correctly, make sure Unity 2021.3 or lower is installed and selected in the next step.

4. In the Unity Hub, click New Project.
   

5. Click the "Editor Version" dropdown menu, and select version 2021.3 or earlier.

6. Click All Templates and then scroll to the Karting Microgame tile.
   

7. Click Download Template.
   

8. If you don't have a Unity engine installed, you will be prompted to install one. If you have a compatible engine installed, skip to step 9.
   
   If you see this message:

   1. Click Install Editor.
   2. On the prompt that appears, select a supported Unity version (noted in the Karting Microgame's Asset Store page) and click Install.
      
   3. No additional modules will be necessary for this tutorial, so click install.
      
   4. Wait for the installation to complete.
   5. Once complete, click New Project again and select Karting Microgame (as in steps 4 and 5).

9. Enter a name for your project and click Create Project.
   Unity will open and import the project data. This may take some time.
   On Windows, you may need to accept any prompts to allow firewall access.
   Once Unity is open, you will see a Welcome dialog explaining how to Get Started with the Karting Microgame tutorial.

10. On the right side of the screen, you'll see the Tutorials Tab. Again, this is used in Unity's tutorial, so we can close this as well by clicking on the menu dropdown and select Close Tab from the menu.
    
    Let's try playing the karting game and listening to things as they are currently.

11. Click the play button at the top of the Unity window.
    
    The game will start playing in the editor.

12. Use the arrow keys on the keyboard to start driving.
    As you can hear, the sound of the engine is very quiet. We can disable the music temporarily to hear the engine.

13. While the game is running, select the BackgroundMusic game object in the Hierarchy tab on the left.

14. Uncheck the Audio Source component in the Inspector pane on the right.
    

15. Continue driving with the arrow keys.

16. Once you've listened to the engine, click the play button to stop playing the game.

The sound of the engine, and the game's audio in general, could use some improvement. We can do this using FMOD.

3.2 Setting up the FMOD Project

Our plan is to use audio content from the FMOD Studio examples. To do this, we need to install the FMOD Studio authoring tool and create a new FMOD Studio project.

1. Go to the FMOD downloads page. You may need to create an account in order to see the downloads.

2. On the downloads page, click on the FMOD Studio Suite section to expand it, then select the 2.03 sub-section.

3. Click the Download link appropriate for the computer platform you are using (Windows or Mac).
   
   A "Unity Verified" version of FMOD for Unity is QA tested and certified by Unity to be a compatible solution.

4. Run the downloaded installer and follow the installation instructions.
   Next, let’s make a copy of the Examples Project that comes with FMOD Studio.

5. Run FMOD Studio by selecting it from the Start Menu on Windows, or the Applications folder on Mac. (On Windows, accept any prompts to allow firewall access.)

6. In the welcome dialog, select the "Examples.fspro" project from the Recent Projects list. It should be the last project in the list; if there are multiple projects named "Examples.fspro" listed, select the last one. (On MacOS, if "Examples.fspro" does not appear in the list, click Open Project to locate it manually. The project is located in the examples folder of the FMOD Studio installation directory.)
   

7. From the menu bar, select "File > Save As..."
   

8. Select a save location and name for the project. As we'll be telling Unity where to look to find the FMOD project, we can save the project where ever we like. Do not select a location within the Assets folder of the Unity project created earlier.
   The examples project contains many events. An event is a unit of sound content that can be controlled from game code, and which can contain both audio files and playback logic. Everything that makes sound in a game should have a corresponding event.
   In our game, the kart’s engine will have its own event. For the purposes of this guide, we’ll use an existing event from the examples project for the kart engine. We’ll cover creating new events later.

9. In the Events browser on the left of the window, select "Vehicles/Ride-on Mower". This causes the event's content to appear in the editor.
   

10. Click the play button in the transport bar to audition the event.
    

11. Drag the RPM parameter's playback position around the parameter ruler.
    
    You should hear a more accurate model of an engine sound being played at various RPMs.
    We'll make our Unity game play this event, and send it relevant parameter data such as the RPM value, during gameplay.

12. Click the stop button to stop auditioning the event.
    
    The next step is to build our FMOD events into banks. We’ll load the banks in Unity later in this tutorial.

13. In the menu bar, select "File > Build..."
    

The banks will be built to a folder within the FMOD Studio project folder.

3.3 Setting up FMOD for Unity

We are now ready to load the banks into Unity so that we can trigger our kart event. To start, we will need to import FMOD for Unity.

1. Open the Unity Asset Store in your web browser, and navigate to FMOD for Unity.
   Note that in Unity 2019.4 and earlier, the asset store opens in the Asset Store window. Search for "FMOD for Unity" in the search bar.

2. Check the major version of the asset matches your version of FMOD Studio e.g. 2.03.xx (additionally this guide expects a minimum of 2.02.04 due to assembly definitions being included). If it doesn't match, download a version of FMOD for Unity whose version number does match from the FMOD for Unity section of the FMOD Downloads page instead.

3. Click the button "Add to My Assets".
   In Unity 2019.4 and earlier, this button is instead labeled "Download".

4. Make sure you're signed in to your Unity account again.

5. In Unity 2020.1 and later,select "Window > Package Manager".
   

6. In the package manager window, ensure the second dropdown in the upper left is set to "My Assets".
   

7. Select the FMOD for Unity asset and click Download in the lower right.
   

8. Once the download completes, click the Import button.
   

9. You will be prompted with a list of assets, leave them all ticked and click the Import button.
   
   (If you are using MacOS 10.15 Catalina, you may encounter warnings at this point. If so, please see the following: Catalina).

10. The FMOD Setup Wizard window opens. Click Start.
    

11. The next page is for updating an existing FMOD For Unity setup. Since this is the first time, click Next.
    

12. Select the FMOD Studio Project button and select the *.fspro file within the FMOD Studio project folder, as created earlier, and click Next.
    
    

13. The next page is to remove the native Unity listener and replace it with the FMOD Listener. Click the Replace Unity Listener with FMOD Audio Listener then click Next.
    

14. This page is for disabling Unity's built-in audio engine. Since we are using the FMOD Engine for the audio there is no need for the Unity built-in audio engine to keep using up resources. Click the Disable built in audio button, then click Next.
    

15. This page lists all of the AudioSource Unity components in the Unity project. This could be useful for locating AudioSource components in the Unity project and disabling or removing them as needed. However, since we want to fully understand how FMOD Event Emitter components can replace Audiosource components as part of this tutorial, please leave this page as it is and click Next.
    

16. The next page is for copying over rules for ignoring certain files and folders when using FMOD for Unity with your Unity project. As we are not using source control in this tutorial, click Next.
    

17. The final page is a list of all the tasks you performed with the FMOD for Unity wizard. Since this was a new project and not changing the Unity AudioSources, the Unity Sources item is listed as incomplete. This is expected, so click Close to exit the setup wizard.
    

Play the game and make sure no errors appear in Unity's console tab.

Congratulations! You’ve now completed the basic setup of FMOD for Unity. The rest of this guide will focus on adding FMOD events to the Karting Microgame.

3.4 Adding Sounds: Kart Engine

As mentioned earlier, we want the player’s kart to use the Ride-on Mower FMOD event. Firstly, let’s add a component to trigger the event.

1. Select the KartClassic_Player/ArcadeEngineAudio game object in the Hierarchy tab on the left.
   

2. Click Add Component at the bottom of the Inspector tab.
   

3. Select "FMOD Studio/FMOD Studio Event Emitter".
   

4. Set the Event Play Trigger field to Object Start.
   

5. Click the search button next to the Event field.
   

6. In the browser popup, double click "Events/Vehicles/Ride-on Mower".
   

7. Under the Initial Parameter Values section, add RPM from the dropdown and set the value to 1000.
   

8. Play the game. You should now hear the kart engine playing at a constant RPM value of 1000.
   Next, we need to link the RPM value determined by the kart’s physics to the FMOD event. To do this, we’ll edit the existing engine audio C# script to pass the RPM value to our event.

9. In the Project tab, navigate to "Assets/Karting/Scripts/KartGame".
   The script we need to edit is assigned to a custom KartGame assembly using an Assembly Definition file, so it won't be able to access the FMOD scripts until we make the KartGame assembly refer to the FMODUnity assembly.
   

10. In the Assembly Definition References section of the Inspector, click the + button to add a new assembly definition asset.
    

11. Click the target icon on the new assembly definition asset and select the FMODUnity assembly.
    

12. Click the Apply button at the bottom of the inspector. You may need to scroll the inspector to see this button.
    
    Editing the assembly definitions may cause the FMOD Setup Wizard to appear. This occurs because editing the assembly definitions causes FMOD for Unity to detect the Unity audio source associated with the changed assembly definition. As we are going to deal with these audio sources later in this tutorial, it is safe to close the FMOD Setup Wizard when it appears. If its appearance gets annoying, feel free to click the "Do not display this again" checkbox on the FMOD Setup Wizard's first page.

13. Now we can make our changes to the engine audio script. Select the "KartClassic_Player/ArcadeEngineAudio" game object in the hierarchy.
    

14. In the inspector, click the Arcade Engine Audio (Script) component's context menu icon, and select "Edit Script" from the menu.
    
    The script file should open in your default code editor, assuming you have one set. If you have not set a default code editor, you may set one by selecting "Edit > Preferences > External Tools".

15. We need to replace the existing code with our own, so select all the code below and press Cmd-C (on MacOS) or Ctrl+C (on Windows) to copy. Then head back to the code editor, press Cmd-A (on MacOS) or Ctrl+A (on Windows) to select all, then Cmd-V (on MacOS) or Ctrl+V (on Windows) to paste this code:

    using UnityEngine;
    
    namespace KartGame.KartSystems
    {
        /// <summary>
        /// This class produces audio for various states of the vehicle's movement.
        /// </summary>
        public class ArcadeEngineAudio : MonoBehaviour
        {
            public float minRPM = 0;
            public float maxRPM = 5000;
            ArcadeKart arcadeKart;
    
            private FMODUnity.StudioEventEmitter emitter;
    
            void Awake()
            {
                arcadeKart = GetComponentInParent<ArcadeKart>();
                emitter = GetComponent<FMODUnity.StudioEventEmitter>();
            }
    
            void Update()
            {
                float kartSpeed     = arcadeKart != null ? arcadeKart.LocalSpeed() : 0;
                // set RPM value for the FMOD event
                float effectiveRPM = Mathf.Lerp(minRPM, maxRPM, kartSpeed);
                if (emitter != null)
                {
                    emitter.SetParameter("RPM", effectiveRPM);
                }
            }
        }
    }
    

16. Save the script and close the text editor.
17. Play the game again. The engine sound will change as you accelerate. However, the engine still needs some tuning.
18. Ensure the "KartClassic_Player/ArcadeEngineAudio" game object is still selected in the Hierarchy tab.
19. Under the Engine Audio script component, set the Min RPM to 500 and the Max RPM to 2000, to match a sensible range for the Ride-on Mower event.
    
20. Play the game again. The kart engine should sound much better!

3.5 Adding Sounds: Ambience

Now that we have the kart engine working correctly, let’s add some ambience to the soundscape.

1. Select the BackgroundMusic game object in the Hierarchy tab on the left.
   

2. Click Add Component at the bottom of the Inspector tab.
   

3. Select "FMOD Studio/FMOD Studio Event Emitter".
   

4. Set the Event Play Trigger field to Object Start.
   

5. Click the search button next to the Event field.
   

6. In the browser popup, double click "event:/Ambience/City".
   

7. Under the Initial Parameter Values section, add Traffic from the dropdown and set the value to 0.3.
   

Play the game again. You should hear the city ambience filling out the soundscape.

3.6 Adding Sounds: Music

Up until now, we’ve been using events from the FMOD examples project. Let’s try creating a new event. This will be a simple event that replicates the original game’s looping background music.

1. In FMOD Studio, right-click (or command-click on Mac) on the Music folder to open the context menu, then select "Event Defaults > 2D Timeline".
   

2. Enter a name for the event: “Kart Music”.
   

3. To assign the event to a bank for export, right-click (or command-click on Mac) the event in the Events browser, select Assign to Bank, and select the Music bank.
   
   We will reuse the original music from the Unity project in our new FMOD event.

4. In the Unity editor, in the Project tab, navigate to "Assets/Karting/Audio/Music".
   

5. Right-click (or command-click on Mac) on the Music asset and select Show in Explorer (or Show in Finder on Mac).
   

6. Drag the Music.mp3 file from the Explorer (Finder on Mac) window to the FMOD Studio event editor window, dropping it over the body of the Audio 1 track in the editor pane to create an instrument.
   

7. Click and drag the instrument to move it left, so that its left edge is at the start of the timeline.
   

8. Click the play button to audition the event and check that the music can be heard.
   

9. Click the stop button to end auditioning.
   
   As in the original game, we want the music to loop continuously.

10. Right-click (or command-click on Mac) on the instrument that was created in the previous steps and select New Loop Region.
    
    Play the event and observe that the music loops when it reaches the end of the loop region.
    The music will be routed separately to the sound effects. This makes it easy to adjust the mix later.

11. In the menu bar, select "Window > Mixer" to open the Mixer window.
    

12. In the Mixer window’s Routing browser, drag the “Music/Kart Music” event into the “Music” group bus.
    
    We need to rebuild the banks to include the new Kart Music event in the game.

13. In the menu bar, select "File > Build..."
    
    This causes the FMOD Bank Refresh Status dialog to appear briefly in Unity. If you're in a hurry, you can click "Refresh banks now" to refresh the banks immediately instead of waiting for the dialog to do it automatically after a few seconds.
    
    Next, let’s trigger this event in the game.

14. In Unity, select the BackgroundMusic game object in the Hierarchy tab on the left.
    

15. Click Add Component at the bottom of the Inspector tab.
    

16. Select "FMOD Studio/FMOD Studio Event Emitter".
    

17. Set the Event Play Trigger field to Object Start.
    

18. Click the search button next to the Event field.
    

19. In the browser popup, double click "event:/Music/Kart Music".
    

20. In the Unity window, click the play button and ensure that the game is running.
    
    As you can hear, this effectively replicates the original game’s music playback. However, you'll find that the background music drowns out the sound of the engine. We need to change the mix to make the music less overpowering, and it'll be easier to do that if we keep the game running and connect to it with live update.

21. In the FMOD Mixer window, click the Live Update button at the bottom of the window.
    

22. Ensure that the “localhost” address is selected. This allows us to connect to a game running on the same machine as FMOD Studio.
    

23. Click the Connect button.
    
    The Live Update button at the bottom of the window should blink a few times, then say "Live Update On."
    

24. Open the mixer window and locate the Music group bus in the mixing desk. You may need to scroll to the right to find it.
    

25. Drag the music bus' volume fader downwards, setting it to -6dB.
    
    The music should lower in volume instantly.
    Live update makes it quick to iterate on the game’s audio.
    Now is a good time to try adjusting things to your liking. For example, after clicking on the Music group, you’ll find you can edit the pan and pitch settings in the deck, or add DSP effects to change the quality of the sound.
    
    Note that if you disconnect Live Update now, the audio in Unity will revert to the previously built state when you exit play in editor mode. To commit your changes so that they can be heard even when live update isn't connected, rebuild the banks in FMOD Studio.

3.7 Removing the existing audio

It is a good idea to remove the pre-existing Unity AudioSources currently present in the project. This is because Unity AudioSources are not part of the FMOD Engine, and so do not take advantage of the FMOD Engine's various features and optimizations.

1. Select "FMOD > Setup Wizard" to open the setup wizard.
   

2. Click on the "Unity Sources" button.
   

3. Select the following game objects from the list to automatically navigate to them. Alternatively, these objects can also be found in the Unity editor's hierarchy:

   • "GameManager/GameHUD"
   • "BackgroundMusic"
   • "KartClassic_Player/ArcadeEngineAudio/engine-idle"
   • "KartClassic_Player/ArcadeEngineAudio/engine_start"
   • "KartClassic_Player/ArcadeEngineAudio/engine-running"
   • "KartClassic_Player/ArcadeEngineAudio/engine-reverse"
   • "KartClassic_Player/ArcadeEngineAudio/Drift"

For each of these game objects:
1. Select the game object
2. Click the context menu icon of the Audio Source component in the Inspector pane on the right.
3. Select Remove Component.

There are multiple copies of some of these objects in the list. The audio source component should be removed from all of these copies.

Once you have removed the audio components from all these game objects, you can close the FMOD Setup Wizard window.

Removing the Audio Source from the "GameManager/GameHUD" object will cause errors in the Feedback Flash HUD script. To fix this, we need to edit FeedbackFlashHUD.cs.

4. Select the "GameManager/GameHUD" object.

5. Scroll down to the Feedback Flash HUD component in the Inspector tab and click the context menu icon.

6. Select Edit Script to open the script file in your default code editor.

7. Delete all the lines that contain `m_audioSource`. Remember that you can use Cmd-F (on MacOS) or Ctrl+F (on Windows) to search the script.

8. Save the script and close the text editor.

There is also a Game Flow Manager component that creates an AudioSource component when you pass the final checkpoint. To get rid of this, we need to edit GameFlowManager.cs.

9. Select the GameManager object.

10. Scroll down to the Game Flow Manager component and click the context menu icon.

11. Select Edit Script to open the script file in your default code editor.

12. Delete all the lines that contain `audioSource`.
13. Save the script and close the text editor.

There are also some components that call AudioUtility.CreateSFX (which creates AudioSource components) to play sound effects when you bump into a wall or pass a checkpoint. To get rid of these, we need to edit AudioUtility.cs.

14. In the Project tab, navigate to "Assets/Karting/Scripts/Utilities/AudioUtility".

15. Double click the AudioUtility script to open it in your default code editor.
16. Delete the contents of the `CreateSFX` function (lines 19-29).
17. Save the script and close the text editor.

There is also an Objective Toast component that creates AudioSource components when the objective messages appear. To get rid of these, we need to edit ObjectiveToast.cs.

18. In the Project tab, navigate to "Assets/Karting/Scripts/UI/ObjectiveToast".

19. Double click the ObjectiveToast script to open it in your default code editor.
20. Delete all the lines that contain `PlaySound` **except** the line that starts with `void PlaySound`.
21. Save the script and close the text editor.

If you play the game again, the warnings will have been fixed. However, you may notice that the starting line sounds continue to play. These are triggered by a Unity timeline asset which we can also remove.

22. In the Project tab, navigate to "Assets/Karting/Timelines/RaceStart".

22. Double click the RaceStart asset to open it in the editor.
23. In the Timeline tab that appears, click on the Audio Track context menu icon and select Delete.

Play the game once more. No audio should be heard and no warnings should appear in the Log tab.

3.8 What's next?

In this guide, you’ve learnt how to add FMOD to an existing Unity game. We’ve also replaced and improved the game’s sound, making the world feel more alive.

To learn more about FMOD and Unity, see the following resources:

• Viking Village - Video Tutorial Series
• Survival Shooter - Video Tutorial Series
• FMOD Studio - User Manual