Can you please update your Unity docs to make these things more clear? I’ve wasted many days over these many months reading and rereading them trying to figure out stuff that simply isn’t there. Internet searches haven’t helped much either. Only searching this forum with magic keywords can one find hints to correct the misleading docs.
The FMOD Unity docs imply that all events and their parameters can be handled through the Studio Event Emitter component (which is somewhat true). But the docs also imply that the parameters on these emitters can also be controlled in script. This, apparently, is SO VERY NOT TRUE! Nowhere on the “Triggering Parameter Changes” doc page does it say that this technique only applies to NON-oneshot events: https://www.fmod.com/resources/documentation-api?page=content/generated/engine_new_unity/paramtrigger.html
Heck, it’s not even clear, coming in as a noob to FMOD, what this Oneshot attribute is even about since you can’t set it or see it anywhere in FMOD Studio (that I can find). Even more confusing for me was that the first Oneshot event I set up through an emitter, and use emitter.SetParameter() with, somehow occasionally produces one of the alternate sounds only available by scripted parameter setting (perhaps through two back-to-back events, dunno). Thus, I thought I had this whole FMOD thing down. But, when I came back sometime later and tried to add other parameterized events, I couldn’t get them to work. I tried every configuration of events and component settings I could think of. I couldn’t isolate the trouble to report it because the engine and tire parameters were working fine and likewise, it seemed, the crash parameter was working too. It took far too much time to go back and discover that the Oneshot event for crash sounds wasn’t really responding as well to the parameter changes as I had first thought.
After some hacking I found I COULD set parameters for these unwieldy emitters with this workaround:
Eventually, I came back to the “Scripting API” and “Scripting Example Basic” docs for the umpteenth time and dug through the code more because they mentioned parameters. Ahah! Something referred to as “oneshots” can’t have parameters set except by what looks like way too many setup statements in code.
So, now I’m wondering which is better and why? Not much help there either that I can find. The emitter components and hacking the Params[].Value? Or, scripting with FMOD.Studio.EventInstance blah blah blah? I’m expecting the answer will be to not use the emitter components with parameterized oneshots… So why, then, use emitter components at all if they are so limited to specific and secret use cases? Why even use them with non-oneshots if you’re going to have to script the other way too? I wish your docs had directed me that way up front.
It’s really hard to recommend FMOD to the other guild members with so much lacking in the documentation. And I haven’t even gotten to my other questions yet (such as best practice for pausing gameplay events for menu events and what the heck this pretty-much-nowhere-mentioned “IngamePause” snapshot thing is about, and why I can’t seem to stop all emitters instantly when destroying all objects and unloading the scene). Ugh. This seems to be a great tool but trying to understand has been maddening at times. Even the Studio also has many things buried in obscure places that I can’t find in the studio documentation. It feels like the intent of FMOD is to keep noobs out. I apologize if I came off as too harsh here – just really frustrated with the difficulties of learning this tool versus most other tools when it feels like it shouldn’t have been as difficult as it has been.
The FMOD Unity docs imply that all events and their parameters can be handled through the Studio Event Emitter component (which is somewhat true).
But the docs also imply that the parameters on these emitters can also be controlled in script.
This, apparently, is SO VERY NOT TRUE! Nowhere on the “Triggering Parameter Changes” doc page does it say that this technique only applies to NON-oneshot events:
The only time this won’t work, is when the emitters event instance has been released and/or recycled. There may be another issue if this isn’t working, check the fmod.log or fmod_editor.log for more logging.
In the case of the StudioEventEmitter script, if you play a one-shot event a second time, the first instance handle is reused for the second event because it can be released before it finishes and it will gte cleaned up when it ends naturally.
Heck, it’s not even clear, coming in as a noob to FMOD, what this Oneshot attribute is even about since you can’t set it or see it anywhere in FMOD Studio (that I can find).
Even more confusing for me was that the first Oneshot event I set up through an emitter, and use emitter.SetParameter() with, somehow occasionally produces one of the alternate sounds only available by scripted parameter setting (perhaps through two back-to-back events, dunno).
//emitter.SetParameter("Size", size);
/*HACK*/emitter.Params[0].Value = size;
emitter.Play();
but that feels hacky so I kept looking.
The list of parameters (Params) inside the emitter is only set when the emitter is started.
But before calling Play, the emitters event instance will be NULL, this would cause the SetParameter call to fail.
The emitter component is generally used in editor, which has options for setting initial parameter values.
Eventually, I came back to the “Scripting API” and “Scripting Example Basic” docs for the umpteenth time and dug through the code more because they mentioned parameters.
Ahah! Something referred to as “oneshots” can’t have parameters set except by what looks like way too many setup statements in code.
The ‘one-shot’ in this case is being used as a fire-and-forget event. Which means you start the event and immediately release the instance (this clears the handle that is normally used for setting parameters).
So, now I’m wondering which is better and why? Not much help there either that I can find. The emitter components and hacking the Params[].Value? Or, scripting with FMOD.Studio.EventInstance blah blah blah?
I’m expecting the answer will be to not use the emitter components with parameterized oneshots… So why, then, use emitter components at all if they are so limited to specific and secret use cases?
Why even use them with non-oneshots if you’re going to have to script the other way too? I wish your docs had directed me that way up front.
Emitter components can be used with all types of events. If you aren’t triggering the events using the Play and Stop events on the emitter then you are probably best using your own scripts.
All you need to do to create and start an event is:
FMOD.Studio.EventInstance instance = FMODUnity.RuntimeManager.CreateInstance(EventName);
instance.start();
Now you have a handle to your own event instance that you can set parameters on as you wish, using instance.SetParameterValue. Now you are directly accessing the FMOD Studio API. https://fmod.com/resources/documentation-api?page=content/generated/studio_api_EventInstance.html#/
Our C# wrapper is made to be a straight 1 to 1 wrapper for our API’s, as well as having some helper functions.
It’s really hard to recommend FMOD to the other guild members with so much lacking in the documentation.
And I haven’t even gotten to my other questions yet (such as best practice for pausing gameplay events for menu events and what the heck this pretty-much-nowhere-mentioned “IngamePause” snapshot thing is about, and why I can’t seem to stop all emitters instantly when destroying all objects and unloading the scene).
Hi Cameron, Thank you for the thorough response. I’m aware of much of this already – I had oneshot events working with parameters in two different ways before posting: by pure script and by hacked emitter component. This is why my complaints are mostly about the documentation. To put some context behind this, I’m working on a fairly complex 2D physics environment and am designing a somewhat deep audio environment to go with it. http://gritsracing.com Thus, simple, preset triggers are not a possibility. So I searched for a better audio engine and found FMOD.
You appear to contradict yourself on how SetParameter should work. I said “But the docs also imply that the parameters on these emitters can also be controlled in script.” And you said this should work. It doesn’t on oneshots (as I pointed out just after that statement), and there are no error messages in the logs over it. Then, you say “But before calling Play, the emitters event instance will be NULL, this would cause the SetParameter call to fail.” So, you then just admitted SetParameter shouldn’t work on oneshots. So, which is it? This is the same confusion as with the docs, which say this “If you wish to trigger parameter changes from code set the option to None. Then in a script attached to the same Game Object add the line GetComponent<FMODUnity.StudioParameterTrigger>().TriggerParameters();” But no warning about oneshots not working there.
So, from my point of view as a new user, SetParameter simply doesn’t work the same with all emitters with parameters, does it? And not explaining that – and the other pros and cons of scripting versus components – up front, to help us decide which way to go with our project from the start, has been a huge time sink.
Or, if there is some secret way to get SetParameter to work with oneshots, then there should be some instructions on how to do it. What the docs give only works with looping events. I’ve tried all the permutations of various parameter settings on components and the various ways of using parameters in Studio that I can find and have had no success. I split out events to individual components just to see if there was a conflict with the looping events. I even tried the Hand Foley events in the FMOD example project with no success. They all respond to changing the parameter value manually on the component when the game is running in Unity, but they won’t respond to SetParameter in script like the looping events do. And, yet, they all respond to the emitter.Params[0].Value hack, so I’m pretty confident they are wired up correctly (that hack, BTW, for anyone else reading, requires Initial Parameter Values to be set in the component first).
It wasn’t until last week when I read your response to this other question that I got a clue that SetParameter isn’t meant to work on oneshots: Set parameter to specific value not working - Unity - FMOD Forums . That person had other issues with their code but your response made it clear that oneshots need more help with parameter setting than is made apparent by the Getting Started guide and the Studio docs (this is somewhat apparent in your API docs but nothing else was cluing me into reading those more thoroughly). Thus, I could only assume that if PlayOneShot isn’t meant to respond to SetParameterValue (which is not terribly intuitive given the workflow in Studio), then emitter components perhaps are not meant to respond to SetParameter. But, again, nowhere is this clear. And now it’s even less clear with your contradictions. And that pretty much answers the header question. It’s a muddy design that will always end in a muddy explanation.
So, please, get someone to rewrite the Getting Started guide and the Triggering Parameter Changes page to help us out a bit here. Provide some explanation of the pros and cons and limitations of scripting vs componenents, and explain why the oneshot attribute and the oneshot limitations with parameters matters so much when deciding which way to go. And, if there is some secret way to get SetParameter to work with emitter components containing oneshots, add that too.
I feel like there is too much focus on the term ‘OneShot’ at the moment.
In Studio an event can be a ‘OneShot’ if it ends naturally.
In code a ‘OneShot’ that is determined by how it is created/played/destroyed, more of a ‘fire-and-forget’ type of sound.
StudioEventEmitter components treat all events the same, the only difference is when Play() gets called a second time on the emitter component.
If the event was deemed to be OneShot from Studio, then the FMOD::Studio::EventInstance gets released and the handle cleared before creating a new one, allowing the event to play out.
This means that you no longer have a handle to that instance and cannot effect it in any way now.
If the event is not deemed to be OneShot, then the FMOD::Studio::EventInstance gets reused, causing the event to start again.
In code a ‘fire-and-forget’ is an event that is created, starts, released immediately.
This will immediately spawn an instance the given event, the instance will play to completion. Parameters cannot be set.
This is generally used for short sounds that you want to play out no matter what, and don’t need any parameter changes.
These can also be created using RuntimeManager functions: PlayOneShot & PlayOneShotAttached. https://fmod.com/resources/documentation-api?page=content/generated/engine_new_unity/scripting.html#/
StudioEventEmitters don’t create a valid FMOD::Studio::EventInstance until Play() is called, and you need a valid FMOD::Studio::EventInstance to call SetParameterValue.
Our wrapper function for StudioEventEmitter::SetParameter is very thin, and only checks that the FMOD::Studio::EventInstance is valid before trying to use FMOD::Studio::EventInstance::setParameterValue().
The Triggering Parameter Changes page isn’t overly clear about it, but the component it is referring to is the StudioParameterTrigger which works by referencing the StudioEventEmitter to update the parameters.
If you would like to share some screenshots or code snippets, it might also help me to understand how you are wanting to use the integration.
Sorry, I got distracted by other parts of the project for a while there and, apparently, this forum doesn’t send email notifications for comments.
If you feel like too much focus is on the term “Oneshot” at the moment, then you are completely missing my primary point. My point is pretty much entirely that the docs are not paying enough attention to it and how setting up parameterized oneshots events in Studio (just like FMOD’s own examples with hand foleys and explosions) should affect our development choices.
Instead, you keep repeatedly explaining things I had pretty much already figured out the hard way before my first post. Thus, I’m left scratching my head as how I’m not communicating effectively that the entirety of FMOD’s examples and docs are misleading as to how use parameterized oneshot events in our projects. After all, the header question here is: “Why are the docs so muddy about parameters on Oneshot events?”
Perhaps if I had grown up using the FMOD API before jumping into the latest FMOD+Unity tech, I could see what is written between the lines in the docs. But I haven’t, so I can’t. All I can say is that your examples and your docs have done me no favors regarding oneshot events (which strangely respond to SetParameter on rare occasion, just to confuse things more), and that I’m still not finding the guidance I’m looking for as to best practices with oneshots that use parameters to play different sounds.
It’s a muddy design that will always end in a muddy explanation.
Point taken. We’re planning to revisit the design and improve our docs accordingly. But, for now, if you have any specific implementation questions, send us your project, explain what you’re trying to do and we’ll do our best to help you out.
Thanks, Andrew. It really was my intent to try to help by trying to explain the unusually confusing journey I’ve been on with FMOD. Otherwise, I wouldn’t have taken all this time to write all this, and would have used that time to instead rip out FMOD and put in another tool – which is tempting since I now have to rebuild much of my sound rigging anyhow (which is not that much yet).
And, yes, when I get to my technical questions that are still lingering in my project, I’ll be more direct about it in another post.
We are currently evaluating Wwise and started looking into FMOD reviews which mention problems with “parameterized one-shot events through FMOD’s Unity components”. While researching the issue google landed me here.
As a potential customer I’d like to gauge FMOD’s reaction time, does anyone know if anything has been done about these problems in the past two years?
Have been using the integration for a year, honestly I think these are non-issues. Most of the time, you won’t even need the Event Emitter if you aren’t triggering events by using the Play and Stop callbacks and managing instances yourself is just as easy as writing 3-4 lines of code. If you need to play an event as an one-shot sound (which really just means that the sound or rather instance will end naturally, releasing from memory after finishing playing) with a parameter set up beforehand you can manage the creation and playback of the event instance yourself or you can very easily overload the PlayOneShot or PlayOneShotAttached helper methods in the source (takes literally one minute) to make this happen.
:stopAllEvents.