FMOD Studio Unity Integration

Introduction
TheFMODStudioUnityintegrationprovidesastreamlinedworkflowforUnitydevelopersto
createhighqualitygameaudiofortheirgames.Theintegrationisprovidedasa.unitypackage
availablefromtheFMODdownloadspage.Thisdocumentexplainsthevariouscomponentsof
theintegration.FormoreinformationvisittheFMODStudioUnityIntegrationforum.
Supported platforms
ThecurrentintegrationsupportsiOS,Android,PCandMac.TheUnitywebplayerisnot
supported,asitdoesnotprovidethenativepluginsupportthattheintegrationrequires.
Licensing
Theintegrationitselfisfree,butyoumusthavetheappropriateFMODLicensetoreleaseatitle
usingFMODStudiowithUnity,asitisnotcoveredbytheUnitylicensealone.Formore
informationaboutlicensingFMODseetheFMODsalespage.TheFMODStudiointegrationisa
nativepluginwhichisavailableinthefreeiOS/AndroidUnitylicensebutrequiresProforPCand
Mac.
Contents
Thissectiondescribesthecontentsoftheintegrationpackage.
Example Scripts
foundinAssets/Plugins/FMOD
TheintegrationpackageincludesscriptswhichdemonstrateusageoftheFMODStudioAPI.you
canusethesescriptsandextendthem,orwriteyourownusingtheC#APIdirectly.Abrief
descriptionofeachoftheexamplescriptsislistedbelow.
FMOD_Listener
Attachthistothecamerainthescene.(thereshouldonlybeonelistener)
FMOD_StudioEventEmitter
Controlstheplaybackofoneevent,usethistoattacheventstoobjectsinsideUnity.Thisismost
suitedtoendlesseventswhichplayforalongtime.Forshortoneshotstyleeventstheycanbe
firedofffromscriptsusingtheFMOD_StudioSystem.
FMOD_StudioSystem
Note:Thisisinternal,don'tattachittoanyobjects
Thisisthecentralsystemwhichcanbeusedtoloadbanksandretrieveevents.Ithassome
conveniencefunctionsthatdemonstrateusageoftheFMODStudioAPI.Itisasingletonsothere
isonlyeveroneofthese,itwillgetcreatedautomatically,youcanaccessitbycalling
FMOD_StudioSystem.instance.
FMOD Studio Runtime C# API
foundinAssets/Plugins/FMOD/Wrapper
ThisistheFMODStudioC#API.ThewrapperexposesthesamefunctionsavailableintheC++
APIforuseinsideUnity.FormoreinformationpleaserefertotheprogrammerAPIdocumenation
thatcomeswiththeFMODStudioAPIinstaller.
FMODStudioAPIusage
ThecontentcreatedinFMODStudioisexportedinto.bankfiles.Thesefilescontaintheencoded
audiodata,aswellasthemetadataforplayback.TheyareloadedasloosefilesusingtheAPI
(System.loadBankFile).TheeventsareretrievedusingGUIDs(System.parseID)orpaths
(System.lookupID).ThesefunctionsprovideanIDwhichcanbeusedtoretrievethe
EventDescription,whichisthenusedtocreateEventInstances.Eventplaybackiscontrolled
usingtheEventInstance.
Setting up the integration
1.Importtheintegrationunitypackage.
2.AddtheFMOD_ListenerscripttotheMainCamera.
Importing .bank files into Unity
InsideFMODStudio:
1.AssignyourEventstobanks.
2.Buildallbanks.(File>Build...)
3.ExportGUIDs.txt.(File>ExportGUIDs...)
InsideUnity:
4.FMOD>RefreshEventList
selecttheGUIDs.txtgeneratedfromthepreviousstep(insidethe/BuildsfolderofyourFMOD
Studioproject)
TheGUIDs.txtisatextfilewhichdescribesalloftheeventsintheFMODStudioproject.The
RefreshEventliststepwillcopythe.bankfilesfromtheFMODStudioprojecttotheUnity
project'sAssets/StreamingAssetsdirectory.ThenitwillcreatetheAssets/FMODAssets
directoryandpopulateitwitheventassetsforeacheventintheFMODStudioproject.
Playing an event inside Unity
1.AddFMOD_StudioEventEmitterscripttoanobjectinthescene.
2.LocatetheeventyouwanttoplayinsideAssets/FMODAssetsandassignittothe
FMOD_StudioEventEmitter.
Scripting
FMOD_StudioSystemcontainssomeconveniencefunctionswhichmakeiteasytocontrol
eventsfromyourUnityscripts.
ThefollowingexamplesdemonstrateusingtheAPIwithC#butareapplicabletotheother
scriptinglanguagesavailableinUnity.
PlayOneShotfireandforgetoneshotevents.Goodforshortsoundslikefootstepsand
gunshots
example:playagunshotsoundatthecurrentposition
FMOD_StudioSystem.instance.PlayOneShot(/Weapons/SingleShot,
transform.position)
GetEventretrieveaneventthiscanbeusedwhenyouwantmorecontrol,suchasmodifying
thegameparameters.
example:getanengineeventandupdatetheRPMparametereachframe
FMOD.Studio.EventInstanceengine
FMOD.Studio.ParameterInstanceengineRPM
voidStart()
{
engine=FMOD_StudioSystem.instance.getEvent("/Vehicles/CarEngine")
engine.start()
engine.getParameter("RPM",outengineRPM)
}
voidUpdate()
{
//getaRPMvaluefromthegame'scarengine
engineRPM.setValue(rpm)
}
voidOnDisable()
{
engine.stop()
engine.release()
}
Note:Whencontrollingtheeventinstanceincode,youmustcallreleasewhenyouarefinishedwithitto
ensuretheresourcesarecleanedup.
Loading Plugin Effects and Plugin Instruments
Note:Importingbanksusingpluginsmightfailwithintegrationversion1.02.09orearlier.Justchange
FMOD.Studio.INITFLAGS.NORMALtoFMOD.Studio.INITFLAGS.ALLOW_MISSING_PLUGINSin
FMODEditorExtension.cs.
TheFMODPluginEffectslikeDistanceFilterandGainarefree,thethirdpartyeffectslikethe
ML1LimiterandAudioWeatherhavetobelicensedseparately.Thereislicensinginformation
availableontheFMODsalespage.
ToloadthepluginsusingUnityyouaddtheplugintotheFMOD_Listener'spluginlist.Thenjust
copythepluginfileintoappropriatesubdirectoryoftheAssets/Pluginsdirectory(insideyourUnity
project)fortheplatformyouaretargeting.ForWindows32bititwouldbe/Assets/Plugins/x86.
Thedirectoryforeachplatformislistedhere.
TogetthefreeFMODplugins,youcancopythefilesinsidethe/PluginsdirectorywhereFMOD
Studioisinstalled.
Configuration Options
Note:Onlyavailableinversion1.3ornewer
Thereareoptionsfeatureswhichcanbeenabledwhichcanhelpduringdevelopment.These
optionsareusefulduringdevelopment.Toenabletheseaddthespecifiedkeywordtothe
ScriptingDefineSymbols,insideUnityPlayerSettings(Edit>ProjectSettings>Player)
Connecting to the tool with Live Update
Option:FMOD_LIVEUPDATE
LiveUpdateallowsyoutomakechangesinsideFMODStudiohavehavethemmirroredonthe
gameside.Thisisparticularlyusefulformixingandtweakingattenuationcurves.
1.AddFMOD_LIVEUPDATEtotheScriptingDefineSymbolsinyourUnityproject.
ThiswillenableStudiotoconnecttoUnitywhilethegameisrunning.
2.Startrunningthegame,eitherbybuildingandexecutingonthetargetdevice,orbyrunningthe
gameinsidetheUnityeditor.
3.InsideFMODStudioopenuptheConnecttoGamedialog(File>ConnecttoGame)
4.EntertheIPaddressofthetargetdevicewhichisrunninggame(ifitisrunningonthesame
machineasFMODStudioyoujustenterlocalhostor127.0.0.1)
StudioshouldnowbeconnectedtothegameandmodificationsmadeinStudiowillbemirrored
aslongasthegameisrunning.
Note:WhenthegamestopsallofthechangesmadeviaLiveUpdatewillbelost,atthatpointitisadvised
torebuildthebanksandimportthemintoUnitytokeepeverythinginsync.
Additional Debug information
Option:FMOD_DEBUG
ThiswillprintadditionalinformationtotheUnityconsoletohelpdiagnoseissuesifsomethinghas
gonewrongwiththeintegration.