FMOD Studio Unity IntegrationIntroduction

TheFMODStudioUnityintegrationprovidesastreamlinedworkflowforUnitydeveloperstocreatehighqualitygameaudiofortheirgames.Theintegrationisprovidedasa.unitypackageavailablefromtheFMODdownloadspage.Thisdocumentexplainsthevariouscomponentsoftheintegration.FormoreinformationvisittheFMODStudioUnityIntegrationforum.

Supported platformsThecurrentintegrationsupportsiOS,Android,PCandMac.TheUnitywebplayerisnotsupported,asitdoesnotprovidethenativepluginsupportthattheintegrationrequires.

LicensingTheintegrationitselfisfree,butyoumusthavetheappropriateFMODLicensetoreleaseatitleusingFMODStudiowithUnity,asitisnotcoveredbytheUnitylicensealone.FormoreinformationaboutlicensingFMODseetheFMODsalespage.TheFMODStudiointegrationisanativepluginwhichisavailableinthefreeiOS/AndroidUnitylicensebutrequiresProforPCandMac.

ContentsThissectiondescribesthecontentsoftheintegrationpackage.

Example ScriptsfoundinAssets/Plugins/FMOD

TheintegrationpackageincludesscriptswhichdemonstrateusageoftheFMODStudioAPI.youcanusethesescriptsandextendthem,orwriteyourownusingtheC#APIdirectly.Abriefdescriptionofeachoftheexamplescriptsislistedbelow.

FMOD_ListenerAttachthistothecamerainthescene.(thereshouldonlybeonelistener)

FMOD_StudioEventEmitterControlstheplaybackofoneevent,usethistoattacheventstoobjectsinsideUnity.Thisismostsuitedtoendlesseventswhichplayforalongtime.ForshortoneshotstyleeventstheycanbefiredofffromscriptsusingtheFMOD_StudioSystem.

FMOD_StudioSystemNote:Thisisinternal,don'tattachittoanyobjects

Thisisthecentralsystemwhichcanbeusedtoloadbanksandretrieveevents.IthassomeconveniencefunctionsthatdemonstrateusageoftheFMODStudioAPI.Itisasingletonsothereisonlyeveroneofthese,itwillgetcreatedautomatically,youcanaccessitbycallingFMOD_StudioSystem.instance.

FMOD Studio Runtime C# APIfoundinAssets/Plugins/FMOD/Wrapper

ThisistheFMODStudioC#API.ThewrapperexposesthesamefunctionsavailableintheC++APIforuseinsideUnity.FormoreinformationpleaserefertotheprogrammerAPIdocumenationthatcomeswiththeFMODStudioAPIinstaller.

FMODStudioAPIusage

ThecontentcreatedinFMODStudioisexportedinto.bankfiles.Thesefilescontaintheencodedaudiodata,aswellasthemetadataforplayback.TheyareloadedasloosefilesusingtheAPI(System.loadBankFile).TheeventsareretrievedusingGUIDs(System.parseID)orpaths(System.lookupID).ThesefunctionsprovideanIDwhichcanbeusedtoretrievetheEventDescription,whichisthenusedtocreateEventInstances.EventplaybackiscontrolledusingtheEventInstance.

Setting up the integration1.Importtheintegrationunitypackage.

2.AddtheFMOD_ListenerscripttotheMainCamera.

Importing .bank files into Unity

InsideFMODStudio:

1.AssignyourEventstobanks.

2.Buildallbanks.(File>Build...)

3.ExportGUIDs.txt.(File>ExportGUIDs...)

InsideUnity:

4.FMOD>RefreshEventListselecttheGUIDs.txtgeneratedfromthepreviousstep(insidethe/BuildsfolderofyourFMODStudioproject)

TheGUIDs.txtisatextfilewhichdescribesalloftheeventsintheFMODStudioproject.TheRefreshEventliststepwillcopythe.bankfilesfromtheFMODStudioprojecttotheUnityproject'sAssets/StreamingAssetsdirectory.ThenitwillcreatetheAssets/FMODAssetsdirectoryandpopulateitwitheventassetsforeacheventintheFMODStudioproject.

Playing an event inside Unity1.AddFMOD_StudioEventEmitterscripttoanobjectinthescene.

2.LocatetheeventyouwanttoplayinsideAssets/FMODAssetsandassignittotheFMOD_StudioEventEmitter.

ScriptingFMOD_StudioSystemcontainssomeconveniencefunctionswhichmakeiteasytocontroleventsfromyourUnityscripts.

ThefollowingexamplesdemonstrateusingtheAPIwithC#butareapplicabletotheotherscriptinglanguagesavailableinUnity.PlayOneShotfireandforgetoneshotevents.Goodforshortsoundslikefootstepsandgunshots

example:playagunshotsoundatthecurrentposition

FMOD_StudioSystem.instance.PlayOneShot(/Weapons/SingleShot,transform.position)

GetEventretrieveaneventthiscanbeusedwhenyouwantmorecontrol,suchasmodifyingthegameparameters.

example:getanengineeventandupdatetheRPMparametereachframe

FMOD.Studio.EventInstanceengineFMOD.Studio.ParameterInstanceengineRPM

voidStart(){engine=FMOD_StudioSystem.instance.getEvent("/Vehicles/CarEngine")engine.start()engine.getParameter("RPM",outengineRPM)}

voidUpdate(){//getaRPMvaluefromthegame'scarengineengineRPM.setValue(rpm)}

voidOnDisable(){engine.stop()engine.release()}

Note:Whencontrollingtheeventinstanceincode,youmustcallreleasewhenyouarefinishedwithitto

ensuretheresourcesarecleanedup.

Loading Plugin Effects and Plugin InstrumentsNote:Importingbanksusingpluginsmightfailwithintegrationversion1.02.09orearlier.JustchangeFMOD.Studio.INITFLAGS.NORMALtoFMOD.Studio.INITFLAGS.ALLOW_MISSING_PLUGINSinFMODEditorExtension.cs.

TheFMODPluginEffectslikeDistanceFilterandGainarefree,thethirdpartyeffectsliketheML1LimiterandAudioWeatherhavetobelicensedseparately.ThereislicensinginformationavailableontheFMODsalespage.

ToloadthepluginsusingUnityyouaddtheplugintotheFMOD_Listener'spluginlist.ThenjustcopythepluginfileintoappropriatesubdirectoryoftheAssets/Pluginsdirectory(insideyourUnityproject)fortheplatformyouaretargeting.ForWindows32bititwouldbe/Assets/Plugins/x86.Thedirectoryforeachplatformislistedhere.

TogetthefreeFMODplugins,youcancopythefilesinsidethe/PluginsdirectorywhereFMODStudioisinstalled.

Configuration OptionsNote:Onlyavailableinversion1.3ornewer

Thereareoptionsfeatureswhichcanbeenabledwhichcanhelpduringdevelopment.Theseoptionsareusefulduringdevelopment.ToenabletheseaddthespecifiedkeywordtotheScriptingDefineSymbols,insideUnityPlayerSettings(Edit>ProjectSettings>Player)

Connecting to the tool with Live UpdateOption:FMOD_LIVEUPDATE

LiveUpdateallowsyoutomakechangesinsideFMODStudiohavehavethemmirroredonthegameside.Thisisparticularlyusefulformixingandtweakingattenuationcurves.

1.AddFMOD_LIVEUPDATEtotheScriptingDefineSymbolsinyourUnityproject.

ThiswillenableStudiotoconnecttoUnitywhilethegameisrunning.

2.Startrunningthegame,eitherbybuildingandexecutingonthetargetdevice,orbyrunningthegameinsidetheUnityeditor.

3.InsideFMODStudioopenuptheConnecttoGamedialog(File>ConnecttoGame)

4.EntertheIPaddressofthetargetdevicewhichisrunninggame(ifitisrunningonthesamemachineasFMODStudioyoujustenterlocalhostor127.0.0.1)

StudioshouldnowbeconnectedtothegameandmodificationsmadeinStudiowillbemirroredaslongasthegameisrunning.

Note:WhenthegamestopsallofthechangesmadeviaLiveUpdatewillbelost,atthatpointitisadvisedtorebuildthebanksandimportthemintoUnitytokeepeverythinginsync.

Additional Debug informationOption:FMOD_DEBUG

ThiswillprintadditionalinformationtotheUnityconsoletohelpdiagnoseissuesifsomethinghasgonewrongwiththeintegration.