Occlusion Settings

Note: This feature requires Physics3d to be installed in your project. Use the Welcome Window to enable it if you haven't yet.

 
Occlusion is an optional feature that will periodically use Raycasts to check if something is blocking the Audio Source in a straight line to the Audio Listener and make it sound different if so, using a Low Pass Filter. If the Raycast hits something, then the further the hit is from the Audio Listener, the more frequencies will be filtered out. Also, any Sound Groups set to "Full 2D" using Spatial Blend Rules will be excluded from occlusion code.

Note: using occlusion will add a Low Pass Filter block to each Variation in each Sound Group that is 3D according to its Spatial Blend Rule. If you already have a Low Pass Filter there, you will not be able to use your own settings at the same time as occlusion, because the occlusion code will constantly hijack the settings based on occlusion calculations.

 

Occlusion is only used for Sound Groups and not Playlist Controller music. Here's what the Occlusion Settings panel looks like at runtime.

 
 

Controls

  • Use Occlusion: Defaults to off. Turning this on will enable occlusion and show the section above. It will be collapsed from view otherwise. Do not use occlusion if you don't need it because Raycasts definitely take some CPU to calculate, especially in large quantities and especially on mobile platforms.
    •  
  • Sound Group Usage: This controls which Sound Groups have occlusion turned on. There are two choices.
       
    • All Groups: The default choice. All Sound Groups will use occlusion (unless they are 2D as noted above).
      •  
    • Turn On Per Group: No Sound Groups will use occlusion by default. Instead, each Sound Group will have a checkbox for "Use Occlusion" that you can turn on.
    •  
  • Min/Max Occl. Cutoff Freq: These default to the Low Pass Filter's min/max frequencies of 0 and 20k. These control the min and max frequencies the Low Pass Filter will use when a RayCast from the Audio Source hits something. The actual frequency used will be calculated based on the distance the Raycast travels from the Audio Source before a hit occurs. The further it is from the Audio Listener, the more frequencies will be cut. This setting also appears on each Sound Group if you wish to override this global setting.
    •  
  • Freq. Change Time (sec): Defaults to 0. This controls how long the new target frequency from the occlusion ray cast will take to transition. During this amount of time, there will be no further ray casts or occlusion calculations.
    •  
  • Ray Cast Mode: This controls what kind of Raycasts will be used (different types only register hits with 2D or 3D colliders). There are two choices.
       
    • Physics 3D: The default. Raycasts will only detect hits with 3D colliders and triggers.
      •  
    • Physics 2D: Raycasts will only detect hits with 2D colliders and triggers.
    •  
  • Max Ray Casts Per Frame: Defaults to 4. This controls the max number of Ray Cast that will run for occlusion. The occlusion code will first check if the Audio Listener is further away than the Audio Source's Max Distance. If so, there is no need to calculate occlusion since the audio is silent at that point already.
     
  • Ray Cast Origin Offset: Defaults to 0. This setting controls the origin of each Ray Cast for occlusion. Increasing this distance will start the Ray Cast X units closer to the Audio Listener instead of exactly at the Audio Source. This setting also appears on each Sound Group if you wish to override this global setting.
     
  • Show Diagnostic Buckets: Defaults to off. When on, you will see the section "Actively Playing Sources" and its categories below. This takes extra CPU although it only runs in the Unity editor, and defaults to off. Turn it on if you need the feature for troubleshooting.
    •  
  • Show Ray Casts: Defaults to on. When on, you will be able to see brief green lines drawn for Raycasts that hit nothing, and red ones for those that get blocked. These appear in Scene view. This is great for visualization problem occlusion areas to see what's going on.
    •  
  • Use Layer Mask: Defaults to off. When on, you can choose which layers should be considered a hit for Raycasts. When off, all layers are a hit (except the special layer of "Ignore Raycasts").
    •  
  • Layer Mask: Only visible when you set Use Layer Mask to on. This is the same as the same-named field on Cameras.
    •  
  • Actively Playing Sources: Only visible during runtime and if "Show Diagnostic Buckets" is on (above), this section has 3 buttons showing helpful occlusion info. Each button can be clicked on to select (in the Hierarchy) the Audio Sources it displays the number of.
       
    1. In Range: This shows the number of Audio Sources in range (Audio Listener is within Max Distance of Audio Source). These Audio Sources will continue to have Raycasts done for occlusion calcuations.
      2.  
    2. Out of Range: This shows the number of Audio Sources out of range (Audio Listener further than Max Distance of Audio Source). These Audio Sources will not do any Raycasts until they are in range.
      3.  
    3. Occluded: This shows the number of Audio Sources where the last Raycast hit an object, so their Low Pass Filter will be set accordingly as described above.