TANKS! - Unity/FMOD Scripting Tutorial No. 1

THE BASICS

Hey everyone! I noticed when I was learning to implement FMOD events in Unity 5 that the information on the internet was a bit fragmented and required a lot of digging before I could get going properly, so I decided to make a series of short tutorials so that other people looking to learn FMOD integration in Unity 5's C# code could get to the fun stuff faster. I am by no means a proper coder, so if anyone has any more efficient ways to do the things I'm doing in this tutorial then shoot me a message and I'll amend it. However, this is the way I initially got started and allows for quick and relatively easy implementation. You can always come back and tidy up the technical details later.

First of all, you need to install Unity 5 and FMOD Studio on your computer. I'm using the Mac version of FMOD, Unity and Xamarin Studio, which I find is a slightly more responsive IDE (Integrated Development Environment) than the one that comes with Unity by default, however, for the purposes of this tutorial, MonoDevelop (Unity 5's default IDE) will work just fine! It also shouldn't matter if you're on Windows - all of the concepts and scripting will remain the same. The Tanks! project being used in this tutorial can be downloaded from the Unity 5 Asset Store here!

Once you have Unity 5 and FMOD installed, with the Tanks demo downloaded and integrated into a project in Unity (I won't go indepth as to how to do this here as there are countless other guides and tutorials), you need to integrate FMOD into Unity. To do this you need the FMOD/Unity integration plugin provided by Firelight Technologies here!

 The FMOD/Unity Integration Download on FMOD's Website

The FMOD/Unity Integration Download on FMOD's Website

Once this has finished downloading, you should end up with a .UnityPackage file. Clicking on this (whilst the Tanks project is open in Unity) will bring up this dialogue box, much the same as when you installed the Tanks demo project.

Once this is integrated, you should have a new FMOD 'dropdown' at the top of your Unity window, as shown below.

 FMOD menu dropdown added to application bar

FMOD menu dropdown added to application bar

You now need to create a new FMOD Studio project. This can be done by opening the FMOD Studio application, hitting File>New and then File>Save As. You'll also want to create a single event in FMOD Studio called "Shot", and then save again.

Then we need to return to Unity and click on FMOD>Edit Settings, and define where we saved the FMOD Studio project we just created in the Studio Project Path box in the Unity inspector.

Doing this means that whenever we build our FMOD project, the banks are loaded in Unity, allowing us to access the FMOD Project's events in C# code and the inspector.


PREPARING UNITY

Before we get into the nitty gritty, there are a few things we must make sure of before started out interactive redesign of the Unity Tanks project.

Firstly, make sure you have some audio in your FMOD "Shot" event, so that when the event is triggered, you will be able to hear the result. There are a lot of FMOD tutorials detailing how to encapsulate audio assets within events, so I won't go into that in this tutorial. Here is a useful link to Sally Kellaway's tutorial series using FMOD with Unreal Engine 4, which covers the basics of FMOD incredibly well, and its integration into UE4, arguably an easier engine to learn implementation in, which I would urge you to work through if you struggle to follow some of this tutorial.

Secondly, we will need to mute all of the original audio in the game. The easiest way to do this without chopping sections out of the code, which can also mess up the game if done incorrectly, we will simply navigate to Assets > _Completed-Assets > AudioMixers in the Unity content browser, double click on the CompletedMainMix file, and then turn all of the faders to their minimum, as shown below.

This will ensure that any audio you're hearing in the game will be your own, and coming from FMOD.

The final point to take care of before touching any code is to attach an FMOD Listener to the camera in the game. This defines where the audio engine is 'hearing' all of the FMOD events from. This is done by clicking on the 'Main Camera' in the Hierarchy window, making sure that the little triangle next to 'Camera Rig' has been expanded.

Once this has been selected, navigate over the Inspector window (right-hand side by default), click the 'Add Component' button at the bottom, and add an 'FMOD Studio Listener'.

Once all of this has been done, you're ready to press on and start poking around in the code!


IMPLEMENTING YOUR FIRST FMOD EVENT

In this tutorial we're going to be focusing on the 'Shot' sound when the shell leaves the tank's gun barrel. The script that controls this is attached to the 'CompleteTank' prefab, found in Assets > _Completed-Assets > Prefabs > CompleteTank. Clicking on this will show it in the inspector window. Scrolling down to the bottom of this window we can see the script attached to the prefab;

Click on the small icon in the top right of the script module and click 'Edit Script' This will open MonoDevelop and show the script governing the 'TankShooting' behaviour. Your inspector will still show this script as having audio files in the 'Charging Clip' and 'Fire Clip' sections, but don't worry that mine shows 'None' - that's just something I was tinkering around with, but as we've already turned down everything on the mixer, having them there won't affect what we're doing. That being said, set them to 'None' if you want to!

You will now see something that looks like this;

We need to declare all of the events that we are going to be using in this script before we go any further. I do this just below the public and private variables that you can see in the screenshot, in the public class section.

The syntax used when declaring an event is as follows;

[FMODUnity.EventRef]
public string 'EVENTNAME'Event;
FMOD.Studio.EventInstance 'EVENTNAME';

So when this is applied to our FMOD event named "Shot", it becomes this;

[FMODUnity.EventRef]
public string ShotEvent;
FMOD.Studio.EventInstance Shot;

So now the first thirty or so lines of the TankShooting script should look like this (the characters following the '//' marks are comments, used in code to detail exactly what is happening in the following lines in plain English;

Four things are needed to get an event to play in a script in Unity through FMOD Studio; we need to declare the event, tell Unity when to create an instance of the FMOD event, where to play it, and when to actually start the event. So far we have only declared our event.

Scrolling down the very bottom of the script, you will see a function marked ‘private void fire’. This is where the script tells Unity to release the shell, firing it.

In this function the programmer has entered a comment; “// Set the shell's velocity to the launch force in the fire position's forward direction.” This is where the shell is fired from the barrel of the tank. Underneath this is the original Unity audio scripting, which triggers Unity AudioClips that we have muted by turning down all of the faders in the mixer. We need to place our FMOD scripting underneath the original audio scripting, for the purposes of this tutorial. In later tutorials I may show how to completely remove any trace of the original audio from the project.

First of all, we need to create an instance of our FMOD in the script. We do this by using the line;

Shot = FMODUnity.RuntimeManager.CreateInstance(ShotEvent);

Once this event has been instanced, we need to set the ‘3D Attributes’, or put simply; how and where to instance it. Placing this line of code directly after our line that instanced the event accomplishes this. This line places the event at the location of the gameObject, this being the CompleteTank prefab.

Shot.set3DAttributes(FMODUnity.RuntimeUtils.To3DAttributes(gameObject));


There is one final thing to do in our checklist of conditions to play a sound in Unity using FMOD - tell it to start. The following line accomplishes this;

Shot.start();

And then, for debugging purposes, we will print to the console “ShotEvent” after our ‘start’ line. This is done by entering the following line;

print("ShotEvent");

This helps in the event that you do not hear your FMOD events playing. If Unity reads the code down to the print command, and prints this to the console, we know our code is ok, meaning the problem must be elsewhere!

The final script should look like this;

Screen Shot 2017-05-11 at 21.43.10.png

Before you get excited, there is one final thing that must be done. We have to tell Unity where to find the ‘Shot’ event in FMOD’s event file structure. This is done by going back to the inspector window within Unity, and looking at the newfound ‘Shot Event’ box in the TankShooting script module, clicking on the magnifying glass icon, as follows;

Screen Shot 2017-05-11 at 14.20.38.png

If you do not see your event in this dropdown box, ensure that you set the path to your FMOD project correctly in FMOD>Edit Settings, and you have saved and built your banks in FMOD (File > Build).

If you now play the game, you should hear your shot sound play when you shoot a shell! Any problems, or questions feel free to message me at joshadambell@live.com!