"–Reality is merely an illusion; albeit a very persistent one."

January 4, 2018January 18, 2019

UE4 SPB Sound Occlusion (Programming)

WHAT

SPB Sound Occlusion is a plugin for Unreal Engine 4 that implements a complex sound occlusion function in C++ which generates real-time collisions from line traces to physical bodies then calculates volume and pitch variations to the audio source relative to the listener’s position.
The function takes into consideration the physical material attached to the render material used by the shapes the audio source’s traces hit as well as how much direct sound the listener receives to finally calculate the volume output an audio source should play.
Each audio source traces its own path to the listener and multiple collision channels can be traced at the same time.
Any kind of physical body is supported: Static meshes, dynamic meshes, characters, physics volumes and etc, all can be traced against an audio source depending on collision channel settings.
Many occlusion presets for physical materials are included to streamline workflow when creating occlusion effects; For wood, metal, plastic, concrete, so on and so forth.

HOW TO USE

Physical Material Setup:

First we need a physical material to be attached to render material of a mesh we wish audio occlusion to consider.
To do this, on the asset browser select or create a new physical material used by the mesh:

Now on Project Settings panel, look for “Sound Occlusion” and the SPB plugin settings will show up in the panel. There are several Material Presets;
Click on the “Physical Materials” list on the top of the panel to register the Material you’ve created earlier:

Because “concrete” is a preset, the plugin will automatically assign ‘concrete’ values to your physical materials, if you name them with that word, when you pick it from the drop-down list.
If you wish to just use your own custom values for this particular occlusion material, just keep the “override” checkbox active and you will be able to edit all values:

Then on your render material, base or instance of a material, open it up with Unreal’s Material Editor and set its “Phys Material” to the physical material you have assigned as “concrete” in Project Settings panel.
After that any meshes using such material will react to the occlusion system accordingly with the values of that material we’ve set previously:

Listener Component Setup:

Now, we need to setup a Listener Component, usually attached to the main Character so this is the focus of this example.
Open the Character Blueprint and from the “+Add Component” button add a “SPB Listener” Component attached to the Capsule Component.
Done that you can click the newly created “SPB Listener” Component to check it’s properties.
On the SPB section of properties there’s a checkbox “Is Player Listener”, in this case we want it set to true because then the plugin will automatically override the origin point of audio spatialization to match the location of our SPB Listener in the game world:

After we’re happy with local position of our SPB Listener Component, relative to the Character’s Capsule Component, the Listener needs two complementary elements; add twice an “LLR Component” to the Character Blueprint… Then an important step that can’t be missed: click the LLR Components and drag them to be children of the SPB Listener Component.
By dragging the LLR Components into the SPB Listener, they are registered as children and from there in C++ land the Listener does some voodoo to keep track of them when we actually run the game. So, again, this is important! Attach LLR Components to SPB Listener, two of them, no more no less!
If you did this right, your Character Blueprint would now look like this:

I should highlight that in big red text, but I really want you to read the whole guide instead of dragging your attention to bold areas of the text while you miss the rest 🙂

Speaker Component Setup:

So the only step missing now is actually creating our SPB Cue or adding an SPB Speaker Component to some Actor that we want to emit sounds and be occluded by the line tracing system.
You will notice that this look alike the default Audio Component, but in this case with an SPB section on its properties:

After we created the SPB Speaker Component and attached to our mesh, just like the process with the Listener, we need two sub-components attached to the Speaker; But this time we need “CLR Component”.
We add twice a CLR Component then drag it as a child of the SPB Speaker Component, if you did it right then when you check the properties panel of a Speaker in the Level you should see that the “None” values for “CL Component” and “CR Component” are now updated to reflect the fact that the plugin, in C++ land, have registered the newly created CLR Components and now they have their properties exposed to the SPB Speaker Component:

Now, by default the Speaker will trace for occlusion on the “World Static” and “World Dynamic” collision channels.
You can edit this list at will, remove or add channels to fit your project accordingly; for maximized performance is good to trace only one channel, the more channels your SPB Speaker traces the more performance impact is caused.
Still, I believe there’s no need to stress too much about it, the heavy code is all executed entirely in C++ so it’s very very fast even while running line traces for hundreds of Speakers on the same Level:

So, done the steps above, the occlusion is ready and you can play-test it! If you click the “Debug” checkbox will can see some of the calculations while ‘Playing in Editor’.
The other settings are very intuitive to use and have detailed tooltips on what they do. Later on I will explain what are “SPB Gates” and what they do, enjoy! Cheers!

(UPDATE) Common Mistakes:

This plugin has been live for a while now and many developers use it daily.
From time to time new developers seem to get confused by a few common mistakes I want to outline here in hopes for these occurrences to disappear. There are usually these few common complaints I receive from new users:

#1: “I have followed all steps, but there’s no rays following my character!”A: What happens is you actually forgot to mark your Listener as ‘Player’. This mistake is so common that I have decided to push an update and make this setting be marked by default when a new Listener Component is created…

#2: “For some reason it still doesn’t work!”A: You don’t have a Game Mode set in your level. SPB Listener accesses variables from your Character that are members of Player Controller class, spawned by your Game Mode class. When you do not properly setup a Game Mode for your Map/Level, SPB cannot find the Spatialization component stored in the Player Controller class…

#3: “Still nothing… I can’t see anything happening *angry face*”A: If your Speaker is using attenuation settings you have to make sure the falloff area is large enough for the player with a Listener attached to move in. When attenuation is activated on the Speaker, it will only trace occlusion until the limits of the falloff area, once the Listener leaves its area the Speaker stops tracing occlusion against that Listener.

#4: “But I disabled attenuation or increased falloff distance and still doesn’t work!”A: In this case one or more of the following things are wrong in your setup:

Your components are not activated.

Your Speaker has no sound to play.

Your Speaker has volume set to zero.

Your list of channels to trace is empty.

Your Speaker isn’t debugging or is marked with ‘No Trace’.

Make sure you have those mistakes above fixed and everything will work correctly.