What does "area_mask" in AudioStreamPlayer3D/2D do?

javlin-studio

I'm working on a Godot Basics for audio and have hit a snag, I can't figure out what the area_mask variable within AudioStreamPlayer3D and AudioStreamPlayer2D does.

cybereality

If you check the documentation it says this:

Areas in which this sound plays. https://docs.godotengine.org/en/stable/classes/class_audiostreamplayer3d.html#class-audiostreamplayer3d-property-area-mask

However, that still isn't enough information. It takes an int value with a default of 1. But I don't see in the docs what the number represents. I mean, I understand that is should mute or play a sound in certain areas, but how does an int achieve that?

javlin-studio

@cybereality My first intuition was that maybe listeners and cameras had also had a corresponding variable and it acted the same way collision masks/layers did but neither have such variable.

I also checked to see if area nodes themselves had some associated variable (they have interplay with audio in other ways and the "area" part of the name point in that direction) but I couldn't find anything that way either.

Azedaxen

area_mask determines which Area layers affect the sound for reverb and audio bus effects. Areas can be used to divert AudioStreams so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are diverted through an audio bus to make them sound like they are being played underwater. More in-depth explanation of buses here

The docs are misleading, as the sound will still play even if it's not set to collide with any areas, it's just that it won't be able to have any audio effects applied by Areas since it's not set to collide with any Areas. So the main way area_mask would be used is if you don't want an AudioStream to be affected by a certain layer of Areas, you'd disable the corresponding mask bit for the AudioStream.

javlin-studio

@Azedaxen Yep, you're right. Honestly cannot believe I missed something so obvious, must have just been way overthinking it due to the vagary of the docs. Thank you very much for the help =) !

Calinou

I opened a pull request based on @Azedaxen's post to improve the documentation: https://github.com/godotengine/godot/pull/57944

cybereality

Thanks @Calinou