Setting Reverb Data of Rooms (EAX)

This document will attempt to explain how to set the new EFX settings in your rooms when mapping.

Previously these settings were known as EAX settings, and required EAX 4.0-compatible sound card. In TDM 2.06, EAX technology was completely replaced with OpenAL EFX, which is now processed in software (by openal-soft) without any requirements on sound card.

General

Setup

The EFX info for a map should be stored in the file "efxs/<mapname>.efx", where <mapname> is the name of your .map file (without extension).

In order to check that you have put the file into right location, start your mission in game. If TDM manages to load your efx file, then you will see the following message in console:

sound: found efxs/<mapname>.efx

If you failed something, then you will see a bit different message there:

sound: missing efxs/<mapname>.efx

In both cases some additional diagnostic messages can be present nearby.

Note: you must enable "OpenAL EFX" in sound settings in the main menu, otherwise TDM won't even try to load the efx file.

EFX file

It is a plain text file, so you can open it up in your text editor of choice.

Any EFX file must start with a header which specifies its version:

Version 2

If you forget this line, then your EFX file will not be loaded. The following versions are supported:

• Version 1 was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
• Version 2 was added in TDM 2.07. It uses the parameters from OpenAL EFX and supports a lot of presets. Recommended for all new missions.

The rest of the file consists of separate blocks, one for each "reverb zone". Each block must start with reverb keyword for Version 1 definitions, and eaxreverb keyword for Version 2 definitions.

Here is an example of such block from mars_city1.efx of the original Doom 3 game (Version 1):

// 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
}

And here is an artificial example of Version 2 definitions:

 eaxreverb "myweirdstreets" {
   reflections_gain 0.5
   reflections_delay 0.0050
   late_reverb_gain 2.5
   late_reverb_delay 0.050
   echo_time 0.25
   echo_depth 0.9000
 }

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.

A proper explanation of the parameters is given below.

Locations

Each reverb zone definition starts with a line which specifies to which location it must be applied:

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

Information about locations and how to set them up is available in another article: Location Settings#The Location Entities. Reverb zones use exactly the same locations as the ones which are used to specify per-area ambient sounds. You should name every info_location entity, i.e. provide a "name" spawnarg for it. This is the name used in reverb zone definitions.

As of TDM 2.06, you can't use capital letters in the name of your location entity or reverb zone. This may or may not change in the future.

Here is an example of an entity which defines "canal_tunnel" location:

//======================= from volta_v1.map ====================
// entity 3532
{
  "classname" "info_location"
  "name" "canal_tunnel"             //this is the name used
  "ambient" "snd_streets"
  "ambient_light" "0.04 0.03 0.02"
  "ambient_light_dynamic" "0.01 0.01 0.01"
  ...
}

And this is the EFX effect (reverb zone) for it:

//======================= from volta_v1.efx ====================
reverb "canal_tunnel" {             //name put to here
  "environment" 22
  "environment size" 1.8000
  "environment diffusion" 1.0000
  "room" -1000
  "room hf" -4000
  ...
}

During playing, the engine prints a message whenever the player's location changes. It allows you to check if you have set up locations properly. For instance, here are console messages showing a proper EFX location change:

Switching to EFX 'canal_tunnel' (#295)
Changed location from 'canal_streets' to 'canal_tunnel'.

It is also possible to specify portal-area number instead of location name in the reverb zone definition. The portal-area number is listed in the .proc file, which is created in the dmap process, in the format of _area<num> (where <num> is the portal area number), e.g. _area15. Beware: this functionality exists for fast hacking only! Do not release a mission with portal-area numbers in .efx file! The main reason to avoid it is that portal-area numbers are auto-generated, so minor changes in your mission can change all of them.

Finally, there is a "default" reverb environment which is used for any area in the map which does not have reverb information specified.

The order that the sound system checks for reverb data is: area number -> location name -> default.

Changes during playing

Type "reloadSounds" command into game console in order to reload EFX definitions.

So when you experiment with EFX, execute this command after each tweak to EFX file to hear the difference immediately.

Suppress effect

Sometimes you want to disable EFX effect on a specific sound. A typical example is when you have a voice in player's head, which must not depend on player's physical environment. Another case is when some sound already has reverb baked in, so you don't what to double-reverb it. Although the best practice is to use sound samples without embedded reverb, combined with proper EFX definitions.

You can disable all EFX effects on one specific sound shader by adding "no_efx" keyword to its body. For instance, here is how non-EFX version of blackjack unsheathing looks like:

blackjack_unsheath
{
  description "Made by pakmannen"
  sound/sfx/tools/melee/blackjack_unsheath.ogg
  no_efx                       //do NOT apply EFX to this sound
}

Note that if you change sound shaders, writing "reloadDecls" in TDM game console is enough to reload them.

There are a lot of stock sounds in TDM which should not be affected by EFX effects. Starting from TDM 2.07, the corresponding core sounds are marked with "no_efx" keyword (see issue 4688). If you discover any core sound which is affected by EFX while you believe it should not, start a discussion on forums.

Presets

Presets are given in this forum topic.

TODO: add presets here

Environment properties

With Version 2 of EFX file, the set of supported properties exactly matches the set of properties defined in OpenAL EFX for the "EAX Reverb" effect. Note that EFX defines several types of effects, including "EAX Reverb", "Standard Reverb", "Chorus", "Distortion", "Echo", "Flanger", etc. Only the first one is important, ignore all the rest (including the so-called "Standard Reverb").

The detailed description of all the properties is given in "Appendix 1 – Effect property descriptions" of the OpenAL Effects Extension Guide(pages 95-101). The short list is also available in a table on page 66 of the guide:

The only difference is that the property names in the guide have the AL_EAXREVERB_ prefix, while in TDM definitions this prefix is removed.

There is one special property PRESET, which is not present in the EFX guide. This property accepts the name of the preset which you want to use:

eaxreverb "myclassroom" {
  preset auditorium
}
eaxreverb "mycave" {
  preset cave
}
eaxreverb "mycorridor" {
  preset hallway
}

If you specify the preset like this, the values for all the reverb properties will be taken from the specified preset. Additionally, you can override values of some properties if you define them manually after defining the preset.

The preset property also accepts index of preset. Don't use indices for anything except experimentation, since they may change in future.

Legacy info

This information is from the old 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 general 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 (-100 dB to 0 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 frequency and its bandwidth (Q) -- are unknown. Value type is LONG; value range is -10000 to 0, expressed in hundredths of one decibel (-100 dB to 0 dB).
• room lf - Undocumented. Assumably, the Room LF property applies a high-pass to reflected sound in much the same way as Room HF applies low-pass. The value type and range is unknown, but is likely LONG, must be between -10000 and 0 and is expressed in hundredths of one decibel.
• decay time - The Decay Time property sets the reverberation decay time, or the time in which reverberation is diminished. It ranges from 0.1 (typically a small room with very dead surfaces) to 20.0 (typically a large room with very live surfaces). Value is FLOAT; value range is 0.1 to 20.0, expressed in seconds.
• decay hf ratio - The Decay HF Ratio property sets the spectral quality of the Decay Time parameter. It is the ratio of high-frequency decay time relative to the time set by Decay Time. The Decay HF Ratio value 1.0 is neutral: the decay time is equal for all frequencies. As Decay HF Ratio increases above 1.0, the high-frequency decay time increases so it’s longer than the decay time at low frequencies. You hear a more brilliant reverberation with a longer decay at high frequencies. As the Decay HF Ratio value decreases below 1.0, the high-frequency decay time decreases so it’s shorter than the decay time of the low frequencies. You hear a more natural reverberation. Value is FLOAT; value range is 0.1 to 20.0, expressed in a linear multiplier variable.
• decay lf ratio - Undocumented. It's likely best to leave the value at 1.0, though the value's type and range is probably the same as the Decay HF Ratio property.
• reflections - The Reflections property controls the overall amount of initial reflections relative to the Room property. The value of Reflections ranges from a maximum of 10 dB to a minimum of -100 dB (no initial reflections at all), and is corrected by the value of the Room property. The Reflections property does not affect the subsequent reverberation decay. You can increase the amount of initial reflections to simulate a more narrow space or closer walls, especially effective if you associate the initial reflections increase with a reduction in reflections delays by lowering the value of the Reflection Delay property. To simulate open or semi-open environments, you can maintain the amount of early reflections while reducing the value of the Reverb property, which controls later reflections. Value type is LONG; value range is -10000 to 1000, expressed in hundredths of one decibel (-100 dB to -10 dB).
• reflections delay - The Reflections Delay property is the amount of delay between the arrival time of the direct path from the source to the first reflection from the source. It ranges from 0 to 300 milliseconds. You can reduce or increase Reflections Delay to simulate closer or more distant reflective surfaces—and therefore control the perceived size of the room. Value is FLOAT; value range is 0.0 to 0.3, expressed in seconds (0 to 300 milliseconds).
• reflections pan - Undocumented. Three values are specified which may correspond to a generic "front", "side" and "back/rear" configuration to control the directivity of early reflections in a 7.1 surround matrix. Value type and range is unknown.
• reverb - The Reverb property controls the overall amount of later reverberation relative to the Room property. (The Room property sets the overall amount of both initial reflections and later reverberation.) The value of Reverb ranges from a maximum of 20 dB to a minimum of -100 dB (no late reverberation at all). Value is LONG; value range is -10000 to 2000, expressed in hundredths of a decibel (-100 dB to 20 dB).
• reverb delay - The Reverb Delay property defines the begin time of the late reverberation relative to the time of the initial reflection (the first of the early reflections). It ranges from 0 to 100 milliseconds. Reducing or increasing Reverb Delay is useful for simulating a smaller or larger room. Value is FLOAT; value range is 0.0 to 0.1, expressed in seconds (0 to 100 milliseconds).
• reverb pan - Undocumented. Three values are specified which may correspond to a generic "front", "side" and "back/rear" configuration to control the directivity of reverberation in a 7.1 surround matrix. Value type and range is unknown.
• echo time - Undocumented. Likely controls the decay time of echoes, or late reflections. A value of 0.1 likely presents a natural amount of echo, while increasing the value likely causes a "Grand Canyon" effect. Value type is likely FLOAT; value range is likely between 0.075 and 0.25, expressed in seconds.
• echo depth - Undocumented. May control directionality or tonal qualities of echoes arriving at the listener. Probably best to leave at 1.0. Value type and range is unknown.
• modulation time - Undocumented. Unknown purpose. Value type and range is unknown.
• modulation depth - Undocumented. Unknown purpose. Value type and range is unknown.
• air absorption hf - The Air Absorption HF property controls the distance-dependent attenuation at high frequencies caused by the propagation medium. It applies to both the direct path and reflected sound. You can use Air Absorption HF to simulate sound transmission through foggy air, dry air, smoky atmosphere, and so on. The default value is -0.05 dB per meter, which roughly corresponds to typical condition of atmospheric humidity, temperature, and so on. Lowering the value simulates a more absorbent medium (more humidity in the air, for example); raising the value simulates a less absorbent medium (dry desert air, for example). Value is FLOAT; value range is -100.0 to 0.0, expressed in hundredths of one decibel per meter (-1 dB to 0 dB). Default value is -5.0, which corresponds to -0.05 dB per meter attenuation.
• hf reference - Likely defines the frequency used for low-pass filters. Value is likely LONG; value range is likely between 0.0 and 20000.0, expressed in Hz. This value is probably best left at 5000.0.
• lf reference - Likely defines the frequency used for high-pass filters. Value is likely LONG; value range is likely between 0.0 and 20000.0, expressed in Hz. This value is probably best left at 250.0.
• room rolloff factor - The Room Rolloff property is one of two methods available in EAX to attenuate the reflected sound (containing both reflections, reverberation and echoes) according to source-listener distance. Value type is FLOAT; value range is 0.0 to 10.0, expressed in a linear multiplier value. It's recommended that users use 0.0, as id Software did not deviate from this value with Doom 3.
• flags - The Flags property is intended to control the relationship of high-level EAX properties to low-level properties. If certain EAX flags are set by setting the Flags property to a particular value, the setting of high-level properties is supposed to control the values of low-level properties based upon a defined scale, overriding specified values. In EAX 2.0, the value type is DWORD, whereas in Doom 3, it appears to be INT or some other type commonly used to store numeric values. In Doom 3, common values are 0, 2, 15, 31, 32, 56 and 63, but no documentation details what these values correspond to. If users wish to experiment with the Flags property, it is recommended that they choose from one of the above values. For reference, here is a table with the counts for each flag value as used in Doom 3:

Flag decimal	Flag binary	Count
0	00000000	497
2	00000010	6
14	00001110	15
15	00001111	94
31	00011111	511
32	00100000	247
56	00111000	59
63	00111111	168

Design

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.

Examples

There are some released FMs with EFX settings:

• Volta and the Stone. While Kingsal says EAX settings are unsupported, TDM loads them properly.
• Patently Dangerous. Probably the first map with EFX settings, but they don't load now.
• Crucible of Omens : Behind Closed Doors. Seems to have many EFX definitions and locations cover most of the map.

See Also

A tutorial based around EFX can be found here here

An old demonstration map of EAX in TDM is included here

A discussion about no_efx is here

The first version of this article was written by Ishtvan at http://forums.thedarkmod.com/topic/2071