Setting Reverb Data of Rooms (EAX)

Originally written by Ishtvan on http://forums.thedarkmod.com/topic/2071

This document will attempt to explain how to set the new EAX settings in your rooms when mapping. After installing the patch on a separate D3 install than the one you use for the mod:

The EAX info for maps is stored in Doom3/pak007.pk4 , the file extension is <mapname>.EFX . They're plain text files so you can open them up in your text editor of choice. I think these files go in the maps directory along with your other map files.

What an EFX file looks like

Lets take a look at mars_city1.EFX. The first thing you'll notice is that it consists of separate blocks, one for each "reverb zone." Lets take a look at one of these blocks:

// reverb maintenance
reverb "maintenance" {
 "environment" 26
 "environment size" 5.0670
 "environment diffusion" 0.6030
 "room" -411
 "room hf" -685
 "room lf" 0
 "decay time" 1.7360
 "decay hf ratio" 0.8030
 "decay lf ratio" 1.0000
 "reflections" 96
 "reflections delay" 0.0080
 "reflections pan" 0.0000 0.0000 0.0000
 "reverb" 27
 "reverb delay" 0.0050
 "reverb pan" 0.0000 0.0000 0.0000
 "echo time" 0.0750
 "echo depth" 1.0000
 "modulation time" 0.2500
 "modulation depth" 0.0000
 "air absorption hf" -5.0000
 "hf reference" 5000.0000
 "lf reference" 250.0000
 "room rolloff factor" 0.0000
 "flags" 56
}

What does all this mean?

There is a lot of sound design stuff that one could make guesses at if you've ever used a reverb plugin in any sort of sound editing program. hf = high frequency, lf = low frequency, etc. Then it looks like there are some engine-specific flags like in the line:

"flags" 56

Below, I included a brief explanation of some reverb sound design variables.

How to associate a sound environment in an EFX file with a location in your map

reverb "<name of the location area you want to apply this to>"
{
    //... 
}

In D3 maps you can put in "location" entities so that something like "Corridor 5" pops up in the HUD. I think the names are func_location to define the location name, and func_location_separator, that you must put at the visportals leading out of your location to define the location boundaries. See the Id maps for more info on how to define location areas. In the EFX file, you can apply reverb to an entire location (ie, everywhere where the HUD says "corridor 5" has the same reverb characteristics).

Sometimes, you may not want to make a new location for a small area with different reverb (like a bathroom). In this case, you can specify portal area number directly in the EFX file, to specify reverb for just this portal area (remember a portal area is a "room" defined by where you place portals). This brings up the question of how you find out what portal area number a given area has? I'm not sure what the answer is at this time. I know there is an SDK function to find out that I've used in soundprop, but I don't know what the best way is for mappers. There might be a cvar that will display the area number when you're walking around in the map; I'm not sure. Please post if you know a good way to find out. Maybe the editor also tells you?

Anyway, to put in reverb for a given area number, just put the portal number after the reverb line in the EFX file, like so.

reverb "<portal area number>"
{
   //...
}

Finally, there is a "default" reverb environment which is used for any area in the map which does not have reverb information specified by either location area or portal area number. The order that the sound system checks for reverb data is : area number -> location name -> default. Brian says it again here:

"The sound system looks for the specific area number first (36) if it can't find that, it searches for the area name "Security Checkpoint", if it can't find that, it uses "default". In general I would recommend against using the area numbers. We only had to do that because there were some areas with the same name and we didn't want to change the map file."

The Variables

In terms of the actual sound design for the values you put into these variables, here is a general tutorial on reverb from FruityLoops (NOTE: This is for a music production plugin, some of these don't apply, it's just to give a general idea on what certain variables do):

• Low Cut Adjusts the low cutoff frequency. Use this to remove low frequencies from the input signal before reverb is added. For example, if you are adding reverb to, say a drum track, you might want to remove some of the 'rumble' from the bass drum by attenuating the bass frequencies. Setting this parameter to the minimum value will bypass the Low Cut filter, displaying OFF in the value field.
• High Cut - Similar to the Low Cut, this adjusts the high cutoff frequency. Use this to remove high frequencies from the input signal.
• Predelay - Controls the delay time between the direct input signal and the first reverb reflection. This should be set to modest values for small rooms, and can be increased in relation to increases in room size. Predelay creates a slap-back echo effect that can both add atmosphere and muffle the signal, so use it wisely.
• Room Size - Use this to set the size of the virtual room where the reverb is created. The Room Size should be adjusted according to the decay time. Small rooms sound better with a short decay time, large rooms sound better with longer reverb times.
• Diffusion - Controls the density of the reflections bouncing off the walls of the virtual room. A low diffusion setting makes the reflections sound more distinct, like closely spaced echoes. A high diffusion setting creates reflections so close they sound more like noise, where no echoes can be distinguished.
• Color - The Color parameter is used for adjusting the decay time of the bass frequencies of the signal. This allows you to change the overall perceived mood or 'sound' of the virtual room. A bright room has a low bass response, while warm rooms have a higher bass response. In a flat room, the response of the bass is equal to the general frequency response. Color has five settings: Brighter, Bright, Flat, Warm, Warmer.
• Decay - Controls the decay time of the reverb, the time it takes for the signal to decay to -60dB (1/1000 of the maximum amplitude). Use low decay times for small rooms or boxes, and long decay times for large rooms, halls or churches. You should also make sure that the Room Size parameter has an appropriate value.
• High Damping - This parameter allows you to adjust damping of the high frequencies in the reverb signal over time. Damping refers to the high frequencies being attenuated and dying out. This causes the sound to become gradually muffled and warm like it is being absorbed in the room. Setting this parameter to the maximum value will bypass the High Damping, displaying OFF in the value field.
• Dry - Sets the relative dry output level.
• Reverb - Sets the relative reverb (wet) signal level.

Environment Properties

This information is from the official EAX 2.0 documentation. Although some properties may have changed in scope and focus from EAX 2.0 to EAX 4.0, one can assume that the properties serve the same purpose and that each property's value bounds are approximately the same.

• environment - Unknown. Likely sets the room to one of an unknown number of environment presets.
• environment size - The Environment Size property sets the apparent size of the surrounding “room.” The value of Environment Size can be considered a characteristic dimension of the room expressed in meters. Scaling Environment Size is equivalent to scaling all dimensions of the room by the same factor. Value type is FLOAT; value range is 1.0 to 100.0, expressed in linear meters.
• environment diffusion - The Environment Diffusion property controls the echo density in the reverberation decay. Reducing diffusion gives the reverberation a more “grainy” character that is especially noticeable with percussive sound sources. If you set a diffusion value of 0.0, the later reverberation sounds like a succession of distinct echoes. Value type is FLOAT; value range is 0.0 to 1.0, expressed in a linear multiplier value.
• room - The Room property is the master volume control for the reflected sound (both early reflections and reverberation) that EAX adds to all sound sources. It sets the maximum amount of reflections and reverberation added to the sound mix in the primary buffer (the listener). Value is LONG; value range is -10000 to 0, expressed in hundredths of one decibel (dB).
• room hf - The Room HF property further tweaks reflected sound by attenuating it at high frequencies. It controls a low-pass filter that applies globally to the reflected sound of all sound sources. The exact qualities of this low-pass filter -- its starting frequency and its bandwidth (Q) -- are unknown. Value type is LONG; value range is -10000 to 0, expressed in hundredths of one decibel (dB).