Skip to content

Sound Filters

Muffle, roughen and echo the game's sounds: a player hiding in a chest hears the world through its walls, one under a spell hears it from far away, a cave rings. Package: net.ixdarklord.coolcatcanvas.api.client.sound (client) and api.sound (server).

Since

Coming in 8.0.0, on every version. On 1.21.1 and 1.20.1, which have no UI sound category, the menus' clicks are the sounds played as MASTER relative to the listener, and named filters leave those alone the same way.

Every sound gets the filters below combined: a low-pass filter on it, and as much of it as they say sent, filtered the same, through a distortion and into a reverb. It's done with OpenAL's EFX extension, which the game's own OpenAL has; without it, sounds are left as they are.

A filter

A SoundFilter is four parts, each 0 to 1:

Part What it does
gain How loud the sound stays; 1 is as loud as it was.
gainHF How much of its high end it keeps. Losing the highs is what makes a sound muffled, as through a wall.
distortion How much of it goes through a distortion, which makes it rough.
reverb How much of it goes into a reverb, which makes it echo.
SoundFilter.muffled(0.8F)                            // through a thick wall
new SoundFilter(0.6F, 0.1F, 0.3F)                    // muffled and rough, as under water
SoundFilter.echoing(0.5F).then(SoundFilter.quieter(0.8F))
SoundFilter.NONE.lerp(underwater, fade)              // part of the way there, for a fade of your own

Named filters

The simplest way: a filter on every sound at once (music included, but not the menus' clicks), which fades in and out on its own.

SoundFilters.set(MyMod.id("underwater"), new SoundFilter(0.6F, 0.1F), 20);   // fades in over a second
SoundFilters.clear(MyMod.id("underwater"), 40);                             // and out over two
boolean on = SoundFilters.isSet(MyMod.id("underwater"));

Setting a name that's already on fades from where it is to the new filter. They're cleared when the player leaves the world.

From the server, SoundFilterControl does the same for one player, as one small packet (players without CoolCatLib are skipped):

SoundFilterControl.set(player, MyMod.id("dazed"), 0.7F, 0.15F, 0.2F, 0.0F, 20);   // gain, highs, distortion, reverb, fade
SoundFilterControl.clear(player, MyMod.id("dazed"), 60);

Providers

For filters that depend on each sound, register a SoundFilterProvider. It's asked about every sound as it starts and as it moves, with a SoundContext: where it plays, which sound event it is, its category, and whether it plays relative to the listener (music, the menus) rather than at a place in the world.

// Only hostile mobs, muffled:
SoundFilters.register(sound -> sound.source() == SoundSource.HOSTILE ? SoundFilter.muffled(0.5F) : SoundFilter.NONE);

// By place, for the sounds in the world only:
SoundFilters.Registration walls = SoundFilters.register(SoundFilterProvider.inWorld(position -> hiding.filter(position)));

SoundFilters.refresh();   // after your provider's answers change: the sounds already playing are filtered again
walls.remove();           // stop asking it

The sound thread

Providers are asked on the sound thread, so they must be quick and read only state that is safe to read from there: an immutable snapshot the game thread swaps in, for example. Named filters need none of this.

Reference

Type Description
SoundFilter Record (gain, gainHF, distortion, reverb), also made with (gain, gainHF[, distortion]). NONE, muffled(amount), quieter(gain), distorted(amount), echoing(amount); then(other), lerp(to, delta), withDistortion, withReverb, isNone().
SoundFilters set(id, filter[, fadeTicks]), clear(id[, fadeTicks]), isSet(id); register(provider) (returns a Registration to remove()), refresh().
SoundFilterProvider filter(SoundContext); inWorld(position -> filter).
SoundContext position(), sound() (the sound event's id, may be null), source(), relative(), inWorld().
api.sound.SoundFilterControl set(player, id, gain, gainHF, distortion, reverb, fadeTicks), clear(player, id, fadeTicks).