Pepper.SFX

Features

Occlusion

Sounds behind walls and cover get quieter and duller, softened at the edges and free of clicks, switched on per sound with one checkbox.

A gunshot on the other side of a wall should sound dull and distant, not as if it went off beside the player. Pepper.SFX muffles 3D sounds when walls, cover or props stand between them and the listener. You tick Use Occlusion on a sound’s container, and Pepper casts the rays and drives the filter.

How it works

  • Every Occlusion Update Interval (0.2 s by default), the Audio Manager casts rays from the listening point to each occluded sound, against the layers in Occlusion Mask. Trigger colliders are ignored, and so are the sound’s own object and the player.
  • Occlusion Ray Count (3 by default) fans the rays across the source, Occlusion Ray Spread Meters wide. A partly hidden sound is partly muffled, so walking past the edge of a wall gives a gradient rather than a jump. Set it to 1 for a hard edge.
  • Fully blocked, a sound drops by about 10 dB and a low-pass filter takes off its top end. Level and cutoff glide to their targets every frame, so nothing steps.
  • The filter doesn’t sit on the AudioSource: a filter component resets each time the voice pool reuses a source, and that clicks. Instead Pepper builds an occlusion mixer slot pool, a set of mixer groups under each bus (six by default), each with a Lowpass effect. A voice borrows a slot before it starts and returns it when it ends, and Pepper writes the cutoff to the slot’s exposed mixer parameter.
  • The same slots carry per-zone reverb sends (Allow Reverb Send) and muffling through doors (Use Propagation), so this setup is the groundwork for both.

Example

Occlusion needs no code. This turret posts its shot as usual, and shows how many of the Weapons bus’s slots are in use, to help you size Slots Per Bus.

using UnityEngine;
using UnityEngine.Audio;
using AudioSystem;

public class Turret : MonoBehaviour
{
    [SerializeField] private AudioEvent fireEvent;        // its container has Use Occlusion ticked
    [SerializeField] private AudioMixerGroup weaponsBus;  // the Mixer Group that container plays through

    public void Fire()
    {
        // Nothing occlusion-specific: if a wall is in the way, the shot comes out muffled.
        fireEvent.Post(gameObject, transform.position);
    }

    void OnGUI()
    {
        var manager = AudioManager.Instance;
        if (manager == null || !manager.OcclusionSlotPoolsReady)
        {
            GUILayout.Label("Occlusion slots aren't set up");
            return;
        }
        int used = manager.GetOcclusionSlotsInUse(weaponsBus);
        int total = manager.GetOcclusionSlotCapacity(weaponsBus);   // -1 if the bus isn't in the layout
        GUILayout.Label($"Weapons occlusion slots: {used} / {total}");
    }
}

Setting it up

  1. In your container, under Mixer Settings, set a Mixer Group and tick Use Occlusion. Under 3D Settings, tick Is 3D.
  2. Create > Audio System > Occlusion Layout. One per project.
  3. Open Window > Audio System > Occlusion Layout (or Open Occlusion Layout Builder on the Audio Manager). Assign your Voice Mixer and the layout asset, leave Slots Per Bus at 6 (8 to 12 for weapon-heavy scenes) and click Scan, Auto-Create, Refresh. Under each bus your occluded containers use, it builds a <Bus>_OcclusionLayer group holding <Bus>_Slot_00, <Bus>_Slot_01 and so on.
  4. On the Audio Manager, assign the same Voice Mixer and Occlusion Layout.
  5. Press Play. The Console reports “Occlusion slot pools ready” with the number of buses and slots.
  6. Tune Occlusion Ray Count, Occlusion Ray Spread Meters, Occlusion Update Interval and Occlusion Mask on the Audio Manager.

Run step 3 again when an occluded container plays through a bus that isn’t in the layout yet.

Good to know

  • Web builds: sounds get quieter behind walls but aren’t muffled, because Unity’s Web audio has no mixer effects.
  • Automatic mixer setup has only been tested on Unity 6000.0.48f1. If it fails on a newer version, click Diagnose Reflection in the window and send us the Console output.
  • No slot, no filter. A voice that gets no slot still gets quieter behind walls but isn’t filtered. If the bus’s pool ran out, the Console warns; raise Slots Per Bus and run the window again. A bus missing from the layout gives no warning. Occluded, reverb-sending and propagation voices share the same slots.
  • In a Blend or Switch Container, each child’s own Use Occlusion applies, not the parent’s.
  • Mobile: raycasts cost more on phones. If the Profiler shows it, raise Occlusion Update Interval or lower Occlusion Ray Count.
  • It isn’t a diffraction model. Sound doesn’t bend round corners; the fan of rays only softens edges.

Learn more