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.
Environment properties
New properties (Version 2)
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.
Presets (Version 2)
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.
The presets were taken from OpenAL-Soft implementation which TDM uses. Here is the full list of preset names:
GENERIC PADDEDCELL ROOM BATHROOM LIVINGROOM STONEROOM AUDITORIUM CONCERTHALL CAVE ARENA HANGAR CARPETEDHALLWAY HALLWAY STONECORRIDOR ALLEY FOREST CITY MOUNTAINS QUARRY PLAIN PARKINGLOT SEWERPIPE UNDERWATER DRUGGED DIZZY PSYCHOTIC CASTLE_SMALLROOM CASTLE_SHORTPASSAGE CASTLE_MEDIUMROOM CASTLE_LARGEROOM CASTLE_LONGPASSAGE CASTLE_HALL CASTLE_CUPBOARD CASTLE_COURTYARD CASTLE_ALCOVE FACTORY_SMALLROOM FACTORY_SHORTPASSAGE FACTORY_MEDIUMROOM FACTORY_LARGEROOM FACTORY_LONGPASSAGE FACTORY_HALL FACTORY_CUPBOARD FACTORY_COURTYARD FACTORY_ALCOVE ICEPALACE_SMALLROOM ICEPALACE_SHORTPASSAGE ICEPALACE_MEDIUMROOM ICEPALACE_LARGEROOM ICEPALACE_LONGPASSAGE ICEPALACE_HALL ICEPALACE_CUPBOARD ICEPALACE_COURTYARD ICEPALACE_ALCOVE SPACESTATION_SMALLROOM SPACESTATION_SHORTPASSAGE SPACESTATION_MEDIUMROOM SPACESTATION_LARGEROOM SPACESTATION_LONGPASSAGE SPACESTATION_HALL SPACESTATION_CUPBOARD SPACESTATION_ALCOVE WOODEN_SMALLROOM WOODEN_SHORTPASSAGE WOODEN_MEDIUMROOM WOODEN_LARGEROOM WOODEN_LONGPASSAGE WOODEN_HALL WOODEN_CUPBOARD WOODEN_COURTYARD WOODEN_ALCOVE SPORT_EMPTYSTADIUM SPORT_SQUASHCOURT SPORT_SMALLSWIMMINGPOOL SPORT_LARGESWIMMINGPOOL SPORT_GYMNASIUM SPORT_FULLSTADIUM SPORT_STADIUMTANNOY PREFAB_WORKSHOP PREFAB_SCHOOLROOM PREFAB_PRACTISEROOM PREFAB_OUTHOUSE PREFAB_CARAVAN DOME_TOMB PIPE_SMALL DOME_SAINTPAULS PIPE_LONGTHIN PIPE_LARGE PIPE_RESONANT OUTDOORS_BACKYARD OUTDOORS_ROLLINGPLAINS OUTDOORS_DEEPCANYON OUTDOORS_CREEK OUTDOORS_VALLEY MOOD_HEAVEN MOOD_HELL MOOD_MEMORY DRIVING_COMMENTATOR DRIVING_PITGARAGE DRIVING_INCAR_RACER DRIVING_INCAR_SPORTS DRIVING_INCAR_LUXURY DRIVING_FULLGRANDSTAND DRIVING_EMPTYGRANDSTAND DRIVING_TUNNEL CITY_STREETS CITY_SUBWAY CITY_MUSEUM CITY_LIBRARY CITY_UNDERPASS CITY_ABANDONED DUSTYROOM CHAPEL SMALLWATERROOM
Their definitions can be seen in efx-presets.h from OpenAL-Soft source code.
Legacy info (Version 1)
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.
Error Check
If you modified the presets in your EFX file, you can check for errors ingame. Load your map and open the console. Type reloadSounds, this will trigger the reload of the EFX used in your map and print out the vars which cause an error (like a value exceeding the maximum range). Note that if your EFX files contain errors, this will make the game ignore the EFX settings you chose.
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
The Version 2 definitions were implemented due to issue 4815, it has some brief explanation.
A tutorial based around EFX can be found 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
